Skip to content

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

CSS

Hero enrichment + custom-craft canon + Quiet theme

Youssefb5b21ceebf16
diff --git a/README.md b/README.md
index ace7ae9..ca9b7a4 100644
--- a/README.md
+++ b/README.md
@@ -28,9 +28,9 @@ The differentiator: Hallmark insists on **structural variety**, not just visual
## What's inside
-- **[`SKILL.md`](skill/SKILL.md)** — the routing file. Design flow, slop test (29 questions), output contract.
-- **[`references/`](skill/references/)** — fourteen short, opinionated rule files: typography, colour, layout, motion, microinteractions, interaction-and-states, responsive, copy, anti-patterns, the 21 named macrostructures, the 33 component archetypes with variation knobs, the 6 primitive structure axes, and the vision-extraction protocol for `study`.
-- **[`site/`](site/)** — a self-demonstrating landing page. Hand-written HTML + CSS + ES module, no framework, no build step. **Fifteen themes** — Specimen, Newsprint, Atelier, Garden, Salon, Linen, Almanac, Midnight, Terminal, Brutal, Manifesto, Sport, **Studio**, **Pastel**, **Riso** — that swap not just colour and typography but the page's hero archetype and footer archetype. Switching themes literally rebuilds the page.
+- **[`SKILL.md`](skill/SKILL.md)** — the routing file. Design flow, slop test (33 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.
- **[`ROADMAP.md`](ROADMAP.md)** — Tier 1, 2, 3 work plus an explicit "things to *not* do" list.
---
@@ -60,7 +60,8 @@ Press `T` to cycle themes, `R` for random, `?theme=studio` for a shareable link.
- **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 29-gate slop test** runs before every output. One yes fails the build.
+- **A 33-gate slop test** runs before every output. One yes fails the build.
+- **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).
- **`study` extracts DNA, not pixels.** Vision-extraction with refusal heuristics, type-role vocabulary (no font ID guessing), and a confirmation step before any code.
---
diff --git a/ROADMAP.md b/ROADMAP.md
index 9d31b57..c3e7539 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -153,15 +153,26 @@ How we know Hallmark is getting better, not just bigger:
## What's already shipped
-For reference. Everything below is in current `0.2.0`.
-
-- ✓ Skill: 4 verbs (default, audit, refine, redesign)
-- ✓ References: typography, color, layout-and-space, motion, microinteractions, structure, interaction-and-states, responsive, copy, anti-patterns
-- ✓ 12 themes with structural fingerprints
-- ✓ Theme picker UI on the landing page
+For reference. Everything below is in current `0.4.0`.
+
+- ✓ Skill: 5 verbs (default, audit, refine, redesign, study)
+- ✓ References: typography, color, layout-and-space, motion, microinteractions, structure, interaction-and-states, responsive, copy, anti-patterns, macrostructures, component-cookbook, study, hero-enrichment, custom-craft, assets
+- ✓ 16 themes with structural fingerprints (including Studio, Pastel, Riso, Quiet)
+- ✓ 21 named macrostructures + 36 component archetypes with within-archetype variation knobs
+- ✓ Sticky-top banner theme picker with random + ?theme= URL parameter
+- ✓ Per-theme component archetype swap (hero + footer rebuild on theme change)
+- ✓ Hero enrichment: demo video / mockup / illustration / abstract background, with Lottie demoted to last resort
+- ✓ Custom-craft canon: pure CSS art, hand-built SVG, declarative animation, View Transitions, Three.js when justified
+- ✓ Asset-source catalogue: Lucide / Phosphor / Heroicons (icons), Simple Icons / SVGL (logos), Nanobanana 2 / Recraft V4 (generated illustration), Storyset / Humaaans (library), Mixkit / Coverr (video), Unsplash / Nappy (photography)
- ✓ Working install path: `cp skill/* ~/.claude/skills/hallmark/`
- ✓ Two test specimens: bakery (`site/_example-bakery/`) and command palette (`site/_example-cmdk/`)
-- ✓ Slop test extended from 12 to 20 questions covering microinteractions
+- ✓ Slop test 33 questions: visual (8), structural (2), microinteractions (10), variety (3), implementation (6), hero enrichment (4)
- ✓ View Transitions on theme switch, with reduced-motion fallback
- ✓ Copy-to-clipboard with silent success on install code blocks
-- ✓ Keyboard shortcut (`T`) to open theme picker, with delay-revealed hint
+- ✓ Keyboard shortcut (`T` cycle, `Shift+T` reverse, `R` random)
+
+---
+
+## Deferred
+
+- **Tier 2.3 — Data-viz / chart canon.** Small multiples, axis restraint, banned types (3D donut, dual-axis), Tufte principles. Mentioned in hero-enrichment.md but full reference not yet written.
diff --git a/site/css/components.css b/site/css/components.css
index 7a244c5..421968d 100644
--- a/site/css/components.css
+++ b/site/css/components.css
@@ -1218,6 +1218,194 @@
.hero__photo-text { display: grid; gap: 0; }
+/* H7 — Demo Video Clipped-by-viewport-edge.
+ Pure-CSS dashboard mockup that extends past the right page edge.
+ No real video — this is a custom-craft demonstration of the clip layout. */
+.hero--clipped {
+ display: grid;
+ grid-template-columns: minmax(20rem, 1fr) 1.4fr;
+ gap: var(--space-2xl);
+ padding-block: var(--space-2xl) var(--space-xl);
+ align-items: center;
+ position: relative;
+}
+
+.hero--clipped .hero__copy { display: grid; gap: 0; }
+.hero--clipped .hero__display { max-width: 16ch; margin: 0; }
+.hero--clipped .hero__lede { max-width: 42ch; }
+.hero--clipped .hero__cta { margin-top: var(--space-xl); }
+
+.hero__mock {
+ width: calc(100% + 12vw); /* the clip — 12% spills past viewport */
+ max-width: none;
+ aspect-ratio: 16 / 10;
+ margin: 0;
+ border-radius: 14px;
+ overflow: hidden;
+ box-shadow: 0 30px 60px -28px oklch(20% 0.02 260 / 0.28),
+ 0 1px 2px oklch(20% 0.02 260 / 0.06);
+ background: var(--color-paper-2);
+ border: var(--rule-hair) solid var(--color-rule);
+ display: flex;
+ flex-direction: column;
+ transform: rotate(-0.4deg) translateY(-2px);
+ transform-origin: left center;
+}
+
+.hero__mock-chrome {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ padding: 10px 14px;
+ background: color-mix(in oklch, var(--color-paper-2) 100%, var(--color-rule) 12%);
+ border-block-end: var(--rule-hair) solid var(--color-rule);
+}
+
+.hero__mock-dot {
+ width: 9px; height: 9px;
+ border-radius: 50%;
+ background: color-mix(in oklch, var(--color-rule-2) 80%, transparent);
+}
+
+.hero__mock-url {
+ margin-inline-start: 12px;
+ font-family: var(--font-mono);
+ font-size: 0.7rem;
+ color: var(--color-muted);
+ letter-spacing: 0.02em;
+}
+
+.hero__mock-body {
+ flex: 1;
+ display: grid;
+ grid-template-columns: 56px 1fr;
+ background: var(--color-paper);
+ min-height: 0;
+}
+
+.hero__mock-rail {
+ display: flex;
+ flex-direction: column;
+ gap: 10px;
+ padding: 16px 12px;
+ background: color-mix(in oklch, var(--color-paper) 100%, var(--color-paper-2) 60%);
+ border-inline-end: var(--rule-hair) solid var(--color-rule);
+}
+
+.hero__mock-rail-item {
+ width: 28px; height: 28px;
+ border-radius: 6px;
+ background: color-mix(in oklch, var(--color-rule) 100%, transparent);
+}
+
+.hero__mock-rail-item.is-active {
+ background: var(--color-accent);
+ opacity: 0.85;
+}
+
+.hero__mock-main {
+ padding: 18px 22px;
+ display: flex;
+ flex-direction: column;
+ gap: 16px;
+ min-height: 0;
+}
+
+.hero__mock-row { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+.hero__mock-row--head { padding-block-end: 4px; }
+
+.hero__mock-bar {
+ height: 8px;
+ border-radius: 2px;
+ background: color-mix(in oklch, var(--color-rule) 80%, transparent);
+ flex: 1;
+}
+.hero__mock-bar--lg { height: 12px; max-width: 180px; }
+.hero__mock-bar--sm { max-width: 80px; }
+.hero__mock-bar--xs { height: 6px; max-width: 56px; }
+.hero__mock-bar--short { max-width: 50%; }
+
+.hero__mock-pill {
+ display: inline-block;
+ width: 64px; height: 22px;
+ border-radius: 999px;
+ background: var(--color-accent);
+ opacity: 0.18;
+}
+
+.hero__mock-grid {
+ display: grid;
+ grid-template-columns: 1fr 1fr 1.4fr;
+ grid-template-rows: 1fr;
+ gap: 12px;
+ flex: 1;
+ min-height: 0;
+}
+
+.hero__mock-card {
+ background: color-mix(in oklch, var(--color-paper) 100%, var(--color-paper-2) 60%);
+ border: var(--rule-hair) solid var(--color-rule);
+ border-radius: 8px;
+ padding: 12px;
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+ min-height: 0;
+}
+
+.hero__mock-card--accent {
+ background: color-mix(in oklch, var(--color-paper) 100%, var(--color-accent) 8%);
+ border-color: color-mix(in oklch, var(--color-accent) 40%, var(--color-rule));
+}
+
+.hero__mock-card--wide {
+ /* spans larger column already */
+}
+
+.hero__mock-stat {
+ font-family: var(--font-display);
+ font-weight: 600;
+ font-size: 1.75rem;
+ letter-spacing: -0.02em;
+ color: var(--color-ink);
+ font-variant-numeric: tabular-nums;
+ line-height: 1;
+}
+
+.hero__mock-spark {
+ flex: 1;
+ background:
+ linear-gradient(95deg,
+ transparent 0 6%,
+ var(--color-accent) 6% 7%,
+ transparent 7% 14%,
+ var(--color-accent) 14% 15%,
+ transparent 15% 28%,
+ var(--color-accent) 28% 29%,
+ transparent 29% 42%,
+ var(--color-accent) 42% 43%,
+ transparent 43% 60%,
+ var(--color-accent) 60% 61%,
+ transparent 61% 80%,
+ var(--color-accent) 80% 81%,
+ transparent 81% 100%);
+ opacity: 0.55;
+ border-radius: 4px;
+ min-height: 36px;
+ align-self: stretch;
+}
+
+.hero__mock-rows { display: flex; flex-direction: column; gap: 8px; }
+
+@media (max-width: 60rem) {
+ .hero--clipped { grid-template-columns: 1fr; gap: var(--space-xl); }
+ .hero__mock { width: 100%; transform: none; aspect-ratio: 16 / 11; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .hero__mock { transform: none; }
+}
+
/* ───────────── FOOTER ARCHETYPES ───────────── */
.foot { display: grid; gap: var(--space-md); padding-block: var(--space-2xl) var(--space-xl); border-block-start: var(--rule-hair) solid var(--color-rule); }
@@ -1368,3 +1556,77 @@
@media (prefers-reduced-motion: reduce) {
.slot[data-populating] > * { animation: none; opacity: 1; }
}
+
+/* ───────────── QUIET — restraint as the design ─────────────
+ Override every "expressive" treatment on the page when Quiet is active.
+ No reveals, no per-theme display weight tricks, no shadow glows.
+ System fonts inherit naturally; just make sure nothing yells. */
+
+[data-theme="quiet"] .reveal,
+[data-theme="quiet"] .reveal.is-in,
+[data-theme="quiet"] .slot[data-populating] > * {
+ opacity: 1;
+ transform: none;
+ animation: none;
+}
+
+[data-theme="quiet"] .hero__display,
+[data-theme="quiet"] .hero__quote p,
+[data-theme="quiet"] .hero__stat,
+[data-theme="quiet"] .section__title,
+[data-theme="quiet"] .foot__wordmark,
+[data-theme="quiet"] .spec__name,
+[data-theme="quiet"] .tell__name {
+ font-family: var(--font-display);
+ font-weight: 500;
+ font-style: normal;
+ text-transform: none;
+ letter-spacing: -0.015em;
+ text-shadow: none; /* override Riso's off-register if a user toggled */
+}
+
+[data-theme="quiet"] .hero__lede,
+[data-theme="quiet"] .hero__letter-body,
+[data-theme="quiet"] .spec__rule,
+[data-theme="quiet"] .tell__why,
+[data-theme="quiet"] .foot__tagline {
+ font-family: var(--font-body);
+ font-style: normal;
+ color: var(--color-neutral);
+}
+
+[data-theme="quiet"] .hero__salutation {
+ font-family: var(--font-body);
+ font-style: normal;
+ font-weight: 500;
+ font-size: var(--text-xl);
+ letter-spacing: 0;
+}
+
+[data-theme="quiet"] .hero__sign,
+[data-theme="quiet"] .hero__signoff {
+ font-family: var(--font-body);
+ font-style: normal;
+}
+
+[data-theme="quiet"] .banner__center {
+ font-family: var(--font-display);
+ font-weight: 500;
+ font-size: var(--text-sm);
+ letter-spacing: 0;
+ text-transform: none;
+}
+
+[data-theme="quiet"] .banner {
+ background: color-mix(in oklch, var(--color-paper) 92%, transparent);
+}
+
+/* No reveal animation on Quiet — the page is intentionally still. */
+[data-theme="quiet"] .hero,
+[data-theme="quiet"] .hero > * {
+ animation: none !important;
+}
+
+/* Quiet's hero never shows the clipped mockup — even if forced. */
+[data-theme="quiet"] .hero--clipped .hero__mock { display: none; }
+[data-theme="quiet"] .hero--clipped { grid-template-columns: 1fr; }
diff --git a/site/css/tokens.css b/site/css/tokens.css
index 55b1c40..619d385 100644
--- a/site/css/tokens.css
+++ b/site/css/tokens.css
@@ -740,3 +740,61 @@
--lh-tight: 0.92;
--lh-snug: 1.10;
}
+
+/* ──────────────────────────────────────────────────────────────
+ QUIET — restraint as the design · system fonts, near-white paper
+ The opposite of every other theme. Average-sized headers (smaller
+ than the others), generous whitespace, no chromatic accent, no
+ ornament, no reveal. System-native typography is the design — a
+ deliberate exception to Hallmark's "pair distinctive display + body"
+ rule. The brief is restraint; the design honours it.
+ ────────────────────────────────────────────────────────────── */
+
+[data-theme="quiet"] {
+ --color-paper: oklch(99.5% 0.002 90); /* barely-warm near-white */
+ --color-paper-2: oklch(97% 0.003 90);
+ --color-paper-3: oklch(94% 0.004 90);
+ --color-rule: oklch(86% 0.003 240);
+ --color-rule-2: oklch(72% 0.003 240);
+ --color-muted: oklch(50% 0.004 240);
+ --color-neutral: oklch(38% 0.004 240);
+ --color-ink-2: oklch(22% 0.005 240);
+ --color-ink: oklch(16% 0.005 240); /* barely-cool near-black */
+ --color-accent: oklch(16% 0.005 240); /* accent IS ink — no chroma */
+ --color-accent-ink: oklch(16% 0.005 240);
+ --color-focus: oklch(16% 0.005 240);
+
+ --font-display: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+ --font-body: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+ --font-serif: ui-serif, Georgia, "Times New Roman", serif;
+ --font-label: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+ --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+
+ --display-weight: 500;
+ --display-style: normal;
+
+ /* Average-sized headers — much smaller than other themes' 3.5–8rem display */
+ --text-display: clamp(1.75rem, 2.5vw + 0.5rem, 2.75rem);
+ --text-display-s: clamp(1.5rem, 2vw + 0.25rem, 2rem);
+ --text-2xl: 1.625rem;
+ --text-xl: 1.25rem;
+ --text-lg: 1.125rem;
+
+ --tracking-display: -0.02em;
+ --tracking-tight: -0.01em;
+ --tracking-label: 0.06em;
+
+ --lh-tight: 1.15;
+ --lh-snug: 1.4;
+ --lh-normal: 1.6;
+ --lh-relaxed: 1.75;
+
+ /* Generous whitespace — the page breathes */
+ --section-gap: 12rem;
+ --section-head-gap: 2.5rem;
+ --space-2xl: 6rem;
+ --space-3xl: 9rem;
+ --space-4xl: 14rem;
+
+ --measure: 60ch;
+}
diff --git a/site/index.html b/site/index.html
index 3d86755..9e18a05 100644
--- a/site/index.html
+++ b/site/index.html
@@ -62,6 +62,7 @@
<button class="banner__dot" type="button" data-theme-btn="studio" aria-label="Studio" style="--dot: oklch(96.5% 0.014 95); --dot-edge: oklch(46% 0.140 145);"></button>
<button class="banner__dot" type="button" data-theme-btn="pastel" aria-label="Pastel" style="--dot: oklch(96% 0.022 285); --dot-edge: oklch(56% 0.130 282);"></button>
<button class="banner__dot" type="button" data-theme-btn="riso" aria-label="Riso" style="--dot: oklch(91% 0.034 30); --dot-edge: oklch(58% 0.170 220);"></button>
+ <button class="banner__dot" type="button" data-theme-btn="quiet" aria-label="Quiet" style="--dot: oklch(99.5% 0.002 90); --dot-edge: oklch(16% 0.005 240);"></button>
<span class="banner__sep" aria-hidden="true"></span>
@@ -487,6 +488,61 @@
</div>
</template>
+ <template id="hero-clipped">
+ <div class="hero hero--clipped">
+ <div class="hero__copy">
+ <p class="hero__eyebrow"><span class="mark" aria-hidden="true"></span>{{eyebrow}}</p>
+ <h1 class="hero__display hero__display--small">{{title}}</h1>
+ <p class="hero__lede">{{lede}}</p>
+ <div class="hero__cta">
+ <pre class="code" data-copy-source><span class="prompt">$</span><span data-copy-text>npx skills add hallmark</span><button class="code__copy" type="button" data-copy-btn aria-label="Copy install command"><span class="code__copy-default">Copy</span><span class="code__copy-done">Copied</span></button></pre>
+ </div>
+ </div>
+ <figure class="hero__mock" aria-hidden="true">
+ <header class="hero__mock-chrome">
+ <span class="hero__mock-dot"></span>
+ <span class="hero__mock-dot"></span>
+ <span class="hero__mock-dot"></span>
+ <span class="hero__mock-url">hallmark.studio</span>
+ </header>
+ <div class="hero__mock-body">
+ <aside class="hero__mock-rail">
+ <span class="hero__mock-rail-item is-active"></span>
+ <span class="hero__mock-rail-item"></span>
+ <span class="hero__mock-rail-item"></span>
+ <span class="hero__mock-rail-item"></span>
+ <span class="hero__mock-rail-item"></span>
+ </aside>
+ <main class="hero__mock-main">
+ <div class="hero__mock-row hero__mock-row--head">
+ <span class="hero__mock-bar hero__mock-bar--lg"></span>
+ <span class="hero__mock-pill"></span>
+ </div>
+ <div class="hero__mock-grid">
+ <div class="hero__mock-card hero__mock-card--accent">
+ <span class="hero__mock-bar hero__mock-bar--xs"></span>
+ <span class="hero__mock-stat">{{mockStat}}</span>
+ <span class="hero__mock-bar hero__mock-bar--sm"></span>
+ </div>
+ <div class="hero__mock-card">
+ <span class="hero__mock-bar hero__mock-bar--xs"></span>
+ <span class="hero__mock-spark" aria-hidden="true"></span>
+ </div>
+ <div class="hero__mock-card hero__mock-card--wide">
+ <span class="hero__mock-bar hero__mock-bar--xs"></span>
+ <div class="hero__mock-rows">
+ <span class="hero__mock-bar"></span>
+ <span class="hero__mock-bar"></span>
+ <span class="hero__mock-bar hero__mock-bar--short"></span>
+ </div>
+ </div>
+ </div>
+ </main>
+ </div>
+ </figure>
+ </div>
+ </template>
+
<!-- ─────────── FOOTER ARCHETYPES ─────────── -->
<template id="footer-masthead">
diff --git a/site/js/main.js b/site/js/main.js
index fe69785..aac74dd 100644
--- a/site/js/main.js
+++ b/site/js/main.js
@@ -40,6 +40,7 @@ const THEMES = {
studio: "Studio",
pastel: "Pastel",
riso: "Riso",
+ quiet: "Quiet",
};
const STORAGE_KEY = "hallmark-theme";
@@ -61,8 +62,9 @@ const ARCHETYPES = {
manifesto: { hero: "marquee", footer: "masthead" },
sport: { hero: "stat-led", footer: "inline" },
studio: { hero: "photographic", footer: "index" },
- pastel: { hero: "letter", footer: "masthead" },
+ pastel: { hero: "clipped", footer: "masthead" },
riso: { hero: "quote-led", footer: "dense" },
+ quiet: { hero: "letter", footer: "inline" },
};
/* — Per-theme copy fixtures —————————————————————————————
@@ -330,21 +332,22 @@ const COPY = {
captionB: "Selected work",
},
pastel: {
- eyebrow: "v0.2 · post-Linear soft",
+ eyebrow: "v0.4 · post-Linear soft",
title: "Soft, but exact.",
- lede: "A skill that prefers soft surfaces and exact rules. Buttery paper. Slate ink. One indigo accent at low chroma — never a gradient.",
+ lede: "A design skill that prefers soft surfaces and exact rules. Buttery paper. Slate ink. One indigo accent at low chroma — never a gradient.",
ctaLabel: "Open it",
proofLabel: "What it does",
proofA: "OKLCH-anchored palettes",
proofB: "Geist sans + Geist Mono",
- proofC: "29-question slop test",
+ proofC: "33-question slop test",
cta: "Open Hallmark",
- stat: "29",
+ stat: "33",
qualifier: "gates, soft-spoken.",
+ mockStat: "33",
quote: "Software can be soft and exact at once. That's the trick.",
attrib: "Pastel · field note",
salutation: "Hey there.",
- letterBody:"This page is soft because the surface should be soft. The rules underneath are not — there are twenty-nine of them, and the page passed every one. We hope it feels like the modern dev tools you already love, just with fewer gradients.",
+ letterBody:"This page is soft because the surface should be soft. The rules underneath are not — there are thirty-three of them, and the page passed every one. We hope it feels like the modern dev tools you already love, just with fewer gradients.",
signoff: "Take care,",
captionA: "Field note 04",
captionB: "Pastel",
@@ -369,6 +372,27 @@ const COPY = {
captionA: "ed. 12",
captionB: "press · 04",
},
+ quiet: {
+ eyebrow: "v0.4",
+ title: "A quiet skill.",
+ lede: "System fonts. Near-white paper. Average-sized headers. A theme that argues against itself.",
+ ctaLabel: "Install",
+ proofLabel: "Notes",
+ proofA: "System-native typography",
+ proofB: "No chromatic accent",
+ proofC: "No reveal animation",
+ cta: "Read on",
+ stat: "16",
+ qualifier: "themes, one of them is this.",
+ mockStat: "16",
+ quote: "Restraint, when it's the brief, is the design.",
+ attrib: "Quiet",
+ salutation: "Hello.",
+ letterBody:"This is a page that doesn't try. The font is whatever your operating system gives. The accent colour is the same as the text. The headlines are average-sized. The whitespace is generous. There is nothing here to surprise you, and that's the design.",
+ signoff: "Yours,",
+ captionA: "Plain",
+ captionB: "Quiet",
+ },
};
/* — Slot population ———————————————————————————————————— */
diff --git a/skill/SKILL.md b/skill/SKILL.md
index 0eef154..e7b9169 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -1,7 +1,7 @@
---
name: hallmark
description: Use this skill when the user asks to design, build, redesign, audit, refine, or study a UI, web page, landing page, dashboard, component, or interface — or when they ask to make something "feel less AI-generated." Hallmark forces intentional design decisions (typography, color, layout, motion, interaction, structure) and refuses to default to the generic AI-UI template. Trigger phrases include "design a", "build a landing page", "make a dashboard", "redesign this site", "redesign the page", "refine this UI", "audit this design", "this looks AI-generated", "fix the design", "polish this", "give this a different look", and any request that will produce HTML / CSS / JSX / Tailwind output. **Also trigger when the user attaches a screenshot of a design they admire** — that is the `hallmark study` verb (extracts design DNA, never pixel-clones).
-version: 0.3.0
+version: 0.4.0
---
# Hallmark
@@ -87,11 +87,24 @@ The non-negotiables live in [`references/`](references/). Read only what you nee
- [`responsive.md`](references/responsive.md) — mobile-first, content-driven breakpoints, safe areas
- [`copy.md`](references/copy.md) — verbs, labels, error structure, link text
- [`anti-patterns.md`](references/anti-patterns.md) — the named tells you must not emit
+- [`hero-enrichment.md`](references/hero-enrichment.md) — when (and when not) to add a demo video / illustration / mockup / animated loop / abstract background to the hero, plus the eight enrichment archetypes (load when reaching Step 4)
+- [`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)
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.
-### 4. Build
+### 4. Decide on hero enrichment
+
+Most pages don't need it. The strongest hero is often a typographic one. **Reach for [`hero-enrichment.md`](references/hero-enrichment.md) only when the brief points there** — a SaaS / dev-tool brief wants a demo video or mockup; a bakery / café / atelier brief wants a hand-built illustration; a manifesto wants nothing.
+
+Eyeball the brief or ask one short question. State the decision in one sentence (e.g., *"Enrichment: E1 Clipped-Edge Demo Video, Tier-A CSS-art mockup."* or *"Enrichment: none — typography only."*). The decision goes into the macrostructure stamp at Step 5.
+
+**The enrichment hierarchy is non-negotiable.** Reach for the highest tier you can ship: typography only → Tier A pure CSS art → Tier B hand-built SVG → Tier C generated still (Nanobanana / Recraft) → Tier D library + customisation → **Tier E Lottie is last resort**, only for complex character motion that hand-build can't reach. Reaching for Lottie when CSS would have built it is the new tell.
+
+When an enrichment archetype requires construction, also load [`custom-craft.md`](references/custom-craft.md). When it requires an external asset, load [`assets.md`](references/assets.md).
+
+### 5. Build
Emit code that satisfies the tone and structural fingerprint. Match the complexity of the code to the ambition of the tone — a brutalist page needs raw, heavy CSS; an austere page needs restraint.
@@ -109,9 +122,9 @@ Always:
- Cut motion before adding it. Most pages have too much, not too little. If removing an animation wouldn't lose the user information, remove it.
- **Stamp the output.** The first non-empty line of the produced CSS file (or the top of `<style>` if inline) MUST be a comment of the form: `/* Hallmark · macrostructure: <name> · tone: <tone> · anchor hue: <hue> */`. This stamp is the durable record of what you chose. The next time Hallmark runs in this project, it reads the stamp and picks a *different* macrostructure.
-### 5. The slop test
+### 6. The slop test
-Before handing back, run the output through these twenty-nine questions. Every answer must be **no**.
+Before handing back, run the output through these thirty-three questions. Every answer must be **no**.
**Visual:**
@@ -157,6 +170,13 @@ Before handing back, run the output through these twenty-nine questions. Every a
28. Does any interactive element lack `:focus-visible`, `:active`, OR `:disabled` styling? (Eight states is the rule. Default + hover is two; you need at least default + hover + focus-visible + active + disabled present in code.)
29. Is there any `transform` / `animation` keyframe that is NOT covered by a `@media (prefers-reduced-motion: reduce)` fallback? Every motion gets a reduced-motion alternative.
+**Hero enrichment gates** (when the page carries enrichment — see [`references/hero-enrichment.md`](references/hero-enrichment.md)):
+
+30. If the page has a demo video, does it autoplay with sound, lack a `poster`, lack `fetchpriority="high"`, or use `loading="lazy"` on the LCP element? (LCP-killers fail this gate.)
+31. If the page has an abstract background, is it more than one accent colour, more than ~5 % footprint, or animating mesh-gradient on the whole page? (Aurora blobs and mesh-on-everything fail this gate.)
+32. Does the page mix two or more icon libraries? (Material + Heroicons + Lucide on the same page = the icon-set tell.)
+33. If the page has illustration, did I default to a Lottie library when a hand-built SVG or pure-CSS shape would have worked? (Lottie is last resort, not the default.)
+
If any answer is yes, fix it. Do not ship slop.
---
diff --git a/skill/references/anti-patterns.md b/skill/references/anti-patterns.md
index 2c72836..cee0c4e 100644
--- a/skill/references/anti-patterns.md
+++ b/skill/references/anti-patterns.md
@@ -72,6 +72,38 @@ Producing the Specimen macrostructure (numbered left-margin labels like `01 —
**Fix.** The Specimen macrostructure is one of twenty-one in [`macrostructures.md`](macrostructures.md), not a default. If the brief is vague, pick from the first ten in that file (Bento Grid, Long Document, Marquee Hero, Stat-Led, Workbench, Conversational FAQ, Manifesto, Photographic, Quote-Led, then Specimen). Reach for Specimen only when the brief explicitly says "editorial", "specimen sheet", "type foundry", or names the Specimen theme.
+### Aurora-blob background
+
+Flowing organic mesh blobs in purple-to-pink-to-cyan, layered behind hero text. Looks "premium" until you've seen it on every Dribbble shot since 2022.
+
+**Why it fails.** It's the 2022–2023 generated-design default. Audiences pattern-match this in milliseconds: AI template.
+
+**Fix.** Solid surface. Or a subtle two-stop CSS gradient + SVG `<feTurbulence>` grain at < 0.1 opacity. See [`hero-enrichment.md`](hero-enrichment.md) E7 for the recipe.
+
+### Floating-orb decoration
+
+Ambient generic 3D spheres or blurred coloured circles drifting behind the hero, often added "for depth". They have no semantic role.
+
+**Why it fails.** Generic 3D ambience is the new corporate-stock-photo. It implies "I needed something here, so I added something here."
+
+**Fix.** Cut them. The hero doesn't need depth; it needs a strong typographic anchor.
+
+### Sound-on autoplay
+
+A hero video that auto-plays with audio. Browsers block it anyway, but intent matters: a video element shipped without `muted` is a video that wanted to shout at the user.
+
+**Why it fails.** Hostile to the audience. Accessibility fail. SEO penalty. Browser blocked.
+
+**Fix.** `<video autoplay muted loop playsinline>` — always all four. A separate audio toggle button if sound is genuinely useful.
+
+### Lazy-loaded LCP
+
+`loading="lazy"` on the hero image or hero video — the LCP element. The page waits to start downloading until the user scrolls to it, except they're already looking at it, so the page just sits there blank.
+
+**Why it fails.** Tanks Largest Contentful Paint. Real-world data: lazy-loaded LCP images show p75 of 720 ms vs. 364 ms for preloaded — 2× slower, 4× more "poor" experiences.
+
+**Fix.** `fetchpriority="high"` and `preload="metadata"` on the LCP element. Lazy-load only below-the-fold media.
+
---
## Major (looks AI-generated)
@@ -124,6 +156,38 @@ Every section fades in when it enters the viewport. Every list staggers. The pag
**Fix.** Pick one orchestrated entrance. Let the rest just *be there*.
+### Mismatched icon sets
+
+Material Icons in the navbar, Heroicons in the feature cards, Lucide in the footer, an emoji "✨" in a hero badge. Each library has its own stroke voice; mixing them is the icon-set tell.
+
+**Why it fails.** Icons are typography. You wouldn't ship a page with three different body fonts; don't ship one with three different icon strokes.
+
+**Fix.** Pick one library per project. Lucide is the default for SaaS, Phosphor when you need weight variants, Heroicons for Tailwind/shadcn projects. See [`assets.md`](assets.md) for the canon.
+
+### AI-illustration look
+
+Smooth-mesh-blob characters with no joint articulation, mid-2010s "modern flat" stock poses, unmistakably-Midjourney compositions with the symmetric default lighting.
+
+**Why it fails.** It reads as AI in milliseconds. The 2026 audience pattern-matches this faster than any other tell.
+
+**Fix.** Hand-build the illustration in pure CSS or SVG (Tier A or B in [`hero-enrichment.md`](hero-enrichment.md)). If you must generate, use Nanobanana 2 or Recraft V4 with reference images, asymmetric crop, and grain post-processing — never raw output. See [`custom-craft.md`](custom-craft.md) Tier E.
+
+### Lottie shortcut
+
+Reaching for a LottieFiles community animation — the spinning logo, the checkmark draw, the loading spinner, the "loading dots" loop — when pure CSS or hand-built SVG would have produced it stronger and lighter.
+
+**Why it fails.** Lottie pulls were an AI-tool shortcut throughout 2023–2024; the audience now reads them as one. The 50–500 KB JSON file plus the runtime cost is a tax on a job CSS does in zero bytes.
+
+**Fix.** Build it custom. Spinning logo → CSS `@keyframes rotate`. Checkmark → SVG `stroke-dasharray` animated. Loading dots → CSS `@property` + `animation-delay`. Lottie is Tier F in the enrichment hierarchy — last resort, only for genuinely articulated character motion.
+
+### Three.js for a still object
+
+A WebGL hero where the 3D doesn't earn its place by being interactive. A stationary spinning thing the user can't touch, can't reorient, can't customise — just a model rotating because someone wanted "3D".
+
+**Why it fails.** The 100–300 KB Three.js bundle, the model, the textures, the GPU work — all for a thing that could be a static photograph or an SVG.
+
+**Fix.** If the user can't manipulate it, it doesn't justify Three.js. Use a still photograph or a hand-built SVG.
+
---
## Microinteraction tells
diff --git a/skill/references/assets.md b/skill/references/assets.md
new file mode 100644
index 0000000..de5e9b6
--- /dev/null
+++ b/skill/references/assets.md
@@ -0,0 +1,372 @@
+# Assets — sourcing canon for icons, logos, illustrations, photography, video
+
+This file is loaded when an enrichment archetype actually needs an external asset (load-on-demand). It catalogues the *3–5 canonical sources per category*, the licence terms, the import patterns, the rules for using them, and the sources to avoid.
+
+**The reflex.** Before reaching here, ask: can this be built? See [`custom-craft.md`](custom-craft.md). The assets in this file are for the moments when hand-building isn't economical or when the brief explicitly calls for stock material. Treat this file as the back-pocket catalogue, not the first move.
+
+---
+
+## Icons
+
+### Canon
+
+| Library | URL | Count | Best for |
+| --- | --- | --- | --- |
+| **[Lucide](https://lucide.dev)** | `lucide.dev` | 1,600+ | Modern SaaS / dev-tool default. The 2026 baseline. Active maintenance. |
+| **[Phosphor Icons](https://phosphoricons.com)** | `phosphoricons.com` | 9,000+ across 6 weights (thin / light / regular / bold / fill / duotone) | Tonal variants without mixing sets. The right pick when you need different *weights* of the same icon for emphasis. |
+| **[Heroicons](https://heroicons.com)** | `heroicons.com` | ~300 | Tailwind / shadcn projects. Tightly curated, opinionated. |
+| **[Tabler Icons](https://tabler-icons.io)** | `tabler-icons.io` | 5,900+ on a 24×24 grid | Breadth — when neither Lucide nor Heroicons covers the symbol you need. |
+| **[Iconoir](https://iconoir.com)** | `iconoir.com` | ~1,500 | Hand-drawn character with a generous free tier. |
+
+### The rules
+
+1. **Pick one library per project.** Mixing Material + Heroicons + Lucide on the same page is the icon-set tell. The skill's audit verb catches this.
+2. **Sizes 16 / 20 / 24 / 32 only.** Snap to grid. 18-px icons don't exist in this canon.
+3. **Stroke 2 px default** (most libraries' regular weight). Switch to bold (2.5 px) only for icons under 20 px or as emphasis.
+4. **Monochrome with `currentColor`.** Icons inherit text colour. Brand-coloured icons only on the singular primary CTA — not as decoration.
+5. **No emoji-as-icon.** Emoji break alignment, accessibility, and brand consistency. Use a real icon library.
+
+### Import patterns
+
+```jsx
+// Lucide — React (most common)
+import { ArrowRight, Check, X } from "lucide-react";
+<ArrowRight size={20} strokeWidth={2} />
+
+// Phosphor — React, with weight prop
+import { ArrowRight } from "@phosphor-icons/react";
+<ArrowRight size={20} weight="regular" />
+
+// Heroicons — React or static HTML
+import { ArrowRightIcon } from "@heroicons/react/24/outline";
+
+// Tabler — vanilla HTML via CDN
+<svg width="20" height="20"><use href="https://cdn.jsdelivr.net/npm/@tabler/icons@latest/icons/arrow-right.svg" /></svg>
+```
+
+### Avoid
+
+- **Font Awesome free** — bloated, dated. The 2018-SaaS look; 600+ generic glyphs that all read as "I picked the icons before designing the page".
+- **Material Icons in a non-Material project** — gives a Google look that doesn't match anything else.
+- **Icon packs with inconsistent stroke widths** — pick a library whose icons share weight; eclectic mixes read as random.
+- **Emoji as semantic icons** — colour, size, weight, alignment all uncontrolled.
+
+---
+
+## Brand / company logos
+
+### Canon
+
+| Source | URL | Count | Best for |
+| --- | --- | --- | --- |
+| **[Simple Icons](https://simpleicons.org)** | `simpleicons.org` | 3,400+ | The industry standard. Monochrome SVG + official hex per brand. MIT licensed. The default for logo walls. |
+| **[SVGL](https://svgl.app)** | `svgl.app` | 600+ | Curated, hand-picked, no spam. Higher quality bar than Simple Icons. |
+| **[theSVG](https://thesvg.org)** | `thesvg.org` | 4,000+ with dark/light/mono/wordmark variants | npm + MCP server for AI. Superset over Simple Icons if your stack supports it. |
+| **[Brandfetch](https://brandfetch.com)** | `brandfetch.com` | 22M+ brands | Paid API. Logo + colours + fonts + guardrails. Useful when building a CMS / form that asks "what's your domain?" and back-fills the brand. |
+| **Official brand asset pages** | Per company | — | Always check first if accuracy matters. Most brands ship a media-kit page (e.g., `vercel.com/design`). |
+
+### The rules
+
+1. **Logo walls: monochrome only.** Use Simple Icons' default colour or the official monochrome variant. Mixed full-colour logos read as 2018-SaaS.
+2. **Height-aligned, not width-aligned.** Pick a baseline (typically 32–48 px height) and let the width float. Brand proportions matter; stretching is a tell.
+3. **2–3× height as gutter.** Logos need breathing room. A wall with 32-px logos wants 64–96-px gutters.
+4. **No hairline borders, no glow halos.** Just the marks on the page.
+
+### Import patterns
+
+```html
+<!-- Simple Icons via CDN — easiest -->
+<img src="https://cdn.simpleicons.org/github" alt="GitHub" height="32">
+<img src="https://cdn.simpleicons.org/figma/aaaaaa" alt="Figma" height="32"> <!-- monochrome override -->
+
+<!-- npm -->
+<!-- npm install simple-icons -->
+import { siGithub } from 'simple-icons/icons';
+<svg viewBox="0 0 24 24"><path d={siGithub.path} fill="currentColor" /></svg>
+
+<!-- SVGL via API -->
+<img src="https://api.svgl.app/?slug=vercel" alt="Vercel">
+```
+
+### Avoid
+
+- **Full-colour logo grids.** Visual chaos; reads as 2018.
+- **Stretched / squished marks.** Always preserve aspect ratio.
+- **Placeholder customer logos from template kits** ("ACME", "Initech", "Hooli"). Use real customer logos, or skip the wall entirely — fake social proof is worse than no social proof.
+- **Mixing wordmarks with marks.** Pick a treatment (all-monogram or all-wordmark) for any single wall.
+
+---
+
+## Generated illustration (Tier C in the enrichment hierarchy)
+
+When characters or specific scenes can't be hand-built economically. **Always post-process.** See [`custom-craft.md`](custom-craft.md) Tier E for full discipline.
+
+### Canon
+
+| Model | URL | Cost | Best for | Output |
+| --- | --- | --- | --- | --- |
+| **[Nanobanana 2 / Gemini 2.5 Flash Image](https://ai.google.dev/gemini-api/docs/image-generation)** | Google AI | $0.039 / image | Character consistency across panels, fast iteration, brand-style adherence via reference images, infographics with text | PNG (transparent supported) |
+| **[Recraft V4](https://www.recraft.ai/)** | recraft.ai | ~$0.04 / image | **The only model with production-grade SVG output.** Logos, icons, illustrations that need to scale. | SVG + PNG |
+| **[Midjourney v8](https://www.midjourney.com)** | midjourney.com | ~$0.14 / image | Aesthetic beauty, atmospheric stills, artistic direction | PNG |
+| **[Flux 2](https://blackforestlabs.ai/)** | blackforestlabs.ai | ~$0.03 / image | Photorealism — skin, fabric, product detail, hands | PNG |
+
+### The rules
+
+1. **Always post-process.** Add grain, asymmetric crop, hand-drawn overlays, colour grading. Raw model output reads as AI 100 % of the time.
+2. **Use reference images** for brand consistency. Nanobanana 2's character-consistency feature is its differentiator vs. Midjourney; feed it your brand assets so generations stay on-style.
+3. **Stamp the model in the macrostructure comment** (`generated: nanobanana-2 · post-processed`). Provenance matters.
+4. **Verify SynthID watermark** is present on Google-generated images.
+5. **No animation.** None of these models output multi-frame; assemble via custom-craft if motion is needed.
+
+### Avoid
+
+- **Symmetrical compositions** — algorithmic; the AI tell. Always crop asymmetrically.
+- **Smooth-mesh-blob faces** — the 2024 generic AI character look.
+- **Default lighting + blue-tinted backgrounds** — the generic AI aesthetic. Specify brand-anchored colour and unusual lighting in the prompt.
+- **Six fingers / doubled furniture / impossible rooms** — less common in 2026 but still lurking. Inspect.
+- **Shipping unmodified output** — see rule 1.
+
+### Prompting recipe (Nanobanana 2)
+
+```
+Subject: <one specific concrete subject> in <one specific concrete pose>.
+Style: <named style — "risograph print", "1960s editorial illustration",
+ "ink-on-paper line drawing", NOT "modern flat" or "clean illustration">.
+Composition: asymmetric, <off-centre subject>, <unusual crop>.
+Lighting: <named lighting — "side-lit, late afternoon", "overcast diffuse">.
+Reference: <attach brand asset / mood board for character consistency>.
+Constraints: no smooth mesh-gradient, no aurora background, no symmetric layout,
+ no smiling people-on-laptops poses.
+```
+
+A specific prompt produces a specific image. A generic prompt produces the AI tell.
+
+---
+
+## Library illustrations (Tier D — not first choice)
+
+When budget and timeline force a shortcut and even Tier C is overkill.
+
+### Canon
+
+| Source | URL | Licence | Best for |
+| --- | --- | --- | --- |
+| **[Storyset](https://storyset.com)** | storyset.com (Freepik) | Free with attribution; paid removes | Animated SVG illustrations with toggleable element animation and on-site colour customisation. Onboarding flows, feature explanations. |
+| **[Humaaans](https://www.humaaans.com)** | humaaans.com (Pablo Stanley) | CC0 | Mix-and-match characters with diverse poses / outfits / skin tones. Hero sections that need humans without stock-photo territory. |
+| **[unDraw](https://undraw.co)** | undraw.co | MIT | Open SVG illustrations with on-export colour swap. Still respected if customised — saturated and instantly recognisable if not. |
+| **[IRA Design](https://www.iradesign.io)** | iradesign.io (Creative Tim) | Free / paid | Moody, sophisticated, isometric scenes for B2B / enterprise. |
+| **[Open Peeps](https://www.openpeeps.com)** | openpeeps.com | CC0 | Hand-drawn character library, naive style. Sits between photography and illustration. |
+
+### The rules
+
+1. **Always customise colour to your brand anchor hue.** The library default colour is the library look. Swap it.
+2. **Crop or recompose** if you can. The unmodified illustration is on a hundred competitor sites; even a crop change differentiates.
+3. **One library per project.** Mixing Storyset + Humaaans + unDraw = visual chaos. Pick one, stick to it.
+4. **Avoid the giveaway poses** — guy on laptop with floating speech bubble, woman in headset on cloud, character holding giant phone. Whatever you saw on Dribbble in 2021, audiences saw too.
+5. **Commission custom for >3 uses.** If the illustration appears in the hero, a feature block, AND promotional material, the per-piece commission cost ($200–$600 freelancer, $399–$999/month subscription for unlimited) wins on brand consistency over libraries.
+
+### Avoid
+
+- **Open Doodles** — dated. The 2019 hand-drawn aesthetic that's been displaced by 2026's tactile rebellion.
+- **"Modern flat" generic poses** — that whole aesthetic is the AI training-distribution default.
+- **AI-generated illustrations** put through library filters — the worst of both worlds.
+- **Stock photography with character cutouts pasted on top** — fights physics, looks haunted.
+
+---
+
+## App mockups / device frames
+
+### Canon
+
+| Source | URL | Best for |
+| --- | --- | --- |
+| **[Browserframe](https://browserframe.com)** | browserframe.com | Browser + mobile device frames with annotation. Built for SaaS demo screenshots. |
+| **[Ray.so](https://ray.so)** | ray.so | Code snippets in macOS window frames. Perfect for developer-tool landing pages. |
+| **[Cleanmock](https://cleanmock.com)** | cleanmock.com | Mobile device frames; minimalist; good for app-store-listing-style heroes. |
+| **[Mockup.style](https://mockup.style)** | mockup.style | Versatile device + browser builder, Figma-friendly export. |
+| **[Device Shots](https://deviceshots.com)** | deviceshots.com | Free device generator with multiple frame styles, fast turnaround. |
+
+### The rules
+
+1. **Browser frame for SaaS / web apps.** Communicates "this is real, on the web". Use Browserframe or hand-build (a 1-px hairline + three macOS dots is enough).
+2. **Floating-no-frame for clean splits.** When the screenshot is beautiful enough to stand naked. Demands a high-quality screenshot.
+3. **Device frame (iPhone / iPad) sparingly.** One hero mockup max — beyond that it reads as generic template work.
+4. **Tilt 1–3°.** Adds life. 0° reads as flat; 5°+ reads as drunk.
+5. **Numbered-pin annotations only.** Numbered circles (1, 2, 3) with a corresponding callout legend below. No arrow-and-label callouts (dated 2018 UX). Label only the *novel* features, not the obvious.
+
+### Avoid
+
+- **Glossy plastic device bezels** — looks 2015. Use minimalist frames or no frame.
+- **Annotation chaos** — more pins than pixels. Three numbered pins is a lot; five is too many.
+- **Stretched aspect ratios** — never resize a mockup beyond its natural ratio.
+- **Visible Figma prototyping artifacts** in the screenshot (ghost-out frames, "hover" indicators). Clean the export.
+
+---
+
+## Hero / demo video
+
+### Canon (when you don't have your own footage)
+
+| Source | URL | Licence | Best for |
+| --- | --- | --- | --- |
+| **[Mixkit](https://mixkit.co)** | mixkit.co (Envato) | No registration, no attribution required, 1080p+ HD | The quality-to-effort sweet spot. |
+| **[Coverr](https://coverr.co)** | coverr.co | Free commercial use | Optimised for hero-section backgrounds and ambient loops. |
+| **[Pexels Videos](https://www.pexels.com/videos/)** | pexels.com/videos | CC0 | Largest free library; 4K available. Volume play. |
+| **[Videvo](https://www.videvo.net)** | videvo.net | Tiered (free + pro) | Community footage + motion graphics. |
+
+### The rules
+
+1. **Codec chain in the `<source>` order: AV1 → WebM VP9 → MP4 H.264.** Browsers pick the first they support. AV1 is 30–50 % smaller than H.264 at equivalent quality; H.264 is the universal fallback.
+2. **Always autoplay-muted-loop-playsinline.**
+ ```html
+ <video autoplay muted loop playsinline preload="metadata"
+ poster="/hero-poster.webp" fetchpriority="high">
+ <source src="/hero.av1.mp4" type='video/mp4; codecs="av01.0.05M.08"'>
+ <source src="/hero.vp9.webm" type="video/webm">
+ <source src="/hero.h264.mp4" type="video/mp4">
+ </video>
+ ```
+3. **Always include a `poster=""`** — prevents layout shift, gives reduced-motion users a static fallback.
+4. **`fetchpriority="high"` on the LCP element.** **Never `loading="lazy"`** on the hero — that kills LCP.
+5. **VTT captions for accessibility.** Even on muted demo loops; people may unmute.
+6. **No sound on autoplay.** Browsers block it anyway, but the principle is firm.
+
+### Compression
+
+- **[ffmpeg](https://ffmpeg.org)** for control:
+ - VP9: `ffmpeg -i input.mp4 -c:v libvpx-vp9 -b:v 0 -crf 30 -c:a libopus -b:a 128k output.webm`
+ - AV1: `ffmpeg -i input.mp4 -c:v libaom-av1 -crf 30 -c:a aac output.mp4`
+ - H.264: `ffmpeg -i input.mp4 -c:v libx264 -preset slow -crf 23 -c:a aac output.mp4`
+- **[HandBrake](https://handbrake.fr)** for GUI / batch: start with the "Vimeo YouTube HQ 1080p" preset, drop bitrate to 3–4 Mbps for web.
+
+### Avoid
+
+- **Watermarked stock** — visible "Pexels.com" stamps in the corner.
+- **30 fps labelled as 60 fps** — reveals itself on modern displays.
+- **Music-heavy demos without a mute toggle** — alienates accessibility users and noisy environments.
+- **`loading="lazy"` on hero video** — kills LCP, tanks Core Web Vitals.
+
+---
+
+## Photography
+
+### Canon
+
+| Source | URL | Licence | Best for |
+| --- | --- | --- | --- |
+| **[Unsplash](https://unsplash.com)** | unsplash.com | CC0 | Largest free collection, moody / cinematic, weekly community uploads. The starting point. |
+| **[Pexels](https://www.pexels.com)** | pexels.com | CC0 | 3.5M+ free photos, diverse photographers. |
+| **[Nappy.co](https://www.nappy.co)** | nappy.co | Free + paid | Curated for diversity and representation. Premium visual direction. |
+| **[Shotstash](https://www.shotstash.com)** | shotstash.com | Free | Lifestyle / minimal aesthetic. Smaller but carefully curated. |
+| **[Open Peeps](https://www.openpeeps.com)** | openpeeps.com | CC0 | Illustrated character library when you want diversity without the photo-stock look. |
+
+### The rules
+
+1. **Always tweak the source.** Gradient overlay, crop, desaturation, blur, or brand-colour wash. The unmodified Unsplash photo is on a hundred competitor sites; even a crop change differentiates.
+2. **Match tone to brief.** Enterprise / B2B: neutral palettes, natural lighting, real workspaces. Consumer / lifestyle: warm lighting, human emotion. Tech / startup: minimal backgrounds, hands-on interaction.
+3. **Diverse representation.** Nappy.co is the best free source for intentional curation; Unsplash and Pexels carry diversity but require search effort.
+4. **Aspect ratios that fit.** Hero photography typically wants 16/9 desktop, 4/3 or 9/16 mobile.
+
+### Avoid
+
+- **Photos with visible logos / trademarks** — copyright risk.
+- **Over-processed HDR** — looks dated, unrealistic.
+- **Staged "team photo" shots** — generic, reads as stock.
+- **Unmodified Unsplash** — a hundred competitor sites used the same photo this week.
+
+---
+
+## Abstract backgrounds
+
+### Canon
+
+| Source | URL | Output | Best for |
+| --- | --- | --- | --- |
+| **CSS gradients (native)** | n/a — write them | Zero bytes, GPU-composited | The default. Linear or radial; 2–3 colour stops max. |
+| **[Mesh Gradient Generator](https://www.learnui.design/tools/mesh-gradient-generator.html)** | learnui.design tools | Figma / SVG export | Apple-style mesh gradients; export carries organic noise. |
+| **[fffuel.co](https://www.fffuel.co/)** | fffuel.co | SVG | `gggrain` for grain noise; `ffflux` for fluid gradients; `uuunion` for wavy meshes. Composable. |
+| **[CSS Gradient](https://cssgradient.io)** | cssgradient.io | CSS strings | Quick gradient picker; copy-paste ready. |
+
+### The rules
+
+1. **CSS gradients first.** Zero bytes; scale infinitely; animate smoothly with `@property`. If a CSS gradient does the job, never reach for SVG or images.
+2. **Two to three colour stops.** More than three reads as generated. Pick stops that share hue and step in lightness.
+3. **Grain via SVG `<feTurbulence>`** at < 0.1 opacity, `mix-blend-mode: multiply`. Cheap, no asset, looks like paper.
+4. **Hero or accent card only — never page-wide.** A 100-vh gradient is a tell; a 40-vh hero gradient with the rest of the page on flat paper is intentional.
+5. **No animation on whole-page gradients.** A subtle 30-s drift on a hero accent is allowed; a slowly-rotating mesh-gradient on the entire page is the new aurora-blob anti-pattern.
+
+### Recipe (CSS gradient + SVG grain)
+
+```css
+.hero {
+ background:
+ linear-gradient(135deg,
+ color-mix(in oklch, var(--color-paper) 100%, var(--color-accent) 4%),
+ color-mix(in oklch, var(--color-paper) 100%, var(--color-paper-2) 50%));
+ position: relative;
+}
+
+.hero::after {
+ content: "";
+ position: absolute; inset: 0;
+ background: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg'><filter id='n'><feTurbulence baseFrequency='0.9' numOctaves='2'/></filter><rect width='100%' height='100%' filter='url(%23n)'/></svg>");
+ opacity: 0.06;
+ mix-blend-mode: multiply;
+ pointer-events: none;
+}
+```
+
+### Avoid
+
+- **Aurora blobs** — the 2022 Dribbble look. Critical anti-pattern.
+- **Purple-to-cyan mesh** — the 2023 default. Critical anti-pattern.
+- **Floating orbs / spheres** — generic 3D ambient. Critical anti-pattern.
+- **Particle / starfield** — 2010s nostalgia, distracting.
+- **Animated mesh-gradient on the whole page** — modern equivalent of the rotating gradient banner.
+
+---
+
+## Lottie / Rive (Tier F — last resort)
+
+### Canon
+
+| Source | URL | Best for |
+| --- | --- | --- |
+| **[LottieFiles](https://lottiefiles.com)** | lottiefiles.com | The Lottie ecosystem. Free + pro tiers; npm + CDN; Figma plugin; AI creator. |
+| **[Rive](https://rive.app)** | rive.app | Interactive real-time animations with state machines. Native runtime; better for app UI micro-interactions than Lottie. |
+
+### The rules
+
+1. **Lottie is last resort.** Reach for it only when complex character motion can't be hand-built. See [`custom-craft.md`](custom-craft.md) Tier F.
+2. **Custom-commissioned over library pulls.** A LottieFiles community animation that fits your brand exists; one that fits *and* doesn't look like every other LottieFiles community animation is rare. Commission ($100–$300 on Upwork; $1,000+ from a studio) for hero work.
+3. **< 2 MB file size.** Anything heavier loses to its own loading state.
+4. **Pause / resume support.** Required for accessibility (motion-sensitive users need control).
+5. **Reduced-motion fallback** to a static keyframe. Required.
+6. **Don't use Lottie for what CSS can do.** Spinning logos, checkmark draws, loading spinners, hover micro-interactions — all CSS territory. The skill catches the "Lottie shortcut" anti-pattern in its slop test.
+
+### Avoid
+
+- **2019-era over-smooth animations.** Looks dated, lacks character.
+- **Animations heavier than the page itself** — 5 MB Lottie files for a 200 KB page.
+- **Animations without pause / resume** — accessibility fail.
+- **LottieFiles community pulls used unmodified** — reads as "I picked this from a library".
+
+---
+
+## Quick-reference: which source for which job
+
+| Need | First reach | Second reach |
+| --- | --- | --- |
+| UI icon (chevron, check, X) | Lucide | Phosphor / Heroicons |
+| Brand logo for a wall | Simple Icons | SVGL / theSVG |
+| A hero illustration the brand owns | Hand-build (Tier A or B) | Commission custom |
+| A hero illustration that's character-driven | Nanobanana 2 (Tier C) | Commission, then library |
+| An SVG-format illustration that needs to scale | Recraft V4 | Hand-build in Figma → SVG |
+| A photograph with diversity | Nappy.co | Unsplash with manual tone-tweak |
+| A demo video of your product | Custom screen recording | (skip; no stock fits) |
+| A textured background | CSS gradient + SVG grain | Mesh Gradient Generator |
+| A character animation | Custom Lottie commission | LottieFiles community + customise |
+| A loading spinner | CSS conic-gradient | (don't reach for Lottie) |
+| A checkmark draw on confirm | SVG `stroke-dasharray` | (don't reach for Lottie) |
+
+When in doubt: build it. The path of least resistance and the path of least-AI-tell are the same path in 2026.
diff --git a/skill/references/component-cookbook.md b/skill/references/component-cookbook.md
index aa555e6..ebfbb17 100644
--- a/skill/references/component-cookbook.md
+++ b/skill/references/component-cookbook.md
@@ -1,6 +1,6 @@
# Component cookbook
-Thirty-three component archetypes you can compose into any macrostructure. Every entry: a *shape*, a one-line "use when", a one-line "don't confuse with", and a short structural sketch (DOM + minimal CSS). Pick from this file when you're building a section and don't know which shape to reach for.
+Thirty-six component archetypes you can compose into any macrostructure. Every entry: a *shape*, a one-line "use when", a one-line "don't confuse with", and a short structural sketch (DOM + minimal CSS). Pick from this file when you're building a section and don't know which shape to reach for.
The same macrostructure (e.g., Bento Grid) can be built from many different combinations of these archetypes. The macrostructure picks the *page shape*; this file picks the *components inside it*.
@@ -26,6 +26,9 @@ When you pick an archetype, **state the knob values you chose** in the macrostru
| **H4 Stat-Led** | Number style: tabular display · italic display · monospace | Qualifier position: below · inline-right · stacked-above | Secondary stats: none · two below · row of four |
| **H5 Letter** | Salutation: greeting · "Dear X," · time-stamp | Body length: 1 paragraph · 2 paragraphs · 3 paragraphs | Signoff: typed name · drawn signature SVG · initials |
| **H6 Photographic** | Image area: full-bleed · 16/7 · 4/3 · 1/1 square | Caption position: lower-left · upper-right · margin | Text below or overlaid |
+| **H7 Demo Video Clipped-Edge** | Clip side: right · left · both | Aspect ratio: 16/10 · 16/9 · 4/3 | Frame: hairline · browser chrome · none |
+| **H8 Mockup Split** | Frame style: browser chrome · macOS toolbar · minimal hairline · floating no-frame | Tilt: 0° · 1.5° · 3° | Screenshot count: 1 · stack-of-3 · orbit-of-3 |
+| **H9 Custom Illustration** | Build method: Tier-A pure-CSS · Tier-B hand-SVG · Tier-C generated · Tier-D library | Animation: none · loop · scroll-linked | Scale: small accent · dominant |
| **F1 Bento (feature)** | Tiles: 4 · 6 · 7 · 9 | Spans: regular · irregular · mosaic | Border: hairline all · accent corners · none |
| **F2 Sticky-scroll stack** | Pinned side: left · right | Right pane content: code · screenshot · diagram | Pin steps: 3 · 4 · 5 |
| **F3 Tabular spec sheet** | Columns: 2 (key/val) · 3 (key/val/unit) · 4 (with footnote) | Rule density: every row · groups of 3 · headers only | Numbers: tabular · proportional |
@@ -142,6 +145,84 @@ Single full-bleed image fills the viewport. Caption sits in a corner.
.hero-photo .caption { position: absolute; bottom: var(--space-md); right: var(--space-md); }
```
+### H7 · Demo Video — Clipped-by-viewport-edge
+Display headline left, demo video right, the rightmost ~10–20 % extending past the viewport so it's intentionally cut off. The clip *is* the design — implies "there's more product than fits the screen". Pioneered by Linear, refined by Vercel / Resend / Cursor.
+*Use when:* the brief is SaaS / dev-tool / dashboard / platform AND you have real footage of the product (or a hand-built CSS-art mockup of it).
+*Don't confuse with:* H4 Stat-Led (number-led, no video) or H8 Mockup Split (still screenshot, not video).
+
+See [`hero-enrichment.md`](hero-enrichment.md) for the full E1 recipe (codec chain, autoplay rules, `prefers-reduced-motion` fallback, mobile collapse). The cookbook entry below is the structural sketch.
+
+```html
+<section class="hero hero--clipped">
+ <div class="hero__copy">
+ <h1>Plan, build, ship.</h1>
+ <p>The project tracker your engineering team won't ignore.</p>
+ </div>
+ <figure class="hero__media">
+ <video autoplay muted loop playsinline preload="metadata"
+ poster="/hero-poster.webp" fetchpriority="high">
+ <source src="/hero.av1.mp4" type='video/mp4; codecs="av01.0.05M.08"'>
+ <source src="/hero.h264.mp4" type="video/mp4">
+ </video>
+ </figure>
+</section>
+```
+```css
+.hero--clipped { display: grid; grid-template-columns: 1fr 1.4fr; gap: var(--space-2xl); overflow: visible; }
+.hero__media { width: calc(100% + 12vw); aspect-ratio: 16 / 10; border-radius: 12px; overflow: hidden; }
+@media (max-width: 60rem) { .hero--clipped { grid-template-columns: 1fr; } .hero__media { width: 100%; } }
+```
+
+### H8 · Mockup Split (browser-framed)
+Headline left, browser-frame mockup right, the mockup tilted 1–3° for life. Frame can be browser chrome, macOS toolbar, minimal hairline, or floating no-frame.
+*Use when:* you're selling a web app and you have a clean, well-lit screenshot.
+*Don't confuse with:* H7 Clipped-Edge (which extends past the viewport) or H2 Split Diptych (which uses photography or proof column, not a product mockup).
+
+```html
+<section class="hero-mock">
+ <div>
+ <h1>The studio's new mute button.</h1>
+ <p>Press <kbd>⌘ M</kbd> from anywhere.</p>
+ </div>
+ <figure class="mock">
+ <header class="mock__chrome"><span></span><span></span><span></span></header>
+ <div class="mock__body"><!-- screenshot or CSS-art mockup --></div>
+ </figure>
+</section>
+```
+```css
+.hero-mock { display: grid; grid-template-columns: 1fr 1.2fr; gap: var(--space-2xl); align-items: center; }
+.mock { transform: rotate(1.5deg); border-radius: 12px; overflow: hidden; box-shadow: 0 24px 60px -20px oklch(20% 0.02 60 / 0.18); }
+.mock__chrome { display: flex; gap: 6px; padding: 10px 12px; background: var(--color-paper-2); border-block-end: var(--rule-hair) solid var(--color-rule); }
+.mock__chrome span { width: 10px; height: 10px; border-radius: 50%; background: var(--color-rule-2); }
+```
+
+### H9 · Custom Illustration Centerpiece
+A single hand-built SVG (Tier B in the enrichment hierarchy — or pure CSS at Tier A for simpler shapes) sitting on the hero as one illustrative element. The bakery loaf, the studio's mascot, the workflow diagram.
+*Use when:* the brand has a *thing* that benefits from being drawn — a craft, a character, a process.
+*Don't confuse with:* H6 Photographic (real photography) or H8 Mockup (a product screenshot, not artwork).
+
+The illustration itself is *built*, not picked from Storyset / Humaaans / unDraw / Lottie. See [`custom-craft.md`](custom-craft.md) for full recipes (CSS art, hand-built SVG, declarative animation). The cookbook entry below is the page-level structural sketch.
+
+```html
+<section class="hero-art">
+ <div>
+ <p class="eyebrow">Maple Street Bread · est. 2026</p>
+ <h1>Sourdough, every morning.</h1>
+ <p>Slow-fermented overnight, baked on stone, before you wake.</p>
+ </div>
+ <svg viewBox="0 0 200 100" class="loaf" aria-label="A loaf of bread">
+ <path class="loaf__body" d="M 20 70 Q 100 10 180 70 L 180 90 L 20 90 Z" />
+ <path class="loaf__score" d="M 60 50 L 90 30 M 100 45 L 130 25 M 140 50 L 165 35" />
+ </svg>
+</section>
+```
+```css
+.hero-art { display: grid; grid-template-columns: 1fr 1fr; gap: var(--space-2xl); align-items: center; }
+.loaf__body { fill: oklch(72% 0.14 50); }
+.loaf__score{ stroke: oklch(38% 0.10 35); stroke-width: 2; fill: none; stroke-linecap: round; }
+```
+
---
## Section heads
diff --git a/skill/references/custom-craft.md b/skill/references/custom-craft.md
new file mode 100644
index 0000000..d3f16ce
--- /dev/null
+++ b/skill/references/custom-craft.md
@@ -0,0 +1,381 @@
+# Custom craft — how to hand-build hero artwork
+
+This file is loaded only when an enrichment archetype requires construction (Tier A or B in [`hero-enrichment.md`](hero-enrichment.md)). It tells you *which technique* to reach for at *which complexity tier* — and what each looks like done well.
+
+**The principle.** Custom-built artwork is the design. Library-picked artwork is a shortcut, and a good audience reads it as one. The skill's job is to make custom-build the path of least resistance — by knowing when CSS alone suffices, when SVG is right, when JS-driven animation earns its bundle cost, and when (rarely) Three.js is justified.
+
+The 2026 canon is set by Lynn Fisher (*A Single Div*), Diana Smith (*Pure CSS Francine* / *Lace*), Rauno Freiberg, Paco Coursey, Jhey Tompkins, and Adam Argyle. The thread: constraint-driven, hand-crafted, performance-respecting, accessibility-embedded. Use the platform; don't fight it.
+
+---
+
+## Tier A · Pure CSS art
+
+**When.** Geometric forms, gradient compositions, glyph-style decoration. Bars, dots, badges, icons, simple loaves, sliced spheres, abstract logos. Anything that's *shapes plus colour*.
+
+**Effort:** high (mastering `clip-path` + `conic-gradient` takes practice).
+**Payoff:** very high (zero bytes, browser-native, infinitely scalable).
+**Bundle cost:** zero.
+
+### The CSS-art toolkit (2026)
+
+| Feature | Use for | Browser support |
+| --- | --- | --- |
+| `clip-path: polygon(…)` | Multi-sided shapes (chevrons, hexagons, custom blobs) | 96 %+ |
+| `clip-path: path("M …")` | Curved hand-drawn outlines from an SVG path | 88 %+ (use feature query for fallback) |
+| `conic-gradient()` | Pie segments, radial dividers, mandalas, rotating colour wheels | 96 %+ |
+| `radial-gradient()` | Spheres, glow points, sun-burst centres | 100 % |
+| `linear-gradient()` (multi-stop) | Composite shapes via stacked stops | 100 % |
+| `mask-image: url(…)` | Layered transparency, morphing shapes, text-clip effects | 95 %+ |
+| `mix-blend-mode` | Compositional depth (multiply, overlay, screen) | 95 %+ |
+| `filter` (drop-shadow, blur, hue-rotate) | Soft shadows on irregular shapes (uses the alpha channel) | 100 % |
+| `@property` | Smoothly-interpolated custom properties (colour, length, angle) | 88 %+ |
+| `animation-timeline: scroll() / view()` | Declarative scroll-linked motion, hardware-composited | Baseline 2025 (88 %) |
+
+### A worked example — the bakery loaf as a single div
+
+```html
+<div class="loaf" aria-label="A loaf of bread"></div>
+```
+
+```css
+@property --rise {
+ syntax: "<length>";
+ initial-value: 0px;
+ inherits: false;
+}
+
+.loaf {
+ width: 12rem;
+ height: 7rem;
+ background:
+ /* crust ridges */
+ radial-gradient(ellipse at 30% 70%, transparent 1.2rem, var(--color-ink-2) 1.21rem 1.3rem, transparent 1.31rem),
+ radial-gradient(ellipse at 50% 70%, transparent 1.2rem, var(--color-ink-2) 1.21rem 1.3rem, transparent 1.31rem),
+ radial-gradient(ellipse at 70% 70%, transparent 1.2rem, var(--color-ink-2) 1.21rem 1.3rem, transparent 1.31rem),
+ /* loaf body */
+ linear-gradient(180deg, oklch(78% 0.12 60), oklch(64% 0.16 50));
+ border-radius: 50% 50% 14% 14% / 70% 70% 30% 30%;
+ transform: translateY(var(--rise));
+ animation: rise 6s ease-in-out infinite alternate;
+ box-shadow: 0 1.2rem 1.5rem -0.8rem oklch(20% 0.02 60 / 0.18);
+}
+
+@keyframes rise {
+ to { --rise: -4px; } /* the breath: 4px over 6s, the loaf is alive */
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .loaf { animation: none; --rise: 0px; }
+}
+```
+
+That's a hand-built bakery centerpiece in about 25 lines, no asset, animated, accessible. The next bakery brief Hallmark touches gets a *different* loaf because the variation knobs change (rise distance, loaf curvature, crust-ridge spacing, colour stop).
+
+### Anti-patterns of CSS art
+
+- **Recalculating `clip-path` on every scroll.** Tanks framerate. Animate `transform` instead, or use `animation-timeline` (which composites off-thread).
+- **Over-nested wrapper divs.** A pure-CSS illustration should fit in one to three elements. Eight nested wrappers reads as "I gave up structuring this".
+- **No reduced-motion fallback.** Every animation must have a `@media (prefers-reduced-motion: reduce)` block.
+- **Random gradient noise.** If the gradient looks generated rather than designed, redo it. Three stops max for any single gradient layer.
+
+---
+
+## Tier B · Hand-built SVG illustration
+
+**When.** Complex illustrations CSS can't express cleanly — characters, articulated figures, organic curves, multi-element scenes. The bakery's full storefront, the studio mascot, the workflow diagram with seven labelled paths.
+
+**Effort:** medium (designing in Figma + cleaning the export).
+**Payoff:** very high (scales infinitely, compresses to < 10 KB, animatable).
+**Bundle cost:** the file size of the SVG — typically 4–15 KB inline.
+
+### Pipeline
+
+1. **Design in Figma.** Use a component system (constraints, variants). Keep paths as paths — don't rasterise. Name layers; the export honours them.
+2. **Export as SVG.** Figma's export is decent. Set "Outline strokes" only if you need stroke-as-fill animation; otherwise keep them strokes.
+3. **Run through [SVGOMG](https://jakearchibald.github.io/svgomg/)** — removes Figma metadata, unnecessary `<defs>`, redundant transforms. 30–60 % size reduction is typical.
+4. **Inline the result in HTML** for animation, or save as `static.svg` and reference via `<img>` or CSS `background-image` for caching.
+5. **Animate declaratively** — CSS keyframes on `<path d="">` (Chrome, Edge, Safari support the `d` property), `@property`-driven attribute interpolation, or [Motion](https://motion.dev) for orchestrated sequences.
+
+### A hand-built SVG with declarative animation
+
+```html
+<svg viewBox="0 0 200 100" class="loaf-svg" aria-label="A loaf of bread">
+ <path class="loaf-body" d="M 20 70 Q 100 10 180 70 L 180 90 L 20 90 Z" />
+ <path class="loaf-score" d="M 60 50 L 90 30 M 100 45 L 130 25 M 140 50 L 165 35" />
+</svg>
+```
+
+```css
+@property --bake {
+ syntax: "<percentage>";
+ initial-value: 0%;
+ inherits: false;
+}
+
+.loaf-body {
+ fill: oklch(72% 0.14 50);
+ filter: drop-shadow(0 4px 8px oklch(20% 0.02 60 / 0.16));
+ transform-origin: 100px 90px;
+ animation: bake 6s ease-in-out infinite alternate;
+}
+
+.loaf-score {
+ stroke: oklch(38% 0.1 35);
+ stroke-width: 2;
+ stroke-linecap: round;
+ fill: none;
+ stroke-dasharray: 0 200;
+ animation: score 1.6s 0.8s var(--ease-out) forwards;
+}
+
+@keyframes bake { to { transform: scaleY(calc(1 + var(--bake) * 0.005)); --bake: 1%; } }
+@keyframes score { to { stroke-dasharray: 200 200; } }
+
+@media (prefers-reduced-motion: reduce) {
+ .loaf-body, .loaf-score { animation: none; }
+ .loaf-score { stroke-dasharray: 200 200; }
+}
+```
+
+The breath comes from `@property --bake` interpolating a percentage; the score-marks draw themselves once on load via `stroke-dasharray`. No JS. 18 lines of CSS. Reduced-motion-safe.
+
+### Animation choices for SVG in 2026
+
+| Method | When | Verdict |
+| --- | --- | --- |
+| **CSS keyframes on `<path d>`** | Path-morphing where shapes have matching anchor counts | Use this. Composable with the rest of CSS, GPU-friendly. |
+| **`@property` + animated CSS variables** | Smoothly interpolated colour, length, angle, percentage | Use this. Declarative, predictable. |
+| **CSS keyframes on `transform` / `opacity`** | Position, rotation, fade | Always. Hardware-accelerated, no layout thrash. |
+| **`stroke-dasharray` draw-on** | Hand-drawn line illustrations that build themselves | Yes. Cheap and effective. |
+| **SMIL `<animate>`** | Legacy SVG-only attribute animation | Acceptable in 2026 but deprioritised — CSS is composable, SMIL isn't. Use only if CSS can't express it. |
+| **JS via Motion / GSAP** | Multi-element orchestrated entrances, scroll-scrubbing, complex timelines | Use when CSS isn't enough — see Tier C below. |
+
+### Anti-patterns of hand-built SVG
+
+- **Shipping the raw Figma export.** Always run SVGOMG. Untouched exports carry hundreds of bytes of metadata, unused `<defs>`, doubled transforms.
+- **A 300-KB SVG.** Anything over 30 KB is suspicious. Most well-built illustrations sit at 4–15 KB. If yours is 100 KB+, you have hidden raster embeds or thousands of unnecessary path commands.
+- **`viewBox` cruft.** A `viewBox="0 0 24 24"` for an icon, or `viewBox="0 0 1920 1080"` for a hero illustration. Match the box to the design's bounds, no padding, no extra space.
+- **Animation with linear easing on everything.** Add ease-out (or a cubic-bezier specified to two decimals); the difference is the difference between "moving" and "alive".
+- **Path morphing between shapes with mismatched anchor counts.** Browsers will interpolate, but the result jitters. Either match anchor counts, or use `clip-path` instead.
+
+---
+
+## Tier C · Declarative animation (CSS-first, JS-when-needed)
+
+The 2026 declarative animation canon. Use the platform first; reach for JS only when the platform can't express the orchestration.
+
+### CSS keyframes + `@property`
+
+`@property` (Baseline 2024, ~88 % support by 2026) lets you define typed custom properties — `<color>`, `<length>`, `<angle>`, `<number>`, `<percentage>` — that the browser knows how to interpolate smoothly. Without `@property`, animating a custom property steps from start to end with no in-between values.
+
+```css
+@property --hue {
+ syntax: "<angle>";
+ initial-value: 0deg;
+ inherits: false;
+}
+
+@keyframes spin-hue { to { --hue: 360deg; } }
+
+.gradient-loop {
+ background: conic-gradient(from var(--hue),
+ oklch(70% 0.2 var(--hue)),
+ oklch(70% 0.2 calc(var(--hue) + 120deg)),
+ oklch(70% 0.2 calc(var(--hue) + 240deg)));
+ animation: spin-hue 8s linear infinite;
+}
+```
+
+That's a smoothly hue-rotating conic gradient. No JS, no library, GPU-composited.
+
+### Scroll-driven animations
+
+`animation-timeline: scroll()` and `view()` reached **Baseline October 2025** — production-ready in Chromium, Edge, Safari Tech Preview, Firefox behind a flag. The rule: progressive enhancement.
+
+```css
+@supports (animation-timeline: view()) {
+ .reveal {
+ animation: fade-up linear both;
+ animation-timeline: view();
+ animation-range: entry 0% cover 30%;
+ }
+}
+
+@keyframes fade-up {
+ from { opacity: 0; transform: translateY(24px); }
+ to { opacity: 1; transform: translateY(0); }
+}
+```
+
+If the browser supports it, the element animates as it enters the viewport. If not, the element is just there — no JavaScript, no library, no IntersectionObserver. The CSS Scroll-Driven Animations community is the canonical reference: [scroll-driven-animations.style](https://scroll-driven-animations.style/).
+
+### View Transitions API
+
+Production-ready in 2026 (Baseline October 2025 for same-document; Chromium 126+, Safari 18.2+ for cross-document). The Hallmark landing page already uses it for theme transitions:
+
+```js
+function applyTheme(theme) {
+ const apply = () => { /* mutate the DOM */ };
+ if (!reduced && document.startViewTransition) {
+ document.startViewTransition(apply);
+ } else {
+ apply();
+ }
+}
+```
+
+The browser handles the cross-fade. No animation libraries needed for state changes.
+
+### Motion / GSAP / friends — when each earns its bundle
+
+| Library | When | Bundle | Verdict |
+| --- | --- | --- | --- |
+| **[Motion](https://motion.dev)** (`motion/react`, `motion`) | Orchestrated multi-element entrances in React (variants, `AnimatePresence`, viewport hooks). The default for React heroes in 2026. | 4 KB base + 2 KB React = 6 KB. Web Animations API–backed. | First reach for React. |
+| **[GSAP](https://gsap.com)** (free since the Webflow partnership) | Ambitious timelines, scrub-on-scroll, SVG path-morphing across mismatched anchors. Hero sequences with 20+ elements, multi-step narratives. | ~50 KB core; 100 KB+ with plugins (ScrollTrigger, Draggable). | Worth it when timelines are core. Overkill for a fade-in. |
+| **AutoAnimate** | Trivial layout transitions in React (a list reflows, an element appears). | 2 KB. | Fine for what it does. |
+| **Anime.js v4** | Lightweight stagger, simple animations, vanilla JS. | ~15 KB. | Acceptable; less common than Motion in 2026. |
+| **Theatre.js** | Visual editor + code API for ambitious orchestration. Niche but powerful. | Heavy (~80 KB+). | Single-page interactive art only. |
+
+**The decision rule:**
+
+```
+Single element, simple motion → CSS keyframes / @property
+Multiple elements, orchestrated entrance → Motion (React) or GSAP (vanilla / complex)
+Scroll-progress-linked → animation-timeline (CSS) — or GSAP ScrollTrigger if complex
+State change between two layouts → View Transitions API
+A list reflows in React → AutoAnimate
+A complex hero narrative with scrubbing → GSAP timeline + ScrollTrigger
+```
+
+Reaching for Motion for a single fade-in (4 KB for nothing) is the bundle-bloat tell. Reaching for GSAP for a list reflow (50 KB for nothing) is the same tell, louder.
+
+### Anti-patterns of declarative animation
+
+- **Animating `width`, `height`, `top`, `left`, `margin`, or `padding`** (causes layout thrash). Animate `transform` and `opacity` only — they composite on the GPU.
+- **Linear easing on UI** (no subtlety; reads as "demo from a tutorial").
+- **Bouncy elastic on hero entrances** (`cubic-bezier(0.34, 1.56, …)` and friends) — reserved for genuine physical interactions like drag-release.
+- **Importing Motion or GSAP for one fade-in.** 50 KB for what `transition: opacity 400ms var(--ease-out)` does in zero bytes.
+- **Scroll-fade-everything.** Every section fading in on scroll. The page never settles. Pick one orchestrated entrance on first load and let the rest *be there*.
+- **Reveal animations with no `prefers-reduced-motion` fallback.** Every transform / animation must be guarded.
+
+---
+
+## Tier D · Three.js / WebGL / shaders
+
+**When justified.** The 3D *is* the hero value — a rotating product the user can interact with, an interactive 3D playground, a generative art piece. Examples: Apple's product pages with interactive bottles / iPhones, Bruno Simon's portfolio, Vercel's WebGL hero galleries.
+
+**When not.** A static spinning thing the user can't interact with. A bloom-overdosed shader background that "looks premium". A 5-MB model loaded eagerly on a marketing page.
+
+**Performance budget.**
+- < 100 draw calls
+- < 2 MB JS + assets total
+- < 6 s load time
+- 60 fps target on mid-range mobile
+
+**Stack.**
+- React Three Fiber (R3F) for React projects — ergonomic, ~30 KB on top of Three.js
+- Vanilla [Three.js](https://threejs.org) otherwise (~100–300 KB depending on features)
+- Models: glTF 2.0 with Draco compression (20–50 % size reduction)
+- Textures: KTX2 / Basis (much smaller than PNG/JPEG)
+
+**Always include a non-WebGL fallback.** If the canvas fails to initialise (no WebGL2, GPU blacklisted, low-power mode), show a static poster image so the page still renders.
+
+### Anti-patterns of Three.js / WebGL
+
+- **Three.js for a stationary product.** No interaction = no justification. Use SVG or a still photograph.
+- **Bloom + glow overdose.** Three or four post-processing passes that just make everything blurry. Pick one effect, dial it down to "barely visible".
+- **5-MB models loaded eagerly.** Always lazy-load the geometry, show a poster while it streams in.
+- **No fallback.** WebGL fails on ~5 % of devices; if the page is unusable for them, you've failed accessibility.
+- **Generic procedural-noise shaders.** Looks like every other Three.js demo on the internet. Custom shaders earn their place; off-the-shelf Perlin noise rarely does.
+
+---
+
+## Tier E · Generated stills (Nanobanana / Recraft V4 / Midjourney)
+
+When characters or specific scenes are needed and hand-build is uneconomical (the brief calls for a small mascot in five poses; the agency is selling a thing that needs an evocative atmospheric still).
+
+| Model | Cost | Best for | Output |
+| --- | --- | --- | --- |
+| **[Nanobanana 2 / Gemini 2.5 Flash Image](https://ai.google.dev/gemini-api/docs/image-generation)** | $0.039 / image | Character consistency across multiple panels, fast iteration, brand-style adherence via reference images, infographics with text | PNG (transparent supported); no SVG, no animation |
+| **[Recraft V4](https://www.recraft.ai/)** | ~$0.04 / image | **The only mainstream model with production-grade SVG output.** Logos, icons, illustrations that need to live in code and scale. | SVG + PNG |
+| **[Midjourney v8](https://www.midjourney.com)** | ~$0.14 / image | Aesthetic beauty, artistic direction, atmospheric stills | PNG |
+| **[Flux 2](https://blackforestlabs.ai/)** | ~$0.03 / image | Photorealism, skin / fabric / product detail | PNG |
+
+### Discipline when generating
+
+- **Always post-process.** Add grain, asymmetric crop, hand-drawn overlays, colour grading. Raw model output reads as AI 100 % of the time. The post-process is what makes it ours.
+- **Use reference images** for brand consistency. Nanobanana's character-consistency feature is the differentiator vs. Midjourney; feed it your existing brand assets so generations stay on-style.
+- **Stamp the model in the macrostructure comment** (`generated: nanobanana-2 · post-processed`). Future audits need to know provenance.
+- **Verify the SynthID watermark** is present (Google's invisible AI-provenance marker).
+- **Multi-frame animation isn't supported** by any of these models. Don't try to assemble keyframes into a Lottie loop — that's Tier F territory and almost always a worse outcome than a single still.
+
+### Anti-patterns of generated stills
+
+- **Symmetrical compositions.** Algorithmic; reads as AI. Crop asymmetrically.
+- **Smooth-mesh-blob faces.** The 2024 "generic AI character" look. Avoid character-led stills if you can't get past this; or use Nanobanana's character-consistency feature with reference images and prompt heavily for asymmetry / imperfection.
+- **Default lighting + blue-tinted backgrounds.** The generic AI tell. Specify brand-anchored colour and unusual lighting in the prompt.
+- **Six fingers, doubled furniture, impossible rooms.** Less common than 2023, but still lurking. Always inspect.
+
+---
+
+## Tier F · Library illustrations + Lottie (last resort)
+
+When budget and timeline force a shortcut. The catalogue is in [`assets.md`](assets.md) — Storyset, Humaaans, unDraw, IRA Design, LottieFiles. Even at this tier:
+
+- **Customise.** Colour-swap to brand anchor hue. Crop or recompose. Don't ship the unmodified library look.
+- **Avoid the giveaway poses.** Every team has seen "guy on laptop with floating speech bubble" a hundred times. Anything that screams "stock illustration" loses.
+
+### Lottie specifically — last resort
+
+**Use Lottie only when:**
+- The motion is character-articulated (a five-frame mascot wave, a multi-joint walking cycle) and CSS / SVG can't reasonably express it
+- You have a custom-commissioned Lottie that matches your brand
+- File is < 2 MB
+- Pause / resume support is wired
+- `prefers-reduced-motion` fallback is a static keyframe
+
+**Don't use Lottie for:**
+- Spinning logo loops — use CSS `@keyframes rotate`
+- Checkmark-draw confirmations — use SVG `stroke-dasharray`
+- Loading spinners — use CSS conic-gradient + rotate
+- Hover micro-interactions — use CSS transitions
+- Hero centerpieces that could be hand-built — use Tier A or B
+
+The Lottie Tell, version 2026: a generic LottieFiles pull where pure CSS would have built it stronger and lighter. The audit verb catches this.
+
+---
+
+## The bakery worked example, end-to-end
+
+**Brief:** "Build a landing page for a small bakery in Lisbon."
+
+**Step 2 (macrostructure):** Long Document — the bakery is a story-led brand, not a SaaS product.
+**Step 3 (theme):** Linen — warm-paper, prose-led, intimate.
+**Step 4 (enrichment):** E5 Custom Illustration Centerpiece. Tier B (hand-built SVG).
+
+**The output:**
+
+A 60-line SVG of a single loaf, three paths (crust + crumb + scoring marks), positioned to the right of the headline at 40 % column width. Animation: `@property --rise` interpolates a 4 px vertical lift over 6 s, ease-in-out, alternate. The score-marks draw themselves on first paint via `stroke-dasharray`. Reduced-motion: static loaf, no animation.
+
+```css
+/* Hallmark · macrostructure: Long Document
+ * H5 hero: Letter (intimate salutation + 2-paragraph body)
+ * enrichment: E5 Custom Illustration · craft: tier-B SVG (60 lines)
+ * animation: @property --rise (6s, alternate) + stroke-dasharray draw-on
+ * theme: Linen · accent: warm-amber ~3% · studied: no
+ */
+```
+
+The next bakery brief Hallmark touches gets a *different* loaf — different curvature, different rise distance, different score pattern, possibly a different illustration entirely (a sourdough boule vs. a baguette vs. a flatbread). The variation knobs in [`hero-enrichment.md`](hero-enrichment.md) make sure of it.
+
+---
+
+## Common mistakes — and the fixes
+
+- **Reaching for Lottie when CSS would do.** The new tell. Build the loaf in pure CSS or hand-built SVG; the Lottie is the shortcut that costs you.
+- **Importing 50 KB of GSAP for a single fade-in.** Use `transition: opacity 400ms var(--ease-out)`. Zero bytes.
+- **Animating `width` or `height` for a "smooth resize".** Reflows the layout; use `transform: scale(...)` and `transform-origin`.
+- **Three.js for a non-interactive rotation.** No interaction = no justification. Use SVG with `transform: rotate()` animated.
+- **Untouched Figma export.** Run SVGOMG. Always.
+- **Generated raster shipped raw.** Post-process. Grain, crop, colour grade. The raw output reads as AI.
+- **Linear easing.** Add ease-out at minimum. The difference between "moving" and "alive".
diff --git a/skill/references/hero-enrichment.md b/skill/references/hero-enrichment.md
new file mode 100644
index 0000000..05d36fc
--- /dev/null
+++ b/skill/references/hero-enrichment.md
@@ -0,0 +1,296 @@
+# Hero enrichment — when, what, and how much
+
+This file is loaded after the macrostructure pick (Step 3 in the design flow), when you reach Step 4: "Decide on hero enrichment." It tells you whether to enrich the hero with media at all, and if so, which archetype and how to build it.
+
+**The promise.** Enrichment is an option, not a default. A typographic-only hero is *always* an acceptable answer. Visual enrichment — demo video, illustration, mockup, animated loop, abstract background, photography — has to *earn its place*. If the hero can be deleted of its enrichment and still works, the enrichment earned its place. If the hero collapses without the enrichment, you propped weak typography on a crutch.
+
+**The bar.** Better nothing than bad something. A page that ships a quiet, well-set typographic hero is always better than a page that ships a stock illustration, a Lottie checkmark, an aurora-blob background, or a generic centred demo video block.
+
+---
+
+## The enrichment hierarchy
+
+Reach for the highest tier the brief lets you ship in the time you have. Skipping tiers is the new tell.
+
+| Tier | What | When |
+| --- | --- | --- |
+| **0 · Typography only** | No enrichment. Display, lede, optional CTA. | Always acceptable. The strongest fail-state. |
+| **A · Custom-built CSS art** | Pure-CSS shapes, gradients, clip-paths, no asset, zero dependency. | Geometric shapes, gradient compositions, glyph-style decoration. |
+| **B · Hand-built SVG** | Designed in Figma, optimised, animated declaratively. | Illustrations more complex than CSS handles cleanly — a loaf, a mascot, a workflow diagram. |
+| **C · Generated illustration** | Nanobanana / Recraft V4 / Midjourney, with provenance + post-processing. | Characters or specific scenes that hand-build can't economically reach. Always post-processed. |
+| **D · Library illustration** | Storyset / Humaaans / unDraw, customised with brand colours. | When budget and timeline force a shortcut — and even then, never unmodified. |
+| **E · Lottie animation** | LAST RESORT. Only when complex character motion can't be hand-built. | Articulated figures, multi-frame mascot loops. Never for "spinning logo" or "checkmark draw" — those are CSS. |
+
+**The discipline.** If you can do it in tier A, do it in tier A. If A can't reach it, try B. Only drop to C when characters demand it. Only D when the brief is explicit about "fast and cheap". Only E when E is genuinely the only option. Reaching for E because it's familiar — and many AI tools do — is the signature of a templated page.
+
+See [`custom-craft.md`](custom-craft.md) for *how* to build at tiers A and B. See [`assets.md`](assets.md) for the catalogue of sources at tiers C, D, and E.
+
+---
+
+## Eyeball or ask — the decision protocol
+
+Two paths to picking enrichment:
+
+```
+If the brief contains explicit visual cues, pick from this map:
+
+ • "demo", "show how it works", "product tour" → E1 / E2 demo video
+ • "platform", "tool", "infra", "dashboard", "developer" → E3 / E4 mockup
+ • "shop", "store", "menu", "products", "items" → E8 photography (or F6 product grid)
+ • "bakery", "kitchen", "café", "atelier" + craft brief → E5 custom illustration (Tier B SVG)
+ • "agency", "studio", "portfolio" → E8 photography or no enrichment
+ • "manifesto", "essay", "book", "letter" → no enrichment (typography only)
+ • Quiet theme picked → no enrichment (the theme IS restraint)
+
+Else if the brief is genuinely ambiguous, ask one question:
+ "Want me to add a demo video, an illustration, or keep it
+ typography-only? I default to typography-only because it's
+ the strongest fail-state."
+
+Else default to no enrichment. State the inference in one sentence
+in your reply, alongside the macrostructure inference.
+```
+
+When in doubt: don't enrich. The hero will be fine. Most great landing pages are typographic.
+
+---
+
+## Eight enrichment archetypes
+
+Each archetype has a one-line definition, "use when", "avoid when", a short code sketch, and 2–3 within-archetype variation knobs (consistent with [`component-cookbook.md`](component-cookbook.md)).
+
+### E1 · Demo Video — Clipped-by-viewport-edge
+
+A display headline left, a demo video right, and the rightmost ~10–20 % of the video extending past the viewport so it's intentionally cut off. The clip *is* the design — it implies "there's more product than fits on this screen". Pioneered by Linear; refined by Vercel, Resend, Cursor.
+
+*Use when:* the brief is a SaaS / dev tool / dashboard / platform and you have real footage of the product.
+*Avoid when:* you don't have real footage. A clipped-edge video of a stock-footage city skyline reads as filler.
+
+**Knobs:**
+- Clip side (right · left · both)
+- Aspect ratio (16/10 · 16/9 · 4/3)
+- Frame treatment (hairline 1 px frame · browser chrome · none)
+
+```html
+<section class="hero hero--clipped">
+ <div class="hero__copy">
+ <h1>Plan, build, ship.</h1>
+ <p>The project tracker your engineering team won't ignore.</p>
+ <a class="btn" href="/signup">Try it free</a>
+ </div>
+ <figure class="hero__media">
+ <video autoplay muted loop playsinline preload="metadata"
+ poster="/hero-poster.webp" fetchpriority="high"
+ aria-label="Tour of the dashboard interface">
+ <source src="/hero.av1.mp4" type='video/mp4; codecs="av01.0.05M.08"'>
+ <source src="/hero.vp9.webm" type="video/webm">
+ <source src="/hero.h264.mp4" type="video/mp4">
+ </video>
+ </figure>
+</section>
+```
+
+```css
+.hero--clipped {
+ display: grid;
+ grid-template-columns: minmax(20rem, 1fr) 1.4fr;
+ gap: var(--space-2xl);
+ align-items: center;
+ overflow: visible; /* let the media spill past the page edge */
+}
+.hero__media {
+ width: calc(100% + 12vw); /* the 12 % of viewport that sits beyond the right edge */
+ aspect-ratio: 16 / 10;
+ border-radius: 12px;
+ border: var(--rule-hair) solid var(--color-rule);
+ overflow: hidden;
+}
+.hero__media video { width: 100%; height: 100%; object-fit: cover; }
+
+@media (max-width: 60rem) {
+ .hero--clipped { grid-template-columns: 1fr; }
+ .hero__media { width: 100%; } /* don't try to clip on mobile — reads as broken */
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .hero__media video { display: none; }
+ .hero__media { background: url('/hero-poster.webp') center/cover; }
+}
+```
+
+**Critical:** never `loading="lazy"` on the hero video — that kills LCP. Use `preload="metadata"` and `fetchpriority="high"`. Always include a `poster=""` and a `<track kind="captions">` for accessibility.
+
+### E2 · Demo Video — Full-bleed muted loop with ghost overlay
+
+Video fills the fold, ghost-tinted via `mix-blend-mode: multiply` over a paper-coloured overlay so the type stays readable. The video is wallpaper, not subject.
+
+*Use when:* the product's *feel* is the message (mood, tactility, atmosphere).
+*Avoid when:* the product needs to be *seen* clearly — use E1 or E3 instead.
+
+**Knobs:**
+- Ghost opacity (0.3 / 0.5 / 0.7)
+- Text alignment (left-bias / centred)
+- Pause behaviour (always-loop · pause-on-hover · pause-when-out-of-viewport)
+
+### E3 · Mock App Screenshot — Browser-framed split
+
+Display headline left, a browser-frame mockup right, the mockup window slightly tilted (1–3°) for life. Frames are from [Browserframe](https://browserframe.com) or hand-built (a 1-px hairline + three macOS dots).
+
+*Use when:* you're selling a web app and you have a clean, well-lit screenshot.
+*Avoid when:* the screenshot is busy or blurry — the frame draws attention to the mess.
+
+**Knobs:**
+- Frame style (browser chrome · macOS toolbar · minimal hairline · none)
+- Tilt angle (0° · 1.5° · 3°)
+- Screenshot count (1 · stack-of-3 · orbit-of-3)
+
+### E4 · Mock App Screenshot — Floating no-frame
+
+Same composition as E3 but without browser chrome — the screenshot floats with a soft shadow and 12 px corner radius. Cleaner; demands a higher-quality screenshot since the chrome isn't there to forgive.
+
+*Use when:* the screenshot itself is beautiful enough to stand naked.
+*Avoid when:* the product needs the "this is a real web app" cue from the chrome.
+
+**Knobs:**
+- Shadow depth (subtle / medium / dramatic)
+- Corner radius (0 · 8 px · 16 px)
+- Background reveal (gradient / solid / none)
+
+### E5 · Custom Illustration Centerpiece
+
+A hand-built SVG (the default, Tier B) or a generated raster (Tier C, when characters demand it) sitting on the hero as a single illustrative element — the bakery loaf, the studio's mascot, the diagram of how the workflow flows.
+
+*Use when:* the brand has a story or a thing-it-makes that benefits from being drawn.
+*Avoid when:* the brand is "modern professional team" generic — illustrating that is the new template.
+
+**Knobs:**
+- Build method (Tier A pure-CSS / Tier B hand-SVG / Tier C generated / Tier D library)
+- Animation (none · loop · scroll-linked)
+- Scale (small accent · dominant)
+
+For *how* to build a hand-drawn loaf in 60 lines of SVG and animate its breath with `@property`, see [`custom-craft.md`](custom-craft.md) — there's a full bakery worked example.
+
+### E6 · Animated Loop — pure CSS / SVG / Motion
+
+A small custom-built loop — an orbiting dot, a breathing rectangle, an animated gradient stop, a type-mask reveal. The point is *small*, custom, and looped *only when reduced-motion is off*.
+
+*Use when:* the page is otherwise still and one small animated element gives it life.
+*Avoid when:* the page already has movement — adding more reads as anxious.
+
+**Knobs:**
+- Medium (CSS keyframes · SVG SMIL/CSS · Motion)
+- Placement (margin · inline-with-headline · corner-accent)
+- Loop duration (≤ 4s — anything longer drags)
+
+### E7 · Abstract Background — subtle gradient + grain
+
+A two-colour CSS gradient at low chroma, overlaid with SVG `<feTurbulence>` grain at < 0.1 opacity. *Not* aurora; *not* purple-to-cyan mesh; *not* floating orbs. The point is *texture you can barely see* — paper-quality, not decoration.
+
+*Use when:* the page would feel synthetic with a flat surface.
+*Avoid when:* the theme already has a paper feel (Specimen, Linen, Riso). Doubling the grain is muddy.
+
+**Knobs:**
+- Gradient direction (45° / 135° / radial)
+- Grain amount (off · subtle · textured)
+- Animation (none · slow drift · scroll-linked parallax)
+
+```html
+<section class="hero hero--bg">
+ <div class="hero__bg" aria-hidden="true">
+ <svg width="0" height="0" style="position: absolute;">
+ <filter id="grain"><feTurbulence baseFrequency="0.9" numOctaves="2"/></filter>
+ </svg>
+ </div>
+ <div class="hero__copy"> ... </div>
+</section>
+```
+```css
+.hero { position: relative; isolation: isolate; }
+.hero__bg {
+ position: absolute; inset: 0; z-index: -1;
+ background:
+ linear-gradient(135deg,
+ color-mix(in oklch, var(--color-paper) 100%, var(--color-accent) 4%),
+ color-mix(in oklch, var(--color-paper) 100%, var(--color-paper-2) 50%));
+}
+.hero__bg::after {
+ content: ""; position: absolute; inset: 0;
+ filter: url(#grain);
+ opacity: 0.06;
+ mix-blend-mode: multiply;
+ pointer-events: none;
+}
+```
+
+### E8 · Hero Photography — single tightly-cropped image
+
+Existing H6 archetype in the cookbook. Cross-referenced here for completeness. See [`component-cookbook.md`](component-cookbook.md) for variation knobs.
+
+---
+
+## Animation discipline (hero specifically)
+
+Cross-references [`motion.md`](motion.md), [`microinteractions.md`](microinteractions.md), and [`custom-craft.md`](custom-craft.md). The hero is the highest-stakes animation surface on the page; the rules are tighter here than elsewhere.
+
+**One orchestrated reveal per page.** Not eight. Not "everything fades in on scroll". One: the hero settles in 0.4–0.8 s with a single coordinated motion, then stops.
+
+**Banned for hero entrances:**
+- Bouncy elastic easing (`cubic-bezier(0.34, 1.56, ...)`) — reads as 2016 Framer demo
+- Scroll-fade-everything (every section fades in when it enters the viewport)
+- Mouse-follow gradients on SaaS landing pages (allowed only on portfolio / creative / agency work)
+- Parallax-on-mouse (motion sickness, gimmicky)
+- Particle / starfield backgrounds (2010s nostalgia, distracting)
+- Auto-rotating hero carousels (WCAG 2.2.2 fail unless paused-on-hover-and-focus is implemented)
+
+**Allowed:**
+- A single image-fade-in-late after the headline lands (~0.6 s after, ~0.4 s duration)
+- Type-unmask on the headline (`clip-path` opening over text)
+- View Transitions API for state changes (theme switch, route change)
+- Number-tick on a stat-led hero (counter from 0 to final, ≤ 1.2 s)
+- A single subtle Lottie / CSS loop ≤ 4 s, with `prefers-reduced-motion` fallback
+
+**Reduced-motion is the default in 2026.** Every animation gets a `@media (prefers-reduced-motion: reduce)` block that either disables the motion or replaces it with a static keyframe. This is non-negotiable; the slop test will catch you.
+
+---
+
+## Quality bar — eight pre-flight questions
+
+Every question must answer *yes* before the enrichment ships. If any answer is *no*, ship the typographic-only hero instead.
+
+1. Does the enrichment **communicate** something the typography can't?
+2. Is it under **2 MB** total (video poster + first segment, illustration + animation JSON, image + grain)?
+3. Does it have a **`prefers-reduced-motion` fallback**?
+4. If video: muted, looped, `playsinline`, with a poster + `fetchpriority="high"` + caption track?
+5. If illustration: built or generated with intent? **Not picked from a Lottie library as a shortcut?**
+6. If background: under one accent colour at < 5 % footprint? (Aurora and mesh-gradients fail this.)
+7. Does it survive being deleted? (If the hero still works without it, it earned its place. If the hero collapses without it, you propped weak typography on a crutch.)
+8. Does its tone match the page's tone? (Risograph illustration on a Brutal page = wrong. Hand-drawn doodle on a Workbench developer-tool page = wrong. Three.js bloom on a Quiet page = wrong.)
+
+The slop test ([`SKILL.md`](../SKILL.md) §5) carries four binary gates that mirror these questions; the audit verb runs them.
+
+---
+
+## Output stamp
+
+When you ship enrichment, the macrostructure stamp records the choice:
+
+```css
+/* Hallmark · macrostructure: Marquee Hero · H1 hero knobs: size=xxl, alignment=left-bias
+ * enrichment: E1 Clipped-Edge Video · clip=right, aspect=16/10, frame=hairline
+ * craft: tier-A CSS art (no real video — pure custom-built mockup)
+ * theme: Pastel · accent: indigo ~3% · studied: no
+ */
+```
+
+This signals to future Hallmark runs (and to the audit verb) what was chosen and how. It also lets the user see the inferences in one place and redirect if anything's off.
+
+---
+
+## Common mistakes — and the fixes
+
+- **Defaulting to E5 illustration on every brief.** Most heroes don't want an illustration. Reach for E0 (typography only) first; reach for E1–E4 when there's a *thing* to show; reach for E5 only when illustration genuinely matches the tone.
+- **Using a stock Lottie checkmark as the hero animation.** That's tier E used to skip tiers A–D. Build the checkmark in pure CSS (`stroke-dasharray` animated to draw the tick); it's 8 lines.
+- **Adding a grain background everywhere.** Grain is a treatment, not a default. Half the existing themes already carry texture (Riso, Linen, Specimen). Don't double up.
+- **Treating the abstract background as the hero.** It isn't. The headline is. The background is paper.
+- **Shipping the unmodified Storyset SVG.** That's tier D ungrounded — the library look. Customise the colour to your anchor hue at minimum; recompose if you can.
+- **A clipped-edge video on mobile.** The clip reads as broken on a 375-px viewport. Always collapse to stacked at < 60 rem.