@1agh/maude 0.17.2 → 0.18.0

package/plugins/design/dev-server/runtime-bundle.ts

@@ -194,7 +194,12 @@ export async function getRuntimeBundle(pkg: RuntimePackage): Promise<BundleCache
         return `[${lvl}] ${l.message}`;
       })
       .join('\n');
-    throw new Error(`Failed to build runtime bundle for "${pkg}":\n${msg || '(no log messages)'}`);
+    const remediation = bunCacheRemediation(pkg, msg);
+    throw new Error(
+      `Failed to build runtime bundle for "${pkg}":\n${msg || '(no log messages)'}${
+        remediation ? `\n\n${remediation}` : ''
+      }`
+    );
   }
 
   const out = built.outputs[0];
@@ -206,6 +211,29 @@ export async function getRuntimeBundle(pkg: RuntimePackage): Promise<BundleCache
   return entry;
 }
 
+/**
+ * Detect the "Bun's global install cache is in a bad state" failure mode and
+ * return a one-paragraph remediation message. Returns null when the build
+ * failure has a different shape (real syntax error, missing package, etc.) —
+ * the original log is enough then.
+ *
+ * Symptoms: log messages like `EISDIR reading '/Users/foo/.bun/install/cache/
+ * react@19.2.6@@@1 @@1/index.js'` or `ENOENT … .bun/install/cache/<pkg>@…`.
+ * Surfacing the cache path + the exact `bun pm cache rm <pkg>` command saves
+ * the user from grepping the error to figure out what to do. Phase 19 / DDR-044.
+ */
+export function bunCacheRemediation(pkg: string, log: string): string | null {
+  const cacheHit = /(EISDIR|ENOENT).*\.bun\/install\/cache\/([\w@/.-]+?)(?:@@@|\/)/i.test(log);
+  if (!cacheHit) return null;
+  const basePkg = pkg.split('/')[0] ?? pkg;
+  return [
+    `  ⚠ Bun's global package cache for "${basePkg}" appears to be in a bad state`,
+    `    (truncated install, EISDIR/ENOENT on an index file).`,
+    ``,
+    `    Fix: run \`bun pm cache rm ${basePkg}\` then reload the page.`,
+  ].join('\n');
+}
+
 function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/plugins/design/dev-server/server.ts

@@ -23,6 +23,12 @@ import { createHttp } from './http.ts';
 import { createInspect } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
 import { createWs } from './ws.ts';
+import { bootSelfHeal } from './boot-self-heal.ts';
+
+// Phase 19 / DDR-044 — covers the marketplace-cache-install gap where
+// node_modules/ ships empty (git clone honors .gitignore). Auto-installs +
+// builds on first boot; opt out with MAUDE_NO_AUTOBUILD=1.
+await bootSelfHeal();
 
 const ctx = createContext();
 

package/plugins/design/dev-server/test/boot-self-heal.test.ts

