Skip to content

Anti-AI-slop design skill for Claude Code, Cursor, and Codex.

CSS

Tier 1 — visual-first README · recipes.md · study-examples.md · study-led positioning

Youssef6b2e701dc6fe
diff --git a/README.md b/README.md
index a3ab6be..7387323 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,49 @@
# Hallmark
-A design skill for AI coding assistants. Makes the UIs they generate look made, not generated.
+**A design skill that studies what you admire — and rebuilds your content with it.**
-→ **Live demo:** [hallmark-murex.vercel.app](https://hallmark-murex.vercel.app) — sixteen themes, eight generation tests, press `T` to cycle.
+→ Live demo: **[hallmark-murex.vercel.app](https://hallmark-murex.vercel.app)** · sixteen themes, eight worked tests, press `T` to cycle.
-**Powered by Together AI.**
+<table>
+ <tr>
+ <td><img src="docs/img/theme-specimen.png" alt="Specimen — warm cream, italic Fraunces, warm-orange accent" /></td>
+ <td><img src="docs/img/theme-studio.png" alt="Studio — cool grey paper, italic Fraunces, forest-green accent" /></td>
+ </tr>
+ <tr>
+ <td><img src="docs/img/theme-brutal.png" alt="Brutal — stark white-and-black, Inter Tight 900, no chromatic accent" /></td>
+ <td><img src="docs/img/theme-newsprint.png" alt="Newsprint — warm cream, Playfair Display roman, deep-red accent" /></td>
+ </tr>
+</table>
+
+Hallmark is the **anti-AI-slop** rule-set for Claude Code, Cursor, and Codex. It encodes the [tactile-rebellion](https://www.creativebloq.com/design/graphic-design/texture-warmth-and-tactile-rebellion-the-big-graphic-design-trends-for-2026) consensus — typography, colour, layout, motion, microinteractions, structural variety — into one opinionated skill that refuses to emit the on-distribution defaults every LLM was trained into.
+
+Powered by Together AI.
+
+---
+
+## Try it
+
+Paste this into Claude Code, Cursor, or Codex with the Hallmark skill installed:
+
+> *"Build me a landing page for Coffeebox — a small-batch coffee subscription. Roast on Sunday, ship on Monday, drink Tuesday. Audience: people who already buy good coffee. Tone: warm, hand-set, editorial."*
+
+If Hallmark is wired correctly, you'll see Long Document · Linen (warm-paper roman-serif) · Tier-B hand-built SVG. Eight more worked briefs are documented in [`recipes.md`](skill/references/recipes.md) — copy/paste them to discover the skill before reading anything else.
---
-## What it is
+## What's distinct — quick map vs the field
-A single, opinionated skill that gives Claude Code, Cursor, and Codex a firm rule-set for typography, colour, layout, motion, microinteractions, copy, responsive behaviour, and structural variety. It refuses to emit the on-distribution defaults every LLM was trained into.
+| | Hallmark | [frontend-design](https://github.com/anthropics/skills) (Anthropic) | [Open Design](https://github.com/nexu-io/open-design) | [Dembrandt](https://github.com/dembrandt/dembrandt) |
+| --- | --- | --- | --- | --- |
+| **Source of taste** | extracts DNA from a screenshot you admire (`study` verb) | art-director brief + ban list | menu of 72 brand presets (Linear, Stripe, Vercel, Notion…) | scrapes a live URL, emits computed tokens |
+| **Output unit** | macrostructure + theme + custom-craft | bans + brief framing | preset application | DTCG `tokens.json` |
+| **Refuses font ID** | yes — names role, never guesses | n/a | n/a | n/a (computes from CSS) |
+| **Refuses pixel-clone** | yes — DNA only, never pixels | n/a | n/a | n/a (full token export) |
+| **Tactile-rebellion alignment** | warm-paper, custom-craft, slopless canon | strong | medium | none — token-only |
+| **Pages by archetype** | 21 named macrostructures, picked per brief | by brief | 5 deterministic directions | n/a |
+| **Verbs** | 5 (default · `audit` · `refine` · `redesign` · `study`) | 1 | 31 | 1 (CLI) |
-The differentiator: Hallmark insists on **structural variety**, not just visual variety. Two pages from two briefs should not share the same hero → 3-feature → CTA → footer rhythm. They should feel like different sites.
+Hallmark's edge is **`study`** — every other tool ships a preset menu or a scraper. Hallmark is the only one that takes a screenshot of a design you admire, names what it sees, refuses paid-template-marketplace listings, and rebuilds your content with the extracted DNA. Three worked study examples in [`study-examples.md`](skill/references/study-examples.md).
---
@@ -20,20 +51,73 @@ The differentiator: Hallmark insists on **structural variety**, not just visual
| Verb | What it does |
| --- | --- |
-| *(default)* | Build new UI. Asks for audience + use case + tone (skippable — the skill states what it inferred either way), picks a macrostructure, applies the rule-set, runs the slop test before handing back. |
+| *(default)* | Build new UI. Asks for audience + use + tone (skippable — the skill states what it inferred). Picks a macrostructure, applies the rule-set, runs the slop test before handing back. |
| `hallmark audit <target>` | Score existing code against the named anti-patterns + structural sameness. Punch list, no edits. |
| `hallmark refine <target>` | Polish in place. Smallest possible diff. Preserves structure. |
| `hallmark redesign <target> [--mood <name>]` | Throw out the structure, keep copy + IA + brand, rebuild with a deliberately different fingerprint. |
-| `hallmark study <screenshot>` | Extract the **DNA** from a design the user admires — macrostructure, archetypes, type-pairing role, colour anchor — and produce a diagnosis report. Optionally rebuild *the user's* content using the extracted DNA. Refuses paid templates and competitor pages. Names font roles, never font IDs. Never copies pixels. |
+| **`hallmark study <screenshot>`** | The differentiator. Extract the **DNA** from a design the user admires — macrostructure, archetypes, type-pairing role, colour anchor — and produce a diagnosis report. Optionally rebuild *the user's* content using the extracted DNA. **Refuses paid templates and competitor pages. Names font roles, never font IDs. Never copies pixels.** |
+
+---
+
+## Eight pages, eight different shapes
+
+Generated by exercising the skill across contrasting briefs. No two share a macrostructure or theme.
+
+<table>
+ <tr>
+ <td width="25%"><img src="site/_tests/_thumbs/01-tide.png" alt="Tide — Quote-Led + Atelier" /></td>
+ <td width="25%"><img src="site/_tests/_thumbs/02-streampipe.png" alt="Streampipe — Workbench + Terminal" /></td>
+ <td width="25%"><img src="site/_tests/_thumbs/03-maple.png" alt="Maple Street Bread — Long Document + Linen" /></td>
+ <td width="25%"><img src="site/_tests/_thumbs/04-meridian.png" alt="Meridian — Manifesto + Manifesto" /></td>
+ </tr>
+ <tr>
+ <td><b>Tide</b><br/><sub>Quote-Led · Atelier · indie podcast</sub></td>
+ <td><b>Streampipe</b><br/><sub>Workbench · Terminal · CSS-art mockup</sub></td>
+ <td><b>Maple Street Bread</b><br/><sub>Long Doc · Linen · hand-built SVG loaf</sub></td>
+ <td><b>Meridian</b><br/><sub>Manifesto · 11-section practice</sub></td>
+ </tr>
+ <tr>
+ <td><img src="site/_tests/_thumbs/05-tracejam.png" alt="Tracejam — Bento Grid + Pastel" /></td>
+ <td><img src="site/_tests/_thumbs/06-anya.png" alt="Anya — Long Document + Studio" /></td>
+ <td><img src="site/_tests/_thumbs/07-foundry.png" alt="Foundry — Stat-Led + Plain (pure white)" /></td>
+ <td><img src="site/_tests/_thumbs/08-cohort.png" alt="Cohort — Marquee Hero + Salon" /></td>
+ </tr>
+ <tr>
+ <td><b>Tracejam</b><br/><sub>Bento · Pastel · clipped-edge mockup</sub></td>
+ <td><b>Anya</b><br/><sub>Long Doc · Studio · personal one-pager</sub></td>
+ <td><b>Foundry</b><br/><sub>Stat-Led · Plain (#fff) · animated counter</sub></td>
+ <td><b>Cohort</b><br/><sub>Marquee Hero · Salon · continuous scroll</sub></td>
+ </tr>
+</table>
+
+Each page is its own self-contained HTML + CSS — no shared theme, no shared layout. Every one carries a `/* Hallmark · macrostructure: … */` stamp at the top of its CSS. See the full set under [`site/_tests/`](site/_tests/) or live at [hallmark-murex.vercel.app](https://hallmark-murex.vercel.app).
---
## What's inside
-- **[`SKILL.md`](skill/SKILL.md)** — the routing file. Design flow (six steps, including `Step 2.5 · Check project memory` reading `.hallmark/log.json`), slop test (35 questions), output contract.
-- **[`references/`](skill/references/)** — sixteen short, opinionated rule files: typography, colour, layout, motion, microinteractions, interaction-and-states, responsive, copy, anti-patterns, the 21 named macrostructures, the 36 component archetypes with variation knobs, the 6 primitive structure axes, the vision-extraction protocol for `study`, and three new files for hero work — `hero-enrichment.md` (when to add visuals to a hero, plus eight enrichment archetypes), `custom-craft.md` (how to hand-build CSS art, SVG, declarative animation, JS-driven motion, with Lottie demoted to last resort), and `assets.md` (sourcing canon for icons, brand logos, generated illustration via Nanobanana / Recraft, library illustration, app mockups, hero video, photography, abstract backgrounds).
-- **[`site/`](site/)** — a self-demonstrating landing page. Hand-written HTML + CSS + ES module, no framework, no build step. **Sixteen themes** — Specimen, Newsprint, Atelier, Garden, Salon, Linen, Almanac, Midnight, Terminal, Brutal, Manifesto, Sport, Studio, Pastel, Riso, **Quiet** — that swap not just colour and typography but the page's hero archetype and footer archetype. Switching themes literally rebuilds the page. The palette is deliberately balanced across the warm / cool / neutral spectrum: warm-paper themes (Specimen, Atelier, Newsprint, Salon, Riso), cool-paper themes (Linen-cool-slate, Studio-cool-grey, Garden, Almanac, Pastel, Sport), neutral-paper (Brutal, Quiet), and three dark themes (Midnight, Terminal, Manifesto) — no single hue band dominates. The "07 · Examples" section ships with **eight** generation tests (under [`site/_tests/`](site/_tests/)) — each a self-contained HTML + CSS demo of the skill, with a real visual thumbnail on the gallery card.
-- **[`ROADMAP.md`](ROADMAP.md)** — Tier 1, 2, 3 work plus an explicit "things to *not* do" list.
+- **[`SKILL.md`](skill/SKILL.md)** — the routing file. Six-step design flow (including `Step 2.5 · Check project memory` reading `.hallmark/log.json`), 38-question slop test, output contract.
+- **[`references/`](skill/references/)** — eighteen short, opinionated rule files: typography, colour, layout, motion, microinteractions, interaction-and-states, responsive, copy, anti-patterns, the 21 named macrostructures, the 36 component archetypes with variation knobs, the 6 primitive structure axes, the vision-extraction protocol for `study`, hero enrichment, custom-craft (CSS art over Lottie), assets, plus the new **[`recipes.md`](skill/references/recipes.md)** (8 worked briefs + a canonical try-it prompt) and **[`study-examples.md`](skill/references/study-examples.md)** (3 worked DNA-extractions).
+- **[`site/`](site/)** — a self-demonstrating landing page. Hand-written HTML + CSS + ES module, no framework, no build step. **Sixteen themes** balanced across the warm / cool / neutral spectrum: warm-paper (Specimen, Atelier, Newsprint, Salon, Riso), cool-paper (Linen-cool-slate, Studio-cool-grey, Garden, Almanac, Pastel, Sport), neutral (Brutal, Quiet), dark (Midnight, Terminal, Manifesto). Switching themes literally rebuilds the page — different hero archetype, different footer archetype.
+
+---
+
+## What's distinct (the long list)
+
+- **One skill, five verbs.** Not eighteen commands.
+- **Tone is a first-class decision.** "Clean and modern" is rejected. Pick an extreme — *editorial · brutalist · soft · technical · luxury · playful · austere*.
+- **Macrostructures over axes.** Pick one of 21 named whole-page shapes wholesale; the macrostructure stamp lives in the CSS comment, so the next Hallmark run picks something different.
+- **Within-archetype variation.** Two Bento Grids should not be twins; each archetype has 2–3 picked-per-output knobs.
+- **Microinteractions as discipline.** Silent success over celebratory toasts. Optimistic update + Undo over confirm dialogs. Hover delay 800 ms, focus delay 0 ms.
+- **A 38-gate slop test** runs before every output. One yes fails the build. Recent additions: no horizontal scroll between 320–1920 px (gate 36), decorative effects on text must be visually verified to sit at x-height not baseline (gate 37), interactive bars must declare `align-items: center` (gate 38).
+- **Project memory.** A per-project `.hallmark/log.json` records each run's macrostructure + theme + enrichment + brief summary. The skill reads the last 3–5 entries before picking and writes a new entry after each build, so consecutive Hallmark outputs in the same project don't repeat shapes or themes.
+- **Theme-diversification rule.** Two consecutive themes must differ on at least one of three axes: paper band (dark / mid / light), display style (italic-serif / roman-serif / geometric-sans / mono / display-heavy / system-native), accent hue (warm / cool / neutral / chromatic-other).
+- **Voice fixtures over LLM defaults.** Each of the 21 macrostructures ships with 2–3 example opening lines from real designer-engineer sites (Pentagram, Klim, Linear, Are.na, Resend, Lynn Fisher, Rauno Freiberg…). "Built for the modern team" is in the banned-phrases list.
+- **Hero enrichment is opt-in.** A typographic-only hero is always acceptable. When enrichment is right, the skill picks from a six-tier hierarchy: typography only → custom-built CSS art → hand-built SVG → generated illustration (Nanobanana / Recraft) → library → Lottie (last resort).
+- **Microinteractions default-on for SaaS-shaped archetypes.** Bento Grid, Stat-Led, Workbench, Marquee Hero pages ship with 2–3 purposeful microinteractions (number reveal, pricing lift, marquee, stagger) without the user having to ask. Editorial / Manifesto / Letter / Quote-Led pages stay still.
+- **SaaS page sequence.** Hero → social proof → features → testimonials → pricing → FAQ → CTA → footer. Real prices, not "contact sales for pricing." Specific testimonials with role + company.
+- **Wordmark may use a different display face.** A Geist-bodied SaaS page can set its wordmark in Fraunces. Same-family collapse on Bento / Stat-Led / Workbench / Marquee Hero is the new "un-branded" tell.
+- **`study` extracts DNA, not pixels.** Refusal heuristics, type-role vocabulary (no font ID guessing), confirmation step before any code. Three worked examples in [`study-examples.md`](skill/references/study-examples.md).
---
@@ -51,28 +135,9 @@ To preview the landing page locally:
cd site && python3 -m http.server 4173 # → http://localhost:4173
```
-Or visit the live deploy at **[hallmark-murex.vercel.app](https://hallmark-murex.vercel.app)**.
-
-Press `T` to cycle themes, `R` for random, `?theme=studio` for a shareable link.
-
----
-
-## What's distinct
+Press `T` to cycle themes, the **shuffle button** (or `R`) to randomise, `?theme=studio` for a shareable link.
-- **One skill, five verbs.** Not eighteen commands.
-- **Tone is a first-class decision.** "Clean and modern" is rejected. Pick an extreme.
-- **Macrostructures over axes.** Pick one of 21 named whole-page shapes wholesale; the macrostructure stamp lives in the CSS comment, so the next Hallmark run picks something different.
-- **Within-archetype variation.** Two Bento Grids should not be twins; each archetype has 2–3 picked-per-output knobs.
-- **Microinteractions as discipline.** Silent success over celebratory toasts. Optimistic update + Undo over confirm dialogs. Hover delay 800 ms, focus delay 0 ms.
-- **A 38-gate slop test** runs before every output. One yes fails the build. Three new gates added in v0.6.0: gate 36 (no horizontal scroll between 320 px and 1920 px — `html { overflow-x: clip }` is mandatory under any clipped-edge enrichment), gate 37 (decorative effects on text — highlighter bands, accent strokes, underlines — must be visually verified to sit in the right vertical zone, not at the baseline like a fat underline), gate 38 (interactive bars must declare `align-items: center` and `line-height: 1` — inheriting line-height fights vertical rhythm).
-- **Project memory.** A per-project `.hallmark/log.json` records each run's macrostructure + theme + enrichment + brief summary. The skill reads the last 3–5 entries before picking, and writes a new entry after each build, so consecutive Hallmark outputs in the same project don't repeat shapes or themes.
-- **Theme-diversification rule.** Two consecutive themes must differ on at least one of three axes: paper band (dark / mid / light), display style (italic-serif / roman-serif / geometric-sans / mono / display-condensed-italic / display-heavy / system-native / risograph), accent hue (warm / cool / neutral / chromatic). Specimen-fall-through is no longer the only diversification check.
-- **Voice fixtures over LLM defaults.** Each of the 21 macrostructures ships with 2–3 example opening lines from real designer-engineer sites (Pentagram, Klim, Linear, Are.na, Resend, Lynn Fisher, Rauno Freiberg, etc.). Each of seven tones in `copy.md` has three voice patterns × five sample sentences. "Built for the modern team" is in the banned-phrases list.
-- **Hero enrichment is opt-in, not a default.** A typographic-only hero is always acceptable. When enrichment is right, the skill picks from a six-tier hierarchy: typography only → custom-built CSS art → hand-built SVG → generated illustration (Nanobanana / Recraft) → library + customise → Lottie (last resort).
-- **Microinteractions are default-on for SaaS-shaped archetypes.** Bento Grid, Stat-Led, Workbench, Marquee Hero, and Conversational FAQ pages ship with 2–3 small purposeful microinteractions (number reveal on stats, pricing card lift, marquee scroll, recommended-tier pulse, stagger reveal on testimonials) without the user having to ask. Editorial / Manifesto / Letter / Quote-Led pages stay still — stillness is the brand on those.
-- **SaaS page sequence.** When the macrostructure is a SaaS-typical archetype, ship hero → social proof / logo wall → features → testimonials → pricing → FAQ → CTA → footer by default. Real prices, not "contact sales for pricing" on every tier; specific testimonials with role and company, not abstract job titles.
-- **Wordmark may use a different display face.** A Geist-bodied SaaS page can set its wordmark in Fraunces; a Crimson-Pro-bodied compliance page can use IBM Plex Mono. Same-family collapse on Bento / Stat-Led / Workbench / Marquee Hero archetypes is the new "un-branded" tell.
-- **`study` extracts DNA, not pixels.** Vision-extraction with refusal heuristics, type-role vocabulary (no font ID guessing), and a confirmation step before any code.
+Or visit the live deploy at **[hallmark-murex.vercel.app](https://hallmark-murex.vercel.app)**.
---
@@ -84,13 +149,16 @@ Built on the open work of:
- tw93's [**kami**](https://github.com/tw93/kami) — the slop-test concept and 20-question scoring
- Leonxlnx's [**taste-skill**](https://github.com/Leonxlnx/taste-skill) — taste vocabulary and the audit verb
- Anthropic's [**frontend-design**](https://github.com/anthropics/skills) and [**canvas-design**](https://github.com/anthropics/skills) skills — the design-context-gate pattern
+- nexu-io's [**Open Design**](https://github.com/nexu-io/open-design) — the deterministic anti-AI-slop checklist; convergent inspiration for several gates
+- [**Dembrandt**](https://github.com/dembrandt/dembrandt) — DTCG token-export pattern (informed Tier-2 roadmap; not yet implemented in Hallmark)
- Google Stitch's [**DESIGN.md**](https://getdesign.md) — single-source design docs
- Marie Claire Dean's [**63 design skills for Claude**](https://marieclairedean.substack.com/p/i-built-63-design-skills-for-claude) — coverage map
- Steve Barclay's [**PencilPlaybook**](https://github.com/stevembarclay/pencilplaybook) — the design-language playbook format
- The [**Slopless**](https://slopless.design) tactile-rebellion canon — the 2026 anti-AI-perfect movement (informed Studio, Pastel, Riso)
+- [925studios' AI Slop Web Design Guide](https://www.925studios.co/blog/ai-slop-web-design-guide) — the canonical slop-tells vocabulary
- Anthropic's [**Skill Engineering**](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) writeup — file budgets, load-on-demand patterns, frontmatter shape
-Where rules overlapped, Hallmark adopted; where they diverged, Hallmark picked.
+Where rules overlapped, Hallmark adopted. Where they diverged, Hallmark picked.
---
diff --git a/docs/img/theme-brutal.png b/docs/img/theme-brutal.png
new file mode 100644
index 0000000..546d1fa
Binary files /dev/null and b/docs/img/theme-brutal.png differ
diff --git a/docs/img/theme-newsprint.png b/docs/img/theme-newsprint.png
new file mode 100644
index 0000000..9362292
Binary files /dev/null and b/docs/img/theme-newsprint.png differ
diff --git a/docs/img/theme-specimen.png b/docs/img/theme-specimen.png
new file mode 100644
index 0000000..2220edd
Binary files /dev/null and b/docs/img/theme-specimen.png differ
diff --git a/docs/img/theme-studio.png b/docs/img/theme-studio.png
new file mode 100644
index 0000000..71ff99f
Binary files /dev/null and b/docs/img/theme-studio.png differ
diff --git a/skill/SKILL.md b/skill/SKILL.md
index 4dab595..acdd391 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -122,6 +122,8 @@ The non-negotiables live in [`references/`](references/). Read only what you nee
- [`custom-craft.md`](references/custom-craft.md) — *how* to hand-build hero artwork: pure CSS art, hand-built SVG, declarative animation (`@property`, `animation-timeline`, View Transitions), JS-driven (Motion / GSAP), and when Three.js earns its place. Load only when an enrichment archetype requires construction.
- [`assets.md`](references/assets.md) — the sourcing catalogue: icons (Lucide / Phosphor / Heroicons / Tabler), brand logos (Simple Icons / SVGL), generated illustration (Nanobanana 2 / Recraft V4 / Midjourney), library illustration, app mockups, hero video, photography, abstract backgrounds, Lottie. Per-category rules and what to avoid. Load only when an enrichment archetype actually needs an external asset.
- [`study.md`](references/study.md) — vision-extraction protocol for the `hallmark study` verb (load only when that verb runs)
+- [`study-examples.md`](references/study-examples.md) — three worked DNA-extractions (Pentagram-style portfolio · Klim-style specimen · Rauno-style personal site) showing the diagnose → confirm → build flow end-to-end. Load whenever `study` runs and the user wants to see what a good DNA-extraction looks like before pasting their own screenshot.
+- [`recipes.md`](references/recipes.md) — eight worked briefs with the prompt, inferred trio, picked macrostructure + theme + enrichment, and a one-paragraph excerpt of the output. The first recipe (Coffeebox) is the canonical try-it prompt the README points users at. Load when the user asks "what does Hallmark output look like?" or wants a near-match for a brief in hand.
For most design work you need `macrostructures`, `component-cookbook`, `typography`, `color`, `layout-and-space`, and `anti-patterns`. **Load `microinteractions` whenever the output has *any* interactive element** — buttons, links, inputs, forms, modals, tabs, dropdowns, toasts, drag handles, command palettes, copy buttons, anything with hover/focus/active states. That is most pages.
diff --git a/skill/references/recipes.md b/skill/references/recipes.md
new file mode 100644
index 0000000..7b5f62c
--- /dev/null
+++ b/skill/references/recipes.md
@@ -0,0 +1,186 @@
+# Recipes — copy-paste prompts that ship Hallmark output
+
+Eight worked briefs you can paste into Claude Code, Cursor, or Codex with the Hallmark skill installed. Each shows the prompt verbatim, the audience/use/tone the skill inferred, the macrostructure + theme + enrichment it picked, and a one-paragraph excerpt of the output. Live page links are included where the test exists in [`site/_tests/`](../../site/_tests/).
+
+The first recipe is the **canonical try-it prompt** — paste it into a fresh project to verify the skill is installed and discover the flow before reading anything else.
+
+---
+
+## 00 · Try it · Coffeebox
+
+**Prompt** (copy/paste verbatim):
+
+> *"Build me a landing page for Coffeebox — a small-batch coffee subscription. Roast on Sunday, ship on Monday, drink Tuesday. Audience: people who already buy good coffee and want fewer trips to the shop. Tone: warm, hand-set, editorial — like a small café's chalkboard."*
+
+**Inferred trio:** explicit (audience: serious-coffee buyers · use: subscribe · tone: editorial-warm).
+
+**Picks:** Long Document · **Linen** (warm-paper roman-serif) · Tier-B hand-built SVG (a small coffee-bean icon, optional).
+
+**Excerpt of the output:**
+
+> *"Coffeebox · est. 2026 · n.º 12.* The first roast leaves the drum at 6:14 a.m. Sunday. By Monday morning it's in a paper bag in your post box. By Tuesday the kitchen smells like a café. Subscribe, skip a week, change the roast — all from the email. We bake what we baked yesterday. We ship what shipped well. We answer the email ourselves."
+
+**Why this is the canonical try-it:** the brief has explicit context (no design-context-gate friction), an editorial tone (different from any AI-default landing page), and a domain (coffee subscription) that has zero overlap with SaaS/dev-tool clichés. If Hallmark produces *Linen-with-italic-Cormorant-and-warm-paper* for this prompt, the skill is wired correctly.
+
+---
+
+## 01 · Tide · Indie podcast
+
+**Prompt:**
+
+> *"Design a landing page for Tide — an indie podcast about long-form interviews with small-studio designers. Just go ahead, pick the rest yourself."*
+
+**Inferred trio** (the user opted out): audience = designers, design-curious listeners · use = listen + subscribe · tone = quiet editorial.
+
+**Picks:** Quote-Led · **Atelier** (warm cream, italic Newsreader) · no enrichment (typography only).
+
+**Excerpt:**
+
+> *"A page should arrive like a person — composed, deliberate, in good clothes." — from the salon.* The hero is the pull-quote. The page below: episode list, host bio, RSS feed. No mockups. No demo. The voice carries the brand.
+
+**Live:** [`_tests/01-tide-podcast/`](../../site/_tests/01-tide-podcast/index.html)
+
+---
+
+## 02 · Streampipe · Open-source CLI
+
+**Prompt:**
+
+> *"Build me a landing page for Streampipe — a small, fast, single-binary CLI for parsing log and event streams from stdin. Filter, transform, route. Composes with anything that emits lines. Audience: developers. Use: install + read docs. Tone: technical. Use the Terminal theme."*
+
+**Inferred trio:** explicit. **Theme requested.**
+
+**Picks:** Workbench · **Terminal** (dark phosphor-green, mono everywhere) · Tier-A hand-built CSS-art terminal mockup (no Lottie, no real video).
+
+**Excerpt:**
+
+> *"$ streampipe --help.* A small, fast, single-binary CLI for parsing log and event streams from stdin. Filter, transform, route. Composes with anything that emits lines.* Then three install snippets in a phosphor-green code block: brew · npm · curl. To the right, a hand-built CSS-art terminal showing `streampipe parse access.log --filter status=5xx` with sample JSON output. Pure CSS, no scripts.
+
+**Live:** [`_tests/02-streampipe-cli/`](../../site/_tests/02-streampipe-cli/index.html)
+
+---
+
+## 03 · Maple Street Bread · Artisan bakery
+
+**Prompt:**
+
+> *"Build a landing page for Maple Street Bread — a small artisan bakery in Lisbon. Sourdough, slow, by hand. We open at seven, thirty loaves, gone by noon, no online orders. Audience: locals. Use: see what we bake, find us. Tone: warm, hand-set."*
+
+**Inferred trio:** explicit.
+
+**Picks:** Long Document · **Linen** (warm-paper, geometric-sans display, low-chroma) · Tier-B hand-built SVG (a 60-line loaf with a `@property --rise` 6 s breathing-loop animation).
+
+**Excerpt:**
+
+> *"Maple Street · est. 2026 · n.º 47.* Saturday, 6:14 a.m. The dough went in at midnight. By the time the lights are on outside, the bench is dusted, the loaves are scored, and the oven is hotter than a summer roof.* Drop-cap "T" on the lede. Loaves list with prices in a margin-aligned column. Visit-and-hours in a colophon at the bottom. No CTA — the brief is "find us," not "convert."
+
+**Live:** [`_tests/03-maple-bakery/`](../../site/_tests/03-maple-bakery/index.html)
+
+---
+
+## 04 · Meridian · Studio manifesto
+
+**Prompt:**
+
+> *"A studio manifesto for Meridian — a small environmental-products design practice in Lisbon. Declarative, no flashy stuff."*
+
+**Inferred trio** (partial): audience = practice peers + clients · use = read it + sign on or move on · tone = declarative editorial.
+
+**Picks:** Manifesto · **Manifesto** (dark, Inter Tight 900 display, single red accent band) · no enrichment.
+
+**Excerpt:**
+
+> *"WE ARE A STUDIO. WE ARE NOT A PLATFORM."* Then five numbered declarations, a bleed-colour band between III and IV ("This is not a roadmap. This is what we believe before we open the laptops."), then four supporting sections: § What we refuse (anti-list with strikethrough) · § Working rules (numbered ops) · § The practice (3-paragraph narrative with drop-cap) · § What we read (annotated bibliography).
+
+**Live:** [`_tests/04-meridian-manifesto/`](../../site/_tests/04-meridian-manifesto/index.html)
+
+---
+
+## 05 · Tracejam · SaaS observability
+
+**Prompt:**
+
+> *"Build me a landing page for Tracejam — a tracing/observability tool for distributed systems. Audience: SREs and platform engineers. Use case: try it / contact sales. Tone: technical."*
+
+**Inferred trio:** explicit.
+
+**Picks:** Bento Grid · **Pastel** (light-cool paper, geometric Geist sans, low-chroma indigo accent) · Tier-A hand-built CSS-art trace waterfall (the right-clipped browser-frame mockup that pushes 12 vw past the viewport edge).
+
+**Excerpt:**
+
+> *"Tracejam · v0.4 · for SREs. Distributed tracing that explains itself.* Open the trace, find the span that regressed, and read why — in plain text — without a glossary, a YAML diff, or a status-page hunt.* Hero left-aligned with two CTAs (Try it free / Talk to sales). To the right, a clipped browser-frame mockup containing a hand-built CSS-art flame chart. Below the hero, a 6-tile Bento with stat / sparkline / pull-quote / code snippet / integrations list / spotlight.
+
+**Live:** [`_tests/05-tracejam-saas/`](../../site/_tests/05-tracejam-saas/index.html)
+
+---
+
+## 06 · Anya · Personal one-pager
+
+**Prompt:**
+
+> *"Personal site for Anya — software architect in Lisbon. Don't ask, just figure it out."*
+
+**Inferred trio** (the user opted out): audience = engineering hiring managers · use = read who I am, see my work · tone = austere, italic-editorial.
+
+**Picks:** Long Document · **Studio** (cool grey paper, italic Fraunces display, forest-green accent) · no enrichment.
+
+**Excerpt:**
+
+> *"Hello, I'm Anya."* (with a green highlighter mark behind "Anya"). I help engineering organisations ship hard distributed-systems work — multi-region rollouts, payment graphs, eventually-consistent ledgers — without breaking the people doing the shipping.* Tabular work-sheet below: years per company, stripe-monzo-and-a-small-infra-startup-that-didn't-survive-2023.
+
+**Live:** [`_tests/06-anya-portfolio/`](../../site/_tests/06-anya-portfolio/index.html)
+
+---
+
+## 07 · Foundry · Compliance SaaS
+
+**Prompt:**
+
+> *"Build me a landing page for Foundry — SOC 2 and ISO 27001 compliance automation for B2B SaaS. Show: how many companies got compliant, what it costs, who uses it. Audience: founders + CTOs. Tone: technical but trustworthy."*
+
+**Inferred trio:** explicit.
+
+**Picks:** Stat-Led · **Plain** (pure-white paper #ffffff, near-neutral cool greys, deep ink-blue accent, Inter Tight display-heavy + Bricolage Grotesque wordmark) · no enrichment.
+
+**Excerpt:**
+
+> *"847.* companies passed audit using Foundry. Average time to compliant: thirty-one days, against an industry average of nine months." — the "847" sized at 22 rem display, animated counting from 0 over 1.4 s on first viewport entry. Below: customer logo wall (8 monochrome wordmarks), three supporting stats, four feature cards, three pull-quote testimonials with role + company, three pricing tiers (Starter $299/mo · Team $899/mo recommended · Scale custom), eight-question conversational FAQ, single-line final CTA, four-column index footer.
+
+**Live:** [`_tests/07-foundry-compliance/`](../../site/_tests/07-foundry-compliance/index.html)
+
+---
+
+## 08 · Cohort · Cohort-based courses
+
+**Prompt:**
+
+> *"Build a landing page for Cohort — the platform for cohort-based courses. Run live courses with 30 to 500 students. Built for educators, not LMS sales teams. Audience: course operators + indie creators. Tone: warm, salon-room, editorial."*
+
+**Inferred trio:** explicit.
+
+**Picks:** Marquee Hero · **Salon** (warm-cream paper, IBM Plex Mono display + Cormorant Garamond serif, warm-amber accent, centered emphasis) · Tier-A continuous CSS marquee (course titles + instructor names scrolling at 50 s, pauses on hover, stops on prefers-reduced-motion).
+
+**Excerpt:**
+
+> Marquee band scrolling across the top: *"Build a SaaS in 30 days · Sahil Lavingia · Writing Strong · David Perell · Notion for Operators · Marie Poulin..."* Below: *"Cohort runs live courses the way your favourite teacher would — with a date, a roster, and a room."* Two CTAs (Run your first cohort / 90-second tour). Then alternating-side feature rows with hand-built CSS card-stack / hours-grid / thread / report visuals. Two-tier pricing. Six-question FAQ. Centered Salon footer.
+
+**Live:** [`_tests/08-cohort-courses/`](../../site/_tests/08-cohort-courses/index.html)
+
+---
+
+## How the recipes are organised
+
+Every recipe shares the same four lines so you can scan a brief and immediately see *which combination Hallmark picks for what*:
+
+1. **Prompt** — verbatim, copy/paste-ready.
+2. **Inferred trio** — what the design-context-gate produces (audience · use · tone). Marked `explicit` if the user provided all three; `the user opted out` if not.
+3. **Picks** — macrostructure · theme · enrichment archetype.
+4. **Excerpt** — one paragraph of the produced copy or layout, so you can verify the output matches the brief without running the skill yet.
+
+When generating something new, look for the closest match in this file and **note what's different** between your brief and the recipe. The macrostructure pick is usually inherited; the theme often shifts (per the diversification rule); enrichment may change tier.
+
+## What the recipes are *not*
+
+- Not templates. Hallmark's whole point is structural variety — duplicating a recipe verbatim is the **Specimen-fall-through** anti-pattern (gate 23 in [`SKILL.md`](../SKILL.md)).
+- Not fixed picks. Two consecutive runs of recipe 00 (Coffeebox) on the same project should produce *different* macrostructures or themes — the [`.hallmark/log.json`](../SKILL.md) project memory enforces this.
+- Not exhaustive. The 21 macrostructures × 16 themes × 8 enrichment archetypes = 2,688 distinct fingerprints. The 9 recipes here are a starter set; the next 50 are yours to discover.
diff --git a/skill/references/study-examples.md b/skill/references/study-examples.md
new file mode 100644
index 0000000..8aa3678
--- /dev/null
+++ b/skill/references/study-examples.md
@@ -0,0 +1,176 @@
+# `hallmark study` — three worked examples
+
+How `study` reads a screenshot the user admires, returns a diagnosis, and (optionally) rebuilds the user's content with the extracted DNA. Each worked example below shows: what the user pasted · what the skill names · what it refuses to do · what it produces.
+
+The whole point of `study`: extract **structural DNA** (macrostructure + archetypes + type-pairing role + colour anchor + rhythm), **never pixels**. If the user wants a 1:1 copy, they want a different tool. Hallmark hands them a diagnosis and lets them keep the bones.
+
+---
+
+## Example A · A Pentagram-style editorial portfolio
+
+**What the user pastes:** a screenshot of a New York studio's portfolio site — large italic-serif name in the top-left margin, numbered project list flowing down the page, generous warm-cream paper, a single warm-orange accent on the active project, a hairline rule between rows. (User says: *"I want my portfolio to feel like this.")*
+
+### Refuse-or-proceed check
+
+Public reference for inspiration → proceed. (Refusal heuristics fire on: paid-template-marketplace listings, competitor live marketing pages, copy-protected portfolios. None match.)
+
+### Diagnosis report (what `study` returns first)
+
+> **Macrostructure:** **Specimen** (numbered left-margin labels + huge italic serif + asymmetric spans + typographic-only CTA).
+>
+> **Hero archetype:** H4 Margin-Number Display — the page's only anchor is a vertical column of two-digit indices.
+>
+> **Pitch archetype:** none. The work is the pitch.
+>
+> **Footer archetype:** Ft1 Single-Line Colophon — studio name, year, contact, three links, no nav.
+>
+> **Display family role:** italic editorial serif (high optical size, soft axis, ink-black). **Body family role:** geometric sans (humanist Inter-Tight-or-similar at 350-400 weight). Two free candidates: *Fraunces* italic display + *Geist* body. One paid candidate the user might confirm: *Tiempos Headline* + *Söhne*. The skill names *roles*, not exact font IDs — visual font ID is unreliable.
+>
+> **Surface lightness band:** light (paper L ≈ 96%). Slight warm tint at hue 80 — Pentagram-warm cream, not stark white.
+>
+> **Accent hue band + chroma:** warm-orange ~25-30°, low chroma (≤ 0.13), used at < 5% of viewport. One accent, applied to active state and the one number the brand wants the visitor to remember.
+>
+> **Density verdict:** sparse. ~3-4 macro elements on the first viewport. Generous vertical margin between rows (≥ `--space-3xl`).
+>
+> **Type-pairing role:** italic-display + sans-body — the canonical editorial pairing.
+>
+> **Two anti-patterns the screenshot has** that you should NOT carry over:
+>
+> 1. The hover-state on the number-label uses a slow ease-in-out 800 ms colour fade. Per `microinteractions.md` § The timing canon, hover state should be 150–200 ms. Carry the *idea* (colour-shift on hover); shorten the *duration*.
+> 2. The footer text is set at 11 px with 0.06em tracking — under the 14 px floor for body copy. Bump to 12-13 px on rebuild, keep the tracking.
+
+### Confirmation question
+
+> *"Adopt this DNA wholesale, or change one axis? For example, I could keep the macrostructure (Specimen) but pick a theme that better matches your work — if your tone is more ink-blue and B2B, I'd suggest **Plain** (pure-white paper) instead of the warm-cream **Specimen** theme."*
+
+### What `study` builds when the user says "go"
+
+Macrostructure stamp:
+```css
+/* Hallmark · macrostructure: Specimen · H4 hero knobs: number-column=margin, alignment=left-bias
+ * theme: Specimen · accent: warm-orange ~3% · enrichment: none
+ * studied: yes · DNA-source: user reference · paid-fonts: not confirmed (free pairing applied)
+ */
+```
+
+Output: the user's actual portfolio entries arranged in a numbered-margin column with italic-Fraunces titles and Geist-body summaries. Hover delays shortened to 200 ms. Footer text bumped to 12 px. The bones come from the screenshot; the words and projects come from the user.
+
+---
+
+## Example B · A Klim-Type-Foundry-leaning specimen
+
+**What the user pastes:** a screenshot of a type-specimen page — full-bleed black paper, single huge geometric-sans display character ("R") tilted -2°, a ruled grid behind it, a footer-band with the typeface name, weight, OpenType features, and a tiny set of glyph callouts. (User says: *"This is the energy I want for our agency rebrand.")*
+
+### Refuse-or-proceed check
+
+Type specimens are typically published references; proceed. (If the screenshot were a paid font foundry's marketing page with an explicit "preview is licensed" watermark, the skill would refuse and ask the user to bring an unconfirmed reference.)
+
+### Diagnosis report
+
+> **Macrostructure:** **Type Specimen** (single character or word centred + ruled grid + footer-band of metadata).
+>
+> **Hero archetype:** H9 Single-Glyph — the entire above-the-fold is one letterform.
+>
+> **Pitch archetype:** none on the first viewport. The page is *the work being specified*. Pitch (if any) lives below the fold as supporting paragraphs.
+>
+> **Footer archetype:** Ft3 Tabular-Specimen — name · weight · OpenType features · designer credit.
+>
+> **Display family role:** geometric-sans-heavy (display-display, weights 800-900). **Body family role:** the same sans at 400 — single-font specimen pages are allowed when the single font *is* the design (per `typography.md`). Free candidate: *Bricolage Grotesque 800*. Paid candidate: *Druk* or *NaN Jaune*. *Refuse to guess the exact paid font ID.*
+>
+> **Surface lightness band:** dark (paper L ≈ 12%). The dark is uniform across the viewport — no gradient.
+>
+> **Accent hue band + chroma:** chromatic-other — single hot-orange callout at ≈ 0.18 chroma, used on **one** OpenType-feature label. Even in a stark specimen, the rule "accent < 5% of viewport" holds.
+>
+> **Density verdict:** ultra-sparse. One element above the fold. Density only increases below.
+>
+> **Type-pairing role:** single-family specimen (single-font is the design). Body and display the same family at different weights.
+>
+> **Two anti-patterns the screenshot has** to NOT carry over:
+>
+> 1. The footer-band uses light-grey text (oklch ~75% lightness) on near-black paper. Contrast ratio ~3.2:1 — fails WCAG AA for body. Bump to oklch ~88% on rebuild.
+> 2. The grid lines behind the glyph are at 1 px solid white at 0.4 opacity. On a 4K display this becomes a sub-pixel that disappears or aliases. Use 1 px solid + colour-mix down to 35% lightness instead — keeps visibility across pixel densities.
+
+### Confirmation question
+
+> *"This DNA is for a specimen page, not a marketing page. If you're rebranding an agency, the glyph hero will be impressive on the first visit and pointless after. Suggested adaptation: Type Specimen as the homepage, then a Long Document or Workbench pattern for the about / case-studies / contact pages. Pick: keep all-Specimen, or hybrid?"*
+
+### What `study` builds (hybrid path)
+
+Macrostructure stamp:
+```css
+/* Hallmark · macrostructure: Type Specimen · H9 hero knobs: glyph=user-mark, tilt=-2deg, grid=1px-soft
+ * theme: Manifesto · accent: hot-orange ~3% · enrichment: none
+ * studied: yes · DNA-source: user reference · paid-fonts: not confirmed (Bricolage 800 free)
+ */
+```
+
+The homepage emits the agency's mark in 22-rem Bricolage 800, ruled grid behind, single-line metadata footer. The about and case-study pages inherit the dark-paper + geometric-sans tokens but switch to **Workbench** macrostructure (left-margin index + 1fr content). Brand consistency, structural variety.
+
+---
+
+## Example C · A small-studio personal site (Rauno-Freiberg-style)
+
+**What the user pastes:** a screenshot of a personal designer-engineer site — dark-mode paper, a small italic-serif name in the top-left, a single demo embed at the centre (CSS-art clock that ticks), a writing list below. (User says: *"I want my own personal site to feel like this.")*
+
+### Refuse-or-proceed check
+
+A *competitor's live portfolio* is the edge case here. Per `study.md` § Refusal heuristics: if the user is in the same domain as the screenshot subject, ask first.
+
+> *"Is this your own work, a public reference for inspiration, or someone else's live site? If it's someone else's live site, I'll extract the DNA at the structural level only — no copy, no demos, no font IDs — and you'll bring your own content. If it's a paid portfolio template, I won't reproduce it."*
+
+User confirms: public reference for inspiration → proceed with DNA extraction only.
+
+### Diagnosis report
+
+> **Macrostructure:** **Long Document** with a centred demo as the hero archetype.
+>
+> **Hero archetype:** H5 Centered-Demo — a single hand-built artefact (CSS art, SVG illustration, declarative animation) sized at ~24 rem, centred on the page, no other hero copy above it.
+>
+> **Pitch archetype:** P3 List-of-Writings — title + date + 1-line summary, in a tabular column.
+>
+> **Footer archetype:** Ft1 Single-Line Colophon.
+>
+> **Display family role:** italic editorial serif. **Body family role:** geometric sans, body weight 400. Free candidate pairing: *Fraunces* italic + *Geist*.
+>
+> **Surface lightness band:** dark (paper L ≈ 16%). Slight cool tint at hue 240. Inks at ~90-95% L, also slight cool.
+>
+> **Accent hue band + chroma:** chromatic-other — green at hue 145, ≈ 0.14 chroma. Used on the active demo's signal element (the ticking dot), nowhere else.
+>
+> **Density verdict:** sparse-medium. Hero demo + ~12-line writing list above the fold.
+>
+> **Type-pairing role:** italic-display-with-sans-body — same as Specimen, just on dark paper.
+>
+> **One anti-pattern the screenshot has** to NOT carry over:
+>
+> 1. The CSS-art clock loops at 1 fps with no `prefers-reduced-motion` fallback. **Always pair declarative animation with a reduced-motion alternative** (`microinteractions.md` § Reduced motion is a first-class state, not an afterthought).
+>
+> One thing the screenshot does *better than most* and you SHOULD carry over:
+>
+> 1. The italic name in the top-left has a baseline at the same y-position as the centred demo's vertical centre — a subtle horizontal-baseline alignment that makes the page feel composed rather than stacked. Carry this; it's invisible until removed.
+
+### Confirmation question
+
+> *"The DNA is portable: dark paper · italic-Fraunces name · centred demo · cool-green accent. Two questions before I build: (1) what's your demo? — I can hand-build it as Tier-A CSS art if you describe it, or you can paste an existing animation. (2) do you have ~5 writings to seed the list, or should I leave a placeholder section?"*
+
+### What `study` builds when the user provides their own demo + writings
+
+Macrostructure stamp:
+```css
+/* Hallmark · macrostructure: Long Document · H5 hero knobs: demo=centered, size=24rem
+ * theme: Midnight · accent: forest-green ~3% · enrichment: Tier-A custom-craft (user-supplied recipe)
+ * studied: yes · DNA-source: user reference · with reduced-motion fallback
+ */
+```
+
+Output: the user's actual name in italic-Fraunces top-left, their demo (e.g. an ambient breathing-loop) hand-built as CSS art with an explicit `@media (prefers-reduced-motion: reduce)` fallback, their writings tabulated below in Geist body. The bones from the screenshot; the demo and writings from the user. **No pixel-faithful reproduction.**
+
+---
+
+## What `study` doesn't do (worth restating)
+
+1. **Names the font role, not the font ID.** Visual font identification is unreliable. The skill proposes one or two real candidates from the canon and asks the user to confirm.
+2. **Never copies pixels.** The DNA is the macrostructure + archetype + colour-anchor + type-pairing — not the dress.
+3. **Refuses the obvious bad sources.** Paid-template-marketplace listings; competitor live marketing pages without explicit user confirmation; copy-protected portfolios without permission.
+4. **Always disclosures the substitutions.** When the screenshot's font is paid (Tiempos / Söhne / Druk) and the user hasn't confirmed a licence, the skill names a free understudy (Fraunces / Inter Tight / Bricolage Grotesque) and *says it's substituting*.
+
+These three examples cover the most common categories of `study` request: an editorial portfolio, a type-specimen statement page, and a small personal site. The protocol is the same for every screenshot — refuse-or-proceed, diagnose, confirm, build. See [`study.md`](study.md) for the full protocol.