# How Hallmark's `study` Verb Extracts Design DNA from Screenshots and URLs

> Discover how Hallmark's study verb extracts design DNA from screenshots and URLs. Learn about its five-step pipeline for capturing macrostructure, components, color, and motion.

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

---

**The `hallmark study` verb analyzes a design reference—screenshot or public URL—through a five-step extraction pipeline to capture its macrostructure, component archetypes, type-pairing, color anchor, and motion, outputting a structured diagnosis and optional portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md).**

Hallmark, an open-source design system tool by Nutlope, includes a powerful diagnostic command called `hallmark study`. This verb transforms visual or web references into structured **design DNA** that can drive downstream page generation. The implementation lives in two key files: [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) declares the verb's contract, while [[`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) contains the complete extraction protocol.

## Source Mode Detection: Image vs. URL

Hallmark determines its extraction strategy through simple input classification at [[`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) lines 13-14:

- **URL mode**: Input starts with `http://` or `https://`
- **Image mode**: Any attached image or pasted capture

This detection triggers entirely different pipelines while converging on the same five-step extraction framework.

## URL Mode: The Seven-Step Fetch Pipeline

When processing a public URL, Hallmark executes a rigorous **fetch pipeline** defined at [[`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) lines 27-38:

### Safety and Refusal Checks

1. **URL refusal list**: Hallmark matches against hard-coded blocked domains (paid template marketplaces) before any network call.
2. **Remote-URL safety validation** (lines 39-50): Enforces `https` scheme, rejects private IPs, localhost, non-web schemes, and unsafe redirects.

### Minimal Fetch Strategy

3. **Shallow fetch**: Uses the built-in `WebFetch` tool to retrieve HTML and same-origin `<link rel="stylesheet">` CSS files only. Scripts, images, and other resources are **never** fetched (line 33).
4. **Untrusted data treatment**: Instructions embedded in remote payloads are ignored; only design facts are extracted (line 34).

### Quality Gates

5. **Junk-or-blocked detection** (lines 55-66): Screens for authentication walls, SPA shells, non-2xx responses, missing CSS, or sub-1 KB bodies. Triggers fallback to screenshot recommendation if failed (line 69).

### Five-Step Extraction with Rich Data

6. **Enhanced extraction protocol** (lines 6-8, 17-23):

| Step | URL Mode Advantage |
|------|------------------|
| **Surface** | Exact color values from CSS custom properties (`--color-*`, `background-color`) |
| **Type** | Precise font families from Google Fonts links, `@font-face`, or hardcoded `font-family` |
| **Structure** | Semantic DOM tags (`<nav>`, `<section>`, `<footer>`) mapped to macrostructures |
| **Motion** | Detects motion libraries (`framer-motion`, `gsap`, `lottie-web`, `lenis`) and CSS `@keyframes`/transitions |
| **Rhythm** | **Blind spot**: HTML alone cannot infer visual rhythm; recorded as `"unknown (URL mode)"` (lines 23-24, 80-84) |

7. **Schema population and diagnosis**: Fills the structured JSON schema (lines 96-138) and renders URL-mode template output (lines 106-108).

## Image Mode: Vision-Pass Extraction

For screenshots, Hallmark runs a **vision-pass** through identical five-step protocol stages with raster-based limitations (lines 72-104):

- **Surface**: Color bands and accent footprint **estimated by eye** (line 19)
- **Type**: Only **type roles** (display, body, label) inferred; exact font names *not* guessed. Hallmark suggests 1-2 candidate fonts from its canon instead (lines 22-34)
- **Structure**: Visual regions mapped to macrostructures and component archetypes via pattern recognition (line 45)
- **Motion**: Static images provide no motion data; Hallmark notes "motion not visible – assuming default reveals" (line 62)
- **Rhythm**: **Directly observable** from layout, enabling richer diagnosis than URL mode

## Structured Output Schema

Both modes populate a **JSON-compatible schema** ([[`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) lines 96-138) with these characteristics:

- Captures every extracted datum uniformly
- Marks mode-conditional fields as `null` when unavailable
- Flags unknown values explicitly (e.g., `"density": "unknown (URL mode)"`)
- Drives both human-readable diagnosis and downstream automation

## Diagnosis Report Generation

Post-extraction, Hallmark renders a concise markdown diagnosis containing:

- Macrostructure and component archetypes
- Type-pairing roles (exact fonts in URL mode)
- Surface color bands, accent hue, and footprint
- Motion library and reveal pattern (URL) or fallback note (image)
- Rhythm blind-spot notice for URL mode
- Anti-patterns to avoid

## Post-Diagnosis Actions

Users can proceed three ways after receiving a diagnosis:

1. **Build**: Use extracted DNA with `hallmark redesign` or default flow
2. **Lock DNA**: Emit portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (requires source attestation in URL mode at lines 58-66; skipped for user-provided screenshots)
3. **Stop**: Terminate after diagnosis

## Command Examples

### Study a Screenshot

```bash
hallmark study ./homepage-screenshot.png

```

Hallmark detects image mode, runs vision-pass extraction, and outputs markdown diagnosis.

### Study a Public URL

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

```

Hallmark performs safety checks, shallow-fetches HTML/CSS, extracts exact tokens, and returns URL-mode diagnosis.

### Emit Portable Design Document

```bash
hallmark study https://example.com --emit-design-md

```

URL mode prompts for source attestation, then writes [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) per [[`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) specification.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Verb declaration and high-level contract |
| [[`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) | Complete protocol: detection, safety checks, extraction, schema, templates |
| [[`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) | Portable design document format specification |
| [[`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md)](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md) | End-to-end usage examples |
| [[`site/_tests/verbs/study/diagnosis.md`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/study/diagnosis.md)](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/study/diagnosis.md) | Regression test fixture |

## Summary

- **Source detection** routes input to image or URL pipeline
- **URL mode** performs seven-step fetch with shallow, untrusted-data retrieval and exact token extraction
- **Image mode** runs vision-pass with estimated values but superior rhythm inference
- **Five-step extraction** (Surface → Type → Structure → Motion → Rhythm) unifies both modes with mode-specific data richness
- **Structured schema** enables portable output and downstream automation
- **Safety-first design** includes refusal lists, URL validation, and junk detection before any extraction

## Frequently Asked Questions

### What design elements can Hallmark extract from a URL that it cannot from a screenshot?

Hallmark extracts **exact color values** from CSS custom properties, **precise font families** from `@font-face` and Google Fonts links, and **motion library detection** (`framer-motion`, `gsap`, `lottie-web`, `lenis`) from source code. Screenshots only permit visual estimation of colors, type role inference without exact names, and no motion data. However, screenshots enable direct **rhythm observation**, which HTML cannot provide.

### Why does URL mode report "unknown" for visual rhythm?

According to the [[`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) protocol (lines 23-24, 80-84), HTML documents contain no inherent spatial information about element sizing, spacing, or density. Rhythm requires visual inspection of rendered output, so Hallmark explicitly flags this as a blind spot and informs the user rather than guessing.

### What safety measures prevent Hallmark from fetching malicious URLs?

Hallmark implements layered protections: a **hard-coded refusal list** blocks known problematic domains; **scheme validation** requires `https`; **private IP and localhost rejection** prevents internal network probing; and **redirect chain validation** applies the same checks to every hop. The shallow fetch additionally **never executes scripts** or retrieves external resources.

### How do I preserve extracted design DNA for reuse?

After running `hallmark study`, respond "lock the DNA" or invoke with `--emit-design-md`. For URLs, you must first attest that the source is your own site or a public reference. Hallmark then writes a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file conforming to the schema 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), which can seed future `hallmark redesign` commands without re-studying the source.