@@ -0,0 +1,112 @@
+// Boot self-heal logic — Phase 19 / DDR-044.
+// Covers the marketplace-cache-install gap: if dist/ or node_modules/ is
+// missing on boot, self-heal runs bun install + build. Opt out with
+// MAUDE_NO_AUTOBUILD=1.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { bootSelfHeal, type SelfHealOptions } from '../boot-self-heal.ts';
+
+let TMP: string;
+
+beforeEach(() => {
+  TMP = mkdtempSync(join(tmpdir(), 'maude-self-heal-'));
+});
+
+afterEach(() => {
+  rmSync(TMP, { recursive: true, force: true });
+});
+
+function harness(extra: Partial<SelfHealOptions> = {}) {
+  const calls: { cmd: readonly string[]; cwd: string }[] = [];
+  const logs: string[] = [];
+  let exited: number | null = null;
+  const opts: SelfHealOptions = {
+    here: TMP,
+    optOut: false,
+    spawn: async (cmd, cwd) => {
+      calls.push({ cmd, cwd });
+      return { code: 0 };
+    },
+    log: (m) => logs.push(m),
+    exit: ((code: number) => {
+      exited = code;
+      throw new Error(`__exit:${code}`);
+    }) as never,
+    ...extra,
+  };
+  return { opts, calls, logs, getExited: () => exited };
+}
+
+function seedDist() {
+  mkdirSync(join(TMP, 'dist'), { recursive: true });
+  writeFileSync(join(TMP, 'dist', 'client.bundle.js'), '/* stub */');
+}
+
+function seedDeps() {
+  mkdirSync(join(TMP, 'node_modules', 'react'), { recursive: true });
+  writeFileSync(join(TMP, 'node_modules', 'react', 'package.json'), '{}');
+}
+
+describe('bootSelfHeal', () => {
+  test('skips when dist + node_modules both present', async () => {
+    seedDist();
+    seedDeps();
+    const { opts, calls } = harness();
+    const result = await bootSelfHeal(opts);
+    expect(result.skipped).toBe('all-present');
+    expect(result.ran).toEqual([]);
+    expect(calls).toEqual([]);
+  });
+
+  test('runs `bun install --production` when node_modules/react is missing', async () => {
+    seedDist();
+    const { opts, calls } = harness();
+    const result = await bootSelfHeal(opts);
+    expect(result.ran).toEqual(['install']);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.cmd).toEqual(['bun', 'install', '--production']);
+    expect(calls[0]?.cwd).toBe(TMP);
+  });
+
+  test('runs `bun run build.ts` when dist/client.bundle.js is missing', async () => {
+    seedDeps();
+    const { opts, calls } = harness();
+    const result = await bootSelfHeal(opts);
+    expect(result.ran).toEqual(['build']);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.cmd).toEqual(['bun', 'run', 'build.ts']);
+  });
+
+  test('runs install BEFORE build when both missing (build needs deps)', async () => {
+    const { opts, calls } = harness();
+    const result = await bootSelfHeal(opts);
+    expect(result.ran).toEqual(['install', 'build']);
+    expect(calls[0]?.cmd).toEqual(['bun', 'install', '--production']);
+    expect(calls[1]?.cmd).toEqual(['bun', 'run', 'build.ts']);
+  });
+
+  test('MAUDE_NO_AUTOBUILD=1: exits 1 with remediation message; no spawn', async () => {
+    const { opts, calls, logs, getExited } = harness({ optOut: true });
+    await expect(bootSelfHeal(opts)).rejects.toThrow('__exit:1');
+    expect(getExited()).toBe(1);
+    expect(calls).toEqual([]);
+    expect(logs.join('\n')).toMatch(/MAUDE_NO_AUTOBUILD=1/);
+    expect(logs.join('\n')).toMatch(/dist\/client\.bundle\.js/);
+    expect(logs.join('\n')).toMatch(/node_modules\/react/);
+  });
+
+  test('spawn failure aborts with exit 1 + remediation hint', async () => {
+    seedDist(); // only deps missing
+    const { opts, logs, getExited } = harness({
+      spawn: async () => ({ code: 42 }),
+    });
+    await expect(bootSelfHeal(opts)).rejects.toThrow('__exit:1');
+    expect(getExited()).toBe(1);
+    expect(logs.join('\n')).toMatch(/exited 42/);
+    expect(logs.join('\n')).toMatch(/MAUDE_NO_AUTOBUILD=1/);
+  });
+});

package/plugins/design/dev-server/test/runtime-bundle-error-mapping.test.ts

