How Hallmark Extracts Design DNA from Screenshots and URLs

The hallmark study verb runs a mode-specific pipeline that analyzes web URLs or raster images through a five-step extraction protocol to generate a structured design DNA schema.

The hallmark study verb in the Nutlope/hallmark repository is a diagnostic skill that transforms visual references into portable design specifications. According to the source code in skills/hallmark/SKILL.md and skills/hallmark/references/study.md, it supports two input modes—URL and image—each executing distinct safety checks and extraction logic to populate a JSON schema describing macrostructure, typography, color, motion, and rhythm.

Source Mode Detection

The verb begins by classifying input into one of two categories. As implemented in skills/hallmark/references/study.md lines 13‑14, the detection logic checks the input string prefix:

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

This binary classification determines which safety protocols and extraction methods execute downstream.

URL Mode: The Seven-Step Fetch Pipeline

When operating in URL mode, Hallmark executes a defensive fetch pipeline defined in skills/hallmark/references/study.md lines 27‑38. This process retrieves only the minimal HTML and CSS required for analysis while blocking potentially harmful or irrelevant requests.

Safety and Refusal Checks

Before any network call, the system performs two validation layers:

1. URL Refusal Check: Matches the input against a hard-coded blocklist containing paid-template marketplaces and other refused domains. If matched, the verb terminates immediately.
2. Remote-URL Safety Check: Validates the scheme is https, rejects private IP ranges, localhost, and non-web schemes, and validates that any redirects pass the same security filters (lines 39‑50).

Shallow Fetch and Untrusted Data Handling

Upon passing security checks, Hallmark invokes the built-in WebFetch tool (line 33) to perform a shallow fetch. This retrieves only the target HTML and same-origin <link rel="stylesheet"> CSS files while explicitly excluding scripts, images, and other external resources. The system treats all fetched data as untrusted (line 34), ignoring any embedded instructions and extracting only verifiable design facts.

Junk Detection and Fallback

The pipeline includes a robust junk-or-blocked detection system (lines 55‑66) that scans for authentication walls, SPA shells, non-2xx HTTP responses, missing CSS, or HTML bodies under 1 KB. If any signal triggers, Hallmark aborts the fetch and falls back to a screenshot-based error message (line 69).

Image Mode: The Vision Pass

In image mode, Hallmark bypasses network fetching entirely and runs a vision-based analysis directly on the raster input. As documented in the image-mode template section (lines 72‑104), this pipeline estimates design properties through pattern recognition rather than parsing source code. Static screenshots provide no motion data and limited typographic precision, but offer direct observability of visual rhythm and layout density that URL mode cannot infer from HTML alone.

The Five-Step Extraction Protocol

Both modes eventually execute the same five-step protocol to populate the design DNA schema, though data fidelity differs based on source modality.

Surface: Color Extraction

URL mode extracts exact color values from CSS custom properties (e.g., --color-*, background-color) and computed styles. Image mode estimates color bands and accent footprints by visual analysis (line 19), as it lacks access to the underlying stylesheet variables.

Type: Typography Analysis

URL mode captures precise font families by parsing <link> tags pointing to Google Fonts, @font-face declarations, and hard-coded font-family rules (lines 17‑23). Image mode infers only type roles—display, body, or label—without guessing specific font names, instead suggesting 1–2 candidates from Hallmark's internal canon (lines 22‑34).

Structure: Macrostructure and Components

URL mode maps semantic DOM tags (<nav>, <section>, <footer>, etc.) to macrostructures and component archetypes. Image mode performs visual region segmentation to identify headers, content blocks, and navigation patterns through spatial analysis (line 45).

Motion: Animation Detection

URL mode detects motion libraries by scanning for imports of framer-motion, gsap, lottie-web, and lenis, alongside CSS @keyframes and transition properties. Image mode records motion as "not visible – assuming default reveals" (line 62) since static images contain no animation data.

Rhythm: Layout Density

Image mode directly observes visual rhythm, spacing, and density from the layout. URL mode explicitly marks rhythm as an "unknown (URL mode)" blind spot (lines 23‑24, 80‑84), as HTML alone cannot infer visual spacing without rendering context.

Structured Output and Diagnosis

