howone 0.1.19 → 0.1.22

package/templates/vite/.howone/skills/hallmark/references/typography.md

@@ -0,0 +1,243 @@
+# Typography
+
+Type carries the design. If the type is wrong, nothing else matters.
+
+## Principles
+
+- A page is a pairing, not a single font. Display face + body face, minimum. *Single-font pages are allowed only when the single font IS the design choice* — a true terminal aesthetic is monospace-everywhere on purpose; a Manifesto poster might be one display face on purpose. The default is a pairing.
+- Commit to extremes. Weight 200 next to weight 800 reads as intentional. Weight 400 next to weight 600 reads as a default setting.
+- Size steps should be ratios, not increments. Major third (1.25), perfect fourth (1.333), perfect fifth (1.5), or golden (1.618). Pick one and use it.
+- Line-height changes with size. Tight for display (1.05–1.2), comfortable for body (1.5–1.65).
+- Measure — line length — lives between 45 and 75 characters. Use `max-width: 65ch` as the default.
+
+## The 2+1 rule — three faces is the ceiling
+
+**A page may use at most three distinct font families.** One **display**, one **body**, and an optional **outlier** for a single typographic moment — wordmark, hero stat, pull quote, masthead — where the page wants exactly one note that doesn't sound like the rest. Four families is slop. Two is canonical. Three is the ceiling, used sparingly.
+
+The pattern:
+
+```css
+:root {
+  --font-display:  "Fraunces", ui-serif, Georgia, serif;       /* headings, hero */
+  --font-body:     "Geist", ui-sans-serif, system-ui, sans;    /* prose, UI */
+  --font-outlier:  "Geist Mono", ui-monospace, monospace;      /* wordmark + hero stat ONLY */
+}
+```
+
+The outlier is a *register*, not a third surface. Rules:
+
+- **Outlier appears in ≤ 2 places** on the whole page. Wordmark + hero stat. Or pull quote + masthead. Two slots, not five. If you find yourself reaching for it a third time, you don't have an outlier — you have a third body font, which is slop.
+- **The outlier carries one role.** It tags a specific kind of content (the brand, the headline figure, the manifesto line). Once you know what it tags, every instance of that role uses it. Don't apply it to one button label and not another.
+- **Mono counts as a face.** A page with Fraunces display, Geist body, and Geist Mono in code blocks is using three families. That's fine — code is the outlier role. Don't sneak in a fourth.
+- **Same family at different weights is one family**, not two. Geist 400 + Geist 700 is one font; pairing it with Fraunces is two. Adding Geist Mono on top is three.
+
+Two families is still the right answer for most pages. Three is for SaaS / brand-heavy / editorial-rich pages where the wordmark needs a different register than the body.
+
+## Banned defaults
+
+These fonts are on-distribution for every LLM. Do not reach for them without a deliberate reason:
+
+- **Sans-serif:** Inter, Roboto, Open Sans, Lato, Poppins, Source Sans, Nunito, Montserrat, Raleway, Work Sans, DM Sans, system-ui, Arial, Helvetica.
+- **Serif:** Merriweather, Playfair Display (as body — banned as overused body serif; ok as display in moderation), Lora, Source Serif, Georgia-as-default.
+- **Mono:** Courier New, Consolas-as-default, system mono.
+
+If the user insists on one, do it. Otherwise pick from the allowlist below.
+
+## The font catalog
+
+Three sources, in priority order:
+
+- **Google Fonts** — free, served via CDN, works everywhere. The default source.
+- **Fontshare** (Indian Type Foundry) — free for commercial use, foundry-grade. The "you didn't know these were free" tier. Drop-in via `<link href="https://api.fontshare.com/v2/css?f=...">`.
+- **Foundry-licensed** — Klim, Pangram Pangram, Production Type, Lineto, Colophon. Only when the user has confirmed they're licensed.
+
+### Free display faces
+
+| Family | Source | Voice | Best for |
+| --- | --- | --- | --- |
+| **Fraunces** | Google | Variable serif, deeply expressive italic, optical-size axis | Editorial, Salon, Atelier, brand-heavy |
+| **Newsreader** | Google | Roman serif with optical-size + italic | Editorial, magazine, long-form |
+| **Instrument Serif** | Google | Tight contrast, italic available, smart for short heads | Brand, atelier, intimate editorial |
+| **Cormorant Garamond** | Google | Classical, high contrast, luxury register | Luxury, fashion, fine arts |
+| **EB Garamond** | Google | Honest classical Garamond, body-grade | Editorial body, longform reading |
+| **Cardo** | Google | Scholarly serif, generous x-height | Reference, academic, slow reading |
+| **Source Serif 4** | Google | Modern transitional, big OT family | SaaS marketing with serif tone |
+| **DM Serif Display** | Google | Bracketed serif, high-contrast display | Headlines that need to feel printed |
+| **Bodoni Moda** | Google | Modern Bodoni revival, dramatic | Fashion, editorial, luxury display |
+| **Playfair Display** | Google | Use only as display; banned as body | Marketing display moments — sparingly |
+| **Geist** | Google | Modern grotesque, geometric, 7 weights | Modern minimal, SaaS, dev tools |
+| **Inter Tight** | Google | Tighter Inter — allowed *only* as a body fallback in technical themes; never as display | UI body in restrained themes |
+| **Bricolage Grotesque** | Google | Variable display sans, bold weights, condensable | Brutal, playful, riso-bold |
+| **Space Grotesk** | Google | Geometric grotesque, slightly quirky | Brutalist, technical |
+| **Anton** | Google | Heavy condensed grotesque | Posters, manifestos |
+| **Big Shoulders Display** | Google | Industrial condensed | Sports, manifestos, declarative |
+| **Tomorrow** | Google | Variable optical condensed | Tech, atmospheric, near-future |
+| **Outfit** | Google | Modern geometric (banned as default; use only when *picked* deliberately) | Restrained tech — sparingly |
+| **General Sans** | Fontshare | Modern grotesque, Geist-adjacent | Modern minimal alternative to Geist |
+| **Switzer** | Fontshare | Neutral sans, broad weight range | SaaS body, restrained |
+| **Cabinet Grotesk** | Fontshare | Display grotesque, 9 weights | Editorial display, magazine |
+| **Clash Display** | Fontshare | Ultra-condensed display | Posters, brand moments |
+| **Satoshi** | Fontshare | Playful geometric sans | Playful, consumer |
+| **Sentient** | Fontshare | Variable serif, soft contrast | Soft editorial, atmospheric |
+| **Erode** | Fontshare | Distressed serif, hand-set feel | Riso, tactile-rebellion, brand-y |
+| **Tanker** | Fontshare | Heavy condensed grotesque, pure display | One-word posters, mastheads |
+
+### Free body faces
+
+| Family | Source | Voice | Best for |
+| --- | --- | --- | --- |
+| **Geist** | Google | The default modern body sans | Modern minimal, SaaS, atmospheric |
+| **The Future** | (in repo) | Hallmark's own body workhorse | Default Hallmark tone |
+| **Newsreader** | Google | Reading serif, optical-size aware | Editorial body, longform |
+| **Source Serif 4** | Google | Body-grade serif | Editorial mid-weight |
+| **EB Garamond** | Google | Classical body | Editorial slow reading |
+| **Spectral** | Google | Slab-ish serif, screen-tuned | Long-form on screen |
+| **Lora** | Google | Calligraphic serif, body-grade | Body — sparingly (over-used) |
+| **Crimson Pro** | Google | Old-style body, generous | Editorial slow body |
+| **IBM Plex Sans** | Google | Engineering sans, broad family | Technical body |
+| **Switzer** | Fontshare | Neutral sans body | SaaS body, restrained |
+| **General Sans** | Fontshare | Geist-adjacent body | Modern minimal body |
+
+### Free mono / outlier faces
+
+| Family | Source | Voice | Best for |
+| --- | --- | --- | --- |
+| **Geist Mono** | Google | Geist's mono companion | Default Hallmark mono, code, captions |
+| **JetBrains Mono** | Google | Engineering mono, ligatures | Code, terminal, technical |
+| **IBM Plex Mono** | Google | Engineering mono, broad family | Technical body-grade |
+| **Commit Mono** | Google | Tighter mono, modern | Code, modern terminal |
+| **Space Mono** | Google | Quirky, slightly retro | Playful tech, riso |
+
+### Tone-based pairing patterns
+
+Each tone gets two rows: a **free baseline** (Google Fonts / Fontshare; works out of the box) and a **paid upgrade** (foundry licences required; only when the user has confirmed the budget and the licence). The free row is the default. **Never name a paid font in code without confirming the user is licensed** — the demo will fall back to system-default and look broken to the user.
+
+| Tone | Tier | Display | Body | Outlier |
+| --- | --- | --- | --- | --- |
+| **Editorial** | Free | Fraunces · Newsreader · EB Garamond · Instrument Serif · Cabinet Grotesk | IBM Plex Sans · Switzer · Source Serif 4 | JetBrains Mono · Geist Mono · Erode (display moment) |
+| | *Paid* | *Tiempos Headline · Söhne Breit · Reckless Display · Migra · Tobias* | *Söhne · Haffer · Untitled Sans* | *Söhne Mono · GT America Mono* |
+| **Technical** | Free | JetBrains Mono · Geist Mono · Geist (700) · Commit Mono | Geist · IBM Plex Sans · Switzer | Tomorrow · Cabinet Grotesk (wordmark) |
+| | *Paid* | *Berkeley Mono · Söhne Mono · GT Pressura · ABC Diatype Mono* | *Söhne · Untitled Sans · ABC Diatype* | *Berkeley Mono · GT Pressura Mono* |
+| **Brutalist** | Free | Bricolage Grotesque (800) · Anton · Tanker · Big Shoulders Display | Geist · Switzer | Space Grotesk (numerals) · Geist Mono |
+| | *Paid* | *Druk · Monument Extended · NaN Jaune · Migra · ABC Pressura* | *Söhne Breit · GT America* | *GT America Mono* |
+| **Soft** | Free | Geist · Bricolage Grotesque (500) · Sentient · Newsreader | Geist · Crimson Pro · Switzer | Geist Mono · Satoshi (label) |
+| | *Paid* | *Söhne · GT Pressura · Pangaia · Tobias* | *Söhne · Halyard Text · Satoshi* | *Söhne Mono · GT Maru Mono* |
+| **Luxury** | Free | Cormorant Garamond · Fraunces · Cardo · DM Serif Display · Bodoni Moda | EB Garamond · Crimson Pro · Source Serif 4 | (rare; small caps from display family) |
+| | *Paid* | *Canela · Tiempos Headline · GT Super · Domaine Display · Migra* | *Tiempos Text · Suisse Int'l · Domaine Text* | *(rarely used at this tier)* |
+| **Playful** | Free | Bricolage Grotesque · Fraunces (italic) · Satoshi · Newsreader (italic) · Sentient | Geist · Newsreader · Satoshi | Geist Mono · Space Mono |
+| | *Paid* | *Clash Display · Cabinet Grotesk · Migra · Tobias · Pangaia* | *Satoshi · Plus Jakarta Sans · GT Maru* | *Space Mono · GT Maru Mono* |
+| **Austere** | Free | system-ui · Inter Tight (regular) · Geist (400) · Switzer (regular) | system-ui · Geist · Switzer | system-ui mono · Geist Mono |
+| | *Paid* | *ABC Diatype · ABC Monument Grotesk · Söhne (regular) · ABC Pressura* | *ABC Diatype · Söhne* | *ABC Diatype Mono · Söhne Mono* |
+| **Atmospheric** | Free | Geist (600) · Sentient · Tomorrow · Bricolage Grotesque | Geist (400) · Switzer | Geist Mono · JetBrains Mono |
+| | *Paid* | *Söhne · GT Pressura · ABC Diatype* | *Söhne · ABC Diatype* | *Berkeley Mono · Söhne Mono* |
+| **Workshop** *(Hallmark's own theme)* | Free | The Future · Geist · Cabinet Grotesk | The Future · Switzer | The Future Mono · Geist Mono |
+| | *Paid* | *Avenir Next · GT Walsheim* | *Söhne · GT Walsheim* | *Berkeley Mono* |
+
+**The discipline.** Default to the free pairings. They're not consolation prizes; Fraunces, Geist, Bricolage Grotesque, Cabinet Grotesk, Sentient, and JetBrains Mono are first-rate faces in 2026. The paid upgrades exist for two cases: (a) the user has explicitly confirmed they're licensed, or (b) the user is asking for a specific named foundry voice (e.g., "make it look like Klim", "I want Söhne"). Reach for Tier 2 only then; otherwise the free row is the right answer. Treat the free row as canon, the paid row as a *cited* alternative.
+
+## Wordmark / logo typography
+
+The wordmark in the navbar and footer **may use a different display face than the body**. On tone-rich themes (Editorial, Salon, Atelier, Linen, Quiet) it **should** — collapsing the wordmark into the body family flattens the visual hierarchy and the page reads as un-branded.
+
+```css
+:root {
+  --display:       "Geist", system-ui, sans-serif;     /* body + display */
+  --font-wordmark: "Fraunces", Georgia, serif;         /* logo only */
+}
+.wordmark {
+  font-family: var(--font-wordmark);
+  font-weight: 600;
+  letter-spacing: -0.015em;
+}
+```
+
+Recommended pairings (free baseline first):
+
+- **Geist body → Fraunces wordmark, IBM Plex Mono wordmark, or Bricolage Grotesque (heavy) wordmark**
+- **Fraunces body → Geist Mono wordmark, Inter Tight wordmark**
+- **System-ui body → JetBrains Mono wordmark, Newsreader wordmark**
+- **Inter Tight body → Fraunces wordmark, EB Garamond wordmark**
+
+When to use the same family for both:
+
+- **Editorial · Letter · Manifesto · Long Document** can collapse to a single family because the body voice carries the brand. The wordmark in these contexts is small, grounded, and earns its weight by being typeset rather than decorated.
+
+When to use a contrasting family:
+
+- **Bento Grid · Stat-Led · Workbench · Marquee Hero** — these archetypes lean visually generic (geometric grids, big numbers, browser-frame mockups) and need the wordmark to do the typographic differentiation work the body can't.
+
+**Avoid the same-family collapse on a SaaS page.** A Geist-only page where the wordmark is also Geist 600 reads as un-designed; the wordmark in Fraunces SemiBold over a Geist body costs nothing and adds the one typographic register that says *this is a brand*.
+
+## Scale
+
+Pick a ratio. The default for Hallmark work is **1.25** (major third). Build the scale from a 16px body, then clamp display sizes for responsive.
+
+```css
+:root {
+  --text-xs:   0.64rem;   /* 10.24px */
+  --text-sm:   0.8rem;    /* 12.8px  */
+  --text-base: 1rem;      /* 16px    */
+  --text-md:   1.25rem;   /* 20px    */
+  --text-lg:   1.5625rem; /* 25px    */
+  --text-xl:   1.9531rem; /* 31.25px */
+  --text-2xl:  2.4414rem;
+  --text-3xl:  3.0518rem;
+  --text-4xl:  3.8147rem;
+  --text-display: clamp(2.75rem, 5vw + 1rem, 5.25rem);
+}
+```
+
+**Display max — keep it ≤ 5.5rem (88 px).** Above that, hero headlines crowd themselves on 1280–1440 px viewports and require multi-line wrapping that almost always reads as drama, not gravity. Even on Manifesto / Brutal display-heavy themes, cap at 6rem (96 px). The exception is a single-line, single-word display (e.g. a stat) that occupies ≤ 12 ch — it can grow to 7rem. **Default emit format is `clamp(2.75rem, 5vw + 1rem, 5.25rem)`.**
+
+### Hero headline sizing — match size to copy length
+
+Count characters in the rendered hero `h1`. Pick the cap by bucket — the rule applies on top of any per-theme `--text-display` clamp:
+
+| Headline length | Size cap | Notes |
+| --- | --- | --- |
+| **≤ 20 chars** (e.g. *"Limitless"*, *"Made not generated"*) | full `--text-display`; single-word can grow to 7rem | Display-heavy themes only |
+| **21–50 chars** (the default sweet spot) | `--text-display` | If it wraps past 2 lines at 414 px, step down to `--text-display-s` |
+| **51–90 chars** | cap at `--text-display-s` | Strongly consider splitting into eyebrow + headline |
+| **> 90 chars** | rewrite shorter, or cap at `--text-4xl` with tighter leading | A 100-char headline at display size is the single most reliable AI tell |
+
+**Aggressive-display themes step down one rung when headline > 50 chars.** Brutal, Riso, and Manifesto clamp `--text-display` at 6.5–9rem — that ceiling is for ≤ 50-char statements only. Past 50 chars, route them to `--text-display-s` automatically. **When you write the headline yourself (no user-supplied copy), aim for ≤ 7 words and ≤ 50 chars from the start** — imperative or nominal phrase, never a gerund opener.
+
+Use no more than five sizes on a single page. If you need more hierarchy, use weight and colour, not another size.
+
+## Weights
+
+- Body: one weight (typically 400 or 350). Bold for emphasis only.
+- Headings: a weight that contrasts the body by at least 300 units. If body is 400, headings are 700 or 200 — not 500 or 600.
+- Never synthesise. Load the weight you need; don't rely on `font-weight: bold` against a single-weight file.
+
+## Required features
+
+- `font-display: swap` on every web font.
+- Match fallback metrics with `size-adjust`, `ascent-override`, `descent-override`, `line-gap-override` to prevent CLS.
+- Tabular numbers on any data display: `font-variant-numeric: tabular-nums;`.
+- Oldstyle figures for body copy where the face supports them: `font-variant-numeric: oldstyle-nums;`.
+- Proper typographic punctuation: `" " — … ‘ ’`. Never straight quotes, never `--` or `...`.
+
+## Body text rules
+
+- Minimum 16px. Below 14px is accessibility-hostile.
+- Line-height 1.5–1.65 on body copy, tighter (1.1–1.3) on display. **Floor for all-caps display heads (`text-transform: uppercase` on `.hero__display` / `.section__title` / `h1` / `h2`) is `1.0` — recommended `1.02–1.08`.** Below 1.0 the cap-tops of line N+1 collide with the baseline of line N (no descenders to cushion the gap); the comma + cap-D on a wrapped "PROMPT, / DIFFERENT" fuse into a single glyph blob. Condensed display faces (Anton, Inter Tight 900, Bebas Neue) make this worse. Gate 67 auto-fails the pattern.
+- Measure 45–75 characters (`max-width: 65ch`).
+- Never all-caps body copy. Never justified text without hyphenation. Never letter-spacing above 0.05em on body.
+
+## Headings rules
+
+- Tight tracking on display sizes (`letter-spacing: -0.02em` to `-0.04em` depending on the face).
+- Loose tracking on small caps / labels (`letter-spacing: 0.08em` to `0.14em`, `text-transform: uppercase`, use small caps if the face has them: `font-variant-caps: all-small-caps;`).
+- Skip no levels. `h1` → `h2` → `h3`. Style them visually how you like, but keep semantic order.
+
+## Bans
+
+- No Inter, no Roboto, no Open Sans. No system stack as the *only* stack.
+- No gradient text on headings (`background-clip: text` with a gradient fill).
+- No single-font pages.
+- No all-caps paragraphs.
+- No font-size below 14px for body copy, below 10px anywhere.
+- No hard-synthesised bold or italic.
+- **No more than three font families on a single page.** Display + body + one outlier is the ceiling. Four families = slop. Audit gate.
+- No outlier face used in more than two slots. Wordmark + hero stat is the canonical pair; if you reach for a third slot, drop it back to the body face.

package/templates/vite/.howone/skills/hallmark/references/verbs/audit.md

@@ -0,0 +1,25 @@
+# `hallmark audit`
+
+Read the file(s) the user pointed at. For each finding, return:
+
+- **Tell** — the named anti-pattern from [`anti-patterns.md`](../anti-patterns.md).
+- **Where** — file path and line range.
+- **Severity** — `critical` (ships as slop), `major` (looks AI-generated), `minor` (small taste issue).
+- **Fix** — one-line concrete correction.
+
+Group by severity. Do not edit. Do not redesign. End with a count: `N critical · M major · K minor`.
+
+Audit *also* checks structural fingerprint: if the page uses the AI template (centered hero, 3 equal feature cards, CTA, footer, with no asymmetry or surprise), flag it as a critical structural finding even if the visual treatment is fine.
+
+**Stamp-vs-page check.** If the audited file contains a `/* Hallmark · macrostructure: <name> · ... */` stamp, verify the page actually matches that name. If the stamp says **Bento Grid** but the page is a centered single-column hero with a CTA, flag it as a critical structural finding: `stamp lies` — the stamp must reflect what shipped or be removed. This catches drift where a previous Hallmark run stamped one thing and a later edit pulled the page back toward the AI template.
+
+**Genre-aware audit.** If the audited file's stamp names a genre (e.g. `genre: atmospheric`), apply the genre-scoped overrides from [`slop-test.md`](../slop-test.md) when grading. A radial-gradient background is a critical tell for editorial — but allowed for atmospheric. A pure-white paper is a tell for editorial — but allowed for modern-minimal. The audit verb must respect the genre the page declared.
+
+**`design.md` audit.** If the project root has a `design.md` (or `DESIGN.md`), read it before grading. Then check every audited page against the system:
+
+- **Theme drift.** Page uses tokens / fonts / accent that don't match `design.md`'s declared system → flag as `critical: design-system drift`. Per-page theme picks are slop on a system-managed project even if each page is internally fine.
+- **Macrostructure family violation.** `design.md` says marketing pages use Marquee Hero or Stat-Led — the audited page is a Letter format → flag as `major: outside design.md family`.
+- **Stamp mismatch.** The page's CSS stamp says `designed-as-app` but reads `design-system: design.md` and the page actually drifts from `design.md` → flag as `critical: stamp lies`. The stamp claims compliance the code doesn't deliver.
+- **No stamp at all on a system-managed project** → flag as `major: missing system reference`. Every page on a `design.md` project must stamp its allegiance to the system.
+
+Inversely, on a project *without* `design.md`, the standard diversification rule applies — flag pages that share macrostructure / theme with a previous Hallmark output as `minor: variety drift`.

package/templates/vite/.howone/skills/hallmark/references/verbs/redesign.md

@@ -0,0 +1,269 @@
+# `hallmark redesign`
+
+The user wants a different page from the same content. They are not happy with the current visual structure — typically because it reads as templated, generic, or AI-shaped. Your job is to redesign the page's structure, rhythm, and component voice while respecting the existing implementation boundaries unless the user explicitly confirms a full rebuild.
+
+## Non-destructive implementation rule
+
+Hallmark redesigns visual and interaction layers. It does not delete production files by default.
+
+- Never delete existing route files, component directories, page trees, or the old website unless the user explicitly asks for deletion or approves a file-level plan that lists the deletions.
+- Default to in-place edits of the named page/component files, or additive new components/tokens wired through the existing route.
+- If the redesign would require removing multiple components, replacing a route tree, or collapsing the app into a single new page, stop and ask for confirmation first.
+- Treat PDFs, README files, `.md` briefs, docs, transcripts, and pitch decks as source material for understanding the product. They are not page copy by default. Summarize and adapt them unless the user explicitly says to use their wording verbatim.
+- Before editing, state the files you expect to modify, create, and delete. Any deletion needs explicit confirmation.
+
+## Step 0 · Detect scope first
+
+Before anything else, decide whether the redesign is **single-page** or **multi-page**. The behaviour diverges hard.
+
+**Multi-page signals (any one fires):**
+- The target is a directory (e.g. `./app/`, `./pages/`, `./src/routes/`).
+- The target is a glob (`**/*.tsx`, `app/*/page.tsx`).
+- The user names more than one file in the brief (`./hero.tsx and ./pricing.tsx`).
+- The user says "the whole site", "every page", "the app", "all the pages", "the marketing site".
+- The codebase has multiple route files (`app/page.tsx`, `app/about/page.tsx`, `app/pricing/page.tsx`, etc.) and the user pointed at the project root.
+
+If any of those fires → **multi-page redesign**. Go to § Multi-page flow.
+If none fires → **single-page redesign**. Go to § Single-page flow.
+
+---
+
+## § Multi-page flow — design.md first, then redesign
+
+A web app needs a *design system*, not seventeen unrelated theme pickings. Hallmark's diversification rule is wrong here: across pages of the same product, **consistency is the goal, not variety**. If you redesign every page with a different macrostructure / theme / accent, you've shipped a slop split-personality app, even if each individual page is fine.
+
+The flow is:
+
+### 1. Read the project, then pause
+
+Before redesigning a single file:
+
+- Walk the target directory. List every page-level file you found, with a one-line description of what it does. (Hero / pricing / docs / dashboard / etc.)
+- Note any existing design assets: a `tokens.css`, a tailwind config with brand values, a logo, brand colours mentioned in `README`, a marketing screenshot.
+- Check for an existing `.hallmark/log.json` — if it has prior runs, read the most recent stamp; if all those entries are different macrostructures / themes, it confirms the user's complaint.
+
+### 2. Produce `design.md` at the project root
+
+Write a single file at the project root: `design.md` (or `DESIGN.md` — match the project's existing case convention). This file is the **one source of truth** every subsequent page redesign reads. Format:
+
+````markdown
+# Design — <Project name>
+
+A locked design system for this app. Every page redesign reads this file before
+emitting code. Do not regenerate per page — extend or amend this file when the
+system needs to grow.
+
+## Genre
+<editorial · modern-minimal · atmospheric · playful>
+
+## Macrostructure family
+Pick one base macrostructure for marketing pages, one for app pages, one for
+content pages (if applicable). Pages within a family share the family's shape;
+they vary only in component archetypes.
+
+- Marketing pages: <macrostructure name + the 1–2 archetypes that vary>
+- App pages:       <macrostructure name + variation knobs>
+- Content pages:   <macrostructure name + variation knobs>
+
+## Theme
+- `--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-focus`   oklch(<L> <C> <H>)
+
+## Typography
+- Display: <face>, weight <N>, style <normal/italic>
+- Body:    <face>, weight <N>
+- Mono:    <face>, weight <N>
+- Display tracking: <em>
+- Type scale anchor: <text-display> = clamp(...)
+
+## Spacing
+4-point named scale. The values are in `tokens.css`. Pages must use named
+tokens (`var(--space-md)`), never raw values.
+
+## Motion
+- Easings: cubic-bezier(<x>, <y>, <z>, <w>) named `--ease-out`, etc.
+- Reveal pattern: <fade only / fade + slide / none>
+- Reduced-motion fallback: opacity-only, ≤ 150 ms.
+
+## Microinteractions stance
+- <silent success / celebratory toasts: never>
+- <hover delay 800 ms · focus delay 0 ms>
+- <other named choices>
+
+## CTA voice
+- Primary CTA: <fill style, shape, copy pattern>
+- Secondary CTA: <outline style, shape, copy pattern>
+
+## Per-page allowances
+- Marketing pages MAY use enrichment (Tier-A CSS art, Tier-B SVG, etc.).
+- App pages MUST NOT use enrichment — function carries the page.
+- Content pages: typography only.
+
+## What pages MUST share
+- The wordmark / logotype.
+- The accent colour and its placement (≤ 5 % per viewport).
+- The display + body fonts.
+- The CTA voice (button shape, border-radius, padding rhythm).
+- Section heading rhythm (numeral + label + display heading pattern).
+
+## What pages MAY differ on
+- Macrostructure within the page-type family (a marketing page can be Marquee
+  Hero on one route and Long Document on another — both still use the system's
+  type, colour, and CTA voice).
+- Hero archetype (within the family's allowance).
+- Enrichment — only on marketing pages, only Tier-A or Tier-B.
+
+## Exports
+
+Drop-in formats for re-using this design system in other projects.
+See [`export-formats.md`](../export-formats.md) for the canonical mapping.
+
+### tokens.css
+```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-outlier: "<face>", ...;
+
+  --space-3xs: 0.25rem;  --space-2xs: 0.5rem;  --space-xs: 0.75rem;
+  --space-sm:  1rem;     --space-md:  1.5rem;  --space-lg: 2rem;
+  --space-xl:  3rem;     --space-2xl: 4.5rem;  --space-3xl: 7rem;
+
+  --text-xs: 0.75rem;  --text-sm: 0.875rem; --text-md: 1.125rem;
+  --text-lg: 1.375rem; --text-xl: 1.75rem;  --text-2xl: 2.25rem;
+
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+  --dur-short: 220ms;
+  --radius-card: <px>; --radius-pill: <px>; --radius-input: <px>;
+}
+```
+
+### Tailwind v4 `@theme`
+```css
+@theme {
+  --color-paper:   oklch(<L> <C> <H>);
+  --color-ink:     oklch(<L> <C> <H>);
+  --color-accent:  oklch(<L> <C> <H>);
+  --font-display:  "<face>", sans-serif;
+  --font-body:     "<face>", sans-serif;
+  --spacing-md:    1.5rem;
+  --text-md:       1.125rem;
+  --ease-out:      cubic-bezier(0.16, 1, 0.3, 1);
+  /* mirror the rest of tokens.css with `--spacing-*` for Tailwind's spacing utilities */
+}
+```
+
+### DTCG `tokens.json`
+```json
+{
+  "color": {
+    "paper":  { "$value": "oklch(<L> <C> <H>)", "$type": "color" },
+    "ink":    { "$value": "oklch(<L> <C> <H>)", "$type": "color" },
+    "accent": { "$value": "oklch(<L> <C> <H>)", "$type": "color" }
+  },
+  "font": {
+    "display": { "$value": "<face>", "$type": "fontFamily" },
+    "body":    { "$value": "<face>", "$type": "fontFamily" }
+  },
+  "space": {
+    "md": { "$value": "1.5rem", "$type": "dimension" }
+  }
+}
+```
+
+### shadcn/ui CSS variables
+```css
+:root {
+  --background:        <L>  <C>  <H>;   /* paper */
+  --foreground:        <L>  <C>  <H>;   /* ink */
+  --primary:           <L>  <C>  <H>;   /* accent */
+  --primary-foreground: <L> <C>  <H>;   /* accent-ink */
+  --muted:             <L>  <C>  <H>;   /* rule */
+  --muted-foreground:  <L>  <C>  <H>;   /* muted */
+  --border:            <L>  <C>  <H>;   /* rule */
+  --input:             <L>  <C>  <H>;   /* rule */
+  --ring:              <L>  <C>  <H>;   /* focus */
+  --radius:            <px>;
+}
+```
+````
+
+State the picks aloud in plain text BEFORE writing the file. *"Genre: modern-minimal. Theme: a custom OKLCH palette anchored on your brand teal. Display: Geist 600. Body: Geist 400. Three macrostructure families: Marquee Hero (marketing), Workbench (app), Long Document (content)."* Then ask: *"Want me to proceed with this system across every page, or amend any of it first?"*
+
+Wait for confirmation. Only after the user confirms (or says "go ahead") do you write `design.md` and start redesigning pages.
+
+### 3. Redesign each page reading from `design.md`
+
+For each target page:
+
+- **Read `design.md` first.** It is now the rule of the project; the per-build references in [`references/`](../) defer to it. Where `design.md` and the references conflict, `design.md` wins.
+- Pick the macrostructure from the family declared in `design.md` for this page's type (marketing / app / content). Within the family, you may vary archetypes — but only those `design.md` allows.
+- Apply the locked theme. Do **not** swap to a different theme to "add variety". The variety lives in macrostructure / archetype choice, not theme.
+- Apply the locked typography, spacing, motion, microinteractions stance.
+- Stamp every page's CSS with: `/* Hallmark · genre: <genre> · macrostructure: <name> · design-system: design.md · designed-as-app */`. The `designed-as-app` flag tells future Hallmark runs to read `design.md`, not invent a new system.
+- Write a single combined `.hallmark/log.json` entry for the multi-page redesign, with `"scope": "app"` instead of one entry per page.
+
+### 4. Diversification rule — INVERTED for multi-page
+
+Across pages of the same app, the diversification rule is *inverted*: consecutive pages MUST share theme, accent, type pairing. They may differ on macrostructure within the family. The 55 slop-test gates that check "differs from previous Hallmark run" are skipped for `designed-as-app` outputs — the system overrides the catalog rotation here.
+
+Pages that drift from `design.md` are slop. The audit verb flags `design.md` drift as a critical structural finding (`stamp-vs-design.md disagreement`).
+
+### 5. When to amend `design.md` instead of overriding
+
+If a page genuinely needs something `design.md` doesn't allow (e.g. a marketing landing for a new sub-product wants a different theme), the rule is **amend `design.md` first**, not override locally. Add an explicit per-page allowance or a `## Variants` section. The file evolves; per-page overrides do not.
+
+---
+
+## § Single-page flow
+
+(The classic redesign behaviour — unchanged.)
+
+**What to preserve:**
+- The copy intent, factual claims, product names, and primary message. Preserve exact wording only when it already lives in the target UI or the user explicitly asks for verbatim copy.
+- The information architecture (which sections exist, in roughly what order)
+- The brand (colours and fonts they've named, if any)
+- The primary action
+- The existing route/component ownership boundaries, unless the user has approved a full rebuild
+
+**What to replace:**
+- The structural fingerprint — pick a **different** combination from [`structure.md`](../structure.md) than the source had.
+- The component voice — different button style, different divider language, different image treatment.
+- The reveal pattern — if the original faded everything in on scroll, the new one might have no reveals at all.
+- The visual rhythm — different sections having different padding, different alignments, deliberate breaks.
+
+**What not to replace without confirmation:**
+- Route trees, production component directories, or the old website's file structure.
+- Working app logic, data fetching, auth, forms, analytics, or integration code.
+- Existing copy with pasted text from PDFs, docs, or markdown files unless the user requested verbatim copy.
+
+**Optional `--mood <name>` argument:**
+
+If the user specifies a mood (`hallmark redesign ./hero.tsx --mood luxury`), pick a tone aligned to that mood and let it drive the structural fingerprint. Mood names map to tones from [`typography.md`](../typography.md) and [`structure.md`](../structure.md). If no mood is given, ask the user what *feeling* they want — one word — and proceed.
+
+**Genre escape hatch.** If the user explicitly asks for a *kind* of design that the current genre doesn't fit (e.g. "redesign this editorial page as a modern SaaS hero"), switch genre too. Load [`genres/<new-genre>.md`](../genres/) and apply its rule overlay. Stamp the new genre into the output so future runs respect it.
+
+**Project-level check.** Before treating this as a true single-page redesign, look for `design.md` at the project root. If it exists, the project is being designed as an app and **the single-page rules don't apply** — read `design.md` and follow it instead. The diversification rule reverses (consistency wins). If you actually want to break from the locked system, *update `design.md` first*, then redesign.
+
+**Output:**
+
+Return the redesigned code, plus a short note explaining:
+
+- The structural fingerprint you picked, axis by axis.
+- Why this combination fits the brief better than the original.
+- One thing you removed and why.
+- (If genre changed) why the new genre fits the user's stated kind of design.

package/templates/vite/.howone/skills/hallmark/site/_tests/01-tide-podcast/brief.md

@@ -0,0 +1,71 @@
+# Test 01 v2 — Tide (indie podcast)
+
+## The prompt (verbatim, same as v1)
+
+> "build me a landing page for my indie podcast called Tide. just go ahead, you pick."
+
+## Step 0 · Pre-flight
+
+> *"No pre-flight signals — proceeding with full Hallmark stack."*
+
+(Vanilla scratch directory; no `package.json`, no `tailwind.config.*`, no existing CSS — silent pre-flight.)
+
+## Step 1 · Design-context gate — skipped
+
+The user opted out. Skill states inferences in one sentence:
+
+> *"Going with: audience = listeners who care about voice and atmosphere · use = listen + subscribe · tone = intimate, hand-set, voice-led. If any of those is wrong, redirect."*
+
+## Step 2.5 · Project memory rotation
+
+> *"This is the first Hallmark v0.6.0 run for this project. No `.hallmark/log.json` rotation needed."*
+
+(But the v1 stamp at `_tests/01-tide-podcast/style.css` says **Quote-Led + Atelier**. The v2 brief is to re-run the same prompt with the new skill — picking a different macro/theme to demonstrate the diversification rule firing in a "second visit" frame.)
+
+> *"Previous run on this brief picked Quote-Led + Atelier. Picking from {Letter, Index-First, Long Document} this time — Letter wins for an audio-domain brief because the medium is voice and a letter to the listener carries weight a pull-quote doesn't repeat."*
+>
+> *"Theme rotation: Atelier (light · italic-serif · warm) → Salon (light · mono-display · warm). Differs on display style. Passes."*
+
+## Step 3 · Visual ruleset loaded
+
+`macrostructures.md` (Letter), `component-cookbook.md` (H6 Letter Hero), `typography.md` (mono-display + roman-serif body — Salon's pairing), `color.md`, `microinteractions.md` (single primitive: caret blink only), `anti-patterns.md`.
+
+## Step 4 · Hero enrichment
+
+> *"Enrichment: none (typography only). Letter macro on Salon theme; the prose is the design. Adding a Lottie or a Midjourney microphone shot would dilute the voice — same anti-slop call as v1."*
+
+## Step 5 · Preview
+
+```markdown
+**Hallmark · v0.6.0**
+
+- **Macrostructure** · Letter
+- **Theme** · Salon (warm-cream paper · IBM Plex Mono display · Cormorant Garamond serif body · warm-amber accent ~2%)
+- **Enrichment** · none (typography only)
+- **Sections** · Masthead · Salutation · Letter body (3 paragraphs) · Listen-where row · Colophon
+- **Motion** · cursor caret blink only (1 primitive)
+- **Slop test** · 38 / 38 ✓
+- **Diversification** · differs from v1 (Quote-Led/Atelier) on macrostructure + display style
+```
+
+## Step 6 · Macrostructure stamp
+
+```
+/* Hallmark · macrostructure: Letter · H6 hero knobs: salutation=greeting, body=3 paragraphs, signoff=initials
+ * theme: Salon · accent: warm-amber ~2% · enrichment: none (typography only)
+ * studied: no · context: skipped, inferred (audio domain) · v0.6.0
+ */
+```
+
+## What changed vs v1
+
+- **Macro:** Quote-Led → Letter. The pull-quote frames a podcast as listened-to-by-others (third-party endorsement); Letter frames it as host-to-listener (first-person address). Both work; Letter is more intimate, which the rotation rule was steering toward.
+- **Theme:** Atelier → Salon. Both warm-cream, both light. Atelier is italic-serif display; Salon is mono display + serif body. Display-style differs, so the diversification gate passes.
+- **Voice:** the v1 page opens with a listener's quote; this opens with the host's salutation. Same word-count budget, different rhetorical posture.
+- **Microinteraction:** v1 had no motion. v2 keeps it just as restrained — only a blinking caret on the salutation, optional.
+
+## What stayed the same
+
+- Enrichment tier: none on both. Voice carries the brand.
+- Section count: ~5, both pages.
+- Slop test: 38 / 38 ✓ on both.