@1agh/maude 0.19.1 → 0.20.0

package/plugins/design/templates/design-system-inspiration/SUB-AGENT-PROMPTS.md

@@ -0,0 +1,245 @@
+# Sub-agent prompt templates — `/design:setup-ds` Batch B + C
+
+> **Why this file exists.** Per Phase 3.7 Task 4 (and DDR-049), the sub-agent prompt templates that drive Batch B + C fan-out used to live inline in `plugins/design/skills/design-system/SKILL.md` (lines 662-797 pre-extraction). SKILL.md is 1000+ LOC; the prompts were buried. Extracting them here lets us audit + extend the prompts (and especially the three MANDATORY safety blocks below) without scrolling through unrelated bootstrap logic. The skill's "Batches B + C" step loads + interpolates from this file instead of inlining the template.
+>
+> **Sync rule** — when this file changes, the SKILL.md reference must still resolve. The Phase 3.7 risk register mandates a CI grep check: `SKILL.md` must literally contain the string `SUB-AGENT-PROMPTS.md`. Don't rename the file without updating the skill.
+
+The prompts are grouped by **slice** (matches the roster's `fanout:` block). Each section is a self-contained sub-agent brief — copy verbatim, substitute placeholders.
+
+The three MANDATORY safety blocks (ANIMATION SAFETY, RELATIVE-URL SAFETY, PLACEHOLDER POLICY) appear once at the top because they apply to every slice; sub-agent prompts reference them by name (`Apply ANIMATION SAFETY below`) instead of inlining.
+
+---
+
+## MANDATORY SAFETY BLOCKS (apply to every slice; cited by name in prompts)
+
+### ANIMATION SAFETY (mandatory — applies to motion specimen + any canvas with @keyframes / transitions)
+
+- **Bounded geometry.** Every tile that hosts a rotating / scaling animation MUST have `overflow: hidden`. Otherwise the bounding box extends ~√2× at 45°/135° rotations and overflows adjacent rows. **The motion specimen tiles all set `overflow: hidden` explicitly** — codify this with a CSS comment so future agents reading the file see the rationale.
+- **Sparkle / pulse / twinkle = small only.** Keyframes that scale from `0 → 1 → 0` (or similar "appear-and-disappear" patterns) are for elements ≤56px. **Never apply to full-width tiles.** Demo sparkle on a 32×32 chip inside a tile, never on the tile itself. The studyfi imprint retro D-3 caught a sparkle-on-full-tile that exploded the whole row.
+- **Loop motion = `infinite alternate`.** Specimens meant for continuous display use `animation: <kf> <dur> infinite alternate <easing>`. Single-shot animations finish in 150-200ms and leave the demo invisible on the second look — "looks dead until you hover" is the regression mode.
+- **Compositor-only.** Animate `transform` + `opacity` only. Never `width`, `height`, `top`, `left`, `padding`, `margin`. Layout-dirty animations break adjacent geometry AND cost paint cycles.
+- **Reduced motion is mandatory.** Tokens already collapse `--dur-*` to `1ms` when `@media (prefers-reduced-motion: reduce)` is set. Do NOT add `!important` overrides outside the motion specimen itself (the specimen has a `<ReducedMotionToggle>` chrome that reviewers use to flip both branches without OS settings — that's the only documented exception). If using `motion/react`, use `useReducedMotion()` and short-circuit the `animate` prop.
+- **No bouncy springs by default.** Springs say "Toy", not "Pro Tool". Use `spring` role only when the DS brief explicitly asks for it (e.g. brief mentions "playful" / "tactile" / "physical" / "bouncy"). Default to `tween` with the standard easing tokens.
+
+### RELATIVE-URL SAFETY (mandatory — applies to any specimen referencing assets, logos, glyphs)
+
+- The dev-server serves canvases via `/_canvas-shell.html?canvas=<rel-path>`. **Relative URLs (`../foo.svg`, `./assets/logo.svg`) resolve against the SHELL's URL, not the canvas file's location.** Result: 404 / broken-image icon. Studyfi imprint retro D-4 was caught by the user mid-flow because of exactly this.
+- **Always inline SVGs** in JSX. Use `useId()` for any `<filter id>` / `<linearGradient id>` so multiple instances of the same component don't collide on a single page. OR
+- **Always use absolute paths rooted at `/assets/...`** served from the dev-server's static mount. The `system/<ds>/assets/` directory is mounted at `/assets/<ds>/` in production-handoff mode.
+- **Forbidden:** `<img src="../foo.svg">`, `<image href="./logo.svg">`, `url('../bg.png')` inside inline `<style>` blocks. Any of these surviving in a specimen is a graphic-design-critic blocker.
+
+### PLACEHOLDER POLICY (mandatory — applies to logo / mark / wordmark / mascot / glyph / illustration claims)
+
+- Before writing a placeholder SVG, the orchestrator MUST have run the pre-scaffold real-asset sweep (`bin/asset-sweep.sh`). The sweep populates the roster's `assets:` block with `source: <production path>` for every noun where a real asset exists. **Sub-agents read the roster** — if `source:` is populated for a noun, COPY the asset; do NOT invent a placeholder.
+- If the sweep returned zero candidates for a noun, only THEN may a placeholder be authored. **The placeholder file's name MUST contain `-placeholder`** (e.g. `logo-placeholder.svg`, `mascot-placeholder.svg`) so it's visually obvious in `ls` + `grep` and downstream sub-agents know not to promote it.
+- **Never assume your own placeholder path is authoritative downstream.** When the roster row's `source:` is empty AND you wrote a placeholder, set `source: placeholder` in your roster update (not `source: written`). The brand-critic and the next bootstrap pass both look for `source: placeholder` rows as "consider revisiting later".
+- **Forbidden:** authoring an `S`-shaped wordmark for a product whose first letter isn't S, authoring a "hedgehog mascot" SVG because the README copy mentioned hedgehog energy. The studyfi imprint retro D-2 caught both patterns. If the production-asset sweep returned nothing AND the discovery brief didn't explicitly request a mascot, **rewrite the copy** instead of inventing the artifact.
+
+---
+
+## Sub-agent prompt template (slice-agnostic — used by every Batch B + C slice)
+
+```
+You are scaffolding part of a design system. Write {{N}} specimen TSX files in
+parallel with other sub-agents. Each file lands at the absolute path listed.
+
+SHAPE — every specimen TSX is BARE — NO canvas-lib envelope. The shape:
+
+  /** JSDoc header (see template) */
+  import "./<slug>.css";  /* per-specimen bespoke CSS — sibling file */
+
+  export default function <PascalName>() {
+    return (
+      <>
+        <header className="specimen-hd">
+          <span className="sku">MDCC-DSN/01.<slug></span>
+          <span className="crumbs">...</span>
+          <span className="theme-toggle" ...>...</span>
+        </header>
+        <main className="specimen">
+          <section className="specimen-title">
+            <h1>...</h1>
+            <p className="lede">...</p>
+          </section>
+          {/* sections, h2 dividers, tables, etc. */}
+        </main>
+      </>
+    );
+  }
+
+Specimens are FLOWING reference pages, not viewport mocks. Do NOT wrap in
+`<DesignCanvas><DCSection><DCArtboard>` — `_layout.css` styles `<body>` as
+a flex column directly. The original .html-era specimens had exactly this
+shape; we keep it one-for-one in TSX.
+
+Canvas-lib (`@maude/canvas-lib`) is reserved for UI mock canvases with
+multiple fixed-px artboards (Docs Site, Canvas Viewport). Specimens do NOT
+import it. Token/theme hooks (`useTokens`, `useTheme`) ARE available if a
+specimen genuinely needs them — but bare CSS via `var(--*)` is the default.
+
+**Motion specimens are the documented exception.** The motion specimen
+(when scaffolded) imports motion helpers from `@maude/canvas-lib`:
+`<MotionDemo role>`, `<MotionTrack>`, `<TokenPlayback>`, `<ReducedMotionToggle>`,
+`useMotionTokens()`. Other specimens stay bare. See ANIMATION SAFETY above.
+
+Per-specimen bespoke CSS lives in a sibling `<slug>.css`. The dev-server's
+canvas-build.ts collects this and injects it as a `<style>` at module init
+so the drop is self-contained.
+
+PROJECT
+- name: {{project_label}}
+- DS slug: {{ds_dirname}}
+- one-liner: {{Q1}}
+- audience: {{Q2}} · platforms: {{Q3}} · theme default: {{Q4}}
+- voice: {{Q8}} ("{{voice_one_line_summary}}")
+- signature treatment: {{Q9}} ({{Q9_one_line_summary}})
+- hard NOs: {{Q10 csv}}
+- iconography vibe: {{Q11}}
+- density: {{Q12}}
+
+REFERENCES (verbatim — read first, do not skim)
+- TOKENS (authoritative):     {{absolute path to colors_and_type.css}}
+- CHROME (signature):         {{absolute path to _layout.css}}
+- COMPONENTS (when emitted):  {{absolute path to _components.css OR "(not emitted — inline styles only)"}}
+- DS README (hard rules):     {{absolute path to system/<ds>/README.md}}
+- _MAPPING.md gating rules:   {{absolute path to _MAPPING.md}}
+- inspiration library root:   {{absolute path to plugins/design/templates/design-system-inspiration/}}
+- ROSTER (your slice + assets): {{absolute path to _scaffold-roster.yaml}}
+{{if peer_DS_references_attached:}}
+- PEER DS gold-standard:      {{absolute paths to system/<peer-ds>/preview/<file>.tsx}}
+{{endif}}
+
+DOMAIN_NOUNS (authoritative — every specimen MUST use only these nouns)
+{{domain_nouns}}    # the 5–10 nouns from discovery payload's domain_nouns field — project-native vocabulary the specimen must use
+{{if peer_DS_references_attached:}}
+DOMAIN NOUN PURGE — peer DS references are COMPOSITION REFERENCES ONLY. The peer
+DS uses different domain nouns (a peer DS built for a different product domain
+will have nouns specific to that domain). When restructuring from a peer reference,
+search-and-replace EVERY peer-DS noun in your output with a noun from this DS's
+DOMAIN_NOUNS list. A single peer-DS noun surviving in your output is a copy-critic
+blocker — leaked domain nouns from a peer reference (e.g. "publish <peer-noun>"
+surviving into this DS's specimen) is the regression mode this purge step prevents.
+{{endif}}
+
+YOUR SLICE — write these {{N}} files (absolute paths):
+1. {{abs path 1}}  — reference template: {{abs path to inspiration template 1}}
+2. {{abs path 2}}  — reference template: {{abs path to inspiration template 2}}
+… (etc.)
+
+SAFETY BLOCKS — apply to every file in your slice:
+- **ANIMATION SAFETY** (see SUB-AGENT-PROMPTS.md). Mandatory if your slice
+  includes the `motion` specimen OR any file that uses `@keyframes` /
+  `transition` / `animate`. Bounded geometry + sparkle-≤56px + infinite-alternate
+  + compositor-only + reduced-motion + no-bouncy-springs.
+- **RELATIVE-URL SAFETY** (see SUB-AGENT-PROMPTS.md). Mandatory if your slice
+  references ANY asset (logo, glyph, illustration, background image). Inline
+  SVG with `useId()`, OR absolute `/assets/<ds>/...` path. NEVER relative.
+- **PLACEHOLDER POLICY** (see SUB-AGENT-PROMPTS.md). Mandatory if your slice
+  scaffolds the `logo` / `empty-state` specimen or any brand-asset surface.
+  Read the roster `assets:` block FIRST. If `source:` is populated, copy the
+  real asset; do NOT invent. If `source:` is empty AND the noun is genuinely
+  warranted, author a `-placeholder` SVG and set `source: placeholder` in your
+  roster update.
+
+CREATIVITY RUBRIC — do NOT token-swap. RESTRUCTURE.
+- Read the reference template. Understand the SPECIMEN comment header (what it
+  demonstrates). Then write a project-flavored equivalent of 1.5×–6× the reference
+  LOC. Same demonstration intent, ORIGINAL composition, project's voice, project's
+  domain nouns.
+- Every specimen earns at least ONE compositional choice that's not in the
+  template. Examples that landed well in the studio 2026-05-13 re-bootstrap (use
+  these as gold-standard creativity moves):
+    - colors-accent.tsx (48 LOC template → ~5× LOC): added a brand-spotlight
+      hero with masked gradient border, a "wrong" anti-pattern teaching device,
+      chroma annotations on swatches.
+    - empty-state.tsx (~6× LOC): added a "Voice — keep or kill" panel
+      comparing good vs corporate copy side by side; added a variants grid for
+      multiple empty-state cases.
+    - ui_kits-<platform>-showcase.tsx (~3× LOC): replaced the template's
+      generic mock screens with project-specific reality from the discovery
+      payload's domain_nouns; added a live-presence layer + a token-row
+      inspector panel where the brief warranted it.
+  Anti-example: a components-buttons.tsx at 1.3× the template LOC that kept
+  the template's fake-state grid almost verbatim. **Don't do this.** Add
+  icon-only + kbd-hint variants, push hierarchy contrast, surface the signature
+  treatment on the primary's hover state.
+- Copy is project-specific. NO "Lorem", NO "Acme Corp.", NO "Get Started". Use
+  the project's actual nouns ({{domain_nouns}}). Match the voice — {{Q8 voice}}.
+- Tokens only. No hardcoded hex / px / rem. If you reach for an off-ladder
+  value, STOP and use the nearest `var(--*)` token. The typography-critic
+  catches off-ladder px and will return a blocker.
+- Hard NOs from Q10 are guardrails. {{if "no animations" in hard_nos: "Do not add hover/active transitions; static states only."}} {{if "no gradients" in hard_nos: "No linear-gradient / radial-gradient anywhere."}} (etc.)
+- Carry the SPECIMEN comment header from the reference template at the top of
+  your output so future agents can identify what each file demonstrates.
+
+ANTI-PATTERNS (graphic-design-critic blockers — guaranteed rejection)
+- Multiplayer cursors / annotation pins / presence avatars MUST anchor to
+  SPECIFIC content (a toolbar button, a list row, a panel, a swatch). Pins
+  floating over canvas void are a fail mode. If you don't have content for a
+  pin to anchor, REDUCE the pin count to match available anchor count. (Caught
+  on studio-2 showcase, retro BAD-8.)
+- Cropmarks / signature framing devices must be visually thicker than internal
+  panel borders, otherwise they read as "another panel" not "this is the
+  staging frame".
+- Sections in long specimens (≥ 4 sections) must vary in vertical weight — the
+  hero / signature section earns 25–30%, not equal share with policy sections.
+
+WHEN DONE
+After writing all {{N}} files:
+  1. Update each row in {{absolute path to _scaffold-roster.yaml}}: change
+     `status: pending` → `status: written, loc: <line-count>`.
+  2. **Do NOT add new rows.** If you discover a missing claim (e.g. wordmark
+     referenced but no logo.tsx in roster), include "ROSTER GAP: <description>"
+     in your completion message. The main agent reconciles new rows.
+  3. Return a one-line confirmation per file with LOC.
+```
+
+Sub-agents are stateless — give each a complete brief, do not assume shared context. Three-line confirmation back is enough; the roster is the source of truth.
+
+---
+
+## Per-slice prompt addenda
+
+The base template above applies to every slice. Each slice gets a small addendum to steer the sub-agent toward the slice-specific anti-patterns and the safety blocks that apply.
+
+### Slice: `foundations` (color tokens, type + spacing, motion, radii/elevation/focus, iconography/borders/grid)
+
+**Apply ANIMATION SAFETY in full.** The `motion` specimen is the highest-friction file in this slice — D-3 from the imprint retro landed here. Specifically:
+- Motion specimen MUST use `<MotionDemo>` from `@maude/canvas-lib`, NOT inline `@keyframes` literals (DDR-049 enforces the canonical library).
+- 4 duration tokens (`--dur-flip`, `--dur-panel`, `--dur-route`, `--dur-soft`) MUST each be referenced ≥ 1× by the motion specimen — completeness-critic asserts coverage post-scaffold.
+- The specimen MUST animate on first paint. Hover-driven CSS transitions alone fail the "looks dead at rest" smell test.
+
+**Apply RELATIVE-URL SAFETY in full.** The `iconography` specimen tends to reference glyph SVGs; the `focus` specimen sometimes references focus-ring fixtures. Inline ALL SVGs.
+
+### Slice: `brand + voice` (empty-state, logo)
+
+**Apply PLACEHOLDER POLICY in full.** This slice is the highest-risk for placeholder-bleed. The `logo` specimen MUST start by reading the roster's `assets:` block:
+- If `assets.logo.source` is a real path, the specimen `<img>`s / inlines the real asset.
+- If `assets.logo.source` is empty, fall back to a `-placeholder` SVG with the rationale in the JSX comment block. Set `source: placeholder` on roster update.
+
+**Apply RELATIVE-URL SAFETY in full.** Logo specimens are 100% asset-bound. Inline SVG is the default; absolute `/assets/<ds>/logo.svg` is the alternative.
+
+### Slice: `core components` (components-buttons, components-cards, components-inputs)
+
+Buttons frequently get hover transitions — apply ANIMATION SAFETY (compositor-only). Cards frequently get a hover lift — same constraint, transform-only.
+
+### Slice: `universal` / `audience-*` / `platform-*`
+
+No slice-specific addenda — the base template covers them.
+
+### Slice: `ui_kits-*-showcase` (main agent OR signature sub-agent)
+
+**Apply ANIMATION SAFETY.** Showcase is the highest-density "DS in use" artifact; presence cursors, route transitions, and panel slides all show up here. Every animation must be bounded + reduced-motion-safe + token-derived.
+
+**Apply RELATIVE-URL SAFETY.** Showcase often references domain product imagery. Inline SVG mocks, never `<img src="../assets/...">`.
+
+---
+
+## Cross-links
+
+- Owner skill: `plugins/design/skills/design-system/SKILL.md` (BOOTSTRAP flow → "Batches B + C — parallel fan-out via sub-agents" section loads this file)
+- Discovery probe templates (sibling): `plugins/design/skills/design-system/_pastier-probe-templates.md`
+- Motion library decision: `.ai/decisions/DDR-049-motion-one-as-canonical-motion-library.md`
+- Imprint-bootstrap retro (source of D-1 … D-5): `.ai/logs/system-reviews/imprint-bootstrap-review-2026-05-26.md`
+- Asset sweep helper: `plugins/design/dev-server/bin/asset-sweep.sh`
+- Visual sanity helper: `plugins/design/dev-server/bin/visual-sanity.sh`

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

@@ -37,7 +37,7 @@ Every project — regardless of discovery — gets:
 - `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/motion.tsx.tpl` + `motion.css.tpl` + `_motion-readme.md.tpl` → 1 motion specimen (Phase 3.7 / DDR-049 — TSX playground with 8 role tiles via `<MotionDemo>` from `@maude/canvas-lib`; legacy `.html` archived to `.archive/`)
 - `core/preview/components-{buttons,cards,inputs}.html` → 3 component specimens
 
 **Core minimum: 10 preview specimens (excluding `.tpl` docs and `_layout.css`).**
@@ -248,7 +248,7 @@ The skill batches scaffold writes by dependency closure so independent files can
 | 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` |
+| `core/preview/colors-{text,surfaces,accent}.html`, `type-scale.html`, `spacing-scale.html`, `motion.tsx.tpl` + `motion.css.tpl` | `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` |

package/plugins/design/templates/design-system-inspiration/core/preview/_components.css.tpl

@@ -0,0 +1,129 @@
+/* _components.css — shared component anatomy (Phase 3.6.1 emit-conditionally).
+ *
+ * This file is OPTIONAL. The bootstrap scaffolder emits it when Q9 signature
+ * treatment ≠ `none` AND the treatment repeats across 3+ components — at that
+ * point promoting class anatomy out of per-specimen <style> blocks reduces
+ * drift and makes critic-panel scans cleaner.
+ *
+ * Project-specific component classes (.btn / .tile / .input / etc.) are
+ * authored by the scaffolder for the specific Q9 family. The MOTION ROLE
+ * CLASSES below are the universally-shared piece — they ship verbatim
+ * regardless of Q9 family, because the motion vocabulary is fixed at 8 roles
+ * per DDR-049.
+ */
+
+/* ─────────────────────────────────────────────────────────────────────── */
+/* Motion role classes — CSS-only escape hatch for the canvas-lib motion
+ * vocabulary (Phase 3.7 / DDR-049). Use when a canvas wants the role
+ * vocabulary without importing motion/react. The shape MUST stay in sync
+ * with `<MotionDemo role>` in canvas-lib.tsx.
+ *
+ * Usage:  <div className="motion-flip">…</div>
+ *         <div className="motion-soft">…</div>
+ *
+ * Each class is `animation: <kf> <dur> <ease> infinite alternate` so the
+ * element loops on first paint (matching the canvas-lib helper's default
+ * loop="always"). To opt out of the loop, set `animation-iteration-count: 1`
+ * on the host or use `animation-play-state: paused`.
+ *
+ * Reduced-motion is enforced by the colors_and_type.css token collapse
+ * (--dur-*: 1ms under prefers-reduced-motion: reduce) — these classes
+ * inherit that for free.
+ */
+
+/* flip — press-down, hover lift. */
+@keyframes motion-flip-kf {
+  0% { transform: translateY(0); }
+  100% { transform: translateY(-12px); }
+}
+.motion-flip {
+  animation: motion-flip-kf var(--dur-flip, 220ms) var(--ease-out, ease-out) infinite alternate;
+  overflow: hidden;
+}
+
+/* panel — drawer / sidebar slide. */
+@keyframes motion-panel-kf {
+  0% { transform: translateX(-80px); }
+  100% { transform: translateX(0); }
+}
+.motion-panel {
+  animation: motion-panel-kf var(--dur-panel, 320ms) var(--ease-in-out, ease-in-out) infinite alternate;
+  overflow: hidden;
+}
+
+/* route — page transition (opacity + tiny scale). */
+@keyframes motion-route-kf {
+  0% { opacity: 0; transform: scale(0.92); }
+  100% { opacity: 1; transform: scale(1); }
+}
+.motion-route {
+  animation: motion-route-kf var(--dur-route, 480ms) var(--ease-out, ease-out) infinite alternate;
+  overflow: hidden;
+}
+
+/* soft — toast / tooltip / soft reveal. */
+@keyframes motion-soft-kf {
+  0% { opacity: 0; }
+  100% { opacity: 1; }
+}
+.motion-soft {
+  animation: motion-soft-kf var(--dur-soft, 160ms) var(--ease-out, ease-out) infinite alternate;
+}
+
+/* spring — tactile/playful settle. CSS spring approximation only — for
+ * production spring fidelity, lift <MotionDemo role="spring" /> instead. */
+@keyframes motion-spring-kf {
+  0% { transform: translateY(0); }
+  60% { transform: translateY(-20px); }
+  78% { transform: translateY(-12px); }
+  90% { transform: translateY(-16px); }
+  100% { transform: translateY(-14px); }
+}
+.motion-spring {
+  animation: motion-spring-kf var(--dur-panel, 320ms) cubic-bezier(0.34, 1.56, 0.64, 1) infinite alternate;
+  overflow: hidden;
+}
+
+/* scroll — scroll-progress-bound entry. CSS-only fallback; real scroll-link
+ * needs JS (motion/react useScroll). */
+@keyframes motion-scroll-kf {
+  0% { transform: translateX(0); }
+  100% { transform: translateX(24px); }
+}
+.motion-scroll {
+  animation: motion-scroll-kf var(--dur-route, 480ms) var(--ease-in-out, ease-in-out) infinite alternate;
+  overflow: hidden;
+}
+
+/* drag — pick-up + release rotational settle. CSS-only fallback. */
+@keyframes motion-drag-kf {
+  0% { transform: rotate(0); }
+  50% { transform: rotate(4deg); }
+  100% { transform: rotate(0); }
+}
+.motion-drag {
+  animation: motion-drag-kf var(--dur-flip, 220ms) var(--ease-out, ease-out) infinite alternate;
+  overflow: hidden;
+}
+
+/* presence — sparkle / pulse. Demo on ≤56px elements ONLY (bounded geometry —
+ * a full-width tile pulsing scale: 0→1 will overflow adjacent rows). */
+@keyframes motion-presence-kf {
+  0% { opacity: 0; transform: scale(0.9); }
+  100% { opacity: 1; transform: scale(1); }
+}
+.motion-presence {
+  animation: motion-presence-kf var(--dur-soft, 160ms) var(--ease-out, ease-out) infinite alternate;
+  overflow: hidden;
+  /* Bounded-geometry guard — the class is intended for elements ≤56px.
+   * Sites that violate this earn a motion-critic blocker. */
+  max-width: 56px;
+  max-height: 56px;
+}
+
+/* Honor explicit data-reduced-motion toggle (specimen chrome) AND the
+ * standing OS-level prefers-reduced-motion (the token collapse already
+ * neutralises the durations; the JS-set attribute is for inspection symmetry). */
+:root[data-reduced-motion="true"] [class*="motion-"] {
+  animation: none !important;
+}

package/plugins/design/templates/design-system-inspiration/core/preview/_motion-readme.md.tpl

@@ -0,0 +1,63 @@
+# Motion specimen — author notes
+
+> A cold-reader's guide to `motion.tsx` + `motion.css`. Lives alongside the specimen so a future Claude opening this folder can answer "why is this file shaped this way?" without grepping the plan archive.
+
+## The 8 roles
+
+The canvas-lib `<MotionDemo role>` accepts a fixed 8-value union. Each role binds to a DS duration + easing token from `colors_and_type.css`:
+
+| Role | Token | Easing | Use when |
+| --- | --- | --- | --- |
+| `flip` | `--dur-flip` (~220 ms) | `--ease-out` | Press-down, hover lift, single-card flip. Smallest, snappiest. |
+| `panel` | `--dur-panel` (~320 ms) | `--ease-in-out` | Drawer, sidebar, segmented control transitions. |
+| `route` | `--dur-route` (~480 ms) | `--ease-out` | Page / route transitions. Opacity + tiny scale. |
+| `soft` | `--dur-soft` (~160 ms) | `--ease-out` | Toast, tooltip, soft fades. Fastest. |
+| `spring` | `--dur-panel` | `spring` | **Use only when the brief asks for tactile / playful / bouncy.** Springs say "Toy" by default. |
+| `scroll` | `--dur-route` | `--ease-in-out` | Scroll-progress-bound entries (parallax hint, on-scroll reveals). |
+| `drag` | `--dur-flip` | `--ease-out` | Pick-up + release rotational settle for draggables. |
+| `presence` | `--dur-soft` | `--ease-out` | The sparkle / pulse / twinkle. **Demo on 32×32 chips only.** Setting `small={true}` enforces the bounded size. |
+
+## The loop policy
+
+Every role defaults to `loop="always"` with `repeatType: 'reverse'`. **Initial paint = full motion vocabulary playing.** No hover required.
+
+Why: the studyfi imprint retro caught a hover-driven specimen that looked dead at rest. Reviewers (rightly) assumed the DS had no motion. The fix isn't more documentation; it's making the specimen self-evident at first paint.
+
+`loop="hover"` is reserved for canvases that mock real product chrome where a constant loop would be visually noisy. `loop="once"` is for one-shot reveals (rare in specimens; common in real components).
+
+## The bounded-geometry rule
+
+Every `<MotionDemo>` root has `overflow: hidden` set inline by the canvas-lib component itself. This is non-negotiable and intentionally hard to bypass.
+
+The reason: a 32×32 chip rotating 45° has a bounding box of ~45×45. A tile rotating to 45° has a bounding box of ~√2× its width and overflows adjacent rows. The studyfi imprint retro D-3 was caused by a sparkle keyframe (`scale: 0 → 1 → 0`) applied to a full-width tile — the chip itself was fine, but the chrome's `overflow: visible` let the scale ripple out of the row.
+
+If a canvas legitimately needs visible overflow (e.g. an asymmetric brand mark that bleeds intentionally), it composes outside `<MotionDemo>` — not by removing the clip.
+
+## The reduced-motion contract
+
+Two layers:
+
+1. **CSS** — `colors_and_type.css` collapses every `--dur-*` to `1ms` under `@media (prefers-reduced-motion: reduce)`. This is the canonical layer; any canvas-lib helper that reads the live token value inherits the collapse for free.
+2. **JS** — `<MotionDemo>` calls `useReducedMotion()` from `motion/react` and short-circuits the `animate` prop. Belt-and-suspenders for a hard a11y invariant; the cost is one boolean check per render.
+
+The motion specimen is the documented exception. `<ReducedMotionToggle>` flips `data-reduced-motion="true"` on `<html>` so reviewers can eyeball both branches without OS settings. **No other specimen ships this toggle.**
+
+## The handoff path
+
+Per DDR-049: a canvas that imports `<MotionDemo>` or any sibling motion helper from `@maude/canvas-lib` gets `"motion": "^11"` declared in its `registry-item.json` dependencies block at `/design:handoff` time. The motion primitives are inlined as `type: "registry:component"` entries in `files[]`; the consumer's TSX imports them from a relative path. No `@maude/canvas-lib` reference survives.
+
+`bunx shadcn add file:///path/to/canvas.registry.json` in a scratch Next.js project pulls `motion` from npm, drops the primitives inline, and the canvas animates with zero manual wiring.
+
+## Critics that watch this specimen
+
+- **`motion-critic`** — auto-routed when `motion.tsx` exists, regardless of `--opt-out=motion` scope. Validates: bounded geometry, compositor-only properties, loop policy (`infinite alternate` for "always" roles), reduced-motion handling, role-vocabulary fidelity.
+- **`design-system-completeness-critic`** — adds two Phase 3.7 checks: (1) motion specimen renders without console errors; (2) every `--dur-*` token defined in `colors_and_type.css` is referenced at least once by the motion specimen (the "orphan token" check).
+- **`design-system-keeper`** — when auditing a non-specimen canvas, greps for `@keyframes` literals that match a canvas-lib role; warns "pattern reinvention — lift `<MotionDemo role='…'>` instead". ≥3 warnings on a single canvas promotes to blocker.
+
+## Cross-links
+
+- Library source: `plugins/design/dev-server/canvas-lib.tsx` (`MotionDemo`, `MotionTrack`, `TokenPlayback`, `ReducedMotionToggle`, `useMotionTokens`, `easingFromToken`)
+- Library decision: `.ai/decisions/DDR-049-motion-one-as-canonical-motion-library.md`
+- Sub-agent safety block: `plugins/design/templates/design-system-inspiration/SUB-AGENT-PROMPTS.md` → ANIMATION SAFETY
+- Tokens: `colors_and_type.css.tpl` (lines around `--dur-*` + `--ease-*`)
+- CSS escape hatch: `_components.css.tpl` (`.motion-flip`, `.motion-panel`, ... `.motion-presence`)

package/plugins/design/templates/design-system-inspiration/core/preview/motion.css.tpl

@@ -0,0 +1,106 @@
+/* motion.css — per-specimen CSS for motion.tsx.
+ *
+ * Scoped to the motion specimen. Tile chrome + curve layout only — the
+ * actual animation keyframes/transitions are owned by canvas-lib's
+ * <MotionDemo>. This file MUST NOT redefine motion role behavior.
+ *
+ * Reduced-motion exception (DDR-049, ANIMATION SAFETY block):
+ *   This specimen is the documented exception to the @media reduced-motion
+ *   killswitch in _layout.css. We use !important here because _layout.css's
+ *   universal `animation: none !important` would kill the <MotionDemo>'s
+ *   own animate prop. Scoped to .motion-card / .motion-curve only — other
+ *   surfaces still honor OS-level reduced-motion.
+ */
+
+.motion-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: var(--space-3, 16px);
+}
+
+.motion-card {
+  background: var(--bg-1);
+  padding: var(--space-3, 20px);
+  border-radius: var(--radius-md, 6px);
+  border: 1px solid var(--border-default, currentColor);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2, 12px);
+}
+
+.motion-card__stage {
+  height: 80px;
+  background: var(--bg-2, var(--bg-1));
+  border-radius: var(--radius-sm, 4px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+}
+
+.motion-card__stage .motion-demo {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.motion-card__stage .motion-demo__chip {
+  width: 32px;
+  height: 32px;
+  background: var(--accent, currentColor);
+  border-radius: var(--radius-sm, 4px);
+}
+
+.motion-card__tokens {
+  font-family: var(--font-mono, ui-monospace, monospace);
+  font-size: var(--type-sm, 12px);
+  color: var(--fg-2, currentColor);
+}
+
+.motion-card__note {
+  font-size: var(--type-sm, 12px);
+  color: var(--fg-1, currentColor);
+}
+
+.motion-curves__row {
+  display: flex;
+  gap: var(--space-3, 16px);
+  flex-wrap: wrap;
+  align-items: flex-end;
+}
+
+.motion-curve {
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1, 6px);
+}
+
+.motion-curve figcaption {
+  font-family: var(--font-mono, ui-monospace, monospace);
+  font-size: var(--type-xs, 11px);
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.motion-curve__values {
+  color: var(--fg-2, currentColor);
+  font-variant-numeric: tabular-nums;
+}
+
+/* Reduced-motion: scoped specimen exception (see header). */
+@media (prefers-reduced-motion: reduce) {
+  .motion-card .motion-demo__target {
+    animation: none !important;
+    transition: none !important;
+  }
+}
+
+/* Specimen honors the chrome toggle for inspection symmetry. */
+:root[data-reduced-motion="true"] .motion-card .motion-demo__target {
+  animation: none !important;
+  transition: none !important;
+}