@@ -0,0 +1,43 @@
+// Phase 19 / DDR-044 — runtime-bundle error-message remediation.
+// When Bun.build fails because the global install cache is corrupted
+// (EISDIR/ENOENT on a cached package's entry file), surface an actionable
+// `bun pm cache rm <pkg>` hint instead of just relaying the raw log.
+
+import { describe, expect, test } from 'bun:test';
+
+import { bunCacheRemediation } from '../runtime-bundle.ts';
+
+describe('bunCacheRemediation', () => {
+  test('returns null on unrelated build failures (real syntax errors etc.)', () => {
+    expect(bunCacheRemediation('react', '[error] Unexpected token <')).toBeNull();
+    expect(bunCacheRemediation('react-dom', '[error] Could not resolve "missing-pkg"')).toBeNull();
+  });
+
+  test('matches EISDIR on .bun/install/cache + names the base package', () => {
+    const log =
+      "[error] EISDIR reading '/Users/iagh/.bun/install/cache/react@19.2.6@@@1 @@1/index.js'";
+    const out = bunCacheRemediation('react', log);
+    expect(out).not.toBeNull();
+    expect(out).toMatch(/bun pm cache rm react/);
+    expect(out).toMatch(/bad state/);
+  });
+
+  test('matches ENOENT on .bun/install/cache too', () => {
+    const log = "[error] ENOENT: '/Users/x/.bun/install/cache/react-dom@19.0.0/index.js'";
+    const out = bunCacheRemediation('react-dom', log);
+    expect(out).toMatch(/bun pm cache rm react-dom/);
+  });
+
+  test('subpath specifiers strip to the base package for the cache rm command', () => {
+    // bun pm cache works on base package names — "react/jsx-runtime" → "react".
+    const log = "[error] EISDIR '/Users/x/.bun/install/cache/react@19.2.6/jsx-runtime.js'";
+    const out = bunCacheRemediation('react/jsx-runtime', log);
+    expect(out).toMatch(/bun pm cache rm react\b/);
+    expect(out).not.toMatch(/bun pm cache rm react\//);
+  });
+
+  test('case-insensitive match (Bun has bounced casing across versions)', () => {
+    const log = '[error] eisdir reading /Users/x/.bun/install/cache/react@19/index.js';
+    expect(bunCacheRemediation('react', log)).not.toBeNull();
+  });
+});

package/plugins/design/templates/canvas.tsx.template

@@ -11,11 +11,11 @@
  *
  * Authored under {{DS_NAME}}. Tokens + shared component classes load via the
  * dev-server's _shell.html harness — link tags arrive automatically from the
- * iframe's ?tokens= / ?components= query. Class names match the DS's
- * `_components.css` (`.btn`, `.tile`, `.sku`, `.seg`, ...). Bespoke classes go
- * into a sibling .module.css iff `css_mode === "modules"`; for `inline` (the
- * MDCC-DSN/01 default) prefer existing classes + `style={{}}` for arbitrary
- * one-off values.
+ * iframe's ?tokens= / ?components= query. Class names come from the DS's
+ * own `_components.css` — see `system/{{DS_NAME}}/preview/` for the available
+ * class shapes. Bespoke classes go into a sibling .module.css iff
+ * `css_mode === "modules"`; for `inline` prefer existing classes + `style={{}}`
+ * for arbitrary one-off values.
  *
  * The envelope primitives (`DesignCanvas`, `DCSection`, `DCArtboard`) and any
  * specimen helpers come from the dev-server-bundled canvas library via the
@@ -40,11 +40,11 @@ export default function {{COMPONENT_NAME}}() {
     <DesignCanvas>
       <DCSection id="overview" title="{{SUBTITLE}}">
         <DCArtboard id="primary" label="A · primary" width={1280} height={800}>
-          <div className="mdcc" data-theme="{{THEME_DEFAULT}}">
+          <div className="{{ROOT_CLASS}}" data-theme="{{THEME_DEFAULT}}">
             {/* Replace this scaffold with the actual canvas content. The
                 envelope this template was rendered against is in
                 {{HISTORY_DIR}}/000-envelope.md. */}
-            <h1 className="sku">{{NAME}}</h1>
+            <h1>{{NAME}}</h1>
             <p>{{BRIEF}}</p>
           </div>
         </DCArtboard>

package/plugins/design/templates/design-system-inspiration/audience-pro/colors-presence.html

@@ -4,7 +4,7 @@ DEMONSTRATES: --presence-online, --presence-away, --presence-offline; presence d
 COMPOSITION: 4 avatars with presence dots (online / away / offline / idle) + a "live cursors" mockup with 3 simultaneous users
 COPY VOICE: real names, real timestamps
 WHEN SCAFFOLDED: presence family (IF "presence" ∈ activeFamilies — typically pro tools with multiplayer)
-NOTES: Presence dot is 8px circle bottom-right of 32-40px avatars (anchor on the visual bottom-right, not on a math grid). Cursor labels are subtle (pill at 11px, low opacity bg). Don't blink presence — too noisy in a busy view.
+NOTES: Presence dot is 8px circle bottom-right of 32-40px avatars (anchor on the visual bottom-right, not on a math grid). Per-user cursor colors below are illustrative only — the inline `oklch(...)` values are NOT part of the project's design system. A real implementation should source these from a `--presence-user-*` family or derive from `--accent` deterministically. Cursor labels are subtle (pill at 11px, low opacity bg). Don't blink presence — too noisy in a busy view.
 -->
 <!doctype html>
 <html lang="en">

package/plugins/design/templates/design-system-inspiration/core/README.philosophy.md.tpl

@@ -19,13 +19,15 @@
 
 ## Foundations
 
-### One-accent rule
+### Token contract
 
-Exactly one accent family lives in `colors_and_type.css`: `--accent`, `--accent-hover`, `--accent-active`, `--accent-fg`. **No `--accent2`.** Calls-to-attention compete with each other; one accent forces hierarchy decisions at design time, not runtime.
+All visuals reference `var(--*)` tokens declared in `colors_and_type.css`. Adding a new visual concept means **extending the tokens CSS first**, never inventing values inline in a canvas.
 
-### Token contract
+{{color_space_block}}
+
+### Accent strategy
 
-All visuals reference `var(--*)` tokens declared in `colors_and_type.css`. No hardcoded hex / px / rem in canvases or production code. Adding a new visual concept means **extending the tokens CSS first**, never inventing values inline.
+{{accent_rules_block}}
 
 ### Active token families
 
@@ -33,8 +35,9 @@ All visuals reference `var(--*)` tokens declared in `colors_and_type.css`. No ha
 
 ## Hard rules (non-negotiable)
 
-- **Accessibility:** WCAG 2.1 AA contrast at every theme. Focus-visible always rendered. Touch targets ≥ 44×44. `prefers-reduced-motion: reduce` respected.
-- **No off-token colors / radii / spacings** in canvases. Extend tokens; don't inline.
+- **Accessibility:** WCAG 2.1 AA contrast at every theme. Focus-visible always rendered. `prefers-reduced-motion: reduce` respected.
+- **Touch targets:** {{touch_target_rule}}
+- **No off-token values** in canvases. Extend tokens; don't inline.
 - **No placeholder copy.** Real product strings only — no "Lorem Solutions Inc.", no "Click here".
 - **Type ladder:** {{type_scale_summary}}
 - **Motion:** every animation uses a `var(--dur-*)` and `var(--ease-*)` token. No magic numbers.
@@ -52,7 +55,8 @@ All visuals reference `var(--*)` tokens declared in `colors_and_type.css`. No ha
 ## Hard-stops the completeness-critic enforces
 
 - Core tokens present (`--accent`, `--bg-0..4`, `--fg-0..3`, `--dur-flip`)
-- Exactly one accent family
+- Accent family count matches the declared strategy ({{accent_strategy_summary}})
+- Color space matches the declared choice ({{color_space_summary}})
 - `system/{{ds_dirname}}/preview/` populated with at least 8 specimens
 - `colors_and_type.css` linked from every specimen
 - `prefers-reduced-motion: reduce` guard present in tokens CSS

package/plugins/design/templates/design-system-inspiration/core/SKILL.md.tpl

@@ -24,8 +24,9 @@ It is **not** auto-invoked by `/design:edit` or `/design:new` on a project with
 
 ## What the agent should remember
 
-- **One accent.** No `--accent2`. Calls-to-attention compete; one accent forces hierarchy decisions.
-- **All visuals reference `var(--*)` tokens.** No hardcoded hex / px / rem in canvases.
+- **Accent strategy:** {{accent_strategy_summary}}. {{accent_rules_summary}}
+- **All visuals reference `var(--*)` tokens.** No off-token values in canvases.
+- **Color space:** {{color_space_summary}}.
 - **Voice:** {{voice_tone_summary}}
 - **Iconography:** {{iconography_summary}}
 - **Theme default:** `{{theme_default}}`. {{theme_extra}}
@@ -47,4 +48,4 @@ It is **not** auto-invoked by `/design:edit` or `/design:new` on a project with
 
 ## How to extend
 
-If a canvas iteration needs a value not currently in the system, **extend `colors_and_type.css` first**. Adding a new variant of an existing token (e.g. `--accent-tertiary`) is fine; adding a parallel accent family (e.g. `--accent2`) violates the one-accent rule and the completeness-critic will block.
+If a canvas iteration needs a value not currently in the system, **extend `colors_and_type.css` first**. Adding a new variant of an existing token (e.g. `--accent-tertiary`) is fine. Adding a parallel accent family (e.g. `--accent2`) is only allowed if the project's declared `accentStrategy` in `config.json` permits it (e.g. `paired` or `chromatic-N`) — the completeness-critic enforces the declared strategy.

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

@@ -4,55 +4,59 @@
  * Authoritative token file. Every canvas in <designRoot>/ui/ links to this.
  * Production code should consume the same values (compiled to TS/JS or kept as CSS vars).
  *
- * Contract:
- * - OKLCH for accent + status colors (better gamut control than HSL/hex)
- * - One accent family only (no --accent2)
- * - Theme: {{theme_default}} (single-block) — duplicate for both-equal projects
- * - Motion durations + easings + reduced-motion guard
- * - 8-step type ladder, 4px-base spacing scale
+ * This file is the single source of truth for the project's visual language.
+ * Every concrete value below is supplied by the discovery payload — there are
+ * NO universal defaults baked into this template. Spacing, type, easing,
+ * shadows, max-width, accent strategy, and color space are all project-flavored.
+ *
+ * Two invariants this template does enforce:
+ *   1. `prefers-reduced-motion: reduce` collapses every duration to 1ms (a11y).
+ *   2. Tokens used by canvases live under one of the documented family prefixes
+ *      (--bg-*, --fg-*, --accent*, --border-*, --status-*, --space-*, --type-*,
+ *      --lh-*, --radius-*, --shadow-*, --dur-*, --ease-*, --layout-*, --font-*).
+ *
+ * Everything else — palette structure, type ladder, motion personality — is
+ * a project decision recorded during /design:setup-ds.
  */
 
 :root,
 .{{root_class}}[data-theme="{{theme_default}}"] {
   /* ─── Surfaces (deepest → highest) ─────────────────────────────────── */
-  --bg-0: {{bg_0_oklch}};   /* page bg                    */
-  --bg-1: {{bg_1_oklch}};   /* card / panel bg            */
-  --bg-2: {{bg_2_oklch}};   /* nested panel / popover     */
-  --bg-3: {{bg_3_oklch}};   /* input bg / subtle row hover */
-  --bg-4: {{bg_4_oklch}};   /* hover / pressed state      */
+  --bg-0: {{bg_0}};   /* page bg                    */
+  --bg-1: {{bg_1}};   /* card / panel bg            */
+  --bg-2: {{bg_2}};   /* nested panel / popover     */
+  --bg-3: {{bg_3}};   /* input bg / subtle row hover */
+  --bg-4: {{bg_4}};   /* hover / pressed state      */
 
   /* ─── Borders ──────────────────────────────────────────────────────── */
-  --border-subtle:  oklch(from var(--bg-1) calc(l + 0.04) c h);
-  --border-default: oklch(from var(--bg-1) calc(l + 0.08) c h);
-  --border-strong:  oklch(from var(--bg-1) calc(l + 0.14) c h);
+  --border-subtle:  {{border_subtle}};
+  --border-default: {{border_default}};
+  --border-strong:  {{border_strong}};
 
   /* ─── Text ─────────────────────────────────────────────────────────── */
-  --fg-0: {{fg_0_oklch}};   /* primary text                */
-  --fg-1: {{fg_1_oklch}};   /* secondary text              */
-  --fg-2: {{fg_2_oklch}};   /* tertiary / muted            */
-  --fg-3: {{fg_3_oklch}};   /* disabled                    */
+  --fg-0: {{fg_0}};   /* primary text                */
+  --fg-1: {{fg_1}};   /* secondary text              */
+  --fg-2: {{fg_2}};   /* tertiary / muted            */
+  --fg-3: {{fg_3}};   /* disabled                    */
 
-  /* ─── Accent (ONE family only) ─────────────────────────────────────── */
-  --accent:        {{accent_oklch}};
-  --accent-hover:  oklch(from var(--accent) calc(l - 0.04) c h);
-  --accent-active: oklch(from var(--accent) calc(l - 0.08) c h);
-  --accent-fg:     {{accent_fg_oklch}};
+  /* ─── Accent ({{accent_strategy_summary}}) ─────────────────────────── */
+{{accent_block}}
 
   /* ─── Status (only if "status" ∈ activeFamilies) ───────────────────── */
-  --status-success: oklch(70% 0.18 145);
-  --status-warn:    oklch(78% 0.16  85);
-  --status-error:   oklch(64% 0.21  25);
-  --status-info:    oklch(70% 0.13 230);
+  --status-success: {{status_success}};
+  --status-warn:    {{status_warn}};
+  --status-error:   {{status_error}};
+  --status-info:    {{status_info}};
 
   /* ─── Presence (only if "presence" ∈ activeFamilies) ───────────────── */
-  --presence-online:  var(--status-success);
-  --presence-away:    var(--status-warn);
-  --presence-offline: var(--fg-3);
+  --presence-online:  {{presence_online}};
+  --presence-away:    {{presence_away}};
+  --presence-offline: {{presence_offline}};
 
   /* ─── Shadows / elevation ──────────────────────────────────────────── */
-  --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.20);
-  --shadow-md: 0 4px 12px oklch(0 0 0 / 0.25);
-  --shadow-lg: 0 12px 32px oklch(0 0 0 / 0.30);
+  --shadow-sm: {{shadow_sm}};
+  --shadow-md: {{shadow_md}};
+  --shadow-lg: {{shadow_lg}};
 
   /* ─── Radii ────────────────────────────────────────────────────────── */
   --radius-xs: {{radius_xs}};
@@ -60,45 +64,45 @@
   --radius-md: {{radius_md}};
   --radius-lg: {{radius_lg}};
   --radius-xl: {{radius_xl}};
-  --radius-pill: 999px;
+  --radius-pill: {{radius_pill}};
 
-  /* ─── Spacing (4px base) ───────────────────────────────────────────── */
-  --space-0:  0;
-  --space-1:  4px;
-  --space-2:  8px;
-  --space-3: 12px;
-  --space-4: 16px;
-  --space-5: 24px;
-  --space-6: 32px;
-  --space-7: 48px;
-  --space-8: 64px;
+  /* ─── Spacing ──────────────────────────────────────────────────────── */
+  --space-0: {{space_0}};
+  --space-1: {{space_1}};
+  --space-2: {{space_2}};
+  --space-3: {{space_3}};
+  --space-4: {{space_4}};
+  --space-5: {{space_5}};
+  --space-6: {{space_6}};
+  --space-7: {{space_7}};
+  --space-8: {{space_8}};
 
   /* ─── Typography ───────────────────────────────────────────────────── */
   --font-display: {{font_display}};
   --font-body:    {{font_body}};
   --font-mono:    {{font_mono}};
 
-  /* 8-step type scale */
-  --type-xs:   12px;  --lh-xs:   16px;
-  --type-sm:   13px;  --lh-sm:   18px;
-  --type-base: 14px;  --lh-base: 20px;
-  --type-md:   16px;  --lh-md:   22px;
-  --type-lg:   18px;  --lh-lg:   26px;
-  --type-xl:   22px;  --lh-xl:   30px;
-  --type-2xl:  28px;  --lh-2xl:  36px;
-  --type-3xl:  36px;  --lh-3xl:  44px;
+  /* Type scale */
+  --type-xs:   {{type_xs}};    --lh-xs:   {{lh_xs}};
+  --type-sm:   {{type_sm}};    --lh-sm:   {{lh_sm}};
+  --type-base: {{type_base}};  --lh-base: {{lh_base}};
+  --type-md:   {{type_md}};    --lh-md:   {{lh_md}};
+  --type-lg:   {{type_lg}};    --lh-lg:   {{lh_lg}};
+  --type-xl:   {{type_xl}};    --lh-xl:   {{lh_xl}};
+  --type-2xl:  {{type_2xl}};   --lh-2xl:  {{lh_2xl}};
+  --type-3xl:  {{type_3xl}};   --lh-3xl:  {{lh_3xl}};
 
   /* ─── Motion ───────────────────────────────────────────────────────── */
   --dur-flip:  {{dur_flip}};
   --dur-panel: {{dur_panel}};
   --dur-route: {{dur_route}};
   --dur-soft:  {{dur_soft}};
-  --ease-out:    cubic-bezier(0.22, 1, 0.36, 1);
-  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+  --ease-out:    {{ease_out_curve}};
+  --ease-in-out: {{ease_in_out_curve}};
 
   /* ─── Layout ───────────────────────────────────────────────────────── */
-  --layout-max-w: 1200px;
-  --layout-gutter: var(--space-4);
+  --layout-max-w:  {{layout_max_w}};
+  --layout-gutter: {{layout_gutter}};
 }
 
 @media (prefers-reduced-motion: reduce) {

package/plugins/design/templates/design-system-inspiration/core/config.json.tpl

@@ -17,6 +17,8 @@
   "extensions": [],
   "completenessProfile": "standard",
   "activeFamilies": {{active_families}},
+  "accentStrategy": "{{accent_strategy}}",
+  "colorSpace": "{{color_space}}",
   "designSystems": [
     {
       "name": "{{ds_dirname}}",

package/plugins/design/templates/design-system-inspiration/core/preview/colors-accent.html

@@ -1,10 +1,10 @@
 <!--
 SPECIMEN: colors-accent
 DEMONSTRATES: --accent, --accent-hover, --accent-active, --accent-fg
-COMPOSITION: 4-state swatch grid + contextual button + link sample, demonstrating one-accent rule
+COMPOSITION: 4-state swatch grid + contextual button + link sample, demonstrating the project's accent strategy
 COPY VOICE: action verbs ("Save", "Confirm", "Continue") — never "Click here" / "Get Started"
 WHEN SCAFFOLDED: always (Core)
-NOTES: This is THE place to demonstrate one-accent rule. The card should NOT show any --accent2 variant. accent-fg must clear WCAG AA against the accent background.
+NOTES: Demonstrates the project's declared `accentStrategy` from config.json. For `single` (default) the card shows one accent family; for `paired` or `chromatic-N` the card should be extended to show every family. accent-fg must clear WCAG AA against the accent background.
 -->
 <!doctype html>
 <html lang="en">
@@ -17,7 +17,7 @@ NOTES: This is THE place to demonstrate one-accent rule. The card should NOT sho
 <body class="app" data-theme="dark">
   <main class="specimen">
     <h1>Accent</h1>
-    <p class="lede">One accent family — four states. The one-accent rule means: when something needs attention, the answer is always this color, never a competing second hue. Sub-states cover hover, active, and the readable foreground that sits on top of it.</p>
+    <p class="lede">Accent family — four states (idle / hover / active / foreground). The project's `accentStrategy` declaration in <code>config.json</code> controls how many families exist; this specimen renders one. Extend it horizontally for `paired` or `chromatic-N` projects so every declared family appears side-by-side.</p>
 
     <div class="grid">
       <div class="swatch"><div class="chip" style="background: var(--accent);"></div><div class="meta"><strong>--accent</strong>Idle</div></div>
@@ -41,7 +41,7 @@ NOTES: This is THE place to demonstrate one-accent rule. The card should NOT sho
     </div>
 
     <footer class="legend">
-      <p>The one-accent rule: no <code>--accent2</code>. Calls-to-attention should compete with each other through hierarchy and size, not through parallel hues.</p>
+      <p>Accent count follows <code>config.accentStrategy</code>. For `single` projects, calls-to-attention compete through hierarchy and size rather than parallel hues. For `paired` / `chromatic-N` projects, each declared family takes its own semantic role (e.g. <code>--accent</code> = primary action, <code>--accent-2</code> = exploratory). The completeness-critic gates the family count against the declared strategy.</p>
     </footer>
   </main>
 </body>

package/plugins/design/templates/design-system-inspiration/meta/presence-multiplayer.html

@@ -4,7 +4,7 @@ DEMONSTRATES: forward-pointer to v1.x multiplayer features — live cursors with
 COMPOSITION: full mockup of a shared canvas with 3 cursors + awareness rail + typing indicator
 COPY VOICE: real names, real "X is editing" strings
 WHEN SCAFFOLDED: meta + presence family (typically v1.1+ projects with Yjs)
-NOTES: This is a forward-pointer specimen showing what the multiplayer UX looks like once Phase 8 (Yjs LAN) lands. The cursor color is per-user (hashed from user ID into an OKLCH band). Don't blink cursors — too noisy.
+NOTES: This is a forward-pointer specimen showing what the multiplayer UX looks like once Phase 8 (Yjs LAN) lands. Per-user cursor colors are illustrative only — the inline `oklch(...)` values below are NOT part of the project's design system. A real implementation should source per-user colors from a `--presence-user-*` family (token-driven) or derive from `--accent` via a deterministic hash on user ID. Don't blink cursors — too noisy.
 -->
 <!doctype html>
 <html lang="en">

package/plugins/design/templates/design-system-inspiration/platform-desktop/ui_kits-desktop-showcase.html

@@ -132,6 +132,9 @@ NOTES:
         </div>
         <div class="spacer"></div>
         <input class="search" type="search" placeholder="search… (⌘ K)" />
+        <!-- Per-team accent picker. The inline `oklch(...)` values below are illustrative only — a real per-tenant
+             implementation should source team accents from a `--accent-team-*` family or compute analogous hues
+             from `--accent`. Don't hardcode tenant brand colors in the design system. -->
         <div class="accent-picker" role="group" aria-label="Accent">
           <button class="accent-swatch is-on" data-team="default" style="background: var(--accent);" aria-label="default"></button>
           <button class="accent-swatch" data-team="cyan" style="background: oklch(72% 0.16 220);" aria-label="cyan"></button>

package/plugins/design/templates/design-system-inspiration/platform-mobile/ui_kits-mobile-showcase.html

@@ -22,7 +22,7 @@ NOTES:
   <link rel="stylesheet" href="../core/colors_and_type.css" />
   <link rel="stylesheet" href="../core/preview/_layout.css" />
   <style>
-    body { padding: 0; margin: 0; background: oklch(8% 0.005 60); display: grid; place-items: start center; min-height: 100vh; }
+    body { padding: 0; margin: 0; background: var(--bg-0); display: grid; place-items: start center; min-height: 100vh; }
     .specimen { max-width: none; margin: 0; padding: var(--space-5) 0; }
 
     .artboard {

package/plugins/design/templates/design-system-inspiration/theme-both/colors-themes-side-by-side.html

@@ -28,7 +28,7 @@ NOTES: Both themes use the SAME tokens (--bg-0..4 etc.); only their OKLCH values
     <p class="lede">The exact same UI rendered in both themes. Tokens carry the difference; the HTML structure is identical. If a component renders differently across themes (beyond color), that's a token-resolution bug, not a per-theme design.</p>
 
     <div class="grid" style="grid-template-columns: 1fr 1fr; gap: 16px;">
-      <div class="pane app" data-theme="dark" style="background: oklch(16% 0.012 245); color: oklch(96% 0.008 245);">
+      <div class="pane app" data-theme="dark" style="background: var(--bg-0); color: var(--fg-0);">
         <h2 style="margin: 0 0 16px;">Dark</h2>
         <div class="card">
           <h3>Match recap</h3>
@@ -40,20 +40,20 @@ NOTES: Both themes use the SAME tokens (--bg-0..4 etc.); only their OKLCH values
         </div>
       </div>
 
-      <div class="pane app" data-theme="light" style="background: oklch(98% 0.005 245); color: oklch(20% 0.012 245);">
+      <div class="pane app" data-theme="light" style="background: var(--bg-0); color: var(--fg-0);">
         <h2 style="margin: 0 0 16px;">Light</h2>
-        <div class="card" style="background: oklch(95% 0.005 245); border-color: oklch(82% 0.010 245);">
+        <div class="card">
           <h3>Match recap</h3>
-          <p class="meta" style="color: oklch(48% 0.012 245);">vs. Sparta U17 · 3-1</p>
+          <p class="meta">vs. Sparta U17 · 3-1</p>
           <div class="row" style="gap: 8px;">
             <button class="btn-primary">View</button>
-            <button class="btn-secondary" style="background: oklch(91% 0.005 245); color: oklch(20% 0.012 245); border-color: oklch(78% 0.010 245);">Share</button>
+            <button class="btn-secondary">Share</button>
           </div>
         </div>
       </div>
     </div>
 
-    <footer class="legend"><p>Inline OKLCH values here are just for the specimen; real projects swap them via <code>[data-theme="light"]</code> selectors in <code>colors_and_type.css</code>. The cascade carries every component without per-component theme overrides.</p></footer>
+    <footer class="legend"><p>Both panes use the same <code>var(--*)</code> tokens; only the <code>data-theme</code> attribute changes. Real projects define both themes inside <code>colors_and_type.css</code> via <code>[data-theme="dark"]</code> and <code>[data-theme="light"]</code> selectors. The cascade carries every component without per-component theme overrides.</p></footer>
   </main>
 </body>
 </html>

package/plugins/design/templates/design-system-inspiration/universal/components-dialogs.html

@@ -15,7 +15,8 @@ NOTES: Modal blocks the page; sheet slides from edge; alert is for irreversible
   <link rel="stylesheet" href="../core/preview/_layout.css" />
   <style>
     .dialog-frame { background: var(--bg-0); border: 1px solid var(--border-subtle); border-radius: var(--radius-lg); padding: var(--space-4); margin-bottom: 24px; position: relative; overflow: hidden; min-height: 220px; }
-    .dialog-frame .veil { position: absolute; inset: 0; background: rgba(0,0,0,0.4); }
+    /* Veil opacity is a base value, not a token (per foundations/opacity.html). Color-space-agnostic. */
+    .dialog-frame .veil { position: absolute; inset: 0; background: color-mix(in srgb, black 40%, transparent); }
     .dialog { background: var(--bg-1); border: 1px solid var(--border-default); border-radius: var(--radius-lg); box-shadow: var(--shadow-lg); padding: var(--space-5); width: 360px; position: relative; }
     .dialog .title { font-family: var(--font-display); font-size: var(--type-lg); font-weight: 600; line-height: var(--lh-lg); margin: 0 0 8px; }
     .dialog .body  { color: var(--fg-1); margin: 0 0 var(--space-4); }
@@ -48,7 +49,7 @@ NOTES: Modal blocks the page; sheet slides from edge; alert is for irreversible
 
     <h2>Sheet</h2>
     <div class="dialog-frame">
-      <div class="veil" style="background: rgba(0,0,0,0.25);"></div>
+      <div class="veil" style="background: color-mix(in srgb, black 25%, transparent);"></div>
       <aside class="dialog dialog-sheet" role="dialog" aria-labelledby="sheet-t">
         <p class="title" id="sheet-t">Player details</p>
         <p class="body">#9 · Forward · Captain</p>

package/plugins/design/templates/design-system-inspiration/universal/logo.html

@@ -19,7 +19,8 @@ NOTES:
   <style>
     body { padding: 24px; display: flex; gap: 20px; align-items: center; flex-wrap: wrap; }
     .frame { padding: 18px 22px; border: 1px solid var(--border-subtle); border-radius: var(--radius-lg); background: var(--bg-1); }
-    .light { background: #ffffff; }
+    /* `.light` frame shows the mark on the opposite-theme surface — sourced from the project's tokens, not hardcoded white. */
+    .light { background: var(--bg-0-light, var(--bg-0)); }
     .label { font-family: var(--font-mono); font-size: 11px; font-weight: 500; color: var(--fg-2); text-transform: uppercase; letter-spacing: 0.04em; margin-top: 10px; display: block; }
   </style>
 </head>