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

The hallmark study command ingests either a local image file or a live web URL and outputs a standardized ten-field "DNA" object that codifies the visual grammar, enabling the Hallmark design skill to reconstruct pages with matching aesthetic logic.

Hallmark is an open-source design skill that translates visual references into structured design decisions. According to the Nutlope/hallmark repository, the study verb serves as the primary entry point for this translation process, accepting both raster image data and HTML markup and normalizing both inputs into a consistent schema used by downstream generation pipelines.

Dual-Path Input Architecture

The hallmark study verb distinguishes input types through simple path detection. When you invoke the command, the parser checks whether the argument is a filesystem path to an image or a valid HTTP URL. This bifurcation determines whether Hallmark activates its vision-model pipeline (for screenshots) or its DOM-analysis pipeline (for URLs). Both pathways converge on the same ten-field DNA structure defined in skills/hallmark/references/verbs/study.md.

# Vision-model pathway (screenshot)

hallmark study ./images/aperture-portfolio.png

# DOM-analysis pathway (live site)

hallmark study https://example.com/portfolio

Extracting DNA from Screenshots

When processing a screenshot, Hallmark treats the image as raw visual data sent directly to a vision model (the same architecture powering Claude and ChatGPT vision capabilities).

Vision Model Analysis

The vision model performs pixel-level analysis of layout composition, typographic hierarchy, color distribution, spacing rhythms, and component archetypes. Rather than returning raw pixel data, the model maps these observations onto the structured fields defined in the study protocol.

According to the test harness in site/_tests/verbs/study/diagnosis.md, a typical screenshot run on aperture-portfolio.png produces the following DNA extraction:

• Macrostructure: The high-level page layout paradigm (e.g., "Specimen")
• Hero Archetype: The specific hero section pattern (e.g., "H4 Margin-Number Display")
• Footer Archetype: Footer classification (e.g., "Ft1 Single-Line Colophon")
• Display Family: The prominent display typeface (e.g., "Fraunces italic")
• Body Family: The primary reading typeface (e.g., "Geist")

The complete extraction covers ten standardized fields that capture the "visual grammar" of the source image.

Extracting DNA from URLs

For URL inputs, Hallmark switches from computer vision to DOM inspection, fetching the target page and analyzing its markup structure.

Client-Side Fetching and Parsing

The client-side orchestration in site/js/main.js handles the HTTP request to fetch the target URL. Once retrieved, the HTML is parsed to inspect heading hierarchies, hero section semantics, navigation and footer elements, CSS typographic classes, and color token definitions.

Heuristic Mapping

A set of heuristics defined in skills/hallmark/references/study.md translates these DOM cues into the same ten-field DNA schema used for screenshots. For example, the algorithm might map a <header> with specific utility classes to a particular hero archetype, or derive surface lightness from computed background-color values. The resulting DNA object is structurally identical to vision-model extractions, ensuring pipeline compatibility.

The extracted fields are rendered for verification in site/_tests/verbs/study/output.html, demonstrating the end-to-end flow from URL to structured design data.

The Ten-Field DNA Schema

Both input methods produce a JSON-like DNA object containing these standardized fields:

{
  "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"
}

This schema captures the essential design decisions—macrostructure, hero archetype, footer archetype, display-family role, body-family role, surface lightness, accent hue, density, and type-pairing—that Hallmark uses to reconstruct pages with consistent visual grammar.

Key Implementation Files

The extraction logic spans several critical files in the Nutlope/hallmark repository:

• skills/hallmark/references/verbs/study.md: Formal specification of the study protocol and the ten DNA fields.
• site/_tests/verbs/study/diagnosis.md: Diagnostic output examples showing DNA extraction from screenshot inputs.
• site/_tests/verbs/study/output.html: Rendered demonstration of pages built from extracted DNA.
• site/js/main.js: Client-side orchestration that triggers the study verb, handles URL fetching, and displays results.

Summary

• The hallmark study verb accepts either image files or HTTP URLs as input sources.
• Screenshots are processed through a vision model that analyzes pixels to extract design patterns.
• URLs are fetched and parsed via DOM inspection with heuristics mapping markup to design fields.
• Both pathways output a standardized ten-field DNA object defined in skills/hallmark/references/verbs/study.md.
• The extracted DNA enables Hallmark to regenerate pages that match the source's visual grammar across layout, typography, and color.

Frequently Asked Questions

What is the difference between studying a screenshot versus a URL in Hallmark?

Studying a screenshot sends the image to a vision model for pixel-level analysis of visual layout, while studying a URL fetches the HTML and applies DOM heuristics to extract structural design cues. Both methods produce identical DNA structures, but screenshots capture the rendered visual state whereas URLs analyze the underlying markup and CSS.

Where is the DNA extraction logic defined in the Hallmark codebase?

The formal protocol and field definitions reside in skills/hallmark/references/verbs/study.md. The client-side implementation for URL fetching is located in site/js/main.js, and example diagnostic outputs demonstrating the extraction results are stored in site/_tests/verbs/study/diagnosis.md.

Can I customize the DNA fields that Hallmark extracts?

The current implementation uses a fixed ten-field schema specified in the study protocol. Modifying the DNA structure would require updating the protocol definition in skills/hallmark/references/verbs/study.md and adjusting both the vision model prompts (for screenshots) and the DOM heuristics (for URLs) to map extractions to your custom fields.

How does Hallmark handle URLs that require authentication?

The current client-side implementation in site/js/main.js performs standard HTTP fetches without authentication headers. URLs requiring authentication would need to be captured as screenshots first, or the fetch logic would need extension to support credential-passing mechanisms before running the hallmark study command.

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