Hallmark Study URL Mode vs Image Mode: How the Source Type Changes Design Analysis

Hallmark's study command automatically detects whether your input is a URL or image and adapts its five-step diagnostic protocol accordingly, with URL mode extracting precise CSS values while image mode relies on visual inference.

When you run hallmark study, the tool needs to decide whether it can fetch and parse live code or must interpret a static visual. This distinction—URL mode versus image mode—determines exactly what design DNA the tool can extract. Understanding these differences helps you choose the right input type for your specific workflow.

---

How Hallmark Detects URL Mode vs Image Mode

The detection logic is straightforward and implemented in skills/hallmark/references/study.md (lines 11-14). Hallmark checks whether your input string starts with http:// or https://:

• URL mode triggered: Input begins with http:// or https://
• Image mode triggered: Any other input (file path, attached image, pasted screenshot)

This automatic routing happens before any network requests or image processing begins.

# URL mode – triggers network fetch and HTML/CSS parsing

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

# Image mode – processes local screenshot without network access

hallmark study --image ./screenshot.png

---

The Five-Step Protocol: What Each Mode Can See

Both modes follow the same diagnostic structure defined in study.md, but the depth of information at each step varies dramatically.

Step 1: Surface (Color Extraction)

Mode	Capabilities
URL mode	Pulls exact color values from CSS custom properties (:root variables, background-color, etc.). Records both the band (e.g., "light") and precise OKLCH/hex/RGB values in fields like paper_value and accent_value.
Image mode	Estimates color bands and accent footprint by visual inspection. Only band-level descriptors (e.g., paper_band, accent_hue_band) are recorded; exact numeric values are omitted.

Step 2: Type (Typography Detection)

• URL mode: Reads declared typefaces from @font-face rules, Google Fonts <link> tags, next/font declarations, or explicit font-family CSS. Captures both roles and exact font names in display_face and body_face fields.
• Image mode: Infers typographic roles only (e.g., "italic editorial serif"). The actual font name is omitted because visual identification is unreliable.

Step 3: Structure (Layout Mapping)

• URL mode: Parses the real DOM structure using semantic elements (<nav>, <section>, <main>, <footer>) to map elements to the 21 named macro-structures defined in macrostructures.md and component archetypes from component-cookbook.md.

• Image mode: Infers structure from visible regions in the screenshot. Without DOM access, it cannot distinguish semantic containers from presentational grouping.

Step 4: Motion (Animation Detection)

Mode	Detection Range
URL mode	Identifies motion libraries (framer-motion, gsap, lottie-web, lenis), CSS @keyframes, transitions, and scroll-triggered reveals. Populates motion_library field.
Image mode	Usually reports "not visible" unless the screenshot itself captures motion blur or the user provides a description.

Step 5: Rhythm (Visual Pacing)

This step reveals a critical blind spot in URL mode:

• URL mode: Rhythm fields are marked unknown (URL mode). HTML cannot convey visual pacing, density, or spacing relationships.
• Image mode: Directly observes spacing, density, and pacing. Can judge rhythm accurately from the screenshot.

---

Schema Output Differences

The final diagnosis report reflects these capabilities in its populated fields:

Field	URL Mode	Image Mode
paper_value, accent_value	Exact color tokens	null
display_face, body_face	Concrete font names	null
motion_library	Detected library name	null
paper_band, accent_hue_band	Populated	Populated
Rhythm assessment	unknown	Actual judgment

---

Safety and Privacy Considerations

URL mode includes additional safeguards before any fetch occurs:

• URL refusal list validation
• Remote-URL safety checks
• "Junk-or-blocked" detection

Image mode bypasses network entirely, applying only image-mode refusal rules. This makes image mode preferable for client-rendered pages, authenticated content, or air-gapped environments.

---

When to Use Each Mode

Choose URL mode when:

• The page renders server-side with accessible CSS
• You need exact color values 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
• Visual rhythm and spacing analysis is priority
• Network access is restricted or undesirable
• You need to analyze a specific state or viewport

---

Summary

• Hallmark study auto-detects URL mode (http:// prefix) versus image mode (all other inputs)
• URL mode excels at: exact colors, precise fonts, DOM structure, motion libraries
• Image mode excels at: visual rhythm, authenticated content, air-gapped analysis
• URL mode has a critical blind spot: cannot assess visual pacing (rhythm fields return unknown)
• Image mode has inherent limitations: no exact values, no motion detection, no DOM semantics
• Choose your input type based on which design DNA components matter most for your analysis

---

Frequently Asked Questions

How does Hallmark detect whether to use URL mode or image mode?

Hallmark checks if your input string starts with http:// or https:// in skills/hallmark/references/study.md (lines 11-14). If it matches, URL mode triggers a network fetch and HTML/CSS parse. Any other input routes to image mode for local visual processing.

Why can't URL mode analyze visual rhythm?

HTML and CSS cannot encode spatial pacing, density relationships, or compositional timing. These visual properties exist only in the rendered output. URL mode marks rhythm fields as unknown (URL mode) because the source code lacks this information.

When should I prefer image mode over URL mode?

Use image mode when analyzing client-rendered SPAs, authenticated content, specific viewport states, or when network access is unavailable. Image mode is also essential when rhythm and spacing analysis matters, as this is URL mode's primary data gap.

Does image mode capture motion or animation details?

Generally no—image mode reports motion as "not visible" unless the screenshot itself shows motion artifacts or the user explicitly describes animation behavior. For reliable motion library detection, URL mode's code-based analysis is required.

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