# How Hallmark Study Extracts Design DNA from Screenshots and URLs: A Technical Deep Dive

> Learn how hallmark study extracts design DNA from screenshots and URLs. This technical deep dive explores its five-step protocol for analyzing visual elements and generating insights.

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

---

**The `hallmark study` verb extracts design DNA by detecting the input type (image or URL), running safety checks, and executing a five-step protocol (Surface, Type, Structure, Motion, Rhythm) that populates a structured JSON schema and renders a human-readable diagnosis.**

The Nutlope/hallmark repository implements a diagnostic tool that "studies" design references to pull out their **design DNA**—including macrostructure, component archetypes, type-pairing, colour anchors, and motion patterns. Whether analyzing a user-provided screenshot or a public web address, the verb follows a declarative pipeline defined in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) and orchestrated by [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). Here is the complete architectural breakdown of how Hallmark processes these two source modes.

## Source Mode Detection

Hallmark distinguishes between input types using simple prefix detection implemented in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md) (lines 13-14).

- **URL mode**: Triggered when input starts with `http://` or `https://`
- **Image mode**: Triggered for any attached image or pasted capture (anything else)

This binary detection determines which safety checks, fetch logic, and extraction heuristics execute downstream.

## URL Mode Pipeline

When a URL is supplied, Hallmark executes a **seven-step fetch pipeline** (lines 27-38 in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)) before performing DNA extraction.

### Safety and Refusal Checks

The pipeline begins with strict security validations:

1. **URL refusal check**: Matches against a hard-coded refuse list (paid-template marketplaces). If matched, the verb refuses before any network call.
2. **Remote-URL safety check**: Validates HTTPS scheme, rejects private IPs, localhost, and non-web schemes. Redirects must pass the same security checks (lines 39-50).
3. **Shallow fetch**: Uses the built-in `WebFetch` tool to retrieve only HTML and same-origin `<link rel="stylesheet">` CSS files (line 33). Scripts, images, and other resources are **never** fetched.
4. **Untrusted data treatment**: Any instructions embedded in the remote payload are ignored; only design facts are extracted (line 34).
5. **Junk-or-blocked detection**: Looks for authentication walls, SPA shells, non-2xx responses, missing CSS, or sub-1 KB bodies (lines 55-66). If triggered, Hallmark falls back to screenshot-fallback messaging (line 69).

### Five-Step Extraction Protocol

After fetching, Hallmark runs the same five-step protocol used for image mode, but with richer data sources (lines 6-8, 17-23):

| Step | URL Mode Extraction Details |
|------|----------------------------|
| **1. Surface** | Extracts exact colour values from CSS custom properties (`--color-*`, `background-color`, etc.). |
| **2. Type** | Captures precise font families from Google Fonts `<link>` tags, `@font-face` declarations, or hard-coded `font-family` values. |
| **3. Structure** | Maps semantic DOM tags (`<nav>`, `<section>`, `<footer>`, etc.) to macrostructures and component archetypes. |
| **4. Motion** | Detects motion libraries (`framer-motion`, `gsap`, `lottie-web`, `lenis`) and CSS `@keyframes` / transitions. |
| **5. Rhythm** | **Blind spot**: HTML alone cannot infer visual rhythm. Hallmark records this as "unknown (URL mode)" and informs the user (lines 23-24, 80-84). |

The schema is then populated according to the structured JSON definition (lines 96-138), followed by rendering the URL-mode diagnosis template (lines 106-108).

## Image Mode Pipeline

When processing a screenshot, Hallmark runs a **vision-pass** using the image-mode side of the five-step protocol. The steps align with URL mode, but data sources differ significantly:

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

The image-mode template is defined in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md) lines 72-104.

## Structured Output and Diagnosis

Both modes output a **JSON-compatible schema** (lines 96-138 in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)) that captures every extracted datum. The schema marks mode-conditional fields as `null` when unavailable and explicitly flags unknown values (e.g., `"density": "unknown (URL mode)"`).

After schema completion, Hallmark renders a concise diagnostic markdown report using the appropriate template. The report enumerates:

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

## Post-Diagnosis Actions

Following the diagnosis, the user can execute three paths:

1. **Build**: Proceed with the extracted DNA using `hallmark redesign` or the default flow.
2. **Lock the DNA**: Emit a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file (see lines 33-44 in the study documentation).
3. **Stop**: Terminate after receiving the diagnosis.

**Important**: Emitting a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) in URL mode requires explicit attestation that the source is the user's own site or a public reference (lines 58-66). Image mode skips this requirement because the screenshot is user-provided. The [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) format specification lives in [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md).

## Code Examples

### Studying a Screenshot

```bash
hallmark study ./landing-page-screenshot.png

```

Hallmark detects image mode, runs the vision pass, and prints a markdown diagnosis.

### Studying a Public URL

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

```

Hallmark performs URL-mode safety checks, fetches HTML/CSS, extracts exact colour tokens and font families, and returns a URL-mode diagnosis.

### Emitting a Design DNA File

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

```

In URL mode, Hallmark requests source attestation before writing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) using the schema defined in [`design-md.md`](https://github.com/Nutlope/hallmark/blob/main/design-md.md).

## Summary

- **Source detection** determines whether Hallmark runs URL-mode or image-mode pipelines.
- **URL mode** performs a seven-step fetch with security checks, extracting exact CSS values, font families, DOM semantics, and motion libraries, but cannot determine visual rhythm.
- **Image mode** relies on visual estimation for colours and type roles, cannot detect motion, but provides accurate rhythm analysis.
- Both modes populate a **structured JSON schema** (lines 96-138 in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)) driving a human-readable diagnosis.
- Users can **lock the DNA** into a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), with URL mode requiring source ownership attestation.

## Frequently Asked Questions

### What is the "design DNA" that Hallmark extracts?

Design DNA refers to the essential genetic code of a interface: its **macrostructure** (page layout), **component archetypes** (UI patterns), **type-pairing** (font relationships), **colour anchor** (primary palette), and **motion** (animation patterns). The `hallmark study` verb extracts these elements into a structured schema that can drive subsequent build processes or be saved as a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file.

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

URL mode analyzes HTML and CSS source code, not rendered pixels. While CSS contains layout properties, the actual **visual rhythm**—the perceived density, pacing, and whitespace balance—requires spatial rendering that only occurs in a browser viewport. Hallmark explicitly marks this as a "blind spot" (lines 80-84 in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)) and advises users to provide screenshots if rhythm analysis is critical.

### How does Hallmark prevent fetching malicious URLs?

The URL pipeline implements a **remote-URL safety check** (lines 39-50) that validates HTTPS schemes, rejects private IP ranges, localhost, and non-web URI schemes. It also matches URLs against a **refusal list** of blocked domains (template marketplaces, etc.) before any network call. Additionally, the `WebFetch` tool operates in a restricted mode that only retrieves HTML and same-origin CSS, ignoring scripts and external resources.

### What happens if the fetched URL returns a login wall or SPA shell?

Hallmark runs **junk-or-blocked detection** (lines 55-66) that identifies authentication walls, SPA shells (empty `<div id="root">` structures), non-2xx HTTP responses, missing CSS, or bodies under 1 KB. When these signals trigger, the verb falls back to a screenshot-fallback message (line 69), prompting the user to provide an image capture instead of relying on the fetched source.