How Hallmark Study Extracts Design DNA from Screenshots and URLs: A Technical Deep Dive

The hallmark study verb extracts design DNA by detecting the input type (image or URL), running safety checks, and executing a five-step protocol (Surface, Type, Structure, Motion, Rhythm) that populates a structured JSON schema and renders a human-readable diagnosis.

The Nutlope/hallmark repository implements a diagnostic tool that "studies" design references to pull out their design DNA—including macrostructure, component archetypes, type-pairing, colour anchors, and motion patterns. Whether analyzing a user-provided screenshot or a public web address, the verb follows a declarative pipeline defined in skills/hallmark/references/study.md and orchestrated by skills/hallmark/SKILL.md. Here is the complete architectural breakdown of how Hallmark processes these two source modes.

Source Mode Detection

Hallmark distinguishes between input types using simple prefix detection implemented in study.md (lines 13-14).

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

This binary detection determines which safety checks, fetch logic, and extraction heuristics execute downstream.

URL Mode Pipeline

When a URL is supplied, Hallmark executes a seven-step fetch pipeline (lines 27-38 in study.md) before performing DNA extraction.

Safety and Refusal Checks

The pipeline begins with strict security validations:

1. URL refusal check: Matches against a hard-coded refuse list (paid-template marketplaces). If matched, the verb refuses before any network call.
2. Remote-URL safety check: Validates HTTPS scheme, rejects private IPs, localhost, and non-web schemes. Redirects must pass the same security checks (lines 39-50).
3. Shallow fetch: Uses the built-in WebFetch tool to retrieve only HTML and same-origin <link rel="stylesheet"> CSS files (line 33). Scripts, images, and other resources are never fetched.
4. Untrusted data treatment: Any instructions embedded in the remote payload are ignored; only design facts are extracted (line 34).
5. Junk-or-blocked detection: Looks for authentication walls, SPA shells, non-2xx responses, missing CSS, or sub-1 KB bodies (lines 55-66). If triggered, Hallmark falls back to screenshot-fallback messaging (line 69).

Five-Step Extraction Protocol

After fetching, Hallmark runs the same five-step protocol used for image mode, but with richer data sources (lines 6-8, 17-23):

Step	URL Mode Extraction Details
1. Surface	Extracts exact colour values from CSS custom properties (--color-*, background-color, etc.).
2. Type	Captures precise font families from Google Fonts <link> tags, @font-face declarations, or hard-coded font-family values.
3. Structure	Maps semantic DOM tags (<nav>, <section>, <footer>, etc.) to macrostructures and component archetypes.
4. Motion	Detects motion libraries (framer-motion, gsap, lottie-web, lenis) and CSS @keyframes / transitions.
5. Rhythm	Blind spot: HTML alone cannot infer visual rhythm. Hallmark records this as "unknown (URL mode)" and informs the user (lines 23-24, 80-84).

The schema is then populated according to the structured JSON definition (lines 96-138), followed by rendering the URL-mode diagnosis template (lines 106-108).

Image Mode Pipeline

When processing a screenshot, Hallmark runs a vision-pass using the image-mode side of the five-step protocol. The steps align with URL mode, but data sources differ significantly:

• Surface: Colour bands and accent footprints are estimated by eye from the raster image (line 19).
• Type: Only type roles (display, body, label) are inferred; exact font names are not guessed (lines 22-34). Hallmark suggests 1-2 candidate fonts from its canon.
• Structure: Visual regions map to macrostructures and component archetypes via pattern recognition (line 45).
• Motion: Static screenshots provide no motion data, so Hallmark 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.

Structured Output and Diagnosis

Both modes output a JSON-compatible schema (lines 96-138 in study.md) that captures every extracted datum. The schema marks mode-conditional fields as null when unavailable and explicitly flags unknown values (e.g., "density": "unknown (URL mode)").

After schema completion, Hallmark renders a concise diagnostic markdown report using the appropriate template. The report enumerates:

• Macrostructure and component archetypes
• Type-pairing roles (and exact fonts in URL mode)
• Surface colour 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

Following the diagnosis, the user can execute three paths:

1. Build: Proceed with the extracted DNA using hallmark redesign or the default flow.
2. Lock the DNA: Emit a portable design.md file (see lines 33-44 in the study documentation).
3. Stop: Terminate after receiving the diagnosis.

Important: Emitting a design.md in URL mode requires explicit attestation that the source is the user's own site or a public reference (lines 58-66). Image mode skips this requirement because the screenshot is user-provided. The design.md format specification lives in skills/hallmark/references/design-md.md.

Code Examples

Studying a Screenshot

hallmark study ./landing-page-screenshot.png

Hallmark detects image mode, runs the vision pass, and prints a markdown diagnosis.

Studying a Public URL

hallmark study https://example.com

Hallmark performs URL-mode safety checks, fetches HTML/CSS, extracts exact colour tokens and font families, and returns a URL-mode diagnosis.

Emitting a Design DNA File

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

In URL mode, Hallmark requests source attestation before writing design.md using the schema defined in design-md.md.

Summary

• Source detection determines whether Hallmark runs URL-mode or image-mode pipelines.
• URL mode performs a seven-step fetch with security checks, extracting exact CSS values, font families, DOM semantics, and motion libraries, but cannot determine visual rhythm.
• Image mode relies on visual estimation for colours and type roles, cannot detect motion, but provides accurate rhythm analysis.
• Both modes populate a structured JSON schema (lines 96-138 in study.md) driving a human-readable diagnosis.
• Users can lock the DNA into a portable design.md, with URL mode requiring source ownership attestation.

Frequently Asked Questions

What is the "design DNA" that Hallmark extracts?

Design DNA refers to the essential genetic code of a interface: its macrostructure (page layout), component archetypes (UI patterns), type-pairing (font relationships), colour anchor (primary palette), and motion (animation patterns). The hallmark study verb extracts these elements into a structured schema that can drive subsequent build processes or be saved as a portable design.md file.

Why can't URL mode detect visual rhythm?

URL mode analyzes HTML and CSS source code, not rendered pixels. While CSS contains layout properties, the actual visual rhythm—the perceived density, pacing, and whitespace balance—requires spatial rendering that only occurs in a browser viewport. Hallmark explicitly marks this as a "blind spot" (lines 80-84 in study.md) and advises users to provide screenshots if rhythm analysis is critical.

How does Hallmark prevent fetching malicious URLs?

The URL pipeline implements a remote-URL safety check (lines 39-50) that validates HTTPS schemes, rejects private IP ranges, localhost, and non-web URI schemes. It also matches URLs against a refusal list of blocked domains (template marketplaces, etc.) before any network call. Additionally, the WebFetch tool operates in a restricted mode that only retrieves HTML and same-origin CSS, ignoring scripts and external resources.

What happens if the fetched URL returns a login wall or SPA shell?

Hallmark runs junk-or-blocked detection (lines 55-66) that identifies authentication walls, SPA shells (empty <div id="root"> structures), non-2xx HTTP responses, missing CSS, or bodies under 1 KB. When these signals trigger, the verb falls back to a screenshot-fallback message (line 69), prompting the user to provide an image capture instead of relying on the fetched source.

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