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

> Discover how the Hallmark study verb extracts design DNA from screenshots or URLs. Get a structured diagnosis report and design.md file.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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)](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/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)](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/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) for version control and portability
3. **Stop**: Retain diagnosis without artifact generation

The [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) emission follows strict provenance rules defined in [[`design-md.md`](https://github.com/Nutlope/hallmark/blob/main/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/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md):

```css
/* 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:

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

```

Study from archived screenshot:

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

```

Programmatic invocation:

```javascript
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:

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

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Verb definitions, mode detection, workflow orchestration |
| [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) | Extraction protocol, refusal heuristics, emission logic |
| [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) | [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) schema specification |
| [`site/_tests/verbs/study/notes.md`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/verbs/study/notes.md) | Vision pipeline test documentation |
| [`site/css/sections.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) files rather than re-studying live URLs that may change.