@1agh/maude 0.15.0

package/plugins/design/templates/design-system-inspiration/_MAPPING.md

@@ -0,0 +1,277 @@
+# Mapping — discovery answer → scaffold file set
+
+> The contract for skill `design-system` (bootstrap mode). Computes which specimens land in `<designRoot>/system/<ds>/preview/` based on the 8 discovery answers + computed `activeFamilies[]`.
+>
+> **Library state (2026-05-13):** 67 reference HTML specimens across 11 category dirs. Earlier copies of this mapping described the conditional dirs as "filled in follow-up phases" — that's no longer true; they're populated and the bootstrap flow MUST honor them.
+
+## Library layout (where to find what)
+
+| Dir | Role | Files | Gate for scaffold |
+|---|---|---|---|
+| `core/` | Always-on tokens + 10 baseline previews + `_layout.css` chrome | 10 + 6 .tpl | always |
+| `universal/` | Always-on cross-cutting components (toggles, dialogs, tooltips, tables, callout, empty-state, logo) | 7 | always (mostly) |
+| `foundations/` | Token-foundation specimens beyond core (borders, elevation, focus, grid, iconography, opacity, radii, selection) | 8 | always-on for any non-`minimal` profile |
+| `status/` | Status-family specimens (colors-status, components-status, skeletons) | 3 | IF `"status" ∈ activeFamilies` |
+| `audience-developer/` | Developer-tool patterns (code-block, diff-view, log-stream, monospace-table, terminal-pane, type-mono) | 6 | IF Q2 audience = `developer tool` |
+| `audience-pro/` | Pro-tool patterns (colors-presence, command-palette, keyboard, list, shortcuts-overlay, toast-menu) | 6 | IF Q2 audience = `pro tool` |
+| `audience-consumer/` | Consumer patterns (banner, generous empty-state, feature-grid, marketing-card, testimonial) | 5 | IF Q2 audience = `consumer app` |
+| `platform-desktop/` | Desktop-only patterns (resize-panels) + `ui_kits-desktop-index.html` catalog + `ui_kits-desktop-showcase.html` full mock | 3 | IF Q3 platforms includes desktop (default) |
+| `platform-mobile/` | Mobile-only patterns (bottom-sheet, pull-to-refresh, segmented-control, tab-bar) + `ui_kits-mobile-index.html` catalog + `ui_kits-mobile-showcase.html` full mock | 6 | IF Q3 platforms includes mobile |
+| `theme-both/` | Side-by-side dark+light comparison | 1 | IF Q4 theme = `both equal` |
+| `patterns/` | Cross-cutting flows (auth, data-density, error-pages, form-layouts, onboarding, pricing) | 6 | opt-in via `config.extensions` or explicit user request — not auto-scaffolded |
+| `meta/` | Cross-cutting concerns (accessibility, i18n, presence-multiplayer, tokens-index) | 4 | opt-in / informational |
+
+**Total reference inventory: 67 HTML specimens.** Typical scaffold output: 18–30 files depending on audience + platforms + theme + completenessProfile.
+
+## Always-on (Core)
+
+Every project — regardless of discovery — gets:
+
+- `core/README.philosophy.md.tpl` → `system/<ds>/README.md`
+- `core/README.orchestration.md.tpl` → `.design/README.md` (if missing)
+- `core/SKILL.md.tpl` → `system/<ds>/SKILL.md`
+- `core/INDEX.md.tpl` → `.design/INDEX.md` (if missing)
+- `core/config.json.tpl` → `.design/config.json` (if missing or in re-bootstrap)
+- `core/colors_and_type.css.tpl` → `system/<ds>/colors_and_type.css`
+- `core/preview/_layout.css` → `system/<ds>/preview/_layout.css` (copy as-is)
+- `core/preview/colors-{text,surfaces,accent}.html` → 3 token specimens
+- `core/preview/type-scale.html` → 1 typography specimen
+- `core/preview/spacing-scale.html` → 1 spacing specimen
+- `core/preview/motion.html` → 1 motion specimen
+- `core/preview/components-{buttons,cards,inputs}.html` → 3 component specimens
+
+**Core minimum: 10 preview specimens (excluding `.tpl` docs and `_layout.css`).**
+
+## Always-on (Foundations layer)
+
+Token-foundation specimens that ship for any non-`minimal` profile:
+
+- `foundations/radii.html` → `system/<ds>/preview/radii.tsx`
+- `foundations/elevation.html` → `system/<ds>/preview/elevation.tsx`
+- `foundations/iconography.html` → `system/<ds>/preview/iconography.tsx` (skill re-curates icon set to project domain at scaffold time — see Rules #8 below)
+- `foundations/focus.html` → `system/<ds>/preview/focus.tsx`
+- `foundations/grid.html` → `system/<ds>/preview/grid.tsx`
+- `foundations/borders.html` → `system/<ds>/preview/borders.tsx`
+- `foundations/opacity.html` → `system/<ds>/preview/opacity.tsx`
+- `foundations/selection.html` → `system/<ds>/preview/selection.tsx`
+
+**Foundations default: +8 files.** Profile `minimal` drops these. Profile `standard`/`strict` includes all eight.
+
+## Always-on (Universal components)
+
+Cross-cutting components every project surfaces:
+
+- `universal/components-toggles.html`
+- `universal/components-dialogs.html`
+- `universal/components-tooltips.html`
+- `universal/components-tables.html`
+- `universal/components-callout.html`
+- `universal/empty-state.html.tpl` (substitute project name)
+- `universal/logo.html` — IF wordmark/logotype claim in README/SKILL.md OR `assets/logos/*.svg` exists. If a claim exists with no asset, the skill ALSO generates a minimal placeholder SVG (see Rule #7).
+
+**Universal components default: +6 to +7 files.**
+
+## Conditional family specimens
+
+Gated by `activeFamilies[]`:
+
+- `status/colors-status.html` → IF `"status" ∈ activeFamilies` (default-on)
+- `status/components-status.html` → IF `"status" ∈ activeFamilies`
+- `status/skeletons.html` → IF `"status" ∈ activeFamilies`
+- `audience-pro/colors-presence.html` → IF `"presence" ∈ activeFamilies` (pro tool + multiplayer)
+- `audience-developer/type-mono.html` → IF `"mono" ∈ activeFamilies` (developer audience OR Q7 picked mono pairing)
+
+## Conditional audience specimens
+
+Gated by Q2 (audience):
+
+- **`audience-developer/*`** — IF Q2 = `developer tool`. Includes: type-mono, components-code-block, components-diff-view, components-log-stream, components-monospace-table, components-terminal-pane. **+6 files.**
+- **`audience-pro/*`** — IF Q2 = `pro tool`. Includes: colors-presence (if presence active), components-command-palette, components-keyboard, components-list, components-shortcuts-overlay, components-toast-menu. **+5 to +6 files.**
+- **`audience-consumer/*`** — IF Q2 = `consumer app`. Includes: components-banner, components-empty-state-generous, components-feature-grid, components-marketing-card, components-testimonial. **+5 files.**
+
+## Conditional platform specimens
+
+Gated by Q3 (platforms):
+
+- **`platform-desktop/*`** — IF Q3 includes desktop. Includes: components-resize-panels (1 file), plus the two ui_kit entries below.
+- **`platform-mobile/*`** — IF Q3 includes mobile or tablet. Includes: components-bottom-sheet, components-pull-to-refresh, components-segmented-control, components-tab-bar (4 files), plus the two ui_kit entries below.
+
+## Always-on (ui_kit — the "DS in use" artifacts)
+
+`platform-<platform>/ui_kits-<platform>-{index,showcase}.html` is **not optional**. Every bootstrap produces at least one composition that demonstrates the DS on a realistic product surface. The two entries serve different purposes:
+
+| File | Role |
+|---|---|
+| `platform-desktop/ui_kits-desktop-index.html` | **Catalog/launcher** — links out to individual platform-desktop specimens. Useful for browsing what desktop-specific patterns the project ships. |
+| `platform-desktop/ui_kits-desktop-showcase.html` | **Full product mock** — multi-screen composition (nav + sidebar + main content + status bar) with theme/accent picker. The single highest-leverage "DS in use" artifact in the bootstrap output. |
+| `platform-mobile/ui_kits-mobile-index.html` | **Catalog/launcher** for mobile specimens. |
+| `platform-mobile/ui_kits-mobile-showcase.html` | **Full product mock** sized to a 375 × 812 artboard. |
+
+Both showcase files use vanilla JS for theme/accent switching and include `EDITMODE-BEGIN`/`EDITMODE-END` markers so agents can edit defaults in-place.
+
+**ui_kit default: +2 files for desktop, +2 more for mobile = +2 to +4 files.**
+
+Hard rule: **never scaffold `ui_kits/<platform>/` as an empty directory.** Either populate at least the showcase (single highest-leverage) or skip the platform entirely. The completeness-critic V12/V13 enforces this.
+
+## Conditional theme
+
+- `theme-both/colors-themes-side-by-side.html` → IF Q4 theme = `both equal`. **+1 file.**
+
+## Opt-in (Patterns + Meta)
+
+These are NOT auto-scaffolded. The user can request specific patterns via `config.extensions[]` or explicit `/design:new` invocations:
+
+- `patterns/patterns-auth.html`, `patterns-data-density.html`, `patterns-error-pages.html`, `patterns-form-layouts.html`, `patterns-onboarding.html`, `patterns-pricing.html` — 6 files
+- `meta/accessibility.html`, `i18n.html`, `presence-multiplayer.html`, `tokens-index.html` — 4 files
+
+If the user mentions onboarding or auth flows in Q1, the skill MAY proactively include the matching pattern; otherwise opt-in only.
+
+## Aesthetic inputs (discovery Round 2)
+
+Round 2 answers (Q5 mood, Q6 color, Q7 typography, Q8 voice) are **payload-driven** — the `design:ux-research-agent` discovers domain-relevant options per project. Token values (font families, OKLCH ranges, voice characteristics) come from the chosen payload option, NOT from a hardcoded mapping table.
+
+| Q | Answer source | Effect on scaffold |
+|---|---|---|
+| Q5 mood | payload `mood_clusters[selected]` | Drives aesthetic decisions in `_layout.css` chrome + `_components.css` defaults. No fixed iconography/radii/motion mapping — those land in their own Q11 / Q9 / motion tokens. |
+| Q6 brand color | payload `color_oklch_options[selected]` | OKLCH range from the chosen option becomes `--accent` family. If user picked "I have a hex" → skill converts to OKLCH, derives hover (−2L) / active (−4L) / fg. If user picked "pick-for-me" → skill picks within the Recommended option's OKLCH range, validated against the mood cue ladder in SKILL.md "Accent color heuristic". |
+| Q7 typography | payload `typography_pairing_options[selected]` | `display_family`, `body_family`, `mono_family` from the chosen option are written verbatim into `colors_and_type.css` `--font-display / --font-body / --font-mono` tokens. |
+| Q8 content tone | payload `voice_tone_options[selected]` | The selected option's `characteristics[]` go into the DS README "Voice" section; the `sample_microcopy` becomes the reference example sub-agents read before writing specimen copy. |
+
+## Pro-designer inputs (discovery Round 3)
+
+Round 3 answers (Q9 signature treatment, Q10 hard-NOs, Q11 iconography, Q12 density) are **payload-driven** — the `design:ux-research-agent` surfaces project-specific options. **This table is NOT a list of valid user-facing answers** (the agent's payload generates those per-project from research). Instead, this is the **vocabulary of scaffold effect families** that every payload option MUST classify itself into via a `family` field. The agent picks options that fit the brief, names them per-project (e.g. `<treatment-id> (anchor: <real-product>)`), and tags each with one of these family IDs so the scaffold knows what CSS / asset behavior to apply.
+
+### Q9 signature treatment — effect families
+
+Every `signature_treatment_options[i]` in the payload MUST set `family` to one of these IDs. The scaffold then applies the corresponding `_layout.css` / token changes regardless of how the option was labeled.
+
+| Family ID | Scaffold effect (what `_layout.css` / tokens do when this family is chosen) |
+|---|---|
+| `chrome-glow` | Body bg = soft accent halo + faint vignette; `--shadow-glow` halo on signature cards. Subtle, accent-anchored ambient warmth. |
+| `body-pattern` | Body bg = repeating pattern (scanlines, dot grid, hatch, noise overlay) at low opacity; `body::before` SVG film/grain; optional `body::after` slow animation gated behind reduced-motion. Heavier, atmospheric. |
+| `frosted-blur` | `.specimen` + cards get `backdrop-filter: blur(20px) saturate(140%)` + low-alpha bg; tokens add a frosted-tint variable. Translucent depth. |
+| `hard-edges` | Radii collapse to `0/2/4`; shadows removed except focus ring; borders bumped to `--border-strong`; thicker outlines on key elements. Brutalist / no-nonsense. |
+| `depth-stretch` | Shadow ladder stretched — `--shadow-md/lg/xl` get longer offsets and softer blurs; cards float higher; hover state lifts more. Soft-floaty depth. |
+| `inset-recess` | Tokens add `--shadow-inset-sm/md`; inputs + toggles use inset-shadow surfaces; never inside chrome with text on it (accessibility). Hardware-toggle / recessed feel. |
+| `none` | No body-level treatment; `_layout.css` stays minimal; chrome reads flat. The opt-out value. |
+
+The agent may also propose treatments outside this catalog — when it does, it must either map them to the closest family OR flag in `research_quality_notes` that a new family ID is needed (which then becomes a spec-change conversation, not a silent extension).
+
+### Q10 hard NOs — sub-agent guardrails
+
+| Q | Answer source | Effect on scaffold |
+|---|---|---|
+| Q10 hard NOs | payload `suggested_hard_NOs[]` + `anti_references[]` (user-picked subset, multi-select) | Each picked guardrail surfaced in DS README "Hard rules"; sub-agents read this list and enforce — "no animations" → no `transition` / `@keyframes` outside reduced-motion fallback; "no gradients" → no `linear-gradient` / `radial-gradient` anywhere; "no emoji" → no emoji glyphs in any scaffolded HTML (use stroke SVG glyphs instead). Hard NOs override the Q9 signature treatment when they conflict (e.g. `frosted-blur` + "no gradients" = use solid translucent fill, no gradient backdrop). |
+
+### Q11 iconography — effect families
+
+Every `iconography_vibe_options[i]` in the payload MUST set `family` to one of these IDs.
+
+| Family ID | Scaffold effect (`iconography.html` content + `assets/glyphs/` SVG style) |
+|---|---|
+| `thin-stroke-geometric` | `iconography.html` scaffolds 12 ASCII-leaning 1px-stroke icons; generated SVG glyphs use 1px stroke + rounded caps; no emoji anywhere. Terminal / IDE heritage. |
+| `outline-product` | Default outline icon set at 1.5–2px stroke on a 20–24px grid; balanced product nouns derived from Q1+Q2. The most common "rounded outline" family. |
+| `industry-specific` | `iconography.html` curated to project domain (the agent's `domain_nouns` from the payload drives glyph selection); each domain noun gets a custom SVG. |
+| `filled-solid` | Filled (not stroked) icons; larger sizes default (24/32). High-contrast presence. |
+| `photographic` | Iconography replaced by photographic thumbnails (e.g. ingredient photos as IDs); `assets/glyphs/` remains nominal; thumbnail scaffolding lives in components. |
+
+### Q12 density — effect families
+
+Every `density_options[i]` in the payload MUST set `family` to one of these IDs.
+
+| Family ID | Scaffold effect (`--space-*` defaults + component padding) |
+|---|---|
+| `dense` | Base `--space-*` shrinks (most padding lands on space-2/3); buttons 7px vertical; tables compact; sidebar 220–248px. Pro-tool / data-heavy. |
+| `balanced` | Default `--space-*`; buttons 8px vertical; sidebar 248–280px. Mid-range. |
+| `roomy` | Base padding bumps (most lands on space-4/5); buttons 10–12px vertical; sidebar 280–320px; type-scale slightly bumped. Consumer / reading-friendly. |
+
+## Brand asset minimums (always-on)
+
+When the README/SKILL.md/specimen copy makes a brand claim (`mascot`, `wordmark`, `logotype`, `glyph`, `illustration`, `hedgehog`, `character`), the skill MUST generate at least one minimal SVG to back the claim. The completeness-critic V20 enforces this.
+
+Minimum scaffold:
+- If a wordmark is claimed → `assets/logos/wordmark.svg` (a simple typographic SVG using the project label + accent color, ~15 lines of SVG)
+- If a mark/glyph is claimed → `assets/logos/mark.svg` OR `assets/glyphs/<name>.svg` (a simple geometric mark in the accent color, ~10 lines of SVG)
+- If domain-specific glyphs are claimed (e.g. dugmate's sport balls) → at least 2–3 example SVGs under `assets/glyphs/`
+
+These don't need to be world-class illustrations — the goal is "claim has an artifact". Better placeholders than empty dirs.
+
+### Claim → receipt (machine-checkable contract)
+
+The bootstrap flow MUST run a claim scan against the freshly-authored README + SKILL.md BEFORE emitting the scaffold roster. Every match in the left column requires the corresponding row in the roster as a `pending` file. After scaffold, the completeness-critic re-verifies this table and flags any mismatch.
+
+| claim substring | required receiving file(s) in roster | rewrite alternative |
+|---|---|---|
+| `wordmark`, `logotype` | `universal/logo.html` + `assets/logos/wordmark.svg` | strip the claim from README + SKILL |
+| `mark` (when not part of `wordmark`) | `universal/logo.html` + `assets/logos/mark.svg` | strip the claim |
+| `glyph`, `terminal-glyph` | `foundations/iconography.html` + ≥ 1 `assets/glyphs/*.svg` | strip the claim from README + SKILL |
+| `mascot`, `character` | `assets/logos/mark.svg` OR `assets/illustrations/<name>.svg` (no dedicated specimen template — generate a placeholder SVG) | strip the claim |
+| `illustration` | `assets/illustrations/<name>.svg` (no template — placeholder) | strip the claim |
+| `hedgehog`, named-creature claims | `assets/logos/mark.svg` or matching illustration | strip the claim |
+
+The bootstrap roster emission step (in SKILL.md → "Pre-scaffold — claim scan + emit `_scaffold-roster.yaml`") consults this table; missing receiving files = the row goes into the roster as `pending`. Studio-2 retro BAD-4 caught the failure mode where `assets/glyphs/` was left empty despite the README claiming terminal glyphs lived there — this table is the structural fix.
+
+## Computed `activeFamilies[]`
+
+The skill computes this array based on discovery answers + audience-conditional logic. Used by the completeness-critic to scope checks.
+
+| Family | Included when |
+|---|---|
+| `accent` | always (every project has one accent) |
+| `status` | always unless audience explicitly excludes (rare; minimal scaffolds may skip status/) |
+| `presence` | audience = pro tool AND project has multiplayer hint in Q1 brief |
+| `mono` | audience = developer tool, OR Q7 typography includes a monospace pairing |
+
+## Typical scaffold sizes (full-library state)
+
+| Project profile (Q2 / Q3 / Q4) | Approx file count |
+|---|---|
+| Consumer marketing (consumer / desktop / dark) | ~22 (10 core + 8 foundations + 6 universal + 5 audience-consumer + 2 desktop ui_kit) |
+| Pro-tool SaaS (pro / desktop+mobile / dark) | ~30 (10 + 8 + 6 + 6 audience-pro + 4 platform-mobile + 4 ui_kit + 3 status) |
+| Developer CLI dashboard (developer / desktop / dark) | ~25 (10 + 8 + 6 + 6 audience-developer + 2 desktop ui_kit + 3 status) |
+| Consumer mobile (consumer / mobile / light) | ~24 (10 + 8 + 6 + 5 audience-consumer + 4 platform-mobile + 2 mobile ui_kit) |
+| Enterprise admin (pro / desktop / both) | ~28 (10 + 8 + 6 + 6 audience-pro + 2 desktop ui_kit + 3 status + 1 theme-both) |
+
+Variance comes from audience-* (5–6 files), platform-mobile (4–6 files including ui_kit), and conditional families (status, mono, presence).
+
+## Fan-out batching (dependency_closure)
+
+The skill batches scaffold writes by dependency closure so independent files can be written in parallel by sub-agents. Three tiers:
+
+| `dependency_closure` | Meaning | Batch | Authored by |
+|---|---|---|---|
+| `root` | The dependency root — tokens, `_layout.css`, READMEs, SKILL.md, `config.json`. Nothing else can be written until these exist. | **A** | main agent, serial |
+| `tokens-only` | Pure token-and-chrome specimens (colors-*, type-*, spacing-scale, motion, radii, elevation, focus, iconography, borders, grid, opacity, selection). No reference-template reading required to generate — token CSS + Q5/Q9 mood are enough. | **B** | parallel sub-agents (3–4 slices of 3–5 files each) |
+| `tokens + chrome + template` | Components and compositions (components-*, empty-state, logo, audience-* specimens, platform-* showcases). Each needs the matching reference template from the inspiration library to understand the demonstration intent. | **C** | parallel sub-agents (3–5 slices of 2–4 files each) |
+| `index` | The catalog launcher (`ui_kits-*-index.html`) that links every peer. Written LAST after all peers exist. | **A (post)** | main agent, serial |
+
+| Dir | `dependency_closure` |
+|---|---|
+| `core/colors_and_type.css.tpl`, `core/SKILL.md.tpl`, `core/README.*.tpl`, `core/config.json.tpl`, `core/preview/_layout.css` | `root` |
+| `core/preview/colors-{text,surfaces,accent}.html`, `type-scale.html`, `spacing-scale.html`, `motion.html` | `tokens-only` |
+| `foundations/*.html` | `tokens-only` |
+| `core/preview/components-{buttons,cards,inputs}.html` | `tokens + chrome + template` |
+| `universal/*.html`, `universal/empty-state.html.tpl`, `universal/logo.html` | `tokens + chrome + template` |
+| `status/*.html` | `tokens + chrome + template` |
+| `audience-*/*.html` | `tokens + chrome + template` |
+| `platform-*/components-*.html` | `tokens + chrome + template` |
+| `platform-*/ui_kits-*-showcase.html` | `tokens + chrome + template` |
+| `platform-*/ui_kits-*-index.html` | `index` (written last) |
+| `theme-both/*.html` | `tokens-only` |
+
+The skill emits `<designRoot>/_history/_system/000-scaffold-roster.yaml` with one row per file (path / batch / deps / status). Sub-agents update `status: pending → written` as they go. See `SKILL.md` "Pre-scaffold — emit `_scaffold-roster.yaml`".
+
+## Rules the agent MUST honor
+
+1. **Never copy a specimen verbatim.** Read SPECIMEN comment → understand the demonstration → generate a fresh, project-flavored equivalent. **Target 1.5×–6× the reference LOC** for signature specimens (accent, empty-state, ui_kits-showcase, logo). Token-swap-only output is a scaffold regression; the skill's `Creativity rubric` (in SKILL.md "Scaffold (3-batch fan-out)") names the gold-standards and anti-examples.
+2. **No placeholder copy in output.** "Lorem Solutions Inc.", "Click here", "Acme Corp." MUST NOT appear in the scaffolded files. Use discovery answers to derive project-specific copy.
+3. **Tokens only.** No hardcoded hex / px / rem / em-letter-spacing in scaffolded files (outside the shared `_layout.css` chrome). Typography-critic catches off-ladder px and returns a blocker — see the studio 2026-05-13 re-bootstrap retro.
+4. **Always include the SPECIMEN header** in the scaffolded file (carry it across) so future reads can identify what each specimen demonstrates.
+5. **Honor `activeFamilies[]`.** Skip families the project didn't opt into (no presence specimens for solo-author projects; no mono for non-developer audiences unless Q7 chose a mono pairing).
+6. **Always scaffold at least the platform ui_kit showcase.** The "DS in use" composition is the single most useful artifact for a designer or stakeholder to evaluate the system. Skipping it makes the DS look like a token inventory instead of a product surface. `ui_kits-<platform>-showcase.html` is the canonical filename inside `system/<ds>/preview/`.
+7. **Claim → asset receipt.** If discovery answers include mascot / illustration / logotype cues (Q5 mentions a brand with distinctive mascot, or Q1 implies "character"), generate at least one minimal SVG into `assets/glyphs/` or `assets/logos/` to back the claim. Never let scaffolded copy say "hedgehog mascot energy" with an empty assets dir.
+8. **Re-curate the iconography family.** `foundations/iconography.html` ships with a generic Lucide-style set (trending, clock, search, filter). The skill MUST replace these with icons relevant to Q11 vibe + project's domain at scaffold time: developer tool → terminal/file/branch/commit; consumer → home/search/notification; pro tool → roster/calendar/analytics. Keep the same SPECIMEN header + size scale + stroke conventions.
+9. **Scaffold output is flat.** All category dirs in the inspiration library (`foundations/`, `status/`, `audience-*/`, `platform-*/`, `theme-both/`, `patterns/`, `meta/`, `universal/`) flatten into `system/<ds>/preview/<filename>.html` in the scaffold output. The category prefix lives only in the library, not in the project tree.
+10. **Honor the Q10 hard-NO list.** Each NO picked in discovery becomes a guardrail every sub-agent reads before writing. "No animations" → no `transition` / `@keyframes` outside reduced-motion fallback. "No gradients" → no `linear-gradient` / `radial-gradient` in any output. "No emoji in chrome" → SVG glyphs only. Hard NOs override the Q9 signature treatment when they conflict (e.g. `glassmorphism` + `no gradients` = use solid translucent fill, no gradient backdrop).
+11. **Honor the Q12 density preference.** `dense pro-tool` collapses default padding by one step; `roomy SaaS` bumps it by one. The default values in `_layout.css` `.specimen` + the `--space-*` usage conventions in components MUST reflect the chosen density.
+12. **Reconcile the roster.** After Batch C completes, the main agent reads `_scaffold-roster.yaml`, asserts every row has `status: written`, and rejects the bootstrap as incomplete otherwise — never silently "complete" a bootstrap with pending rows.

package/plugins/design/templates/design-system-inspiration/_README.md

@@ -0,0 +1,71 @@
+# Design system inspiration library
+
+> **For the agent (skill `design-system`, bootstrap mode):** this directory is a **reference inventory**, NOT a substrate to copy literally. Read each specimen as "this is what a good X looks like, this is which tokens it demonstrates, this is the copy voice it uses" — then **generate a fresh, project-flavored equivalent** during scaffold.
+
+## What this directory is
+
+A library of ~20 (skeleton) → ~62 (full) HTML/markdown specimens that demonstrate **what a complete design system looks like in `.design/system/<ds>/`** for various project types. Each specimen:
+
+- Sits in a directory keyed by **when it applies** (`core/` = always, `audience-pro/` = only pro-tool projects, etc.)
+- Has a **SPECIMEN comment header** at the top (`<!-- SPECIMEN: … -->`) listing what tokens it demonstrates, the composition it shows, the copy voice it uses, and when the bootstrap scaffold should include it.
+- Uses **placeholder tokens** (`var(--accent)`, `var(--bg-1)`, …) — the agent must replace them with the project's actual computed values during scaffold.
+
+## What this directory is NOT
+
+- **Not a literal substrate.** Do not `cp -R` this tree into a project's `.design/system/<ds>/`. The output should be project-flavored — fresh content using the project's tokens, project's copy voice, and only the specimens that fit the project's audience / platform / theme.
+- **Not authoritative source.** The agent regenerates files; this library teaches the SHAPE.
+- **Not placeholder copy.** When you scaffold, no "Lorem Solutions Inc." should appear in the output. Replace all placeholder copy with project-flavored content derived from discovery answers (Q1 product one-liner, Q5 mood references, Q8 content tone).
+
+## Directory layout (when fully populated)
+
+```
+templates/design-system-inspiration/
+├── _README.md             # this file
+├── _MAPPING.md            # discovery answer → which files apply (the contract)
+├── core/                  # ALWAYS — every project gets these (10 specimens)
+│   ├── README.philosophy.md.tpl       # system/<ds>/README.md template
+│   ├── README.orchestration.md.tpl    # .design/README.md template
+│   ├── SKILL.md.tpl                   # system/<ds>/SKILL.md template
+│   ├── INDEX.md.tpl                   # .design/INDEX.md template
+│   ├── config.json.tpl                # .design/config.json template
+│   ├── colors_and_type.css.tpl        # tokens skeleton
+│   └── preview/
+│       ├── _layout.css                # shared specimen chrome (copy as-is)
+│       ├── colors-text.html
+│       ├── colors-surfaces.html
+│       ├── colors-accent.html
+│       ├── type-scale.html
+│       ├── spacing-scale.html
+│       ├── motion.html
+│       ├── components-buttons.html
+│       ├── components-cards.html
+│       └── components-inputs.html
+├── universal/             # default-on unless explicitly excluded — common components
+│   ├── components-toggles.html
+│   ├── components-dialogs.html
+│   ├── components-tooltips.html
+│   ├── components-tables.html
+│   ├── components-callout.html
+│   └── empty-state.html.tpl
+└── (foundations/ status/ audience-*/ platform-*/ theme-*/ patterns/ meta/ — added in follow-up phases)
+```
+
+## How the bootstrap-mode agent uses this library
+
+1. **Read `_MAPPING.md`** to know which subdirectories apply to the current project based on discovery answers (Q2 audience, Q3 platforms, Q4 theme, plus universal default-ons).
+2. **Read each applicable specimen's SPECIMEN comment header** to learn what tokens / composition / voice it demonstrates.
+3. **Generate a fresh equivalent** in the project's `.design/system/<ds>/` using the project's actual tokens (from Q6 brand color, Q7 typography) and project's actual copy voice (from Q1 product one-liner, Q8 content tone).
+4. **Never copy a specimen verbatim** — even if the project's profile matches the specimen's intended use case 1:1.
+
+## Editing the library
+
+- Add new specimens by creating an HTML file with a SPECIMEN comment header (see existing files for the format).
+- Add new mappings to `_MAPPING.md` so the agent knows when to include the new specimen.
+- Keep specimens ≤ ~120 lines each. They're for the agent to READ, not paginate.
+- Token usage: only `var(--…)` references, no hardcoded hex / px / rem outside `_layout.css`. The shared chrome can have hardcoded base styles.
+
+## Placeholder syntax (`.tpl` files only)
+
+Templates (`.tpl` extension) use `{{name}}` double-brace placeholders. Distinct from flow's `PROJECT_NAME` namespace. The CLI helper (`maude design init`) strips the `.tpl` suffix during scaffold and substitutes placeholders from the discovery payload.
+
+Plain `.html` files have no placeholders — the agent reads them as references and writes fresh files.

package/plugins/design/templates/design-system-inspiration/audience-consumer/components-banner.html

@@ -0,0 +1,68 @@
+<!--
+SPECIMEN: audience-consumer-banner
+DEMONSTRATES: page-level info / warn / error / promo banners, dismissible variant, position at top of page
+COMPOSITION: 4 banner types stacked, each with icon + body + CTA + optional dismiss button
+COPY VOICE: terse — banners interrupt; respect the user's attention
+WHEN SCAFFOLDED: audience-consumer
+NOTES: Banner sits above the page chrome (not inside a card). Always dismissible UNLESS it's a system error blocking action. Don't stack more than one promo banner at once.
+-->
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Audience — consumer banner</title>
+  <link rel="stylesheet" href="../core/colors_and_type.css" />
+  <link rel="stylesheet" href="../core/preview/_layout.css" />
+  <style>
+    .banner { display: flex; align-items: center; gap: 12px; padding: 10px 16px; border-radius: var(--radius-sm); margin: 0 0 12px; font-size: var(--type-sm); }
+    .banner .icon { flex-shrink: 0; }
+    .banner .body { flex: 1; }
+    .banner .actions { display: flex; gap: 8px; align-items: center; }
+    .banner button { background: transparent; border: 0; color: inherit; font: inherit; padding: 4px 10px; border-radius: var(--radius-xs); cursor: pointer; opacity: 0.85; }
+    .banner button:hover { opacity: 1; background: oklch(0 0 0 / 0.15); }
+    .banner .dismiss { font-size: 18px; line-height: 1; padding: 2px 6px; }
+    .banner--info { background: oklch(from var(--status-info) l c h / 0.18); color: var(--status-info); border: 1px solid var(--status-info); }
+    .banner--warn { background: oklch(from var(--status-warn) l c h / 0.18); color: var(--status-warn); border: 1px solid var(--status-warn); }
+    .banner--error { background: oklch(from var(--status-error) l c h / 0.18); color: var(--status-error); border: 1px solid var(--status-error); }
+    .banner--promo { background: oklch(from var(--accent) l c h / 0.18); color: var(--accent); border: 1px solid var(--accent); }
+    .banner strong { color: inherit; }
+  </style>
+</head>
+<body class="app" data-theme="dark">
+  <main class="specimen">
+    <h1>Banners</h1>
+    <p class="lede">Page-level announcements. They sit above content (not inside a card) and respect the user's attention — terse copy, single CTA, dismissible unless they block action.</p>
+
+    <div class="banner banner--info">
+      <span class="icon">ⓘ</span>
+      <div class="body"><strong>New:</strong> match recap cards now include xG. <a href="#" style="color: inherit; text-decoration: underline;">See what changed</a>.</div>
+      <div class="actions"><button class="dismiss" aria-label="Dismiss">×</button></div>
+    </div>
+
+    <div class="banner banner--warn">
+      <span class="icon">⚠</span>
+      <div class="body"><strong>Heads up:</strong> league sync is paused while the federation updates their endpoint. Manual entry still works.</div>
+      <div class="actions"><button>Status page</button></div>
+    </div>
+
+    <div class="banner banner--error">
+      <span class="icon">⚠</span>
+      <div class="body"><strong>Couldn't load the roster.</strong> The league API is returning errors. We're retrying every 30s.</div>
+      <div class="actions"><button>Retry now</button></div>
+    </div>
+
+    <div class="banner banner--promo">
+      <span class="icon">★</span>
+      <div class="body"><strong>2 weeks free</strong> on the Club plan when you import your squad before Sunday.</div>
+      <div class="actions">
+        <button>Try Club</button>
+        <button class="dismiss" aria-label="Dismiss">×</button>
+      </div>
+    </div>
+
+    <footer class="legend">
+      <p>Error banners are usually NOT dismissible — they block meaningful work, so dismissing them hides a real problem. Info, warn, and promo banners should always have an × close button.</p>
+    </footer>
+  </main>
+</body>
+</html>

package/plugins/design/templates/design-system-inspiration/audience-consumer/components-empty-state-generous.html

@@ -0,0 +1,39 @@
+<!--
+SPECIMEN: audience-consumer-empty-state-generous
+DEMONSTRATES: oversized empty state with illustration slot, headline, supporting sentence, primary + optional secondary CTA
+COMPOSITION: full-bleed empty state with 80-120px breathing room around content
+COPY VOICE: warm and specific — names what's missing ("No match recaps yet"), suggests a clear first action
+WHEN SCAFFOLDED: audience-consumer (generous variant; pro tools use the universal/empty-state.html)
+NOTES: Generous version takes more vertical space (~480px min height) — used on dashboards, not nested panes. Illustration is a 96px decorative SVG, not a stock photo.
+-->
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Audience — consumer empty state (generous)</title>
+  <link rel="stylesheet" href="../core/colors_and_type.css" />
+  <link rel="stylesheet" href="../core/preview/_layout.css" />
+</head>
+<body class="app" data-theme="dark">
+  <main class="specimen">
+    <h1>Empty state — generous</h1>
+    <p class="lede">For consumer dashboards where the empty state IS the screen. More breathing room, a friendly headline, and a clear next step — never just "Nothing here yet."</p>
+
+    <div style="background: var(--bg-1); border: 1px solid var(--border-subtle); border-radius: var(--radius-lg); padding: 80px 40px; text-align: center; max-width: 600px;">
+      <div style="width: 96px; height: 96px; background: oklch(from var(--accent) l c h / 0.1); border-radius: var(--radius-pill); color: var(--accent); display: inline-flex; align-items: center; justify-content: center; margin: 0 auto 24px;">
+        <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/></svg>
+      </div>
+      <h2 style="font-family: var(--font-display); font-size: var(--type-2xl); font-weight: 600; margin: 0 0 8px;">No match recaps yet</h2>
+      <p style="color: var(--fg-1); font-size: var(--type-md); line-height: var(--lh-md); max-width: 40ch; margin: 0 auto 24px;">When your team plays its first match, the recap will land here automatically — with goals, ratings, and a shareable card for the club channel.</p>
+      <div style="display: flex; justify-content: center; gap: 12px;">
+        <button style="background: var(--accent); color: var(--accent-fg); border: 0; padding: 10px 20px; border-radius: var(--radius-md); font: inherit; font-weight: 500; cursor: pointer;">Log a match</button>
+        <button style="background: transparent; color: var(--fg-1); border: 1px solid var(--border-default); padding: 10px 20px; border-radius: var(--radius-md); font: inherit; cursor: pointer;">See a demo recap</button>
+      </div>
+    </div>
+
+    <footer class="legend" style="margin-top: 48px;">
+      <p>This is the version you want on a marketing-flavored dashboard. For dense pro tools, use <code>universal/empty-state.html</code> — same idea, tighter spacing.</p>
+    </footer>
+  </main>
+</body>
+</html>

package/plugins/design/templates/design-system-inspiration/audience-consumer/components-feature-grid.html

@@ -0,0 +1,62 @@
+<!--
+SPECIMEN: audience-consumer-feature-grid
+DEMONSTRATES: 3-column feature grid, icon-headline-body pattern, balanced visual weight
+COMPOSITION: 6 features in a 3x2 grid, each with icon + 2-4 word title + 1-sentence body
+COPY VOICE: title is the benefit ("Sync with the club"), body is the proof ("Auto-pushes match recaps to your team channel.")
+WHEN SCAFFOLDED: audience-consumer
+NOTES: Icons are 24px on top, never inline with the title. Keep titles ≤ 4 words. Bodies ≤ 16 words. Don't list 9 features — pick the top 6 that actually differentiate.
+-->
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Audience — consumer feature grid</title>
+  <link rel="stylesheet" href="../core/colors_and_type.css" />
+  <link rel="stylesheet" href="../core/preview/_layout.css" />
+  <style>
+    .feature { display: grid; gap: 8px; padding: 20px; background: var(--bg-1); border: 1px solid var(--border-subtle); border-radius: var(--radius-md); }
+    .feature .icon { width: 36px; height: 36px; background: oklch(from var(--accent) l c h / 0.15); color: var(--accent); border-radius: var(--radius-sm); display: inline-flex; align-items: center; justify-content: center; }
+    .feature .title { font-family: var(--font-display); font-size: var(--type-md); font-weight: 600; margin: 4px 0 0; }
+    .feature .body { color: var(--fg-1); font-size: var(--type-sm); margin: 0; }
+  </style>
+</head>
+<body class="app" data-theme="dark">
+  <main class="specimen">
+    <h1>Feature grid</h1>
+    <p class="lede">Six features, no more. Icon + 2–4-word title + one-sentence body. Each title is the benefit; each body is the proof.</p>
+
+    <div class="grid" style="grid-template-columns: repeat(auto-fill, minmax(220px, 1fr)); gap: 16px;">
+      <div class="feature">
+        <span class="icon">⚡</span>
+        <h3 class="title">Real-time match view</h3>
+        <p class="body">See goals, subs, and cards as they happen. No refresh needed.</p>
+      </div>
+      <div class="feature">
+        <span class="icon">📋</span>
+        <h3 class="title">One-tap roster sync</h3>
+        <p class="body">Pull from the league, push to your team chat in two taps.</p>
+      </div>
+      <div class="feature">
+        <span class="icon">📊</span>
+        <h3 class="title">Season-long stats</h3>
+        <p class="body">Track goals, minutes, and clean sheets without a spreadsheet.</p>
+      </div>
+      <div class="feature">
+        <span class="icon">🎯</span>
+        <h3 class="title">Match recap card</h3>
+        <p class="body">Shareable summary auto-built when the final whistle blows.</p>
+      </div>
+      <div class="feature">
+        <span class="icon">🏃</span>
+        <h3 class="title">Training planner</h3>
+        <p class="body">Drag-and-drop drills, share the session, mark attendance.</p>
+      </div>
+      <div class="feature">
+        <span class="icon">🔔</span>
+        <h3 class="title">Smart notifications</h3>
+        <p class="body">Only the things you asked for. No "5 highlights you missed."</p>
+      </div>
+    </div>
+  </main>
+</body>
+</html>

package/plugins/design/templates/design-system-inspiration/audience-consumer/components-marketing-card.html

@@ -0,0 +1,63 @@
+<!--
+SPECIMEN: audience-consumer-marketing-card
+DEMONSTRATES: generous padding, large typography, prominent CTA, optional eyebrow + image slot
+COMPOSITION: 3 marketing-card variants — feature card, pricing tier, testimonial-adjacent — each at consumer density
+COPY VOICE: consumer-friendly but specific ("Real-time match insights", not "Powerful analytics")
+WHEN SCAFFOLDED: audience-consumer
+NOTES: Consumer density = more padding (--space-5/6 inside cards), bigger type (--type-lg / --type-xl for headlines), one clear CTA. Avoid sentence-cap headlines longer than 6 words.
+-->
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Audience — consumer marketing card</title>
+  <link rel="stylesheet" href="../core/colors_and_type.css" />
+  <link rel="stylesheet" href="../core/preview/_layout.css" />
+  <style>
+    .mcard { background: var(--bg-1); border: 1px solid var(--border-subtle); border-radius: var(--radius-lg); padding: var(--space-5); display: grid; gap: 12px; max-width: 360px; }
+    .mcard .eyebrow { font-size: var(--type-xs); text-transform: uppercase; letter-spacing: 0.08em; color: var(--accent); font-weight: 600; }
+    .mcard .title { font-family: var(--font-display); font-size: var(--type-xl); line-height: var(--lh-xl); font-weight: 600; margin: 0; }
+    .mcard .body { color: var(--fg-1); margin: 0; }
+    .mcard .cta { background: var(--accent); color: var(--accent-fg); border: 0; padding: 10px 18px; border-radius: var(--radius-md); font: inherit; font-weight: 500; cursor: pointer; align-self: start; }
+    .mcard .hero { height: 120px; border-radius: var(--radius-md); background: linear-gradient(135deg, var(--accent) 0%, oklch(from var(--accent) calc(l - 0.15) c h) 100%); }
+  </style>
+</head>
+<body class="app" data-theme="dark">
+  <main class="specimen">
+    <h1>Marketing card</h1>
+    <p class="lede">Generous breathing room, one CTA. The eyebrow names the category at low visual weight; the title carries the proposition.</p>
+
+    <div class="row" style="gap: 24px; align-items: start;">
+      <div class="mcard">
+        <span class="eyebrow">New in 2.0</span>
+        <h2 class="title">Real-time match insights</h2>
+        <p class="body">See who's hot, who's not, and who needs a sub — without leaving the sideline.</p>
+        <button class="cta">Try it free</button>
+      </div>
+
+      <div class="mcard">
+        <div class="hero"></div>
+        <span class="eyebrow">For clubs</span>
+        <h2 class="title">Plan a season in a week</h2>
+        <p class="body">Squad lists, fixture sync, training notes — every coach on one shared view.</p>
+        <button class="cta">See a demo</button>
+      </div>
+
+      <div class="mcard" style="border-color: var(--accent);">
+        <span class="eyebrow" style="color: var(--accent);">Most popular</span>
+        <h2 class="title">Club</h2>
+        <div style="display: flex; align-items: baseline; gap: 4px;">
+          <span style="font-family: var(--font-display); font-size: var(--type-3xl); font-weight: 600;">$24</span>
+          <span style="color: var(--fg-2);">/month per team</span>
+        </div>
+        <ul style="margin: 0; padding-left: 18px; color: var(--fg-1);">
+          <li>Up to 5 squads</li>
+          <li>Full season archive</li>
+          <li>Match recap exports</li>
+        </ul>
+        <button class="cta">Start free trial</button>
+      </div>
+    </div>
+  </main>
+</body>
+</html>