How the `hallmark study` Command Extracts Design DNA: A 5-Step Pipeline Explained

The hallmark study command extracts design DNA through a deterministic five-step pipeline that converts visual inputs—screenshots or live URLs—into a structured schema describing macrostructure, component archetypes, typography, color, and motion.

This design-DNA extractor powers the Hallmark CLI's ability to analyze existing interfaces and rebuild them without copying pixels. Whether you're studying a competitor's landing page or archiving your own design system, the command collapses visual complexity into portable, reusable data. Below is the complete architectural breakdown as implemented in skills/hallmark/SKILL.md and skills/hallmark/references/study.md.

---

Step 1: Input Detection (Image vs. URL Mode)

The pipeline begins with automatic input detection. The command inspects the input string for http:// or https:// prefixes to branch between two acquisition paths:

• Image mode: Local raster files (PNG, JPG, WebP) processed through vision analysis
• URL mode: Live web pages fetched and parsed for exact CSS values

This detection logic is defined in SKILL.md where it states: "Detection is automatic based on the input prefix."

# Image mode – analyze a screenshot

hallmark study ./reference-screenshot.png

# URL mode – analyze a live page

hallmark study https://example.com/portfolio

---

Step 2: Refusal and Safety Checks

Before any data extraction, the command runs refusal heuristics to prevent unauthorized scraping. The safety layer includes:

• Domain blocklists (e.g., themeforest.net/* for paid templates)
• Authentication-wall detection
• SPA shell detection (pages without rendered content)
• Remote-URL safety verification in URL mode

If a URL fails safety checks, the verb falls back to requesting a screenshot rather than proceeding. This refusal-or-proceed check is documented in references/study.md under the "Refuse-or-proceed check" section.

---

Step 3: Data Acquisition

The acquisition strategy diverges based on the mode detected in Step 1:

Image Mode: Vision Pass

A pre-trained image-analysis model populates the structured-fields schema from visual cues. Font-related fields remain null since raster images cannot reliably convey exact typeface names.

URL Mode: WebFetch Parsing

A shallow WebFetch retrieves the page's HTML and linked CSS files. The parser extracts:

• Exact font-family declarations
• Precise color values (hex, RGB, OKLCH)
• Layout and spacing tokens
• Motion/animation references

As noted in references/study.md: "URL mode reads the page's HTML and CSS via WebFetch" while "Vision pass" handles image mode through computer vision.

---

Step 4: Structured-Fields Schema

All extracted data normalizes into a fixed 10-field schema that forms the canonical design DNA:

Field	Description
macrostructure	High-level layout pattern (e.g., "Portfolio-grid", "Hero–Features–Social-proof")
archetypes	Recurring component types (Header, Card, Footer, CTA-block)
display_face	Primary display typeface (URL mode only)
body_face	Body text typeface (URL mode only)
paper_value	Background/neutral color anchor
accent_value	Primary action/highlight color
motion_library	Animation style (minimal, playful, cinematic)
rhythm	Visual pacing detected in image mode
density	Information compactness
attestation	Source ownership verification (URL mode)

The schema output is defined in references/study.md under "The structured-fields schema." URL mode populates all fields; image mode leaves display_face and body_face as null.

---

Step 5: Diagnosis Report Generation

The extracted DNA renders into a human-readable markdown report summarizing the design system's key decisions. A typical diagnosis reads:

macrostructure: Portfolio-grid
archetypes: Header, Card, Footer
type-pairing: Inter × JetBrains Mono
colour anchor: OKLCH h 210 c 0.12
motion library: minimal

The report also flags anti-patterns to avoid during reconstruction—preserving not just what works but what shouldn't be replicated. This format targets the "Diagnosis report" specification in references/study.md.

---

Optional: DNA Locking and Portable Export

After diagnosis, users have two hand-off paths:

Rebuild immediately with hallmark redesign, which consumes the extracted DNA to generate new implementation code.

Emit a portable design.md specification for reuse across projects. URL mode requires an attestation step—confirming the source is your own work or a public reference—before writing the file. This emission protocol is documented in references/study.md under "Emitting a design.md from study."

# After study diagnosis, request the portable spec

> lock the DNA

# or

> give me a design.md

---

Output Stamping for Traceability

All generated CSS or inline <style> blocks begin with a DNA stamp comment:

/* Hallmark · macrostructure: Portfolio-grid · archetypes: Header,Card,Footer · type-pairing:Inter×Mono */

This stamp, defined in SKILL.md under "Stamp the output," enables future Hallmark runs to detect that a study-DNA system is already in place—preventing redundant theme rotation and preserving design continuity.

---

Summary

• Dual-mode extraction: The same verb handles raster images and live HTML/CSS through unified detection logic in SKILL.md
• Safety-first architecture: Refusal heuristics and attestation requirements prevent unauthorized template scraping
• Deterministic schema: 10 fixed fields collapse visual design into reproducible data structures
• Downstream integration: Extracted DNA feeds directly into hallmark redesign or portable design.md specifications
• Traceability: Output stamping ensures future runs recognize existing DNA systems

---

Frequently Asked Questions

What is design DNA in Hallmark's terminology?

Design DNA is the structured abstraction of a visual interface—not pixels or code, but the underlying decisions that define it. According to the Hallmark source code, this includes macrostructure (layout patterns), component archetypes, typography pairing, color anchors, and motion characteristics. The hallmark study command extracts this DNA into a 10-field schema that other verbs can reconstruct without copying the original assets.

Why can't image mode extract exact font names?

Raster images lack embedded font metadata. While computer vision can detect typographic characteristics (serif vs. sans-serif, weight, relative sizing), it cannot reliably identify precise font-family declarations. URL mode solves this by parsing actual CSS font-family rules from the live page's stylesheets—hence why display_face and body_face remain null in image mode outputs.

What happens if I try to study a paid template site?

The command refuses the request. The refusal heuristics in references/study.md explicitly block domains like themeforest.net/* and detect authentication walls. If URL mode triggers a refusal, Hallmark falls back to asking for a screenshot—shifting to image mode where the same visual analysis proceeds without direct HTML/CSS access.

Can I use extracted DNA for commercial projects?

Only with proper attestation. When emitting a design.md from URL mode, Hallmark requires you to confirm the source is either your own work or a public reference. This extra verification step, documented in references/study.md, ensures compliance with copyright restrictions before the DNA becomes portable across projects.

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