How Hallmark Study Extracts Design DNA from Screenshots and URLs

The hallmark study command analyzes visual references through a five-step extraction protocol that identifies macrostructure, typography, color systems, motion patterns, and layout rhythm, outputting a structured diagnosis that can be serialized to a portable design.md file.

The hallmark study verb in the Nutlope/hallmark repository is a diagnostic tool that reverse-engineers design references into structured design DNA. Whether you provide a static screenshot or a live URL, the tool executes a retrieval and analysis pipeline defined in skills/hallmark/references/study.md and orchestrated through skills/hallmark/SKILL.md.

Source Mode Detection

The system first classifies your input to determine which analysis pipeline to run. According to lines 13–14 in skills/hallmark/references/study.md, the detection logic is straightforward:

• URL mode: Triggered when input starts with http:// or https://
• Image mode: Triggered for any attached image or pasted capture

This routing decision determines whether Hallmark performs a shallow web fetch or a vision-based analysis.

URL Mode: The Seven-Step Fetch Pipeline

When processing a web address, Hallmark follows a seven-step fetch pipeline (lines 27–38 in study.md) that prioritizes safety and precision before extracting design tokens.

Security and Refusal Checks

Before fetching, the system performs two validation layers:

1. URL refusal check: Matches against a hard-coded blocklist of paid-template marketplaces and restricted domains, refusing the request immediately if matched.
2. Remote-URL safety check: Validates the scheme (requiring https), rejects private IPs, localhost, and non-web schemes, and validates redirect chains (lines 39–50).

Shallow Fetch and Validation

The pipeline retrieves only the HTML and same-origin CSS via the built-in WebFetch tool (line 33). Scripts, images, and external resources are never fetched. The system treats all fetched data as untrusted, ignoring any embedded instructions (line 34).

A junk-or-blocked detection phase (lines 55–66) checks for authentication walls, SPA shells, non-2xx responses, missing CSS, or bodies under 1 KB. If triggered, Hallmark falls back to screenshot-mode messaging (line 69).

URL-Specific Extraction

After successful retrieval, Hallmark runs the five-step extraction protocol with access to semantic DOM and computed styles:

• Surface: Extracts exact color values from CSS custom properties (--color-*) and background-color declarations.
• Type: Captures precise font families from Google Fonts links, @font-face rules, or hardcoded font-family values.
• Structure: Maps semantic DOM tags (<nav>, <section>, <footer>) to macrostructures and component archetypes.
• Motion: Detects motion libraries (framer-motion, gsap, lottie-web, lenis) and CSS @keyframes or transitions.
• Rhythm: Records as "unknown (URL mode)" because HTML alone cannot infer visual spacing (lines 23–24, 80–84).

Image Mode: Vision-Based Analysis

For screenshots, Hallmark executes a vision pass using the same five-step protocol, but derives data from raster analysis rather than code:

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

The image-mode template is defined in study.md lines 72–104, while the URL-mode template occupies lines 106–108.

The Five-Step DNA Extraction Protocol

Both modes follow the same architectural protocol, differing only in data source fidelity:

Step	Domain	URL Mode Input	Image Mode Input
1. Surface	Color system	CSS custom properties	Visual estimation
2. Type	Typography	Exact font families	Role inference
3. Structure	Layout architecture	Semantic DOM tags	Visual regions
4. Motion	Animation patterns	Library detection	Null (not visible)
5. Rhythm	Spacing system	Unknown (blind spot)	Direct observation

Structured Output and Diagnosis

After extraction, Hallmark populates a JSON-compatible schema (lines 96–138 in study.md) that captures every datum, marking mode-conditional fields as null or "unknown" when unavailable. This schema drives a human-readable diagnosis report using the appropriate template.

The diagnosis enumerates:

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

Post-Diagnosis Actions

Upon completing the analysis, three paths are available:

1. Build: Use the extracted DNA in hallmark redesign or the default build flow.
2. Lock the DNA: Emit a portable design.md file per the format defined in skills/hallmark/references/design-md.md.
3. Stop: Terminate after receiving the diagnosis.

Emission in URL mode requires explicit user attestation that the source is either their own site or a public reference (lines 58–66). Image mode skips this step because the screenshot is user-provided.

Practical Usage Examples

Invoke the verb via CLI with the source as the argument:

# Analyze a local screenshot

hallmark study ./screenshot.png

# Analyze a public URL

hallmark study https://example.com

# Emit a design.md after analysis (URL mode requires attestation)

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

Summary

The hallmark study verb extracts design DNA from visual references through:

• Source detection that routes input to URL or image pipelines
• Safety checks including URL blocklists and IP validation
• Shallow fetching of HTML/CSS only (URL mode)
• Five-step extraction covering Surface, Type, Structure, Motion, and Rhythm
• Schema-driven output generating structured JSON and markdown diagnoses
• Portable serialization to design.md with ownership attestation for web sources

Frequently Asked Questions

What is the difference between URL mode and image mode in hallmark study?

URL mode fetches live HTML and CSS to extract exact design tokens like hex colors and font families, but cannot determine visual rhythm. Image mode analyzes static screenshots to infer layout rhythm and visual hierarchy, but can only estimate colors and suggest font candidates rather than identifying exact typefaces.

Why does URL mode show "unknown" for rhythm analysis?

HTML and CSS alone cannot convey the visual spacing and compositional balance that a human perceives when viewing a rendered page. According to lines 80–84 in study.md, Hallmark explicitly flags this as a blind spot in URL mode, whereas image mode can observe rhythm directly from the rendered layout.

How does hallmark study handle security when fetching external URLs?

The tool implements a multi-layer safety system: it checks against a hard-coded refusal list of restricted domains, validates that URLs use HTTPS, rejects private IP ranges and localhost, sanitizes redirect chains, and treats all fetched content as untrusted to prevent instruction injection (lines 39–50).

Can I export the design DNA after running a study?

Yes. After the diagnosis, you can lock the DNA to emit a portable design.md file following the schema in skills/hallmark/references/design-md.md. When extracting from URLs, you must first attest that you own the source or that it is a public reference before the file can be generated.

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