How Hallmark's `study` Verb Extracts Design DNA from Screenshots and URLs

The hallmark study verb analyzes a design reference—screenshot or public URL—through a five-step extraction pipeline to capture its macrostructure, component archetypes, type-pairing, color anchor, and motion, outputting a structured diagnosis and optional portable design.md.

Hallmark, an open-source design system tool by Nutlope, includes a powerful diagnostic command called hallmark study. This verb transforms visual or web references into structured design DNA that can drive downstream page generation. The implementation lives in two key files: [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) declares the verb's contract, while [skills/hallmark/references/study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) contains the complete extraction protocol.

Source Mode Detection: Image vs. URL

Hallmark determines its extraction strategy through simple input classification at [study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) lines 13-14:

• URL mode: Input starts with http:// or https://
• Image mode: Any attached image or pasted capture

This detection triggers entirely different pipelines while converging on the same five-step extraction framework.

URL Mode: The Seven-Step Fetch Pipeline

When processing a public URL, Hallmark executes a rigorous fetch pipeline defined at [study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) lines 27-38:

Safety and Refusal Checks

1. URL refusal list: Hallmark matches against hard-coded blocked domains (paid template marketplaces) before any network call.
2. Remote-URL safety validation (lines 39-50): Enforces https scheme, rejects private IPs, localhost, non-web schemes, and unsafe redirects.

Minimal Fetch Strategy

3. Shallow fetch: Uses the built-in WebFetch tool to retrieve HTML and same-origin <link rel="stylesheet"> CSS files only. Scripts, images, and other resources are never fetched (line 33).
4. Untrusted data treatment: Instructions embedded in remote payloads are ignored; only design facts are extracted (line 34).

Quality Gates

5. Junk-or-blocked detection (lines 55-66): Screens for authentication walls, SPA shells, non-2xx responses, missing CSS, or sub-1 KB bodies. Triggers fallback to screenshot recommendation if failed (line 69).

Five-Step Extraction with Rich Data

6. Enhanced extraction protocol (lines 6-8, 17-23):

Step	URL Mode Advantage
Surface	Exact color values from CSS custom properties (--color-*, background-color)
Type	Precise font families from Google Fonts links, @font-face, or hardcoded font-family
Structure	Semantic DOM tags (<nav>, <section>, <footer>) mapped to macrostructures
Motion	Detects motion libraries (framer-motion, gsap, lottie-web, lenis) and CSS @keyframes/transitions
Rhythm	Blind spot: HTML alone cannot infer visual rhythm; recorded as "unknown (URL mode)" (lines 23-24, 80-84)

7. Schema population and diagnosis: Fills the structured JSON schema (lines 96-138) and renders URL-mode template output (lines 106-108).

Image Mode: Vision-Pass Extraction

For screenshots, Hallmark runs a vision-pass through identical five-step protocol stages with raster-based limitations (lines 72-104):

• Surface: Color bands and accent footprint estimated by eye (line 19)
• Type: Only type roles (display, body, label) inferred; exact font names not guessed. Hallmark suggests 1-2 candidate fonts from its canon instead (lines 22-34)
• Structure: Visual regions mapped to macrostructures and component archetypes via pattern recognition (line 45)
• Motion: Static images provide no motion data; Hallmark notes "motion not visible – assuming default reveals" (line 62)
• Rhythm: Directly observable from layout, enabling richer diagnosis than URL mode

Structured Output Schema

Both modes populate a JSON-compatible schema ([study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) lines 96-138) with these characteristics:

• Captures every extracted datum uniformly
• Marks mode-conditional fields as null when unavailable
• Flags unknown values explicitly (e.g., "density": "unknown (URL mode)")
• Drives both human-readable diagnosis and downstream automation

Diagnosis Report Generation

Post-extraction, Hallmark renders a concise markdown diagnosis containing:

• Macrostructure and component archetypes
• Type-pairing roles (exact fonts in URL mode)
• Surface color bands, accent hue, and footprint
• Motion library and reveal pattern (URL) or fallback note (image)
• Rhythm blind-spot notice for URL mode
• Anti-patterns to avoid

Post-Diagnosis Actions

Users can proceed three ways after receiving a diagnosis:

1. Build: Use extracted DNA with hallmark redesign or default flow
2. Lock DNA: Emit portable design.md (requires source attestation in URL mode at lines 58-66; skipped for user-provided screenshots)
3. Stop: Terminate after diagnosis

Command Examples

Study a Screenshot

hallmark study ./homepage-screenshot.png

Hallmark detects image mode, runs vision-pass extraction, and outputs markdown diagnosis.

Study a Public URL

hallmark study https://example.com

Hallmark performs safety checks, shallow-fetches HTML/CSS, extracts exact tokens, and returns URL-mode diagnosis.

Emit Portable Design Document

hallmark study https://example.com --emit-design-md

URL mode prompts for source attestation, then writes design.md per [design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) specification.

Key Implementation Files

File	Purpose
[skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)	Verb declaration and high-level contract
[skills/hallmark/references/study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md)	Complete protocol: detection, safety checks, extraction, schema, templates
[skills/hallmark/references/design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md)	Portable design document format specification
[docs/study-examples.md](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md)	End-to-end usage examples
[site/_tests/verbs/study/diagnosis.md](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/study/diagnosis.md)	Regression test fixture

Summary

• Source detection routes input to image or URL pipeline
• URL mode performs seven-step fetch with shallow, untrusted-data retrieval and exact token extraction
• Image mode runs vision-pass with estimated values but superior rhythm inference
• Five-step extraction (Surface → Type → Structure → Motion → Rhythm) unifies both modes with mode-specific data richness
• Structured schema enables portable output and downstream automation
• Safety-first design includes refusal lists, URL validation, and junk detection before any extraction

Frequently Asked Questions

What design elements can Hallmark extract from a URL that it cannot from a screenshot?

Hallmark extracts exact color values from CSS custom properties, precise font families from @font-face and Google Fonts links, and motion library detection (framer-motion, gsap, lottie-web, lenis) from source code. Screenshots only permit visual estimation of colors, type role inference without exact names, and no motion data. However, screenshots enable direct rhythm observation, which HTML cannot provide.

Why does URL mode report "unknown" for visual rhythm?

According to the [study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) protocol (lines 23-24, 80-84), HTML documents contain no inherent spatial information about element sizing, spacing, or density. Rhythm requires visual inspection of rendered output, so Hallmark explicitly flags this as a blind spot and informs the user rather than guessing.

What safety measures prevent Hallmark from fetching malicious URLs?

Hallmark implements layered protections: a hard-coded refusal list blocks known problematic domains; scheme validation requires https; private IP and localhost rejection prevents internal network probing; and redirect chain validation applies the same checks to every hop. The shallow fetch additionally never executes scripts or retrieves external resources.

How do I preserve extracted design DNA for reuse?

After running hallmark study, respond "lock the DNA" or invoke with --emit-design-md. For URLs, you must first attest that the source is your own site or a public reference. Hallmark then writes a portable design.md file conforming to the schema in [design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md), which can seed future hallmark redesign commands without re-studying the source.

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