Hallmark Study Verb Modes: URL Mode vs Image Mode Explained

Hallmark's study verb operates in two mutually exclusive modes—URL mode and image mode—automatically selected based on whether your input starts with http:// or https://.

The study verb is a core feature of the Nutlope/hallmark repository that extracts design "DNA" from any source you provide. It analyzes visual and structural signals to generate a diagnostic report you can use to rebuild your own content or export as a portable design.md file.

How Hallmark Detects Which Mode to Use

Mode selection is automatic and deterministic. The tool inspects your input string and branches immediately—no flags or manual configuration required.

Mode	Trigger	Processing Method
URL mode	Input starts with http:// or https://	Fetches live page via WebFetch, parses HTML/CSS
Image mode	Any non-URL input (file path, pasted image, screenshot)	Runs local vision analysis on bitmap data

This logic is codified in [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L28): "Detection is automatic: a URL (http:// / https:// prefix) routes to URL mode; anything else (an attached image, a pasted capture) routes to image mode."

URL Mode: Analyzing Live Web Pages

When you pass a web address, Hallmark enters URL mode and performs network-based extraction.

What URL Mode Captures

• Exact font names from CSS declarations
• Precise colour values (hex, RGB, HSL)
• Structural signals from DOM hierarchy and layout

URL Mode Limitation

Rhythm (timing and animation curves) cannot be inferred from static HTML/CSS. The diagnostic report explicitly notes this gap since motion design requires runtime observation.

URL Mode Example

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

The WebFetch utility retrieves the page, and Hallmark's parser extracts computable design tokens without executing JavaScript or rendering the page visually.

Image Mode: Analyzing screenshots and bitmaps

When your input lacks a URL prefix, Hallmark enters image mode and processes the file locally through computer vision.

What Image Mode Captures

• Macrostructure (grid systems, visual hierarchy)
• Archetypes (design patterns and genre classification)
• Type-pairing relationships between fonts
• Colour anchor (dominant and accent palettes)
• Rhythm (timing, spacing, and motion cues visible in the frame)

Unlike URL mode, image mode makes no network requests. All analysis runs on the local bitmap, making it suitable for offline workflows or confidential designs.

Image Mode Example

hallmark study ./screenshots/portfolio.png

As documented in [skills/hallmark/references/study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md#L13): "If the user's input starts with http:// or https:// → URL mode; otherwise → image mode. Same verb, same diagnosis output, different signal sources."

Comparing Hallmark Study Modes: When to Use Each

Both modes produce identical output schemas—a structured diagnosis you can act on immediately or serialize to design.md. Choose based on what information you need and what source material you have available.

Factor	URL Mode	Image Mode
Best for	Live sites, precise front-end auditing	Screenshots, mood boards, competitors' work
Font accuracy	Exact family names from CSS	Inferred from visual similarity
Colour precision	Native CSS values	Extracted from pixel sampling
Rhythm detection	Not available	Available (if visible in frame)
Network required	Yes	No
Privacy	Source site sees request	Completely local

The [site/index.html](https://github.com/Nutlope/hallmark/blob/main/site/index.html#L412) interface exposes this duality with a single command pattern: /hallmark study <screenshot | URL>.

Working with Study Output

Regardless of mode, the study verb emits a diagnostic you can use in two ways:

1. Rebuild — Apply the extracted DNA to your own content immediately
2. Export — Generate a design.md file for version control or sharing

The uniform output format means your toolchain needs no branching logic for mode-specific handling.

Summary

• Two modes power Hallmark's study verb: URL mode for live pages, image mode for static files
• Automatic detection: http:// or https:// prefix triggers URL mode; all other inputs trigger image mode
• URL mode delivers precise CSS-extracted fonts and colours but cannot capture rhythm
• Image mode runs vision inference locally, capturing rhythm and macrostructure without network access
• Both modes produce identical diagnostic schemas for flexible downstream use

Frequently Asked Questions

How does Hallmark choose between URL mode and image mode?

Hallmark inspects the input string prefix. If it starts with http:// or https://, the tool routes to URL mode; otherwise it assumes image mode. This is documented in [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L28) and requires no user flags.

Can I force image mode even if my filename looks like a URL?

No. The current implementation has no override flag—mode selection is strictly prefix-based. To analyze a screenshot with a URL-like filename, rename it or pass it through a different entry point.

Why can't URL mode detect animation timing?

URL mode parses static HTML and CSS without executing JavaScript or rendering frames. Since rhythm data exists only in runtime behavior (transitions, keyframes with delays), it falls outside the observable surface. Image mode can infer rhythm only when motion is frozen as blur trails or sequential frames in the screenshot.

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