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

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 and 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, 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, 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:

## 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.

Rebuild with Extracted DNA

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

hallmark study https://example.com

# User says: "build this"

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

Emit a Portable design.md

Requesting to "lock the DNA" or "give me a design.md" creates a portable specification:

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 format is specified in 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:

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

In 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	Core verb definition, syntax, mode switching, safety checks, stamp format
skills/hallmark/references/study.md	Detailed protocol: refusal heuristics, extraction steps, schema, emission rules
skills/hallmark/references/design-md.md	Portable design.md format specification
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 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, 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}