How Hallmark Study Extracts Design DNA from Screenshots vs URLs: A Deep Dive into the CLI's Dual-Input Pipeline

hallmark study accepts either a local image file or a web-page URL, then routes each input type through a distinct extraction path—vision-model analysis for screenshots, DOM parsing for URLs—before converging both onto the same ten-field structured DNA format.

The hallmark study command is the entry point for Hallmark's design-skill system, analyzing visual references and distilling them into structured design decisions. Whether you point it at a static screenshot or a live webpage, the tool ultimately produces identical JSON-like "DNA" that drives downstream page generation. This article examines the dual-path implementation in Nutlope/hallmark, tracing how each input type is processed and where the pipelines merge.

The Ten-Field DNA Schema

Before examining the extraction paths, understand what hallmark study actually produces. Both inputs yield the same structured output covering macrostructure, hero archetype, pitch, footer, display-family role, body-family role, surface lightness, accent hue, density, and type-pairing. These ten fields are formally defined in skills/hallmark/references/verbs/study.md, which serves as the canonical protocol specification for the entire study verb.

The consistency of this schema is deliberate. By forcing screenshot and URL inputs into identical structures, Hallmark ensures that downstream generation logic—templates, component selection, styling—can operate without knowing the original source.

Extracting Design DNA from Screenshots

When you invoke hallmark study with an image path, the tool treats the input as raw visual data requiring interpretation.

Step 1: Vision Model Ingestion

The image file is sent to Hallmark's vision model—the same architecture underlying Claude and ChatGPT-Vision capabilities. This happens without intermediate DOM or markup; pixel data alone drives the analysis.

Step 2: Perceptual Feature Detection

The model directly infers layout topology, typographic relationships, color distributions, spacing rhythms, and component archetypes from the visual field. This perceptual approach captures design decisions that may not be explicitly encoded in CSS classes or HTML structure.

Step 3: Schema Mapping

The vision model's outputs are mapped onto the ten DNA fields defined in the study protocol. For example, the model might classify a hero section as "H4 Margin-Number Display" based on visual inspection of typographic scale and inset positioning.

The diagnostic test in site/_tests/verbs/study/diagnosis.md demonstrates this pipeline with a real screenshot (aperture-portfolio.png), showing the extracted DNA fields alongside their visual source.

Extracting Design DNA from URLs

URLs trigger a fundamentally different extraction strategy that substitutes structural analysis for perceptual inference.

Step 1: Client-Side Fetching

The input URL is recognized by the command parser and handed to site/js/main.js, which handles the HTTP request. This client-side orchestration retrieves the target page's raw HTML.

Step 2: DOM Inspection and Heuristic Parsing

Rather than rendering and screenshotting, Hallmark parses the HTML directly. The extraction logic inspects heading hierarchies, identifies hero section boundaries, detects navigation and footer elements, reads typographic class names, and extracts color tokens from stylesheets or inline declarations.

A dedicated heuristic layer—also specified in skills/hallmark/references/study.md—translates these structural cues into the same ten-field DNA schema. For instance, a <footer class="site-footer minimal"> combined with single-line copyright text might map to "Ft1 Single-Line Colophon."

Step 3: Pipeline Convergence

The resulting DNA object is structurally identical to screenshot-derived output. Both paths feed into the same downstream generation system, as evidenced by site/_tests/verbs/study/output.html, which renders pages from DNA regardless of source.

Pathway Comparison: Screenshots vs URLs

Dimension	Screenshot Path	URL Path
Input handler	File system read	site/js/main.js HTTP fetch
Primary analysis	Vision model pixel interpretation	DOM parsing + heuristic mapping
Information captured	Visual appearance (rendered result)	Structural intent (source markup)
Color accuracy	Perceptual ( post-compositing)	Token-based (CSS variables, hex values)
Typography detection	Inferred from rasterized glyphs	Parsed from font-family declarations
Layout analysis	Visual bounding box relationships	HTML nesting and semantic roles
Failure modes	Low-resolution inputs, complex image compression	JavaScript-dependent rendering, CORS restrictions

The dual paths exist because design intent and design execution often diverge. A URL reveals what the developer specified; a screenshot reveals what the browser rendered. Hallmark's architecture lets practitioners choose their source of truth.

Running hallmark study in Practice

Both input types use identical CLI syntax:

# Screenshot input — perceptual extraction

hallmark study ./images/aperture-portfolio.png

# URL input — structural extraction

hallmark study https://example.com/portfolio

Sample output (consistent across both paths):

{
  "macrostructure": "Specimen",
  "heroArchetype": "H4 Margin-Number Display",
  "footerArchetype": "Ft1 Single-Line Colophon",
  "displayFamily": "Fraunces italic",
  "bodyFamily": "Geist",
  "surfaceLightness": "light (~96% L)",
  "accentHue": "warm-orange ~25-30°",
  "density": "sparse",
  "typePairing": "italic-display + sans-body"
}

Key Implementation Files

Understanding the codebase requires examining these specific locations:

• skills/hallmark/references/verbs/study.md — Canonical protocol defining the ten DNA fields and extraction heuristics
• site/_tests/verbs/study/diagnosis.md — Diagnostic output example from screenshot-based extraction
• site/_tests/verbs/study/output.html — Rendered demonstration of DNA-to-page generation
• site/js/main.js — Client-side orchestration for URL fetching and result display

Summary

• hallmark study unifies dual extraction paths behind a single CLI interface, accepting either image files or web URLs
• Screenshots route through vision-model analysis in skills/hallmark/references/verbs/study.md, interpreting rendered pixels into structured DNA
• URLs route through DOM parsing in site/js/main.js, applying heuristics to map HTML structure onto identical DNA fields
• Both paths converge on a ten-field schema formalized in the study protocol, enabling consistent downstream page generation
• Input choice affects information fidelity: screenshots capture actual rendered appearance, URLs capture developer-specified intent

Frequently Asked Questions

What happens if a URL returns JavaScript-rendered content?

The URL path fetches static HTML without executing JavaScript. If critical design elements are injected post-load by frameworks like React or Vue, the DOM parser may miss them. For JS-heavy sites, capture a screenshot and use the image path instead.

Can I extract DNA from a PDF or Figma file?

Neither format is directly supported. The CLI strictly accepts image files (PNG, JPG, WebP) or HTTP/HTTPS URLs. Convert PDFs to images first; for Figma designs, export frames as PNG or publish to a shareable URL.

Why would the same page yield different DNA from screenshot vs URL?

Perceptual vs. structural analysis produces legitimate divergences. A screenshot captures computed styles, web font substitutions, and responsive breakpoints actually rendered. A URL captures source-declared values before browser interpretation. The vision model may also infer "microstructure" that explicit markup obscures.

Where is the vision model hosted?

The analysis references Hallmark's vision model but does not specify hosting in the provided source files. Based on the CLI architecture, inference likely occurs via API call rather than local execution, though site/js/main.js handles all client-side orchestration transparently.

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