Hallmark Study URL Mode vs Image Mode: Key Differences for Design Diagnosis

Hallmark's study verb diagnoses design DNA from either a live webpage (URL mode) or a screenshot (image mode), with each source providing different depths of information across five analysis steps.

Hallmark's study verb is the core diagnostic tool in the Nutlope/hallmark repository for extracting design system "DNA" from any source. Understanding when to use URL mode versus image mode ensures you capture the most accurate tokens, typefaces, and structural information available. The trigger logic is simple: input strings starting with http:// or https:// activate URL mode; everything else—including attached images or pasted screenshots—triggers image mode.

How Source Mode Is Determined

The mode selection happens automatically based on input format. According to skills/hallmark/references/study.md (lines 11-14), the router checks:

• URL mode: Input matches /^https?:\/\//
• Image mode: Any other input (file paths, image buffers, clipboard captures)

This routing decision cascades through all five analysis steps, determining what data each step can actually collect.

Step-by-Step Comparison: What Each Mode Can Capture

Surface (Step 1): Color Extraction

URL mode pulls exact color values from CSS custom properties in :root, background-color, and other computed styles. It records both the band (e.g., "light") and the precise OKLCH/hex/RGB value.

Image mode estimates color bands and accent footprint by visual perception. No exact numeric values are recorded—only qualitative descriptors like paper_band and accent_hue_band.

Type (Step 2): Typography Identification

URL mode reads declared typefaces from:

• @font-face declarations
• Google Fonts <link> tags
• next/font configurations
• Explicit font-family CSS rules

Both roles and exact font names are stored (e.g., display_face: "Inter Display").

Image mode only infers roles (e.g., "italic editorial serif"). The actual font name is omitted because visual identification is unreliable.

Structure (Step 3): Layout Mapping

URL mode parses the real DOM—<nav>, <section>, <main>, <footer>, and other semantic elements—to map elements to the 21 named macro-structures defined in skills/hallmark/references/macrostructures.md and component archetypes from skills/hallmark/references/component-cookbook.md.

Image mode infers structure from visible regions in the screenshot. No DOM insight means nested relationships and semantic meaning must be guessed from visual hierarchy alone.

Motion (Step 4): Animation Detection

URL mode detects motion libraries (framer-motion, gsap, lottie-web, lenis), CSS @keyframes, transitions, and scroll-triggered reveals by scanning source code and stylesheets.

Image mode usually reports motion as "not visible" unless the screenshot itself is animated (rare) or the user explicitly describes motion in accompanying text.

Rhythm (Step 5): Visual Pacing

URL mode has a blind spot here. HTML cannot convey visual pacing, so rhythm fields are marked unknown (URL mode).

Image mode directly observes spacing, density, and pacing from the screenshot, enabling actual rhythm judgment.

Schema Output Differences

The final diagnosis report (template defined in study.md lines 73-99) populates different fields depending on source mode:

URL Mode Populates	Image Mode Populates
paper_value, accent_value (exact colors)	paper_band, accent_hue_band (qualitative)
display_face, body_face (exact font names)	Role descriptors only (font names null)
motion_library (detected libraries)	null or "not visible"
Rhythm: unknown (URL mode)	Rhythm: actual observations

Safety and Privacy Considerations

URL mode runs multiple safety checks before fetching:

• URL-refusal list (blocked domains)
• Remote-URL safety validation
• "Junk-or-blocked" detection (cloudflare, paywalls, bot protection)

Image mode requires no network safety steps. Only image-mode refusal rules apply (malformed images, unsupported formats).

CLI Usage Examples

# URL mode – fetches HTML + same-origin CSS

hallmark study https://example.com/product-page

# Image mode – supplies a screenshot; no network fetch occurs

hallmark study --image ./screenshot.png

When to Use Each Mode

Choose URL mode when:

• The page renders server-side with accessible CSS
• You need exact color tokens and font names
• Motion libraries and animation details matter
• The site is public and fetchable

Choose image mode when:

• The page is client-rendered or behind authentication
• The site blocks automated fetching
• Visual rhythm, spacing, and density are critical
• You have a precise screenshot of the intended state

Summary

• URL mode excels at precise tokens, exact typography, DOM structure, and motion detection—fails at rhythm.
• Image mode captures rhythm and works with inaccessible pages—sacrifices exact values for visual fidelity.
• Mode selection is automatic based on input format (http prefix vs. image path).
• Both modes output to the same diagnosis report schema, but populated fields differ significantly.

Frequently Asked Questions

Can I force image mode even with a URL string?

No. The mode router in study.md strictly checks for http:// or https:// prefixes. To analyze a URL as an image, capture a screenshot first and pass the image path.

Why does URL mode report "unknown" for rhythm?

HTML and CSS contain no semantic information about visual pacing, density, or spacing rhythm. These qualities only exist in the rendered visual output, which requires image mode observation.

Does image mode ever detect exact font names?

No. As documented in the type analysis step, image mode deliberately omits exact font names because visual identification is unreliable. Only inferred roles like "bold geometric sans" are reported.

What happens if URL mode hits a blocked or protected site?

The fetch layer runs "junk-or-blocked" detection. If triggered, the study aborts with an error rather than returning partial or misleading data. Use image mode with a manual screenshot as the fallback.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}