How the Hallmark Study Verb Extracts Design Information: A Technical Deep Dive

The hallmark study command extracts design DNA—macrostructure, component archetypes, type-pairing, colour anchors, and rhythm—through either a five-step vision pass on screenshots or shallow HTML/CSS parsing of URLs, outputting a structured diagnosis report and optional portable design.md file.

The hallmark study verb is one of Hallmark's most powerful diagnostic tools in the Nutlope/hallmark repository. Unlike simple screenshot tools that copy pixels, this verb performs structural analysis to decompose any reference design into reusable, portable design tokens that can rebuild your own content or generate documentation.

How Hallmark Study Detects Input Mode

The verb automatically determines its extraction pipeline based on your input. As defined in [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) line 28, the detection logic is straightforward:

• URL mode: Argument starts with http:// or https://
• Image mode: All other inputs treated as local image paths

This dual-mode architecture lets designers study live production sites or archived screenshots with the same command interface.

Safety and Refusal Checks

Before extraction begins, Hallmark runs refusal heuristics to prevent misuse and ensure quality. These checks are documented in [references/study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) line 504.

URL mode protections:

• Refuse-list blocks commercial template marketplaces (themeforest.net/*, templatemonster.com/*)
• Remote-safety check detects auth-walls, SPA shells, and non-2xx responses

Image mode protections:

• Vision-pass refusal heuristic filters low-quality screenshots

If any check fails, the verb gracefully degrades—requesting a better screenshot rather than producing unreliable output.

Image Mode: The Five-Step Vision Pipeline

When studying screenshots, Hallmark executes a structured vision pass that populates ten diagnostic fields. This pipeline is outlined in [site/_tests/verbs/study/notes.md](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/study/notes.md) lines 11-14.

Extracted design DNA includes:

• macrostructure: Overall layout topology (hero-asymmetric, bento-grid, editorial-stream, etc.)
• archetype: Component pattern library (minimal-chrome, brutalist, glassmorphic, etc.)
• type-pairing: Display and body font relationship
• colour_anchor: Primary OKLCH hue and saturation strategy
• rhythm: Motion cadence (transitions, scroll-triggering, stagger patterns)

Critically, rhythm extraction only works in image mode—live pages don't reveal their motion DNA without JavaScript execution, which Hallmark deliberately avoids.

URL Mode: Shallow WebFetch Extraction

For live sites, Hallmark performs a strictly shallow fetch—no browser automation, no script execution. As implemented in the URL pipeline:

1. WebFetch retrieves raw HTML and allowed CSS
2. Parser extracts exact font family declarations
3. Colour values captured in OKLCH notation when available
4. Motion library references flagged (framer-motion, gsap, etc.)

The rhythm blind-spot is explicitly noted in the diagnosis report—designers must visually assess animation or provide screenshots for that dimension.

The Diagnosis Report Structure

Both modes converge on a one-page human-readable report using templates from [references/study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) line 512. Standard sections include:

Section	Content
Macrostructure	Layout topology with grid/flex specifics
Component Archetypes	Reusable pattern vocabulary
Typography	Exact pairings and scale ratios
Colour System	Anchor hue, secondary strategy, contrast logic
Anti-patterns	Common mistakes to avoid in reconstruction
Rhythm (image only)	Motion timing and trigger patterns

Emission of Portable Design DNA

After diagnosis, three follow-up paths exist:

1. Build: Hand off to hallmark redesign with extracted DNA
2. Lock the DNA: Emit design.md for version control and portability
3. Stop: Retain diagnosis without artifact generation

The design.md emission follows strict provenance rules defined in [design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/design-md.md) line 19:

• Image mode: Direct emission (user owns screenshot)
• URL mode: Attestation step required—must confirm own work or public reference; unauthorized third-party sites are refused

CSS Stamping for Diversification

Final output receives a DNA stamp in the generated CSS or <style> block, per [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md):

/* hallmark-stamp
   macrostructure: bento-grid
   tone: editorial-calmp
   anchor-hue: 220
   studied: yes
*/

This stamp enables the diversification logic in subsequent runs—preventing literal replication while preserving the essential character of the studied design.

Practical Usage Examples

Study a live portfolio page:

hallmark study https://www.usehallmark.com/examples/hum-07/

Study from archived screenshot:

hallmark study ./references/vercel-home-2024.png

Programmatic invocation:

const { execSync } = require('child_process');

const dna = execSync(
  'hallmark study https://example.com/portfolio'
).toString();

// Parse diagnosis report for automated pipelines
console.log(dna);

Emit portable design specification:

hallmark study ./screenshot.png
> give me a design.md

Key Implementation Files

File	Purpose
skills/hallmark/SKILL.md	Verb definitions, mode detection, workflow orchestration
skills/hallmark/references/study.md	Extraction protocol, refusal heuristics, emission logic
skills/hallmark/references/design-md.md	design.md schema specification
site/_tests/verbs/study/notes.md	Vision pipeline test documentation
site/css/sections.css	UI rendering and DNA stamp classes

Summary

• Dual-mode architecture automatically routes screenshots through vision pipeline and URLs through shallow HTML/CSS parsing
• Image mode extracts rhythm; URL mode explicitly documents this blind-spot
• Refusal heuristics prevent misuse of commercial templates and low-quality inputs
• Provenance attestation required for design.md emission from third-party URLs
• CSS stamping preserves extraction metadata for downstream diversification logic

Frequently Asked Questions

Why doesn't Hallmark extract rhythm from URLs?

URL mode uses shallow WebFetch without JavaScript execution. Motion design—transitions, scroll triggers, stagger patterns—only exists at runtime in the DOM. The system explicitly marks this as a "rhythm blind-spot" in URL-mode reports. To capture rhythm, provide a screenshot or screen recording.

What prevents Hallmark from cloning copyrighted designs?

Three mechanisms: (1) URL refuse-list blocks major template marketplaces, (2) remote-safety checks reject auth-walled content, and (3) design.md emission requires attestation for non-owned URLs. The verb extracts structural DNA (layout topology, type systems, colour logic) rather than pixel-for-pixel replication.

How does the vision pipeline differ from typical AI vision APIs?

Hallmark's five-step pass is schema-constrained—it doesn't generate freeform descriptions. Each step populates specific fields (macrostructure, archetype, colour_anchor) defined in [references/study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md). This produces deterministic, comparable, and rebuildable design tokens rather than prose observations.

Can I use Hallmark study in CI/CD pipelines?

Yes, though URL mode is safer for automation since it doesn't require managed screenshot assets. The Node.js execSync pattern shown above lets you capture diagnosis output for downstream processing. For reproducible builds, commit the emitted design.md files rather than re-studying live URLs that may change.

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