# How to Use the `hallmark study` Command to Extract Design DNA

> Learn to use the hallmark study command to extract design DNA from screenshots or URLs. Analyze macrostructure, components, typography, and colors with this five-step pipeline.

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

---

**The `hallmark study` command converts screenshots or live URLs into structured "design DNA" through a deterministic five-step pipeline that analyzes macrostructure, component archetypes, type pairings, and color systems.**

The `hallmark study` command is the core design intelligence engine in the [Nutlope/hallmark](https://github.com/Nutlope/hallmark) repository. Unlike traditional design tools that require manual documentation, this verb automates **reverse-engineering of visual design systems** into machine-readable specifications. Whether you're analyzing a competitor's landing page or archiving your own work, the command produces structured data that downstream Hallmark verbs consume directly.

## How `hallmark study` Detects Your Input Mode

The command begins with **automatic detection** based on input prefix analysis, as defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md):

- **URL mode**: Triggered by `http://` or `https://` prefixes
- **Image mode**: Triggered by file paths ending in raster extensions (`.png`, `.jpg`, `.webp`)

```bash

# URL mode — fetches live HTML/CSS for exact values

hallmark study https://example.com/awesome-landing

# Image mode — runs vision analysis for structural patterns

hallmark study path/to/screenshot.png

```

URL mode provides **complete DNA coverage** including exact font names and computed color values. Image mode extracts macrostructure and visual rhythm but leaves font fields null since raster data cannot reliably identify typefaces.

## Safety and Refusal Checks

Before any data acquisition, the command executes **refusal heuristics** documented in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md). These protect against unauthorized extraction:

- **Blocked domains**: Paid template marketplaces (`themeforest.net/*`, etc.) are automatically refused
- **Auth-walled content**: Pages requiring authentication trigger fallback to image mode
- **SPA shell detection**: Empty JavaScript-rendered containers prompt screenshot request

The **Remote-URL Safety** check also runs in URL mode to verify the target permits scraping. When any check fails, the verb gracefully degrades to asking for a manual screenshot instead.

## The Five-Stage Extraction Pipeline

### Stage 1: Data Acquisition

URL mode performs a **shallow WebFetch** that retrieves:
- Raw HTML document
- Linked CSS files (stylesheets, `<style>` blocks, inline styles)

Image mode runs a **vision-pass** using a pre-trained image analysis model that populates structural fields without text parsing.

### Stage 2: Schema Population

Extracted facts flow into a **fixed 10-field schema** defined in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md):

| Field | Description | URL Mode | Image Mode |
|-------|-------------|----------|------------|
| `macrostructure` | Layout paradigm (Portfolio-grid, Editorial-flow, etc.) | ✅ | ✅ |
| `archetypes` | Recurring component types (Header, Card, Hero, Footer) | ✅ | ✅ |
| `display_face` | Heading typeface name | ✅ | null |
| `body_face` | Paragraph typeface name | ✅ | null |
| `paper_value` | Background/base color | ✅ | ✅* |
| `accent_value` | Primary interactive color | ✅ | ✅* |
| `motion_library` | Animation approach (Minimal, Rich, None) | ✅ | ✅ |
| `type_scale` | Modular scale ratio | ✅ | null |
| `grid_unit` | Base spacing grid | ✅ | null |
| `rhythm` | Visual pacing density | ✅ | ✅ |

\* Color values in image mode are approximated via pixel sampling rather than computed CSS.

### Stage 3: DNA Synthesis

The populated schema is **collapsed into design DNA** — a compressed, deterministic representation of the visual system's intent rather than its implementation details.

### Stage 4: Diagnosis Report

A human-readable markdown report generates automatically, following the format in [`site/_tests/verbs/study/diagnosis.md`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/study/diagnosis.md):

```

macrostructure: Portfolio-grid
archetypes: Header, Hero, Card-grid, Footer
type-pairing: Inter × JetBrains Mono
colour anchor: OKLCH h 210 c 0.15
motion-library: Minimal-scroll-reveal
anti-patterns: Avoid card shadows on dark mode

```

