How to Use the `hallmark study` Command to Extract Design DNA

The hallmark study command converts screenshots or live URLs into structured "design DNA" through a deterministic five-step pipeline that analyzes macrostructure, component archetypes, type pairings, and color systems.

The hallmark study command is the core design intelligence engine in the Nutlope/hallmark repository. Unlike traditional design tools that require manual documentation, this verb automates reverse-engineering of visual design systems into machine-readable specifications. Whether you're analyzing a competitor's landing page or archiving your own work, the command produces structured data that downstream Hallmark verbs consume directly.

How hallmark study Detects Your Input Mode

The command begins with automatic detection based on input prefix analysis, as defined in skills/hallmark/SKILL.md:

• URL mode: Triggered by http:// or https:// prefixes
• Image mode: Triggered by file paths ending in raster extensions (.png, .jpg, .webp)

# URL mode — fetches live HTML/CSS for exact values

hallmark study https://example.com/awesome-landing

# Image mode — runs vision analysis for structural patterns

hallmark study path/to/screenshot.png

URL mode provides complete DNA coverage including exact font names and computed color values. Image mode extracts macrostructure and visual rhythm but leaves font fields null since raster data cannot reliably identify typefaces.

Safety and Refusal Checks

Before any data acquisition, the command executes refusal heuristics documented in references/study.md. These protect against unauthorized extraction:

• Blocked domains: Paid template marketplaces (themeforest.net/*, etc.) are automatically refused
• Auth-walled content: Pages requiring authentication trigger fallback to image mode
• SPA shell detection: Empty JavaScript-rendered containers prompt screenshot request

The Remote-URL Safety check also runs in URL mode to verify the target permits scraping. When any check fails, the verb gracefully degrades to asking for a manual screenshot instead.

The Five-Stage Extraction Pipeline

Stage 1: Data Acquisition

URL mode performs a shallow WebFetch that retrieves:

• Raw HTML document
• Linked CSS files (stylesheets, <style> blocks, inline styles)

Image mode runs a vision-pass using a pre-trained image analysis model that populates structural fields without text parsing.

Stage 2: Schema Population

Extracted facts flow into a fixed 10-field schema defined in references/study.md:

Field	Description	URL Mode	Image Mode
macrostructure	Layout paradigm (Portfolio-grid, Editorial-flow, etc.)	✅	✅
archetypes	Recurring component types (Header, Card, Hero, Footer)	✅	✅
display_face	Heading typeface name	✅	null
body_face	Paragraph typeface name	✅	null
paper_value	Background/base color	✅	✅*
accent_value	Primary interactive color	✅	✅*
motion_library	Animation approach (Minimal, Rich, None)	✅	✅
type_scale	Modular scale ratio	✅	null
grid_unit	Base spacing grid	✅	null
rhythm	Visual pacing density	✅	✅

* Color values in image mode are approximated via pixel sampling rather than computed CSS.

Stage 3: DNA Synthesis

The populated schema is collapsed into design DNA — a compressed, deterministic representation of the visual system's intent rather than its implementation details.

Stage 4: Diagnosis Report

A human-readable markdown report generates automatically, following the format in site/_tests/verbs/study/diagnosis.md:

macrostructure: Portfolio-grid
archetypes: Header, Hero, Card-grid, Footer
type-pairing: Inter × JetBrains Mono
colour anchor: OKLCH h 210 c 0.15
motion-library: Minimal-scroll-reveal
anti-patterns: Avoid card shadows on dark mode

The report explicitly flags anti-patterns to avoid when rebuilding with this DNA.

Stage 5: Optional Hand-off

After diagnosis, three paths emerge:

1. Immediate rebuild: hallmark redesign consumes the DNA in-memory
2. DNA locking: Emit a portable design.md specification
3. Stamped output: CSS includes /* Hallmark · macrostructure: ... */ comment for future detection

URL mode requires attestation ("Is this your own work or a public reference?") before emitting design.md, as documented in references/study.md.

Working with Extracted Design DNA

Rebuilding from Study Results

# Run study, then immediately rebuild

hallmark study https://example.com/awesome-landing

# ... diagnosis displays ...

hallmark redesign  # Uses extracted DNA from previous step

The redesign verb rehydrates the DNA without re-analyzing the source, enabling rapid iteration.

Creating Portable Design Specifications

# Request explicit design.md emission after study

hallmark study https://example.com/awesome-landing

# User replies: "lock the DNA" or "give me a design.md"

The emitted file follows the specification in references/design-md.md and contains:

---
hallmark-version: 0.1.0
dna-source: study
extraction-date: 2024-01-15
---

## Design DNA

- **macrostructure**: Editorial-flow
- **archetypes**: Hero-asymmetric, Pull-quote, Chapter-divider
- **type-pairing**: Source Serif 4 × Source Sans 3
- **colour-system**: OKLCH warm-neutral with indigo accent
- **motion**: Scroll-driven parallax, minimal hover

This portable format lets other AI tools or future Hallmark sessions import the design system without re-running extraction.

Key Architectural Decisions

Dual-mode parity with graceful degradation — The same schema serves both image and URL inputs, ensuring downstream verbs receive predictable data structures regardless of source fidelity.

Deterministic over creative — The DNA extraction intentionally strips aesthetic opinion, capturing only reproducible system properties. This prevents "hallucinated" design choices during rebuilds.

Stamping for idempotency — The output CSS comment (/* Hallmark · ... */) recorded in SKILL.md enables future hallmark study runs to recognize their own DNA and avoid circular re-interpretation.

Summary

• Automatic detection routes inputs to URL mode (precise) or image mode (structural)
• Refusal heuristics block paid templates and auth-walled content automatically
• 10-field schema captures macrostructure, archetypes, typography, color, and motion
• Diagnosis reports present DNA in human-readable markdown with anti-pattern warnings
• Portable design.md emission enables cross-tool reuse with URL-mode attestation
• Stamped CSS output prevents duplicate processing in future pipeline runs

Frequently Asked Questions

What is "design DNA" in Hallmark?

Design DNA is a structured, 10-field specification that distills a visual design system into machine-readable properties including layout paradigm, component archetypes, type pairings, color anchors, and motion approaches. Unlike raw CSS or design files, DNA captures abstract intent that Hallmark verbs can reconstruct into new implementations without copying specific pixels or proprietary assets.

Why does URL mode ask "Is this your own work?"

The attestation step in URL mode protects against inadvertent extraction of copyrighted commercial designs. Per references/study.md, Hallmark blocks known template marketplaces at the refusal stage, but user-hosted sites require explicit confirmation of ownership or public-reference status before emitting a portable design.md. Image mode bypasses this check since screenshots already imply user possession.

Can I study a design without rebuilding immediately?

Yes. After the diagnosis report displays, simply request "lock the DNA" or "give me a design.md" instead of running hallmark redesign. The emitted design.md file persists the extraction for later use, and you can rebuild anytime with hallmark redesign --from design.md or import the specification into other tools that support the format documented in references/design-md.md.

Why are fonts null in image mode?

Raster images lack embedded font metadata — pixels cannot reliably identify typeface names, weights, or foundry information. The vision-pass model detects typographic hierarchy (display vs. body roles) and measures relative sizing, but cannot name specific fonts. URL mode extracts exact font-family declarations from CSS, making it the preferred mode when precise type specifications matter for your design DNA.

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