# How Hallmark's `study` Verb Extracts Design DNA: A Deep Dive into URL and Image Mode Analysis

> Discover how Hallmark's study verb extracts design DNA by analyzing URL and image modes. Learn about its macro-structure, component archetypes, and more without pixel copying.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-16

---

**Hallmark's `study` verb extracts the structural DNA of a design—its macro-structure, component archetypes, type-pairing, colour anchor, and rhythm—without copying any pixels.**

The `study` verb in the Nutlope/hallmark repository is a diagnostic tool that reverse-engineers the underlying design system from any web page or screenshot. This guide explains how it detects input modes, runs safety checks, performs extraction, and generates portable design specifications based on the source code 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).

## Mode Detection: URL vs. Image

The `study` verb automatically switches between two operating modes based on input detection.

- **`hallmark study <url>`** — Activates **URL mode** when the argument starts with `http://` or `https://`
- **`hallmark study <filename>`** — Activates **image mode** for any attached screenshot or local image file

This detection happens at parse time in the verb dispatcher, with no explicit flags required from the user.

## Refusal and Safety Checks

Before extraction begins, `hallmark study` enforces content policies that vary by mode.

### URL Mode Protections

According to [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), the verb:

1. **Refuses template-marketplace domains** — URLs matching patterns like `themeforest.net/*` are blocked
2. **Runs Remote URL Safety checks** — Validates that the target is accessible and contains parseable styling signals
3. **Detects SPA shells and login walls** — If the page returns empty markup or requires authentication, the verb falls back to requesting a screenshot

### Image Mode Protections

- A **vision-pass** validates screenshot content before analysis, rejecting corrupted or non-visual inputs

These checks ensure the tool only extracts DNA from legitimate, accessible sources.

## The Extraction Pipeline

Once cleared, the verb executes mode-specific extraction routines that populate a ten-field **structured-fields schema**.

### Image Mode: Vision-Pass Analysis

In image mode, `hallmark study` performs a complete vision analysis to identify:

| Field | Description |
|-------|-------------|
| **Macro-structure** | Overall page architecture (e.g., "Marquee Hero") |
| **Archetypes** | Component patterns (Hero → Body → Footer) |
| **Type-pairing** | Display and body font combinations |
| **Colour anchor** | Dominant OKLCH hue and saturation |
| **Rhythm** | Baseline and lead multiples (image mode only) |

The **rhythm** field is exclusive to image mode—this temporal-spatial pattern cannot be inferred from code alone.

### URL Mode: HTML/CSS Pass

As implemented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), URL mode:

1. **Shallow-fetches** the page via `WebFetch`
2. **Parses HTML** and permitted stylesheets
3. **Extracts exact values**:
   - Font family names from `@font-face` and `font-family` declarations
   - Colour tokens as OKLCH "paper" (background) and "accent" (primary) values

URL mode produces more precise **typographic and colour data** but cannot detect rhythm, since element positioning may differ from rendered output.

## Diagnosis Report Generation

After extraction, `hallmark study` emits a one-page markdown diagnosis report containing:

- Identified **macro-structure** and **archetypes**
- **Type-pairing** with exact font names
- **Colour anchor** with hue approximation
- **Rhythm** (image mode only)
- **Anti-patterns flagged** — Specific elements that should *not* be copied (exact pixel positions, paid fonts, licensed imagery)

Example output structure:

```markdown

## Diagnosis Report

- **Macrostructure:** Marquee Hero
- **Archetypes:** Hero → Body → Footer
- **Type-pairing:** Display = "Inter Tight"; Body = "Inter"
- **Colour anchor:** Desaturated forest-green (hue ≈ 140°)
- **Rhythm:** 3 × baseline, 1.5 × lead
- **Anti‑patterns:** Avoid copying exact pixel positions, paid fonts…

```

## Optional Hand-Offs and DNA Locking

The verb supports two post-study workflows documented in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md).

### Rebuild with Extracted DNA

Requesting to **"build"** hands the extracted parameters to the `hallmark redesign` verb:

```bash
hallmark study https://example.com

# User says: "build this"

# → Hands off to `hallmark redesign` with studied parameters

```

### Emit a Portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)

Requesting to **"lock the DNA"** or **"give me a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)"** creates a portable specification:

```bash
hallmark study https://example.com

# User says: "lock the DNA"

# → Creates `design.md` with extracted tokens

```

For URL mode, an **attestation step** is required—the user must confirm the source is their own work or a public reference. Without confirmation, emission is refused. The [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) format is specified in [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md).

## CSS Stamps for Future Runs

When code is generated from a studied design, the first non-empty line of the CSS contains a **stamp comment** recording:

```css
/* hallmark: macro=MarqueeHero tone=neutral hue=140 studied:yes theme:studied-DNA source:https://example.com */

```

In [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), this stamp format ensures:
- `studied: yes` — Flags this as derived from `hallmark study`
- `theme: studied-DNA (source: <URL or image>)` — Prevents rotation to catalog themes on subsequent runs

## Key Files and Implementation

| File | Role |
|------|------|
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Core verb definition, syntax, mode switching, safety checks, stamp format |
| [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) | Detailed protocol: refusal heuristics, extraction steps, schema, emission rules |
| [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) | Portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) format specification |
| [`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md) | Worked examples of input, diagnosis, and rebuilds |
| `site/_tests/verbs/study/` | Test fixtures for validation |

## Summary

- **`hallmark study`** detects input mode automatically by inspecting the argument (URL vs. filename)
- **Safety checks** block template markets, SPA shells, and unverified sources before extraction
- **Image mode** uses vision-pass analysis to detect rhythm; **URL mode** extracts precise font and colour tokens from HTML/CSS
- The **diagnosis report** identifies macro-structure, archetypes, type-pairing, colour anchor, and anti-patterns
- Optional hand-offs to **`redesign`** or **[`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)** emission enable reuse of extracted DNA
- **CSS stamps** ensure subsequent runs respect the studied design system

## Frequently Asked Questions

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

URL mode shallow-fetches live pages to extract exact font names and OKLCH colour values from HTML and CSS, but cannot detect rhythm. Image mode performs vision analysis on screenshots to identify spatial rhythm patterns, but extracts approximate rather than exact colour and typography values. Choose URL mode for precision on accessible sites; use image mode for login-protected pages or when rhythm analysis matters.

### Why can't URL mode detect design rhythm?

Rhythm depends on rendered spatial relationships—baseline grids, vertical spacing, and element flow—that often differ from raw CSS declarations due to dynamic layouts, viewport adaptation, and JavaScript manipulation. According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), only the vision-pass in image mode can observe these actual rendered patterns.

### What happens if I try to study a theme marketplace URL?

The refusal list in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) blocks domains like `themeforest.net/*`. The verb returns an error and suggests providing a screenshot instead. This protects against inadvertent license violations and ensures the tool focuses on reference analysis rather than template duplication.

### How do I reuse a studied design in future Hallmark projects?

Request **"lock the DNA"** after studying to generate a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file, or ensure the generated CSS retains its `studied:yes` stamp. Either method preserves the macro-structure, tone, and hue settings, preventing automatic theme rotation on subsequent `hallmark` commands.