# How the `hallmark study` Command Extracts Design DNA: A 5-Step Pipeline Explained

> Discover how the hallmark study command extracts design DNA. Explore the 5-step pipeline that transforms visuals into a structured schema covering macrostructure, typography, color, and motion.

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

---

**The `hallmark study` command extracts design DNA through a deterministic five-step pipeline that converts visual inputs—screenshots or live URLs—into a structured schema describing macrostructure, component archetypes, typography, color, and motion.**

This design-DNA extractor powers the Hallmark CLI's ability to analyze existing interfaces and rebuild them without copying pixels. Whether you're studying a competitor's landing page or archiving your own design system, the command collapses visual complexity into portable, reusable data. Below is the complete architectural breakdown as implemented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md).

---

## Step 1: Input Detection (Image vs. URL Mode)

The pipeline begins with automatic **input detection**. The command inspects the input string for `http://` or `https://` prefixes to branch between two acquisition paths:

- **Image mode**: Local raster files (PNG, JPG, WebP) processed through vision analysis
- **URL mode**: Live web pages fetched and parsed for exact CSS values

This detection logic is defined in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) where it states: *"Detection is automatic based on the input prefix."*

```bash

# Image mode – analyze a screenshot

hallmark study ./reference-screenshot.png

# URL mode – analyze a live page

hallmark study https://example.com/portfolio

```

---

## Step 2: Refusal and Safety Checks

Before any data extraction, the command runs **refusal heuristics** to prevent unauthorized scraping. The safety layer includes:

- Domain blocklists (e.g., `themeforest.net/*` for paid templates)
- Authentication-wall detection
- SPA shell detection (pages without rendered content)
- Remote-URL safety verification in URL mode

If a URL fails safety checks, the verb **falls back to requesting a screenshot** rather than proceeding. This refusal-or-proceed check is documented in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md) under the "Refuse-or-proceed check" section.

---

## Step 3: Data Acquisition

The acquisition strategy diverges based on the mode detected in Step 1:

### Image Mode: Vision Pass

A pre-trained image-analysis model populates the structured-fields schema from visual cues. Font-related fields remain `null` since raster images cannot reliably convey exact typeface names.

### URL Mode: WebFetch Parsing

A shallow **WebFetch** retrieves the page's HTML and linked CSS files. The parser extracts:

- Exact font-family declarations
- Precise color values (hex, RGB, OKLCH)
- Layout and spacing tokens
- Motion/animation references

As noted in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md): *"URL mode reads the page's HTML and CSS via WebFetch"* while *"Vision pass"* handles image mode through computer vision.

---

## Step 4: Structured-Fields Schema

All extracted data normalizes into a **fixed 10-field schema** that forms the canonical design DNA:

| Field | Description |
|-------|-------------|
| `macrostructure` | High-level layout pattern (e.g., "Portfolio-grid", "Hero–Features–Social-proof") |
| `archetypes` | Recurring component types (Header, Card, Footer, CTA-block) |
| `display_face` | Primary display typeface (URL mode only) |
| `body_face` | Body text typeface (URL mode only) |
| `paper_value` | Background/neutral color anchor |
| `accent_value` | Primary action/highlight color |
| `motion_library` | Animation style (minimal, playful, cinematic) |
| `rhythm` | Visual pacing detected in image mode |
| `density` | Information compactness |
| `attestation` | Source ownership verification (URL mode) |

The schema output is defined in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md) under "The structured-fields schema." URL mode populates all fields; image mode leaves `display_face` and `body_face` as `null`.

---

## Step 5: Diagnosis Report Generation

The extracted DNA renders into a **human-readable markdown report** summarizing the design system's key decisions. A typical diagnosis reads:

```

macrostructure: Portfolio-grid
archetypes: Header, Card, Footer
type-pairing: Inter × JetBrains Mono
colour anchor: OKLCH h 210 c 0.12
motion library: minimal

```

The report also flags **anti-patterns to avoid** during reconstruction—preserving not just what works but what shouldn't be replicated. This format targets the "Diagnosis report" specification in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md).

---

## Optional: DNA Locking and Portable Export

After diagnosis, users have two hand-off paths:

**Rebuild immediately** with `hallmark redesign`, which consumes the extracted DNA to generate new implementation code.

**Emit a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)** specification for reuse across projects. URL mode requires an **attestation step**—confirming the source is your own work or a public reference—before writing the file. This emission protocol is documented in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md) under "Emitting a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) from study."

```bash

# After study diagnosis, request the portable spec

> lock the DNA

# or

> give me a design.md

```

---

## Output Stamping for Traceability

All generated CSS or inline `<style>` blocks begin with a **DNA stamp comment**:

```css
/* Hallmark · macrostructure: Portfolio-grid · archetypes: Header,Card,Footer · type-pairing:Inter×Mono */

```

This stamp, defined in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) under "Stamp the output," enables future Hallmark runs to detect that a study-DNA system is already in place—preventing redundant theme rotation and preserving design continuity.

---

## Summary

- **Dual-mode extraction**: The same verb handles raster images and live HTML/CSS through unified detection logic in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)
- **Safety-first architecture**: Refusal heuristics and attestation requirements prevent unauthorized template scraping
- **Deterministic schema**: 10 fixed fields collapse visual design into reproducible data structures
- **Downstream integration**: Extracted DNA feeds directly into `hallmark redesign` or portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) specifications
- **Traceability**: Output stamping ensures future runs recognize existing DNA systems

---

## Frequently Asked Questions

### What is design DNA in Hallmark's terminology?

Design DNA is the **structured abstraction of a visual interface**—not pixels or code, but the underlying decisions that define it. According to the Hallmark source code, this includes macrostructure (layout patterns), component archetypes, typography pairing, color anchors, and motion characteristics. The `hallmark study` command extracts this DNA into a 10-field schema that other verbs can reconstruct without copying the original assets.

### Why can't image mode extract exact font names?

Raster images lack embedded font metadata. While computer vision can detect **typographic characteristics** (serif vs. sans-serif, weight, relative sizing), it cannot reliably identify precise font-family declarations. URL mode solves this by parsing actual CSS `font-family` rules from the live page's stylesheets—hence why `display_face` and `body_face` remain `null` in image mode outputs.

### What happens if I try to study a paid template site?

The command **refuses the request**. The refusal heuristics in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md) explicitly block domains like `themeforest.net/*` and detect authentication walls. If URL mode triggers a refusal, Hallmark falls back to asking for a screenshot—shifting to image mode where the same visual analysis proceeds without direct HTML/CSS access.

### Can I use extracted DNA for commercial projects?

Only with proper **attestation**. When emitting a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) from URL mode, Hallmark requires you to confirm the source is either your own work or a public reference. This extra verification step, documented in [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md), ensures compliance with copyright restrictions before the DNA becomes portable across projects.