How the Hallmark Study Verb Extracts Design DNA from Screenshots and URLs

The hallmark study command ingests visual references through either image pixel analysis or HTML DOM parsing to produce a structured "design DNA" object containing ten standardized fields that encode layout, typography, and color decisions.

The hallmark study verb serves as the primary entry point in the Nutlope/hallmark repository for reverse-engineering design systems. Whether you provide a static screenshot or a live URL, the tool digests the visual input and distills it into a structured set of design decisions—referred to as the DNA—that powers Hallmark's page generation engine.

Dual Input Pathways for DNA Extraction

The hallmark study verb extract DNA through two distinct technical pipelines that converge on an identical data schema.

Screenshot Analysis via Vision Model

When you invoke hallmark study with an image file, the system treats the input as raw pixel data. According to the study protocol defined in skills/hallmark/references/verbs/study.md, the image is sent to a vision model (the same architecture that powers Claude and ChatGPT vision capabilities) that analyzes layout, typography, color, spacing, and component archetypes directly from the pixels.

The model maps these visual properties onto ten standardized fields: macrostructure, hero archetype, pitch, footer, display-family role, body-family role, surface lightness, accent hue, density, and type-pairing. The test harness in site/_tests/verbs/study/diagnosis.md demonstrates this pipeline using aperture-portfolio.png, showing how the vision model extracts structural DNA without accessing underlying HTML or CSS.

URL Analysis via DOM Inspection

For web-based references, hallmark study accepts a URL argument and triggers client-side fetching logic implemented in site/js/main.js. The system executes an HTTP request to retrieve the target page's HTML, then parses the DOM to identify structural cues including heading hierarchies, hero sections, navigation patterns, typographic classes, and color tokens.

Rather than using computer vision, this pathway applies a set of heuristics defined in the study protocol to map DOM elements onto the same ten-field DNA schema used for screenshots. The extracted fields are then serialized into the identical JSON structure, ensuring pipeline compatibility regardless of whether the input originated from a static image or a live website.

The Standardized DNA Schema

Both extraction methods produce a unified "design DNA" object that captures the essential genetic code of a visual system. The structured output includes:

• macrostructure: The overall page architecture classification (e.g., "Specimen")
• heroArchetype: The hero section pattern (e.g., "H4 Margin-Number Display")
• pitch: The value proposition presentation style
• footerArchetype: The footer layout pattern (e.g., "Ft1 Single-Line Colophon")
• displayFamily: The display typeface role (e.g., "Fraunces italic")
• bodyFamily: The body text typeface (e.g., "Geist")
• surfaceLightness: Background luminosity values (e.g., "light (~96% L)")
• accentHue: Primary accent color angle (e.g., "warm-orange ~25-30°")
• density: Information density classification (e.g., "sparse")
• typePairing: The font relationship strategy (e.g., "italic-display + sans-body")

This schema enables Hallmark to reconstruct pages with consistent visual grammar using the downstream generation pipeline demonstrated in site/_tests/verbs/study/output.html.

Practical Usage Examples

Extracting design DNA requires only a single command followed by either a filesystem path or web address.

Analyze a local screenshot file:

hallmark study ./images/aperture-portfolio.png

Analyze a live web page:

hallmark study https://example.com/portfolio

Both commands return a JSON-like DNA object. You can inspect the rendered reconstruction of this data in site/_tests/verbs/study/output.html, which validates the end-to-end flow from input extraction to page generation.

Summary

• The hallmark study verb supports dual input methods: screenshot files and web page URLs.
• Screenshots are processed by a vision model that analyzes pixels directly to extract visual properties and component archetypes.
• URLs are fetched via site/js/main.js and parsed using DOM heuristics to identify structural and typographic patterns.
• Both pathways produce identical design DNA containing ten standardized fields defined in skills/hallmark/references/verbs/study.md.
• The resulting DNA serves as the structured input for Hallmark's design-generation engine, enabling reconstruction of the original visual grammar.

Frequently Asked Questions

What is the difference between screenshot and URL extraction in Hallmark?

Screenshot extraction uses a vision model to analyze raw pixels, making it ideal for capturing design intent from static images or mockups without underlying code. URL extraction parses the actual HTML and CSS through DOM inspection, making it better suited for analyzing live implementations and existing web architectures. Both methods output the same standardized DNA format defined in the study protocol.

Where is the study protocol defined in the Hallmark repository?

The formal specification for the ten-field DNA schema and extraction logic resides in skills/hallmark/references/verbs/study.md. This document defines how both vision model outputs and DOM parsing results map to specific design tokens, ensuring consistent DNA generation across input types.

Can I use hallmark study on any image format?

The command accepts standard image files as demonstrated in site/_tests/verbs/study/diagnosis.md, which processes a PNG file (aperture-portfolio.png). The vision model processes pixel data regardless of specific image format, provided the file contains readable visual information suitable for analysis.

How does the URL extraction handle dynamic content?

The URL fetching logic in site/js/main.js handles the initial HTTP request and HTML retrieval. The extraction relies on parsing the static DOM structure for typographic classes, color tokens, and layout hierarchies. Complex single-page applications requiring JavaScript execution for full rendering may depend on the specific implementation details of the fetching mechanism.

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