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

> Learn how the Hallmark study verb extracts design DNA from screenshots and URLs. It analyzes visual grammar to codify page aesthetics for reconstruction.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/study.md).

```bash

# 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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:

```json
{
  "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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/study.md)**: Formal specification of the *study* protocol and the ten DNA fields.
- **[`site/_tests/verbs/study/diagnosis.md`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/study/diagnosis.md)**: Diagnostic output examples showing DNA extraction from screenshot inputs.
- **[`site/_tests/verbs/study/output.html`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/study/output.html)**: Rendered demonstration of pages built from extracted DNA.
- **[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/study.md). The client-side implementation for URL fetching is located in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), and example diagnostic outputs demonstrating the extraction results are stored in [`site/_tests/verbs/study/diagnosis.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.