# How Hallmark Study Extracts Design DNA from Screenshots and URLs

> Learn how Hallmark Study extracts design DNA from screenshots and URLs. Discover its five-step protocol for analyzing macrostructure, typography, color, motion, and layout rhythm. Get a structured design diagnosis.

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

---

**The `hallmark study` command analyzes visual references through a five-step extraction protocol that identifies macrostructure, typography, color systems, motion patterns, and layout rhythm, outputting a structured diagnosis that can be serialized to a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file.**

The `hallmark study` verb in the Nutlope/hallmark repository is a diagnostic tool that reverse-engineers design references into structured **design DNA**. Whether you provide a static screenshot or a live URL, the tool executes a retrieval and analysis pipeline defined in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) and orchestrated through [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).

## Source Mode Detection

The system first classifies your input to determine which analysis pipeline to run. According to lines 13–14 in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), the detection logic is straightforward:

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

This routing decision determines whether Hallmark performs a shallow web fetch or a vision-based analysis.

## URL Mode: The Seven-Step Fetch Pipeline

When processing a web address, Hallmark follows a **seven-step fetch pipeline** (lines 27–38 in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)) that prioritizes safety and precision before extracting design tokens.

### Security and Refusal Checks

Before fetching, the system performs two validation layers:

1. **URL refusal check**: Matches against a hard-coded blocklist of paid-template marketplaces and restricted domains, refusing the request immediately if matched.
2. **Remote-URL safety check**: Validates the scheme (requiring `https`), rejects private IPs, localhost, and non-web schemes, and validates redirect chains (lines 39–50).

### Shallow Fetch and Validation

The pipeline retrieves only the HTML and same-origin CSS via the built-in `WebFetch` tool (line 33). Scripts, images, and external resources are **never** fetched. The system treats all fetched data as untrusted, ignoring any embedded instructions (line 34).

A **junk-or-blocked detection** phase (lines 55–66) checks for authentication walls, SPA shells, non-2xx responses, missing CSS, or bodies under 1 KB. If triggered, Hallmark falls back to screenshot-mode messaging (line 69).

### URL-Specific Extraction

After successful retrieval, Hallmark runs the five-step extraction protocol with access to semantic DOM and computed styles:

- **Surface**: Extracts exact color values from CSS custom properties (`--color-*`) and `background-color` declarations.
- **Type**: Captures precise font families from Google Fonts links, `@font-face` rules, or hardcoded `font-family` values.
- **Structure**: Maps semantic DOM tags (`<nav>`, `<section>`, `<footer>`) to macrostructures and component archetypes.
- **Motion**: Detects motion libraries (`framer-motion`, `gsap`, `lottie-web`, `lenis`) and CSS `@keyframes` or transitions.
- **Rhythm**: Records as "unknown (URL mode)" because HTML alone cannot infer visual spacing (lines 23–24, 80–84).

## Image Mode: Vision-Based Analysis

For screenshots, Hallmark executes a **vision pass** using the same five-step protocol, but derives data from raster analysis rather than code:

- **Surface**: Color bands and accent footprints are **estimated by eye** (line 19).
- **Type**: Only **type roles** (display, body, label) are inferred; exact font names are not guessed. Hallmark suggests 1–2 candidate fonts from its canon instead (lines 22–34).
- **Structure**: Visual regions are mapped to macrostructures by pattern recognition rather than semantic tags (line 45).
- **Motion**: Static images provide no motion data, so the output 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, while the URL-mode template occupies lines 106–108.

## The Five-Step DNA Extraction Protocol

Both modes follow the same architectural protocol, differing only in data source fidelity:

| Step | Domain | URL Mode Input | Image Mode Input |
|------|--------|----------------|------------------|
| 1. Surface | Color system | CSS custom properties | Visual estimation |
| 2. Type | Typography | Exact font families | Role inference |
| 3. Structure | Layout architecture | Semantic DOM tags | Visual regions |
| 4. Motion | Animation patterns | Library detection | Null (not visible) |
| 5. Rhythm | Spacing system | Unknown (blind spot) | Direct observation |

## Structured Output and Diagnosis

After extraction, Hallmark populates a **JSON-compatible schema** (lines 96–138 in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)) that captures every datum, marking mode-conditional fields as `null` or "unknown" when unavailable. This schema drives a human-readable diagnosis report using the appropriate template.

The diagnosis enumerates:

- Macrostructure and component archetypes
- Type-pairing roles (and exact fonts in URL mode)
- Surface color 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

Upon completing the analysis, three paths are available:

1. **Build**: Use the extracted DNA in `hallmark redesign` or the default build flow.
2. **Lock the DNA**: Emit a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file per the format defined in [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md).
3. **Stop**: Terminate after receiving the diagnosis.

Emission in URL mode requires explicit user attestation that the source is either their own site or a public reference (lines 58–66). Image mode skips this step because the screenshot is user-provided.

## Practical Usage Examples

Invoke the verb via CLI with the source as the argument:

```bash

# Analyze a local screenshot

hallmark study ./screenshot.png

```

```bash

# Analyze a public URL

hallmark study https://example.com

```

```bash

# Emit a design.md after analysis (URL mode requires attestation)

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

```

## Summary

The `hallmark study` verb extracts **design DNA** from visual references through:

- **Source detection** that routes input to URL or image pipelines
- **Safety checks** including URL blocklists and IP validation
- **Shallow fetching** of HTML/CSS only (URL mode)
- **Five-step extraction** covering Surface, Type, Structure, Motion, and Rhythm
- **Schema-driven output** generating structured JSON and markdown diagnoses
- **Portable serialization** to [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) with ownership attestation for web sources

## Frequently Asked Questions

### What is the difference between URL mode and image mode in hallmark study?

URL mode fetches live HTML and CSS to extract exact design tokens like hex colors and font families, but cannot determine visual rhythm. Image mode analyzes static screenshots to infer layout rhythm and visual hierarchy, but can only estimate colors and suggest font candidates rather than identifying exact typefaces.

### Why does URL mode show "unknown" for rhythm analysis?

HTML and CSS alone cannot convey the visual spacing and compositional balance that a human perceives when viewing a rendered page. According to lines 80–84 in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md), Hallmark explicitly flags this as a blind spot in URL mode, whereas image mode can observe rhythm directly from the rendered layout.

### How does hallmark study handle security when fetching external URLs?

The tool implements a multi-layer safety system: it checks against a hard-coded refusal list of restricted domains, validates that URLs use HTTPS, rejects private IP ranges and localhost, sanitizes redirect chains, and treats all fetched content as untrusted to prevent instruction injection (lines 39–50).

### Can I export the design DNA after running a study?

Yes. After the diagnosis, you can **lock the DNA** to emit a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file following the schema in [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md). When extracting from URLs, you must first attest that you own the source or that it is a public reference before the file can be generated.