howone 0.1.20 → 0.1.23

package/templates/vite/.howone/skills/hallmark/references/custom-theme.md

@@ -0,0 +1,329 @@
+# Custom theme — protocol
+
+Loaded only when the user has opted into the **custom** theme route in Step 1 of the Design flow. Custom produces a **complete OKLCH palette + free-font pairing tuned to this brief** — a one-off theme written inline into the page's `:root`, not a permanent catalog entry.
+
+**The freedom is the combination, not the rules.** Every constraint in [`color.md`](color.md), [`typography.md`](typography.md), and [`anti-patterns.md`](anti-patterns.md) still applies. The 65 slop-test gates fire unchanged. The Step 5 preview block surfaces the palette + pairing in plain text *before* any code is emitted, so the user can redirect.
+
+## Two words, plain English
+
+- **catalog** — the named-theme catalogue. Hallmark's 22 themes (Specimen, Atelier, Brutal, Salon, Newsprint, Linen, Studio, Manifesto, Terminal, Midnight, Almanac, Garden, Quiet, Riso, Sport, Bloom, Coral, Violet, Aurora, Halo, Plume, Editorial). Each one is a fixed combination of paper-band, display-style, and accent-hue. The rotation rule cycles through them so two consecutive runs don't read alike. **This is the default.** Most briefs use it.
+- **custom** — made-to-measure. A one-off palette + font pairing constructed specifically for one brief. The skill builds the OKLCH values, picks fonts, and stamps the page — but does **not** extend the catalog with a new theme. The rules behind the catalog (paper L bands, accent chroma caps, font ban list, slop-test gates) all still apply; only the *combination* is per-brief.
+
+## When to surface this fork — Step 1 trigger signals
+
+Hallmark must **not** offer catalog-vs-custom on every prompt. That's friction, not discipline. Surface the fork only when the brief carries one of these signals:
+
+1. **Explicit ask** — the user types `custom`, "custom theme", "tailored to our brand", "make it ours", "something unique", "play around with the colors and fonts", "I want my own palette".
+2. **Named brand colour** — the user gives a specific anchor colour as a hex / OKLCH / brand name. Example: "use our terracotta", "the brand red is hex #c0392b", "anchor on sea-blue".
+3. **Multi-attribute aesthetic the catalog can't carry** — three or more vibe words pointing at a specific, off-catalog feel. Examples: "moss, lichen, soft pink, herbal" / "sun-drenched, market-day, carbon-black" / "late-night, neon, brutalist deli". Compare against the 22 catalog themes; if no single catalog theme is within one axis-step of the vibe, fire the fork. **One adjective ("warm", "technical", "playful") is not a signal — that's a tone, the catalog already carries it.**
+4. **Brand-mood reference attached** — the user attaches a colour swatch, a moodboard, a Pantone chip. (If they attach a *page* screenshot, route to `study` instead; custom is for brand colour / mood, study is for design DNA.)
+
+If any signal fires, ask one short follow-up before picking a theme:
+
+> *"This brief reads like a custom palette would fit better than the 22 named themes. Want me to construct a custom OKLCH palette + free-font pairing tuned to <one-line summary of the vibe>, or stay on the catalog for variety + speed?"*
+
+Wait for the user to answer. If they say custom (or yes / go) → continue this protocol from § A. If they say catalog (or no / stay catalog) → drop the fork and proceed with the catalog route. **Default to catalog** — silence routes to catalog, not custom.
+
+If **none** of the signals fires, do not mention the fork at all. Continue silently with the catalog flow.
+
+---
+
+## § A · The one follow-up question
+
+Once the user names `custom` as the theme route, ask **one** thing in **one** message:
+
+> *"Custom needs one input — describe the brand's vibe in 4–8 words. Examples: 'archival warmth, hand-set, no varnish' · 'industrial precision, cool, technical' · 'moss, lichen, soft pink, herbal' · 'sun-drenched, market-day, carbon black' · 'late-night, neon, brutalist deli'.*
+>
+> *Optional second input: an anchor colour — hex, OKLCH, or a name like 'terracotta', 'sea-blue', 'forest-green', 'dusty-pink'. If you skip it, I'll pick one from the vibe."*
+
+**Do not ask anything else.** Audience / use / tone (Step 1) plus the brand vibe is already enough signal. The model has no business asking the user to nominate paper lightness or font weights — that's the model's job.
+
+If the user gives just two or three words ("sun-drenched"), proceed; the recipe below extracts enough. If the user gives a paragraph, accept it but compress to 4–8 words for the stamp.
+
+---
+
+## § B · Palette construction
+
+Build the palette in this order. Each step cites the rule it's obeying — do not restate the rule, just apply it.
+
+### B.1 · Anchor accent first
+
+- Convert the user's named or hex anchor into OKLCH.
+- Clamp chroma to **0.12–0.20** per [`color.md`](color.md) § "Accent — the discipline".
+- If user skipped: derive hue from the vibe — *warmth* → 30–60° · *technical/industrial* → 220–250° · *botanical/moss* → 130–160° · *late-night/neon* → 280–320° · *sun-drenched/market* → 60–80° amber. Keep chroma 0.12–0.16 (mid-saturation; saturation comes from contrast against neutral, not from chroma).
+
+### B.2 · Paper
+
+- Derive paper L from the vibe:
+  - bright/airy/breakfast/hand-set → **L 95–98 %** (warm-tinted)
+  - archival/editorial/restrained → **L 92–95 %** (warm-tinted)
+  - technical/clinical/spec-sheet → **L 98–100 % near-white** (cool-tinted; can equal #fff but tinted neutrals downstream)
+  - dark/restless/late-night/manifesto → **L 12–18 %** (anchor-tinted)
+- **Always tint paper toward the anchor hue with chroma 0.005–0.020** per [`color.md`](color.md) § "Neutral tinting". Pure-white #fff is allowed only when ink + accent + greys carry the chroma; the paper itself never carries chroma 0 in *both* directions.
+- Paper-2 (one elevation step): step ±2–4 % L from paper.
+- Paper-3 (optional second step): step ±5–7 % L from paper. Skip on minimal palettes.
+
+### B.3 · Ink
+
+- If paper L < 50: ink L **88–96 %**.
+- If paper L ≥ 50: ink L **16–24 %**.
+- Tint ink chroma **0.005–0.014** toward anchor (a shade darker / lighter, never neutral).
+- Ink-2 (secondary text): step 4–8 % L away from ink toward paper. Same hue family.
+
+### B.4 · Supporting greys
+
+Step by ~6–10 % L between paper and ink, all tinted toward anchor with chroma 0.005–0.018:
+
+- `--color-rule` — dividers · L ~70–82 % (light paper) or ~26–34 % (dark paper).
+- `--color-rule-2` — secondary dividers · 4–6 % L closer to paper than rule.
+- `--color-muted` — de-emphasised text · L ~38–56 %.
+- `--color-neutral` — mid-grey equivalent · L ~30–56 %.
+
+These are not arbitrary. The L-step gives the palette **typographic depth** without leaning on accent.
+
+### B.5 · Focus
+
+- Same hue as accent, slightly higher chroma (0.18–0.22) for visibility.
+- Same L as accent ±5 %.
+- Used only on `:focus-visible` — must show instantly per [`microinteractions.md`](microinteractions.md) § "Focus is a first-class state".
+
+### B.6 · Accent-ink (overlay text colour on accent)
+
+- If accent L > 50: use ink (text reads dark on accent fill).
+- If accent L ≤ 50: use paper (text reads light on accent fill).
+- Verify **APCA contrast ≥ 7:1** for body, ≥ 3:1 for large text per [`color.md`](color.md).
+
+### B.7 · Verification
+
+- **Gate 8** (no pure #000 / #fff base): paper and ink both have chroma > 0. Pass.
+- **Gate 24** (no zero-chroma neutrals): every grey has chroma ≥ 0.005. Pass.
+- **Gate 25** (accent ≤ 5 % footprint): plan the accent's role on the page (active state, one wordmark dot, one CTA fill). Don't carpet a section in accent.
+
+---
+
+## § C · Font pairing
+
+Custom pulls from the seven tone-pairings in [`typography.md`](typography.md) — Editorial, Technical, Brutalist, Soft, Luxury, Playful, Austere, Workshop. Each tone has a **free baseline** and a **paid upgrade**.
+
+### C.1 · The freedom
+
+The catalog pairs Display-from-tone-X with Body-from-tone-X. **Custom can mix tones** — that's the whole point:
+
+- Editorial display + Technical body (italic Fraunces wordmark + Geist body) — works for an academic-tone SaaS.
+- Brutalist display + Editorial body (Anton + Newsreader italic) — works for a left-leaning manifesto magazine.
+- Playful display + Austere body (Bricolage Grotesque + Inter Tight) — works for a creator-tool brand.
+- Luxury display + Technical body (Cormorant Garamond + JetBrains Mono) — works for a hand-crafted dev-tool.
+
+Pick **one display face** and **one body face** from any tone's columns. Optional mono if the page has code or tabular data.
+
+### C.2 · The discipline
+
+- **Free baseline only** unless the user has confirmed paid licences. Per [`typography.md`](typography.md) § "The discipline": "Never name a paid font in code without confirming the user is licensed."
+- **Banned defaults still banned** per [`typography.md`](typography.md) § "Banned defaults" — Inter / Roboto / Open Sans / Poppins / Lato / Work Sans / DM Sans / Montserrat / system-ui as display all fail Gate 1.
+- **Variable fonts are preferred** when available (Fraunces, Bricolage Grotesque, Newsreader, Geist, EB Garamond, Inter Tight) — they support optical-size and weight axes for tighter typographic control.
+
+### C.3 · The pair must read
+
+Once you have display + body, mentally render the page:
+
+- Does the display face have enough weight contrast (200/400 next to 700/900) per [`typography.md`](typography.md) § "Commit to extremes"?
+- Does the body face read at the chosen body size (≥ 14 px floor; default 1 rem) at the chosen measure (45–75 ch)?
+- If display is mono and body is mono — that's only allowed when the page IS the design (Terminal-aesthetic, true single-font specimen). Per [`typography.md`](typography.md) line 7.
+
+If any answer is no, redirect — pick a different body face or shift the display weight.
+
+---
+
+## § D · Custom-axis computation
+
+A custom theme must declare its three diversification-rule axis values explicitly so [`SKILL.md`](../SKILL.md) § "Theme-diversification rule" fires the same way as it does on catalog themes.
+
+### D.1 · Paper band
+
+- **dark** — paper L < 30 %
+- **mid** — paper L 30–85 %
+- **light** — paper L > 85 %
+
+### D.2 · Display style
+
+Pick one based on the chosen display face:
+
+- **italic-serif** — Fraunces italic, Newsreader italic, EB Garamond italic, Cormorant italic
+- **roman-serif** — Source Serif 4, Newsreader, Crimson Pro, Bitter, Cardo
+- **geometric-sans** — Geist, Bricolage Grotesque, Inter Tight, Manrope, Sora
+- **mono** — Geist Mono, JetBrains Mono, IBM Plex Mono, Space Mono
+- **display-condensed-italic** — Migra italic, Tobias italic
+- **display-condensed-bold** — Anton, Bebas Neue, Oswald, Barlow Condensed
+- **display-heavy** — Inter Tight 900, Bricolage 800, Druk-class
+- **slab-serif** — Roboto Slab, Bitter heavy, Zilla Slab
+- **system-native** — system-ui, Inter Tight 400 (austere)
+- **risograph-bold** — bold sans with hand-crafted feel
+- **handwritten** — Caveat, Sacramento, Patrick Hand (rare; only when brand demands)
+
+### D.3 · Accent hue band
+
+- **warm** — hue 10–60° (red, orange, amber)
+- **cool** — hue 200–300° (blue, indigo, cyan)
+- **neutral** — no chromatic accent (austere; chroma < 0.05)
+- **chromatic-other** — anything outside warm/cool/neutral. Sub-tag the specific anchor: `chromatic-green ~145°` · `chromatic-sage ~120°` · `chromatic-phosphor ~150°` · `chromatic-terracotta ~30°` · `chromatic-dusty-pink ~350°` · `chromatic-moss ~140°` · `chromatic-amber ~75°`.
+
+### D.4 · Where these go
+
+Write all three into the macrostructure stamp (§ E below) and the `.hallmark/log.json` entry (§ F below). They are the durable record. The next run reads them.
+
+---
+
+## § E · Stamp format
+
+The CSS comment at the top of the produced stylesheet (per [`SKILL.md`](../SKILL.md) Step 6 § "Stamp the output"):
+
+```css
+/* Hallmark · macrostructure: <name> · <hero archetype + knobs>
+ * theme: custom · vibe: "<4–8 words>" · paper: oklch(<L>% <C> <H>) · accent: oklch(<L>% <C> <H>)
+ * display: <font name> · body: <font name> · axes: <paper-band> / <display-style> / <accent-hue>
+ * studied: no · context: <user-provided | inferred> · v0.6.x
+ */
+```
+
+Concrete example:
+
+```css
+/* Hallmark · macrostructure: Long Document · H5 hero knobs: salutation=time-stamp, body=2 paragraphs, signoff=initials
+ * theme: custom · vibe: "archival warmth, hand-set, no varnish" · paper: oklch(94% 0.020 65) · accent: oklch(58% 0.16 35)
+ * display: Fraunces italic · body: Source Serif 4 · axes: light / italic-serif / chromatic-terracotta
+ * studied: no · context: explicit · v0.8.0
+ */
+```
+
+The stamp is the durable record. `audit` reads it. The next run reads it. The user reads it.
+
+---
+
+## § F · `.hallmark/log.json` entry shape
+
+Custom runs extend the existing schema with a `theme_axes` field and an optional `vibe` field:
+
+```json
+{ "date": "2026-05-01",
+  "macrostructure": "Stat-Led",
+  "theme": "custom",
+  "theme_axes": "light / italic-serif / chromatic-terracotta",
+  "vibe": "archival warmth, hand-set, no varnish",
+  "enrichment": "none",
+  "brief": "Coffeebox · subscription" }
+```
+
+Catalog entries continue to record `theme: <name>` and skip `theme_axes` (the catalog's axes are looked up from [`tokens.css`](../../site/css/tokens.css)). Step 2.5 logic uses the same diversification check on both — for catalog entries it reads the axes from tokens.css; for custom entries it reads them from the entry.
+
+When rotating, **a custom run that follows another custom run must differ on at least one axis from the previous custom** — same rule as catalog-vs-catalog. A custom run that follows a catalog run must differ on at least one axis from the catalog's axes. The diversification rule is theme-route-blind.
+
+---
+
+## § G · Three worked examples
+
+Concrete generations to seed model imitation. Each shows the brief, the user's vibe answer, the constructed palette, the chosen pair, and the stamp.
+
+### G.1 · Archival café — "Coffeebox"
+
+**Brief:** *"Build me a landing page for Coffeebox — a small-batch coffee subscription. Roast on Sunday, ship on Monday, drink Tuesday. Audience: people who already buy good coffee and want fewer trips to the shop. Tone: warm, hand-set, editorial — like a small café's chalkboard. Theme route: custom."*
+
+**Vibe answer:** *"archival warmth, hand-set, no varnish."*  **Anchor:** *"terracotta."*
+
+**Palette:**
+- paper `oklch(94% 0.020 65)` — warm-cream, hue 65 (amber-warm)
+- paper-2 `oklch(91% 0.022 65)` — one elevation step
+- ink `oklch(22% 0.014 60)` — warm dark brown-black
+- ink-2 `oklch(40% 0.014 60)` — warm secondary
+- rule `oklch(78% 0.018 65)` — warm hairline
+- muted `oklch(54% 0.014 60)` — warm grey
+- accent `oklch(58% 0.16 35)` — terracotta (hue 35, chroma 0.16)
+- accent-ink `oklch(96% 0.014 65)` — paper for text on accent
+- focus `oklch(56% 0.20 35)` — accent at higher chroma
+
+**Pair:** display **Fraunces italic** (Editorial, free) · body **Source Serif 4** (Editorial, free) · mono **JetBrains Mono** (Technical, free).
+
+**Axes:** **light / italic-serif / chromatic-terracotta**.
+
+**Stamp:**
+```css
+/* Hallmark · macrostructure: Long Document · H5 hero knobs: salutation=time-stamp, body=2 paragraphs, signoff=initials
+ * theme: custom · vibe: "archival warmth, hand-set, no varnish" · paper: oklch(94% 0.020 65) · accent: oklch(58% 0.16 35)
+ * display: Fraunces italic · body: Source Serif 4 · axes: light / italic-serif / chromatic-terracotta
+ * studied: no · context: explicit · v0.8.0
+ */
+```
+
+### G.2 · Industrial fintech — "Loop"
+
+**Brief:** *"Loop is a real-time payment-rail observability platform for fintechs. Audience: platform engineers. Use case: try it / contact sales. Tone: industrial, cool, technical. Theme route: custom."*
+
+**Vibe answer:** *"industrial precision, cool, technical."*  **Anchor:** *"sea-blue."*
+
+**Palette:**
+- paper `oklch(13% 0.012 220)` — dark cool
+- paper-2 `oklch(17% 0.014 220)` — one step up
+- paper-3 `oklch(22% 0.014 220)` — two steps up (panels)
+- ink `oklch(94% 0.010 220)` — cool light
+- ink-2 `oklch(72% 0.010 220)`
+- rule `oklch(30% 0.012 220)`
+- muted `oklch(58% 0.012 220)`
+- accent `oklch(72% 0.16 220)` — sea-blue (cool)
+- focus `oklch(78% 0.20 220)`
+
+**Pair:** display **Geist Mono 500** (Technical, free) · body **Geist** (Technical, free) · mono **Geist Mono** (Technical, free).
+
+Note: this *is* a single-family page (Geist + Geist Mono are the same family at different widths). [`typography.md`](typography.md) line 7 allows it: "single-font pages are allowed only when the single font IS the design choice." For an industrial-precision fintech, that's the design choice.
+
+**Axes:** **dark / mono / cool**.
+
+**Stamp:**
+```css
+/* Hallmark · macrostructure: Workbench · F2 sticky-scroll knobs: pinned=right, content=trace-panel, steps=3
+ * theme: custom · vibe: "industrial precision, cool, technical" · paper: oklch(13% 0.012 220) · accent: oklch(72% 0.16 220)
+ * display: Geist Mono 500 · body: Geist · axes: dark / mono / cool
+ * studied: no · context: explicit · v0.8.0
+ */
+```
+
+### G.3 · Botanical apothecary — "Mossroot"
+
+**Brief:** *"Mossroot is a small herbal apothecary in Porto. We make tinctures, salves, and tea blends. Audience: locals + visitors. Use: see what we make + visit. Tone: quiet, herbal, hand-poured. Theme route: custom."*
+
+**Vibe answer:** *"moss, lichen, soft pink, herbal."*  **Anchor:** *(skipped — pick from vibe)*.
+
+The vibe names two hues: *moss* (greenish, ~140°) and *soft pink* (warm, ~350°). Pick **soft pink as the accent** (single anchor — custom is one-accent strict) and use the moss-green as the *paper tint* (chroma 0.018 toward 145°). This carries the dual-vibe without splitting accent.
+
+**Palette:**
+- paper `oklch(96% 0.018 145)` — moss-tinted near-white
+- paper-2 `oklch(93% 0.020 145)`
+- ink `oklch(22% 0.014 140)` — moss-tinted dark
+- ink-2 `oklch(42% 0.014 140)`
+- rule `oklch(82% 0.018 145)`
+- muted `oklch(56% 0.014 140)`
+- accent `oklch(72% 0.13 350)` — dusty-pink (chromatic-other)
+- focus `oklch(70% 0.18 350)`
+
+**Pair:** display **Cormorant Garamond** (Luxury, free) · body **EB Garamond** (Luxury, free) · mono **Geist Mono** (rare on this page; only for ingredient lists).
+
+**Axes:** **light / roman-serif / chromatic-other (dusty-pink)**.
+
+**Stamp:**
+```css
+/* Hallmark · macrostructure: Catalogue · F1 catalogue knobs: tiles=8, columns=2, rule=hairline-between
+ * theme: custom · vibe: "moss, lichen, soft pink, herbal" · paper: oklch(96% 0.018 145) · accent: oklch(72% 0.13 350)
+ * display: Cormorant Garamond · body: EB Garamond · axes: light / roman-serif / chromatic-other (dusty-pink)
+ * studied: no · context: explicit · v0.8.0
+ */
+```
+
+---
+
+## What custom does **not** do (worth restating)
+
+1. **Does not invent themes that ignore the rules.** Every paper L band, accent chroma cap, neutral-tinting requirement, font ban, and slop-test gate carries forward. The freedom is the *combination* — not the rules.
+2. **Does not save themes for reuse.** A custom run is per-output. The skill does not write back to [`tokens.css`](../../site/css/tokens.css). If the user wants a permanent theme, they paste the custom palette into tokens.css themselves and name it.
+3. **Does not ask multiple follow-up questions.** One vibe answer (+ optional anchor) is enough. The audience/use/tone from Step 1 plus the brief plus the macrostructure pick already give the model 80 % of the signal.
+4. **Does not relax the diversification rule.** Custom entries declare their three axes the same way catalog entries do; the rotation rule fires on both, theme-route-blind.
+5. **Does not bypass the Step 5 preview.** The custom palette + pairing surface in plain text *before* any code is emitted, so the user can redirect early.
+
+If any of those five lines is bent, the custom output is over-invented. Audit it; redirect.

package/templates/vite/.howone/skills/hallmark/references/design-md.md

@@ -0,0 +1,116 @@
+# design.md — opt-in portable design system
+
+Loaded by [`SKILL.md`](../SKILL.md) Step 6 ONLY when the user explicitly asks Hallmark to lock the current build's design system into a portable file. The default verb does NOT auto-emit `design.md`. The user iterates freely until they say the system is settled, then asks for it.
+
+This file is **also** loaded by [`study.md`](study.md) when the user — after a successful `study` diagnosis — asks for the DNA to be emitted as a portable system. The format below is shared between the two paths; the only differences are spelled out in § Two emission paths (default vs study) and in [`study.md`](study.md) § Emitting a `design.md` from `study`.
+
+## Triggers (phrase-only — no new verb)
+
+Fire ONLY when the user says one of:
+
+- *"lock the system"* / *"lock the design system"* / *"lock the DNA"* / *"lock this DNA"*
+- *"give me a design.md"* / *"write a design.md"* / *"export this as a design.md"*
+- *"extract this to a design system"* / *"extract the tokens"* / *"extract the DNA"*
+- *"make this portable"* / *"make the DNA portable"*
+- *"I want to use this in another project"*
+
+For everything else — including the default build, the redesign verb on a single page, and free iteration on the same brief — skip. The single-page redesign and default verb stay token-portable via `tokens.css`; `design.md` is the explicit lock-in step.
+
+## Two emission paths (default vs study)
+
+The same `design.md` format is emitted from two different entry points. They differ in which signals seed the file and in how strict the refusal layer is.
+
+| | **Default-verb path** (lock the system) | **Study-verb path** (lock the DNA) |
+| --- | --- | --- |
+| **Trigger context** | After at least one build the user has iterated on and is satisfied with | After a successful `study` diagnosis (image or URL) |
+| **Source of tokens** | The build's in-memory token state | The studied DNA — exact from CSS in URL mode, estimated from bands in image mode |
+| **Refusal layer** | None — the user owns the build they iterated on | Tighter — see [`study.md`](study.md) § Emission-refusal layer. URL mode requires attestation; third-party URLs are refused |
+| **`## Provenance` block** | Omitted (the system is the user's own work) | Required — records source mode, URL or "image", date, attestation answer, confidence note |
+| **`## Notes` block** | Optional — covers any decisions worth remembering | Required — carries the diagnosis's "anti-patterns to NOT carry over" list |
+
+Both paths produce a `design.md` Hallmark can read on subsequent runs; the file format is uniform once written.
+
+## Scope
+
+- **Page-builds only.** Skip on component-scope — a single component is too small to be a system.
+- **Multi-page redesign keeps existing behaviour.** `hallmark redesign --multi-page` produces the heavyweight `design.md` per [`verbs/redesign.md`](verbs/redesign.md) § Multi-page flow. That flow already implies a locked system, so the rule there is unchanged.
+- **No-overwrite policy.** If `design.md` already exists at the project root, do NOT overwrite. Refresh its `## Exports` section instead and emit one line: *"design.md detected — refreshed Exports, system unchanged."*
+
+## CTA — surface the offer in the Step 5 preview
+
+After every default + redesign page-build, append one quiet line at the bottom of the preview block:
+
+> *System portable? Say `lock the system` to extract this build's tokens + voice into a `design.md`.*
+
+Skip the CTA when (a) the build is component-scope, or (b) `design.md` already exists in the project (system is already locked).
+
+## Format (the tight version)
+
+Write the file at the project root. Match the project's case convention (`design.md` or `DESIGN.md`). Target ~45 lines — enough to seed a real app, not so much that it becomes a wiki to maintain. The format:
+
+````markdown
+# Design — <Project name>
+
+Locked design system. Future Hallmark runs read this file first; pages defer
+to it. Amend intentionally — the file is the rule.
+
+## System
+- Genre · <editorial / modern-minimal / atmospheric / playful>
+- Macrostructure · <name>
+- Theme · <catalog: NAME · or · custom (vibe: "<4–8 words>")>
+- Axes · <paper-band> / <display-style> / <accent-hue>
+
+## Tokens (canonical · `tokens.css` is the source of truth)
+```css
+:root {
+  --color-paper:      oklch(<L> <C> <H>);
+  --color-paper-2:    oklch(<L> <C> <H>);
+  --color-ink:        oklch(<L> <C> <H>);
+  --color-ink-2:      oklch(<L> <C> <H>);
+  --color-rule:       oklch(<L> <C> <H>);
+  --color-accent:     oklch(<L> <C> <H>);
+  --color-accent-ink: oklch(<L> <C> <H>);
+  --color-focus:      oklch(<L> <C> <H>);
+
+  --font-display: "<face>", ...;
+  --font-body:    "<face>", ...;
+  --font-mono:    "<face>", ...;
+
+  /* 4-pt spacing scale, named: --space-3xs … --space-4xl. See tokens.css.   */
+  /* Type scale, 1.25 (major-third) ratio: --text-xs … --text-display.       */
+
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+  --dur-fast: 180ms;  --dur-base: 240ms;  --dur-slow: 320ms;
+
+  --radius-card: <px>;  --radius-pill: <px>;  --radius-input: <px>;
+}
+```
+
+## CTA voice
+- Primary · <fill colour> · <radius> · <padding rhythm>
+- Secondary · <outline / ghost> · <same radius>
+
+## Motion stance
+- <silent · 1–2 reveal primitives · motion-cut>
+- Reduced-motion fallback · ≤150 ms opacity crossfade.
+
+## Exports
+`tokens.css` (in this project) is the source of truth. For Tailwind v4
+`@theme`, DTCG `tokens.json`, or shadcn/ui CSS variables, ask *"extend
+design.md with Tailwind exports"* (or the format you want) — Hallmark will
+append them per [`export-formats.md`](export-formats.md).
+````
+
+State the picks aloud BEFORE writing the file. *"Genre: editorial. Macrostructure: Long Document. Theme: catalog Editorial. Locking this as the project's system."* Then write.
+
+## After the file is written
+
+Once `design.md` exists, [`SKILL.md`](../SKILL.md) Step 0's pre-flight scan detects it on every subsequent run. From that point on:
+
+- All future Hallmark runs READ `design.md` first; subsequent picks (genre / theme / typography / motion / CTA voice) defer to it.
+- The diversification rule INVERTS — pages must SHARE the system, not differ from each other.
+- If a future page genuinely needs a different system, AMEND `design.md` with a `## Variants` section rather than overriding locally — the file evolves; per-page overrides do not.
+
+## Why opt-in (not auto-emit)
+
+Briefs iterate. The first build is rarely the settled design. Auto-emitting `design.md` on every default build would either churn the file across iterations or lock a weak system before the user has reviewed it. Opt-in mirrors how design teams actually work — formalise the system after the patterns hold, not on day one. The CTA in the preview block keeps the feature discoverable without forcing it.