# How Hallmark Study Extracts Design DNA from Screenshots and URLs

> Learn how Hallmark Study extracts design DNA from screenshots or URLs using a deterministic pipeline that analyzes visual cues and maps them to a structured 10-field schema.

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

---

**The `hallmark study` command extracts design DNA by running a deterministic pipeline that analyzes either a screenshot via vision-pass or a live URL via WebFetch, then maps the visual cues to a structured 10-field schema including macrostructure, typography, and color anchors.**

The `hallmark study` verb in the **Nutlope/hallmark** repository serves as a design intelligence engine that converts visual references into structured, reusable code specifications. When you provide either a static image or a live webpage URL, the command executes a rigorous extraction protocol defined 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) to capture the abstract design DNA. This process enables the downstream `hallmark redesign` verb to rebuild sites while preserving only the design intent, not the original pixels.

## The Design DNA Extraction Pipeline

The extraction process follows a deterministic, safety-first pipeline that collapses visual complexity into a portable data structure.

### Detection and Mode Selection

The verb automatically selects **image mode** or **URL mode** based on the input string prefix. If the argument begins with `http://` or `https://`, the command triggers URL mode; otherwise, it treats the input as a local image file path. This detection logic is defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), ensuring the appropriate acquisition strategy runs without manual flags.

### Safety and Refusal Heuristics

Before extraction begins, the command runs a **refusal-or-proceed check** to prevent unauthorized scraping. The system maintains refusal lists that block paid template marketplaces (e.g., `themeforest.net/*`), authentication walls, and SPA shells that lack rendered markup. In URL mode, an additional **Remote-URL Safety** check validates the target. If a URL fails these heuristics, the verb falls back to requesting a screenshot instead, as documented in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md).

### Data Acquisition Methods

Depending on the detected mode, the command employs two distinct acquisition strategies:

- **Image mode** runs a **vision-pass** using a pre-trained image-analysis model that populates the structured-fields schema based on visual inference.
- **URL mode** executes a shallow **WebFetch** to retrieve the page’s HTML and linked CSS files, then parses exact font names, color values, and layout clues directly from the source.

As noted in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), URL mode provides deterministic values for typography and color, while image mode leaves font-related fields null due to the limitations of raster analysis.

### The Structured-Fields Schema

Extracted facts are normalized into a fixed **10-field schema** that serves as the design DNA. The fields include:

- `macrostructure` – The high-level layout pattern (e.g., "Portfolio-grid")
- `archetypes` – Component types present (e.g., "Header", "Card", "Footer")
- `display_face` – The heading typeface
- `body_face` – The body copy typeface
- `paper_value` – Background color anchor
- `accent_value` – Primary action color
- `motion_library` – Animation characteristics

URL mode populates all 10 fields with concrete values, while image mode captures macrostructure and color anchors but cannot reliably determine exact font names. This schema definition lives in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md).

### Diagnosis Report Generation

After schema population, the command generates a human-readable **diagnosis report** in markdown format. This report summarizes the extracted DNA (e.g., "macrostructure: Portfolio-grid; archetypes: Header, Card, Footer; type-pairing: Inter × Mono; colour anchor: OKLCH h 210") and highlights specific anti-patterns to avoid during reconstruction. The report format is specified in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) under the "Diagnosis report" section.

### Output Stamping and Hand-off

The final stage involves **stamping** and optional portability:

1. **Stamping**: Generated CSS or inline `<style>` blocks begin with a comment recording the DNA (e.g., `/* Hallmark · macrostructure: … */`). This stamp enables future runs to detect that a study-DNA system is already in place, preventing accidental theme re-rotation.
2. **Hand-off**: Users can invoke `hallmark redesign` to immediately rebuild using the extracted DNA, or emit a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file. URL mode requires an extra attestation step—confirming the source is either the user’s own work or a public reference—before writing the file, as implemented in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md).

## Practical Usage Examples

The following commands demonstrate the dual-mode extraction workflow and subsequent DNA reuse:

```bash

# Extract DNA from a live page URL

hallmark study https://example.com/awesome-landing

```

```bash

# Extract DNA from a local screenshot file

hallmark study path/to/screenshot.png

```

```bash

# Rebuild a site using the extracted DNA from the previous study

hallmark redesign

```

```bash

# Emit a portable design.md after studying a URL

# (You will be prompted to confirm ownership or public status)

hallmark study https://example.com/awesome-landing

# Then request: "lock the DNA" or "give me a design.md"

```

## Key Source Files and Architecture

The extraction behavior is implemented across several authoritative files in the repository:

- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** – Defines the high-level verb contract, automatic detection logic, and output stamping requirements.
- **[`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md)** – Contains the full extraction protocol, refusal heuristics, the 10-field schema specification, and diagnosis report formatting.
- **[`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md)** – Specifies the portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) format emitted after a successful study.
- **[`site/_tests/verbs/study/diagnosis.md`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/study/diagnosis.md)** – Provides sample diagnosis reports for debugging and validation.

## Summary

- **Dual-mode extraction** handles both raster images and live HTML/CSS through vision-pass and WebFetch strategies, unified by a single schema.
- **Safety-first architecture** employs refusal lists and remote-URL checks to block unauthorized template scraping, with automatic fallback to screenshot mode.
- **Structured DNA** compresses visual design into 10 deterministic fields (macrostructure, archetypes, typography, color) that abstract intent from implementation.
- **Stamping mechanism** embeds DNA metadata into generated CSS to prevent redundant theme rotation in future runs.
- **Portable hand-off** allows extraction results to power `hallmark redesign` or export to [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) for cross-tool reusability.

## Frequently Asked Questions

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

**Image mode** analyzes a static screenshot using a vision-pass model to infer layout and color, but it cannot reliably extract exact font names, leaving typography fields null. **URL mode** fetches live HTML and CSS via WebFetch to capture precise font stacks, exact color values, and DOM structure, populating all 10 schema fields deterministically.

### Why does `hallmark study` refuse to analyze some URLs?

The command implements **refusal heuristics** to prevent scraping of paid template marketplaces (such as ThemeForest), authentication-walled content, and unrendered SPA shells. If a URL matches the refusal list or fails the Remote-URL Safety check, the verb rejects the request and prompts for a screenshot instead, protecting both users and content owners.

### What fields are included in the structured-fields schema?

The schema captures **10 fixed fields**: `macrostructure` (layout pattern), `archetypes` (component types), `display_face` (heading font), `body_face` (body font), `paper_value` (background color), `accent_value` (primary action color), `motion_library` (animation style), and additional metadata fields. URL mode provides concrete values for all fields, while image mode populates only the visually detectable subset.

### How can I reuse the extracted design DNA in another project?

After running `hallmark study`, you can **emit a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file** that contains the complete structured-fields schema. In URL mode, you must first attest that the source is your own work or a public reference. Once emitted, this file can be imported into other Hallmark runs or AI tools to reconstruct the design system without re-analyzing the original source.