# How Hallmark's Study Verb Extracts Design DNA from Screenshots

> Learn how Hallmark's study verb extracts design DNA from screenshots. Discover its five-step protocol for analyzing colors, typography, layout, and motion from static images.

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

---

**The `hallmark study` verb converts screenshots into structured design DNA through a five-step protocol that captures surface colors, typography roles, layout macrostructures, and motion patterns while explicitly flagging data limitations inherent to static images.**

The Hallmark study verb, documented in [[`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), serves as a diagnostic engine within the Nutlope/hallmark repository that transforms visual references into reusable design specifications. Unlike pixel-copying tools, this verb extracts structural fingerprints—macrostructures, archetype knobs, and color bands—that enable systematic recreation of design systems without infringing on original assets.

## Source Mode Detection

The verb first determines whether it operates in **image mode** or **URL mode**. Any input that is not a valid URL defaults to image mode, triggering the screenshot analysis pathway. This detection logic ensures that static images receive appropriate handling constraints, as documented in the source mode section of [[`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md).

## The Five-Step Extraction Protocol

When operating in image mode, the verb executes a vision pass that follows the same schema as URL mode but acknowledges specific knowledge limitations. The protocol systematically analyzes five design dimensions.

### Step 1 — Surface Analysis

The verb estimates **colour bands** including paper darkness, base hue, accent hue, and accent footprint. It identifies distinctive surface treatments such as grain textures or glassmorphism effects. These values are extracted from the visual pixels but translated into semantic tokens rather than raw color values.

### Step 2 — Typography Extraction

Because screenshots cannot reliably reveal exact font files, the verb records **type roles** rather than specific typefaces. For example, it might identify an "italic editorial serif" for headlines or "neutral grotesque" for body text. Based on these roles, it proposes one to two candidate fonts from the Hallmark canon, such as Instrument Serif or Tobias, as defined in the type analysis section of [[`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md).

### Step 3 — Structure Mapping

The verb maps visible regions to one of twenty-one named **macrostructures** enumerated in [[`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). It assigns **archetype knobs**—parameterized configurations like "H2-Split → ratio=7/5"—drawn from the [[`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md). This structural fingerprint defines the layout's skeletal framework independent of specific content.

### Step 4 — Motion Detection

Static screenshots cannot display animation, so the verb explicitly records "motion not visible – assuming default reveals." This placeholder acknowledges the limitation while providing a sensible default for subsequent build phases.

### Step 5 — Rhythm Assessment

Rhythm represents a gestalt judgment requiring temporal or interactive observation. The verb marks rhythm as **unknown** and flags this limitation in the output schema, preventing false confidence in the extracted DNA.

## Structured Schema and Diagnosis Report

After completing the five passes, the verb populates a JSON-like schema where every field is required. Fields that cannot be determined in image mode receive `"unknown"` or null values, as specified in the structured fields section of [[`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md).

The extracted schema renders into a concise human-readable report using the image-mode template. This diagnosis lists:

- Identified macrostructure and archetype knobs
- Type roles and font candidates
- Colour bands and accent footprint
- Distinctive surface treatments
- Detected anti-patterns (referenced from [[`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md))

## From Diagnosis to Implementation

The study verb offers three hand-off paths after generating the diagnosis:

1. **Build directly**: Invoke the default verb to construct a page using the extracted DNA
2. **Emit design.md**: Generate a portable specification file by issuing the `lock the DNA` command, which writes [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) to the project root per the format in [[`design-md.md`](https://github.com/Nutlope/hallmark/blob/main/design-md.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md)
3. **Terminate**: Stop after receiving the diagnosis for manual review

The portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file contains the complete DNA—macrostructure, tokens, system block, and provenance—enabling version control and sharing of design specifications.

## Code Examples

Run the study verb against a screenshot:

```bash
hallmark study screenshot.png

```

*Sample output:*

```

You sent me a Split Studio.

The hero is an H2-Split … …
The type pairing is italic editorial serif with neutral grotesque body, monospace for labels.
I won't try to identify exact typefaces from a screenshot — fonts to consider:
Instrument Serif, Tobias.
The surface is warm cream … The accent is neutral ….
...
Want me to build with this DNA, or change one axis first?

```

To persist the extracted DNA as a portable specification:

```bash
hallmark study screenshot.png

# After the diagnosis appears, type:

lock the DNA

```

This command generates a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file at the project root containing the structured design DNA.

To build a new page using the studied DNA:

```bash
hallmark default --use-study-dna

```

The default verb reads the previously generated [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (or in-memory schema) and constructs a page inheriting the colour bands, type roles, macrostructure, and archetype knobs identified during the study.

## Summary

- The `hallmark study` verb operates in **image mode** for screenshots, defaulting to this state when input is not a URL.
- It extracts design DNA through a **five-step protocol**: Surface, Type, Structure, Motion, and Rhythm, with explicit handling for data unavailable in static images.
- **Type analysis** records semantic roles (e.g., "italic editorial serif") rather than exact font files, proposing candidates from the Hallmark canon.
- **Structure mapping** identifies one of 21 macrostructures and assigns archetype knobs from the component cookbook.
- The output follows a **structured schema** documented in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md), rendering as both machine-readable JSON and human-readable diagnosis reports.
- Users can **hand off** results to the build system, export a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file, or terminate after diagnosis.

## Frequently Asked Questions

### What is the difference between image mode and URL mode in Hallmark's study verb?

**Image mode** processes static screenshots with acknowledged limitations—motion and rhythm are marked unknown, and fonts are inferred as roles rather than specific files. **URL mode** analyzes live pages where the verb can inspect DOM structure, detect actual font files, and observe motion behaviors. The verb automatically selects image mode when the input lacks a URL protocol prefix.

### Why can't the study verb identify exact font names from screenshots?

Screenshots render typography as rasterized pixels without embedded font metadata. While computer vision can classify visual characteristics (serif, weight, contrast), it cannot reliably distinguish between visually similar font files (e.g., Helvetica vs. Arial). Consequently, [[`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) mandates that the verb record **type roles** (descriptive categories) and suggest 1-2 candidates from the Hallmark font canon rather than asserting specific font identities.

### What are macrostructures in Hallmark's design DNA extraction?

Macrostructures are the twenty-one named layout archetypes defined in [[`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) that describe high-level page organization—such as "Split Studio," "Editorial Flow," or "Dashboard Grid." During the structure step, the study verb maps screenshot regions to these patterns and assigns **archetype knobs** (parameterized ratios, spacing values) from [[`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md), creating a reproducible layout framework.

### How do I convert a study diagnosis into a working webpage?

After running `hallmark study screenshot.png`, you have three options: type `lock the DNA` to generate a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) specification file, allow the system to automatically hand off to the default build verb, or manually invoke `hallmark default --use-study-dna`. The build process reads the extracted DNA—colour bands, type roles, macrostructure, and archetype knobs—to generate a new page that inherits the studied design characteristics without copying original pixels.