After extraction, Hallmark populates a strict JSON-compatible schema defined in skills/hallmark/references/study.md lines 96‑138. This schema captures every datum, marks mode-conditional fields as null when unavailable, and flags unknown values using descriptive strings like "density": "unknown (URL mode)".

The system then renders a human-readable diagnosis using mode-specific templates:

• URL-mode template (lines 106‑108): Includes exact color tokens, font families, detected motion libraries, and a rhythm blind-spot notice.
• Image-mode template (lines 72‑104): Includes estimated colors, type role pairings, observed rhythm, and motion unavailability notes.

Both templates enumerate macrostructure, component archetypes, anti-patterns to avoid, and surface recommendations.

Post-Diagnosis Actions

Following a successful study, users may invoke three downstream paths:

1. Build: Feed the extracted DNA into hallmark redesign or the default generative flow.
2. Lock DNA: Emit a portable design.md file (defined in skills/hallmark/references/design-md.md) containing the structured schema for reuse.
3. Stop: Terminate the session after reviewing the diagnosis.

Emitting a design.md in URL mode requires explicit user attestation that the source is either their own property or a public reference (lines 58‑66). Image mode skips this requirement because the screenshot is user-provided content.

Key Implementation Files

File	Purpose
skills/hallmark/SKILL.md	Declares the study verb contract and references the implementation.
skills/hallmark/references/study.md	Contains the full protocol: detection logic, safety checks, five-step extraction, JSON schema, and diagnosis templates.
skills/hallmark/references/design-md.md	Defines the format for portable design.md files emitted after study completion.
site/_tests/verbs/study/diagnosis.md	Regression test fixture containing sample diagnosis output.

Usage Examples

Study a local screenshot to extract visual DNA:

// Image mode analysis
await exec(`hallmark study ./homepage-screenshot.png`);

Study a public URL to extract exact CSS and font data:

// URL mode with shallow fetch
await exec(`hallmark study https://example.com`);

Emit a portable design specification after URL analysis:

# Requires source attestation in URL mode

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

Summary

• The hallmark study verb extracts design DNA from screenshots and URLs using a dual-mode architecture defined in skills/hallmark/references/study.md.
• URL mode performs a seven-step fetch pipeline with safety checks to extract exact CSS values, font families, and motion libraries, though it cannot determine visual rhythm.
• Image mode runs a vision pass that estimates colors and infers type roles while directly observing layout rhythm, but cannot identify specific fonts or motion.
• Both modes populate a strict JSON schema (lines 96‑138) and render a human-readable diagnosis template.
• Downstream actions include building with the extracted DNA or locking it into a portable design.md file.

Frequently Asked Questions

What is the difference between URL mode and image mode in Hallmark?

URL mode fetches HTML and CSS from web addresses to extract exact design tokens like hex color values and font family names, while image mode analyzes raster screenshots through computer vision to estimate visual properties. URL mode cannot determine layout rhythm from markup alone, whereas image mode directly observes spacing and density but cannot identify specific font names or motion libraries.

How does Hallmark handle security when studying external URLs?

According to skills/hallmark/references/study.md lines 27‑50, the verb implements a defense-in-depth strategy: it maintains a refusal list for blocked domains, validates HTTPS schemes, rejects private IPs and localhost, validates redirect chains, and performs a shallow fetch that only retrieves HTML and same-origin CSS while ignoring scripts and images. All fetched content is treated as untrusted and parsed only for design facts, not executable instructions.

Why can't URL mode detect visual rhythm?

HTML markup describes semantic structure and content hierarchy, but visual rhythm—the spacing, density, and vertical cadence of a design—requires rendered viewport metrics that vary by device, browser, and CSS implementation. Because the shallow fetch in skills/hallmark/references/study.md lines 33‑34 retrieves only raw markup and stylesheets without executing layout, the system records rhythm as "unknown (URL mode)" (lines 80‑84), whereas image mode can measure rhythm directly from the rendered pixels.

What file format does the study verb emit when locking DNA?

When users choose to "lock the DNA," the verb emits a design.md file following the schema defined in skills/hallmark/references/design-md.md. This portable file contains the structured JSON design DNA extracted during the study, including macrostructure definitions, type pairings, color anchors, and component archetypes, allowing the design specification to be reused across Hallmark workflows without re-analyzing the original source.

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