The report explicitly flags **anti-patterns to avoid** when rebuilding with this DNA.

### Stage 5: Optional Hand-off

After diagnosis, three paths emerge:

1. **Immediate rebuild**: `hallmark redesign` consumes the DNA in-memory
2. **DNA locking**: Emit a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) specification
3. **Stamped output**: CSS includes `/* Hallmark · macrostructure: ... */` comment for future detection

URL mode requires **attestation** ("Is this your own work or a public reference?") before emitting [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), as documented in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md).

## Working with Extracted Design DNA

### Rebuilding from Study Results

```bash

# Run study, then immediately rebuild

hallmark study https://example.com/awesome-landing

# ... diagnosis displays ...

hallmark redesign  # Uses extracted DNA from previous step

```

The `redesign` verb rehydrates the DNA without re-analyzing the source, enabling rapid iteration.

### Creating Portable Design Specifications

```bash

# Request explicit design.md emission after study

hallmark study https://example.com/awesome-landing

# User replies: "lock the DNA" or "give me a design.md"

```

The emitted file follows the specification in [`references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/references/design-md.md) and contains:

```markdown
---
hallmark-version: 0.1.0
dna-source: study
extraction-date: 2024-01-15
---

## Design DNA

- **macrostructure**: Editorial-flow
- **archetypes**: Hero-asymmetric, Pull-quote, Chapter-divider
- **type-pairing**: Source Serif 4 × Source Sans 3
- **colour-system**: OKLCH warm-neutral with indigo accent
- **motion**: Scroll-driven parallax, minimal hover

```

This portable format lets other AI tools or future Hallmark sessions import the design system without re-running extraction.

## Key Architectural Decisions

**Dual-mode parity with graceful degradation** — The same schema serves both image and URL inputs, ensuring downstream verbs receive predictable data structures regardless of source fidelity.

**Deterministic over creative** — The DNA extraction intentionally strips aesthetic opinion, capturing only reproducible system properties. This prevents "hallucinated" design choices during rebuilds.

**Stamping for idempotency** — The output CSS comment (`/* Hallmark · ... */`) recorded in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) enables future `hallmark study` runs to recognize their own DNA and avoid circular re-interpretation.

## Summary

- **Automatic detection** routes inputs to URL mode (precise) or image mode (structural)
- **Refusal heuristics** block paid templates and auth-walled content automatically
- **10-field schema** captures macrostructure, archetypes, typography, color, and motion
- **Diagnosis reports** present DNA in human-readable markdown with anti-pattern warnings
- **Portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)** emission enables cross-tool reuse with URL-mode attestation
- **Stamped CSS output** prevents duplicate processing in future pipeline runs

## Frequently Asked Questions

### What is "design DNA" in Hallmark?

Design DNA is a **structured, 10-field specification** that distills a visual design system into machine-readable properties including layout paradigm, component archetypes, type pairings, color anchors, and motion approaches. Unlike raw CSS or design files, DNA captures **abstract intent** that Hallmark verbs can reconstruct into new implementations without copying specific pixels or proprietary assets.

### Why does URL mode ask "Is this your own work?"

The **attestation step** in URL mode protects against inadvertent extraction of copyrighted commercial designs. Per [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md), Hallmark blocks known template marketplaces at the refusal stage, but user-hosted sites require explicit confirmation of ownership or public-reference status before emitting a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md). Image mode bypasses this check since screenshots already imply user possession.

### Can I study a design without rebuilding immediately?

Yes. After the diagnosis report displays, simply request **"lock the DNA"** or **"give me a design.md"** instead of running `hallmark redesign`. The emitted [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file persists the extraction for later use, and you can rebuild anytime with `hallmark redesign --from design.md` or import the specification into other tools that support the format documented in [`references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/references/design-md.md).

### Why are fonts null in image mode?

Raster images lack **embedded font metadata** — pixels cannot reliably identify typeface names, weights, or foundry information. The vision-pass model detects typographic hierarchy (display vs. body roles) and measures relative sizing, but cannot name specific fonts. URL mode extracts exact font-family declarations from CSS, making it the preferred mode when precise type specifications matter for your design DNA.