@xmesh/system-design 0.0.1

package/styles/_semantic.css

@@ -0,0 +1,146 @@
+/* ============================================================
+   xmesh DS · _semantic.css — LEGACY ALIAS LAYER.
+
+   This file used to define `--c-*` role tokens directly. After the
+   MD3 migration, every `--c-*` token is a one-line alias of either
+   a canonical `--md-sys-*` token or an `--xm-*` extension. Components
+   should reference `--md-sys-*` / `--xm-*` directly; the aliases
+   below remain only so unmigrated components keep working during the
+   per-component rollout (Phase 7).
+
+   This file deletes in Phase 10 once every component has migrated.
+   ============================================================ */
+
+/* ---------- Surfaces ---------- */
+:root {
+  --c-canvas:        var(--md-sys-color-surface);
+  --c-canvas-deep:   var(--md-sys-color-surface-container-lowest);
+  --c-canvas-raised: var(--md-sys-color-surface-container-low);
+  --c-card:          var(--md-sys-color-inverse-surface);
+  --c-card-soft:     var(--md-sys-color-surface-container-high);
+  --c-input:         var(--md-sys-color-inverse-surface);
+  --c-overlay:       oklch(0 0 0 / 0.5);
+  --c-paper:         var(--xm-color-paper);
+
+  --c-photo-overlay:     var(--xm-photo-overlay);
+  --c-photo-overlay-ink: var(--xm-photo-overlay-ink);
+
+  --c-sidebar-hover:  var(--md-sys-color-surface-container-lowest);
+  --c-sidebar-active: var(--md-sys-color-surface-container-lowest);
+
+  --c-bubble-user: var(--md-sys-color-surface-container-lowest);
+  --c-bubble-bot:  var(--md-sys-color-surface-container-low);
+
+  --c-composer-surface:       var(--md-sys-color-surface-container-high);
+  --c-composer-surface-hi:    var(--md-sys-color-surface-container);
+  --c-composer-border:        var(--md-sys-color-outline);
+  --c-composer-border-active: var(--md-sys-color-outline);
+}
+
+:root[data-theme="light"] {
+  --c-card:          var(--md-sys-color-inverse-surface);
+  --c-card-soft:     var(--md-sys-color-surface-container);
+  --c-input:         var(--md-sys-color-inverse-surface);
+
+  --c-sidebar-hover:  var(--md-sys-color-surface-container);
+  --c-sidebar-active: var(--md-sys-color-surface-container-high);
+
+  --c-bubble-user:    var(--md-sys-color-surface-container-high);
+  --c-bubble-bot:     var(--md-sys-color-inverse-surface);
+
+  --c-composer-surface:       var(--md-sys-color-inverse-surface);
+  --c-composer-surface-hi:    var(--md-sys-color-surface-container-low);
+  --c-composer-border:        var(--md-sys-color-outline-variant);
+  --c-composer-border-active: var(--md-sys-color-outline-variant);
+}
+
+/* ---------- Borders ---------- */
+:root {
+  --c-border:        var(--md-sys-color-outline-variant);
+  --c-border-strong: var(--md-sys-color-outline);
+  --c-border-subtle: var(--md-sys-color-outline-variant);
+  --c-border-canvas: var(--md-sys-color-outline);
+  --c-border-bubble: var(--xm-color-bubble-outline);
+  --c-border-focus:  var(--md-sys-color-primary);
+}
+
+/* ---------- Text ---------- */
+:root {
+  --c-text:           var(--md-sys-color-inverse-on-surface);
+  --c-text-body:      var(--md-sys-color-inverse-on-surface);
+  --c-text-muted:     var(--xm-color-inverse-on-surface-muted);
+  --c-text-hint:      var(--xm-color-inverse-on-surface-muted);
+
+  --c-text-canvas:        var(--md-sys-color-on-surface);
+  --c-text-canvas-strong: var(--md-sys-color-on-surface);
+  --c-text-canvas-muted:  var(--md-sys-color-on-surface-variant);
+  --c-text-canvas-soft:   var(--xm-color-on-surface-soft);
+
+  --c-text-on-bubble-user: var(--md-sys-color-on-surface);
+}
+
+/* ---------- Accent / brand ---------- */
+:root {
+  --c-accent:          var(--md-sys-color-primary);
+  --c-accent-strong:   var(--xm-color-primary-pressed);
+  --c-accent-soft:     var(--md-sys-color-primary-container);
+  --c-accent-ink:      var(--md-sys-color-on-primary);
+  --c-accent-on:       var(--md-sys-color-on-primary);
+  --c-accent-disabled: var(--md-sys-color-surface-container-high);
+
+  --c-primary:          var(--md-sys-color-primary);
+  --c-primary-strong:   var(--xm-color-primary-pressed);
+  --c-primary-soft:     var(--md-sys-color-primary-container);
+  --c-primary-ink:      var(--md-sys-color-on-primary);
+  --c-primary-disabled: var(--md-sys-color-surface-container-high);
+
+  --c-secondary:        var(--md-sys-color-secondary);
+  --c-secondary-strong: var(--md-sys-color-secondary);
+  --c-secondary-soft:   var(--md-sys-color-secondary-container);
+  --c-secondary-ink:    var(--md-sys-color-on-secondary);
+}
+
+/* ---------- Snackbar overlay scrim ---------- */
+:root {
+  --c-snk-overlay-strong: var(--xm-snackbar-scrim-strong);
+  --c-snk-overlay:        var(--xm-snackbar-scrim);
+  --c-snk-overlay-soft:   var(--xm-snackbar-scrim-soft);
+}
+
+/* ---------- Badge groups: HTTP methods + file extensions ---------- */
+:root {
+  --c-method-get-bg:    var(--xm-method-get-bg);    --c-method-get-ink:    var(--xm-method-get-ink);
+  --c-method-post-bg:   var(--xm-method-post-bg);   --c-method-post-ink:   var(--xm-method-post-ink);
+  --c-method-put-bg:    var(--xm-method-put-bg);    --c-method-put-ink:    var(--xm-method-put-ink);
+  --c-method-delete-bg: var(--xm-method-delete-bg); --c-method-delete-ink: var(--xm-method-delete-ink);
+  --c-method-patch-bg:  var(--xm-method-patch-bg);  --c-method-patch-ink:  var(--xm-method-patch-ink);
+
+  --c-ext-yml-bg:  var(--xm-ext-yml-bg);  --c-ext-yml-ink:  var(--xm-ext-yml-ink);
+  --c-ext-json-bg: var(--xm-ext-json-bg); --c-ext-json-ink: var(--xm-ext-json-ink);
+}
+
+/* ---------- Documentation-only scales ----------
+   Kept so the colors preview can render canvas + surface ramps
+   without referencing primitives directly. Removed in Phase 8 when
+   colors.html is rewritten to teach the MD3 vocabulary instead. */
+:root {
+  --c-canvas-0: var(--x-canvas-0);
+  --c-canvas-1: var(--x-canvas-1);
+  --c-canvas-2: var(--x-canvas-2);
+  --c-canvas-3: var(--x-canvas-3);
+  --c-canvas-4: var(--x-canvas-4);
+  --c-canvas-5: var(--x-canvas-5);
+  --c-canvas-6: var(--x-canvas-6);
+  --c-canvas-7: var(--x-canvas-7);
+  --c-canvas-8: var(--x-canvas-8);
+
+  --c-surface-0: var(--x-surface-0);
+  --c-surface-1: var(--x-surface-1);
+  --c-surface-2: var(--x-surface-2);
+  --c-surface-3: var(--x-surface-3);
+  --c-surface-4: var(--x-surface-4);
+  --c-surface-5: var(--x-surface-5);
+  --c-surface-6: var(--x-surface-6);
+  --c-surface-7: var(--x-surface-7);
+  --c-surface-8: var(--x-surface-8);
+}

package/styles/_space.css

@@ -0,0 +1,61 @@
+/* ============================================================
+   xmesh DS · _space.css — radii, spacing, motion (alias layer).
+
+   Radii alias `--md-sys-shape-corner-*`; motion aliases
+   `--md-sys-motion-*`. Spacing tokens (`--s-N`) stay primitive — MD3
+   has no canonical spacing scale, and the 4px-base xmesh ladder is
+   the system primitive that components reference directly.
+
+   Naming: `--s-N` = N×4px (the 4px ladder). `--s-N-5` = N×4+2px (the 2px
+   optical grid — half-steps for dense chrome). Every spacing value in a
+   component must come from this ladder; `scripts/check-spacing.mjs` enforces
+   it (see docs/adr/0003). Genuine sub-grid exceptions (1px hairlines, button
+   tight-chrome, documented clearance paddings) live in
+   scripts/spacing-allowlist.json, not here.
+   ============================================================ */
+
+/* ---------- Radii (alias to MD3 shape corners) ---------- */
+:root {
+  --r-pill:     var(--md-sys-shape-corner-full);
+  --r-composer: var(--md-sys-shape-corner-extra-large);
+  --r-bubble:   var(--md-sys-shape-corner-large);
+  --r-card:     var(--md-sys-shape-corner-medium);
+  --r-field:    var(--md-sys-shape-corner-button);
+  --r-btn:      var(--md-sys-shape-corner-button);
+  --r-chip:     var(--md-sys-shape-corner-small);
+  --r-icon:     var(--md-sys-shape-corner-extra-small);
+}
+
+/* ---------- Spacing — 4px base + 2px half-steps (xmesh primitive scale) ---------- */
+:root {
+  /* 4px ladder — --s-N = N×4px */
+  --s-1:   4px;
+  --s-2:   8px;
+  --s-3:  12px;
+  --s-4:  16px;
+  --s-5:  20px;
+  --s-6:  24px;
+  --s-7:  28px;
+  --s-8:  32px;
+  --s-9:  36px;
+  --s-10: 40px;
+  --s-11: 44px;
+  --s-12: 48px;
+
+  /* 2px half-steps — --s-N-5 = N×4+2px (the optical grid for dense chrome) */
+  --s-0-5:  2px;
+  --s-1-5:  6px;
+  --s-2-5: 10px;
+  --s-3-5: 14px;
+  --s-4-5: 18px;
+  --s-5-5: 22px;
+}
+
+/* ---------- Motion (alias to MD3 motion tokens) ---------- */
+:root {
+  --m-fast:     var(--md-sys-motion-duration-short3);
+  --m-base:     var(--md-sys-motion-duration-short4);
+  --m-slow:     var(--md-sys-motion-duration-medium1);
+  --m-ease:     var(--md-sys-motion-easing-standard);
+  --m-ease-out: var(--md-sys-motion-easing-emphasized-decelerate);
+}

package/styles/_type.css

@@ -0,0 +1,139 @@
+/* ============================================================
+   xmesh DS · _type.css — type role shorthands + helper classes.
+
+   The actual MD3 typescale lives in `md3/_type.css`. This file
+   composes the MD3 sub-tokens into `font:`-shorthand role aliases
+   (`--t-h1`, `--t-body`, …) and renders the `.x-*` helper classes
+   that previews use. The shorthands let component CSS write
+   `font: var(--t-body);` in one line — there's no MD3 equivalent,
+   so the composition lives here.
+
+   Family + raw-size tokens stay defined for the few callsites that
+   reference them directly; component CSS should prefer the role
+   shorthands or the MD3 sub-tokens.
+   ============================================================ */
+
+/* ---------- Families, weights, raw scale ---------- */
+:root {
+  --t-family-display: "Source Serif 4", "Newsreader", "Cormorant Garamond", "EB Garamond", "Tiempos Headline", Georgia, serif;
+  --t-family-ui:      "Inter",  -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  --t-family-mono:    "JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace;
+
+  --t-weight-regular:  400;
+  --t-weight-medium:   500;
+  --t-weight-semibold: 600;
+  --t-weight-bold:     700;
+
+  --t-size-xs:   11px;
+  --t-size-sm:   12px;
+  --t-size-base: 13px;
+  --t-size-md:   15px;
+  --t-size-lg:   16px;
+  --t-size-xl:   18px;
+  --t-size-2xl:  18px;
+  --t-size-3xl:  22px;
+  --t-size-4xl:  28px;
+  --t-size-5xl:  34px;
+
+  --t-leading-tight:  1.2;
+  --t-leading-snug:   1.35;
+  --t-leading-normal: 1.5;
+  --t-leading-loose:  1.7;
+
+  --t-tracking-tight:  -0.02em;
+  --t-tracking-snug:   -0.01em;
+  --t-tracking-normal: 0;
+  --t-tracking-wide:   0.04em;
+
+  --t-features: "ss01", "cv11";
+}
+
+/* ---------- Role shorthand — composes MD3 typescale sub-tokens ----------
+   `font:` order is `weight size/line-height family`. Each role binds to
+   the matching MD3 role (display-small, body-large, etc.) so the values
+   flow from md3/_type.css. */
+:root {
+  --t-h1:
+    var(--md-sys-typescale-display-small-weight)
+    var(--md-sys-typescale-display-small-size) /
+    var(--md-sys-typescale-display-small-line-height)
+    var(--md-sys-typescale-display-small-font);
+
+  --t-h2:
+    var(--md-sys-typescale-headline-large-weight)
+    var(--md-sys-typescale-headline-large-size) /
+    var(--md-sys-typescale-headline-large-line-height)
+    var(--md-sys-typescale-headline-large-font);
+
+  --t-h3:
+    var(--md-sys-typescale-headline-medium-weight)
+    var(--md-sys-typescale-headline-medium-size) /
+    var(--md-sys-typescale-headline-medium-line-height)
+    var(--md-sys-typescale-headline-medium-font);
+
+  --t-h4:
+    var(--md-sys-typescale-title-large-weight)
+    var(--md-sys-typescale-title-large-size) /
+    var(--md-sys-typescale-title-large-line-height)
+    var(--md-sys-typescale-title-large-font);
+
+  --t-display:
+    var(--md-sys-typescale-headline-medium-weight)
+    var(--md-sys-typescale-headline-medium-size) /
+    var(--md-sys-typescale-headline-medium-line-height)
+    var(--md-sys-typescale-headline-medium-font);
+
+  --t-wordmark:
+    var(--xm-typescale-wordmark-weight)
+    var(--xm-typescale-wordmark-size) /
+    var(--xm-typescale-wordmark-line-height)
+    var(--xm-typescale-wordmark-font);
+
+  --t-eyebrow:
+    var(--md-sys-typescale-label-small-weight)
+    var(--md-sys-typescale-label-small-size) /
+    var(--md-sys-typescale-label-small-line-height)
+    var(--md-sys-typescale-label-small-font);
+
+  --t-body:
+    var(--md-sys-typescale-body-large-weight)
+    var(--md-sys-typescale-body-large-size) /
+    var(--md-sys-typescale-body-large-line-height)
+    var(--md-sys-typescale-body-large-font);
+
+  --t-body-strong:
+    var(--md-sys-typescale-title-medium-weight)
+    var(--md-sys-typescale-body-large-size) /
+    var(--md-sys-typescale-body-large-line-height)
+    var(--md-sys-typescale-body-large-font);
+
+  --t-small:
+    var(--md-sys-typescale-body-small-weight)
+    var(--md-sys-typescale-body-small-size) /
+    var(--md-sys-typescale-body-small-line-height)
+    var(--md-sys-typescale-body-small-font);
+
+  --t-button:
+    var(--md-sys-typescale-label-large-weight)
+    var(--md-sys-typescale-label-large-size) /
+    var(--md-sys-typescale-label-large-line-height)
+    var(--md-sys-typescale-label-large-font);
+
+  --t-mono:
+    var(--xm-typescale-mono-weight)
+    var(--xm-typescale-mono-size) /
+    var(--xm-typescale-mono-line-height)
+    var(--xm-typescale-mono-font);
+}
+
+/* ---------- Helper classes ---------- */
+.x-h1       { font: var(--t-h1);       color: var(--c-text);       letter-spacing: var(--t-tracking-tight); margin: 0; }
+.x-h2       { font: var(--t-h2);       color: var(--c-text);       letter-spacing: var(--t-tracking-tight); margin: 0; }
+.x-h3       { font: var(--t-h3);       color: var(--c-text);       letter-spacing: var(--t-tracking-snug);  margin: 0; }
+.x-h4       { font: var(--t-h4);       color: var(--c-text);       letter-spacing: var(--t-tracking-snug);  margin: 0; }
+.x-display  { font: var(--t-display);  color: var(--c-text);       letter-spacing: var(--t-tracking-snug);  margin: 0; }
+.x-wordmark { font: var(--t-wordmark); color: var(--c-text);       letter-spacing: var(--t-tracking-snug);  margin: 0; }
+.x-body    { font: var(--t-body);    color: var(--c-text-body);  margin: 0; }
+.x-small   { font: var(--t-small);   color: var(--c-text-muted); margin: 0; }
+.x-eyebrow { font: var(--t-eyebrow); color: var(--c-text-muted); text-transform: uppercase; letter-spacing: var(--t-tracking-wide); margin: 0; }
+.x-mono    { font: var(--t-mono);    color: var(--c-text-body); }

package/styles/_xmesh-extensions.css

@@ -0,0 +1,232 @@
+/* ============================================================
+   xmesh DS · _xmesh-extensions.css — non-MD3 tokens.
+
+   Anything that has no canonical MD3 home but is needed to keep
+   xmesh's voice intact lives here under the `--xm-*` namespace.
+   Components may reference these alongside `--md-sys-*` tokens.
+   ============================================================ */
+
+:root {
+  /* Categorical badges — HTTP method + file extension.
+     These signal *category*, not severity. Not an MD3 concept. */
+  --xm-method-get-bg:    oklch(0.32 0.08 220);
+  --xm-method-get-ink:   oklch(0.86 0.10 220);
+  --xm-method-post-bg:   oklch(0.32 0.08 145);
+  --xm-method-post-ink:  oklch(0.86 0.10 145);
+  --xm-method-put-bg:    oklch(0.32 0.08 70);
+  --xm-method-put-ink:   oklch(0.86 0.10 70);
+  --xm-method-delete-bg: oklch(0.32 0.10 25);
+  --xm-method-delete-ink: oklch(0.86 0.12 25);
+  --xm-method-patch-bg:  oklch(0.32 0.07 290);
+  --xm-method-patch-ink: oklch(0.86 0.10 290);
+
+  --xm-ext-yml-bg:  oklch(0.32 0.08 70);
+  --xm-ext-yml-ink: oklch(0.86 0.10 70);
+  --xm-ext-json-bg: oklch(0.32 0.08 145);
+  --xm-ext-json-ink: oklch(0.86 0.12 145);
+
+  /* Snackbar scrim — neutral gradient, not an MD3 concept. */
+  --xm-snackbar-scrim-strong: oklch(0 0 0 / 0.42);
+  --xm-snackbar-scrim:        oklch(0 0 0 / 0.32);
+  --xm-snackbar-scrim-soft:   oklch(0 0 0 / 0.18);
+
+  /* Alert severity palette — categorical exception to the "no hue for
+     severity" rule. The original rule (POLICIES.md 3a) assumed icon +
+     copy alone could carry severity, but inline alerts also need to be
+     scannable at a glance in long content surfaces, so we tint the bg /
+     border / ink per severity. Hues align with --xm-method-* (blue 220
+     / green 145 / amber 70 / red 25) so the categorical palettes stay
+     coherent. Chroma stays low so the surface still reads as chrome,
+     not as content. Dark-theme values use a dim, desaturated tint;
+     light-theme values use a pale wash on the cream canvas. */
+  --xm-alert-info-bg:     oklch(0.27 0.05 235);
+  --xm-alert-info-border: oklch(0.42 0.08 235);
+  --xm-alert-info-ink:    oklch(0.92 0.06 235);
+  --xm-alert-info-chip:   oklch(0.42 0.10 235);
+
+  --xm-alert-success-bg:     oklch(0.27 0.05 150);
+  --xm-alert-success-border: oklch(0.42 0.08 150);
+  --xm-alert-success-ink:    oklch(0.92 0.08 150);
+  --xm-alert-success-chip:   oklch(0.42 0.10 150);
+
+  --xm-alert-warning-bg:     oklch(0.28 0.06 75);
+  --xm-alert-warning-border: oklch(0.46 0.10 75);
+  --xm-alert-warning-ink:    oklch(0.94 0.10 90);
+  --xm-alert-warning-chip:   oklch(0.46 0.12 75);
+
+  --xm-alert-critical-bg:     oklch(0.28 0.07 25);
+  --xm-alert-critical-border: oklch(0.48 0.13 25);
+  --xm-alert-critical-ink:    oklch(0.94 0.08 30);
+  --xm-alert-critical-chip:   oklch(0.48 0.16 25);
+
+  /* Photo overlay (image artifact backdrop) */
+  --xm-photo-overlay:     oklch(0 0 0 / 0.5);
+  --xm-photo-overlay-ink: var(--x-ink-canvas-0);
+
+  /* Paper artboard — warm cream sheet for previews */
+  --xm-color-paper: var(--x-paper);
+
+  /* On-surface fourth tier — MD3 only ships on-surface + variant.
+     xmesh's old --c-text-canvas-soft (very faint metadata) lives
+     here as the third soft tier. */
+  --xm-color-on-surface-soft: var(--x-ink-canvas-3);
+
+  /* Inverse on-surface third tier (muted metadata on the card stack).
+     The card stack is theme-following (ADR 0006): in dark theme the card
+     is dark, so this muted tier is a LIGHT ink; light theme keeps the
+     dark muted ink (overridden in the light block below). */
+  --xm-color-inverse-on-surface-muted: var(--x-ink-canvas-2);
+
+  /* Pressed-primary tint — MD3 prescribes a state-layer overlay,
+     but a few callsites need a specific darker primary value. */
+  --xm-color-primary-pressed: var(--x-accent-strong);
+
+  /* Primary FILL — the resting coral background for filled CTAs.
+     --md-sys-color-primary (L~0.64) doubles as accent *text* on the dark
+     canvas, where it must stay light enough to read; as a button *fill*
+     behind white ink that same tone only reaches 3.5:1. This token splits
+     the fill role off at a darker tone so white-on-fill clears WCAG AA
+     (5.1:1) without darkening accent-as-text. AA-validated by
+     scripts/check-contrast.mjs. */
+  --xm-color-primary-fill: oklch(0.55 0.115 40);
+
+  /* Disabled inks — MD3 has no disabled-text role; it prescribes an opacity
+     overlay, which dims ink AND surface together and crushes contrast below
+     AA (the foot-gun these replace). These are pre-darkened/lightened so the
+     disabled label still clears 4.5:1 on its host family. Components set
+     `color:` to one of these instead of `opacity:` on the whole control.
+       *-on-surface-disabled         → on the dark canvas / surface family
+       *-inverse-on-surface-disabled → on the card stack (inverse-surface);
+          a light dimmed ink in dark theme (dark card), dark in light. */
+  --xm-color-on-surface-disabled:         oklch(0.66 0.01 60);
+  --xm-color-inverse-on-surface-disabled: oklch(0.72 0.01 60);
+
+  /* Disabled filled-container fill — for filled controls (primary button,
+     filled chips) so the whole element no longer gets dimmed by opacity.
+     A muted neutral the disabled ink above is validated against (canvas-1
+     gives the on-surface-disabled ink ~5.1:1 of headroom). */
+  --xm-state-disabled-container: var(--x-canvas-1);
+
+  /* Bubble border — outline-variant doesn't quite read on the
+     bubble surface; this is a slightly stronger hairline. */
+  --xm-color-bubble-outline: oklch(0.34 0.006 60);
+
+  /* Mono typescale — JetBrains Mono. Not an MD3 concept. */
+  --xm-typescale-mono-font:        var(--t-family-mono);
+  --xm-typescale-mono-size:        13px;
+  --xm-typescale-mono-line-height: 1.5;
+  --xm-typescale-mono-tracking:    0;
+  --xm-typescale-mono-weight:      400;
+
+  /* Wordmark — display family at button size, weight 500, lh 1 */
+  --xm-typescale-wordmark-font:        var(--t-family-display);
+  --xm-typescale-wordmark-size:        18px;
+  --xm-typescale-wordmark-line-height: 1;
+  --xm-typescale-wordmark-tracking:    -0.01em;
+  --xm-typescale-wordmark-weight:      500;
+
+  /* Drawer directional shadow — has no MD3 home (MD3 elevation
+     levels are non-directional). */
+  --xm-elevation-drawer: -16px 0 40px oklch(0 0 0 / 0.35);
+
+  /* Snackbar inner highlight rim + composite shadow */
+  --xm-elevation-snackbar:
+    0 1px 0 oklch(1 0 0 / 0.04) inset,
+    0 18px 40px oklch(0 0 0 / 0.32),
+    0 4px 10px oklch(0 0 0 / 0.18);
+
+  /* Pressed inset (button :active feel — kept as canonical xmesh) */
+  --xm-elevation-pressed:      inset 0 1px 0 oklch(0 0 0 / 0.10);
+  --xm-elevation-pressed-soft: inset 0 1px 0 oklch(0 0 0 / 0.08);
+
+  /* Focus ring — MD3 doesn't standardise the box-shadow form */
+  --xm-state-focus-ring: 0 0 0 3px var(--md-sys-color-primary-container);
+
+  /* Switch (xm-switch) — MD3 ships no switch role tokens, so the off-track fill
+     and the thumb shadow live here (AD-10). On-track is the coral primary role;
+     the off-track is a muted neutral that reads on the inverse-surface card and
+     gives the (dark, off-state) thumb something to sit on. The thumb itself
+     uses MD3 roles directly: outline ink when off (on the off-track), on-primary
+     when on (on the coral track). */
+  --xm-switch-track-off:    var(--x-surface-5);
+  --xm-switch-thumb-shadow: 0 1px 2px oklch(0 0 0 / 0.3);
+
+  /* Slider (xm-slider) — MD3 ships no slider role tokens. The active fill +
+     thumb are the coral primary role; these are the sub-values with no MD3 home
+     (AD-10): the inactive (unfilled) track color, plus the track height and
+     thumb size geometry. The slider rides the inverse-surface card tier, so the
+     inactive track is a muted neutral that reads on the card. */
+  --xm-slider-track-inactive: var(--x-surface-5);
+  --xm-slider-track-height:   4px;
+  --xm-slider-thumb-size:     16px;
+  --xm-slider-thumb-shadow:   0 1px 2px oklch(0 0 0 / 0.3);
+
+  /* Overlay stacking tier (AD-5a) — fixed order, not open-order luck:
+     tooltip < menu/select-listbox < dialog. The native top layer already
+     gives last-opened-wins within one primitive class; these z-index values
+     order the NON-modal popovers among themselves (a menu sits above a
+     tooltip). Modal <dialog>s ride the native top layer above every popover
+     by spec, which matches `dialog` being the highest tier. A Floating-UI-
+     positioned escape-hatch overlay reuses these values — it must NOT invent
+     its own z-index. */
+  --xm-overlay-z-tooltip: 1000;
+  --xm-overlay-z-menu:    1100;
+  --xm-overlay-z-dialog:  1200;
+}
+
+:root[data-theme="light"] {
+  /* Categorical badges in cream theme */
+  --xm-method-get-bg:    oklch(0.94 0.07 220); --xm-method-get-ink:    oklch(0.36 0.10 220);
+  --xm-method-post-bg:   oklch(0.94 0.07 145); --xm-method-post-ink:   oklch(0.36 0.10 145);
+  --xm-method-put-bg:    oklch(0.94 0.07 70);  --xm-method-put-ink:    oklch(0.36 0.10 70);
+  --xm-method-delete-bg: oklch(0.94 0.07 25);  --xm-method-delete-ink: oklch(0.40 0.12 25);
+  --xm-method-patch-bg:  oklch(0.94 0.06 290); --xm-method-patch-ink:  oklch(0.38 0.10 290);
+
+  --xm-ext-yml-bg:  oklch(0.92 0.08 70);  --xm-ext-yml-ink:  oklch(0.40 0.10 70);
+  --xm-ext-json-bg: oklch(0.92 0.08 145); --xm-ext-json-ink: oklch(0.38 0.12 145);
+
+  --xm-snackbar-scrim-strong: oklch(0.40 0.01 60 / 0.28);
+  --xm-snackbar-scrim:        oklch(0.40 0.01 60 / 0.18);
+  --xm-snackbar-scrim-soft:   oklch(0.40 0.01 60 / 0.08);
+
+  /* Alert palette — cream-theme washes. Backgrounds sit slightly
+     above the cream canvas; ink is the deep version of the hue so it
+     reads on the pale tint. */
+  --xm-alert-info-bg:     oklch(0.94 0.04 235);
+  --xm-alert-info-border: oklch(0.82 0.07 235);
+  --xm-alert-info-ink:    oklch(0.34 0.10 235);
+  --xm-alert-info-chip:   oklch(0.78 0.08 235);
+
+  --xm-alert-success-bg:     oklch(0.94 0.05 150);
+  --xm-alert-success-border: oklch(0.80 0.09 150);
+  --xm-alert-success-ink:    oklch(0.34 0.10 150);
+  --xm-alert-success-chip:   oklch(0.78 0.10 150);
+
+  --xm-alert-warning-bg:     oklch(0.95 0.06 85);
+  --xm-alert-warning-border: oklch(0.80 0.10 75);
+  --xm-alert-warning-ink:    oklch(0.36 0.10 60);
+  --xm-alert-warning-chip:   oklch(0.78 0.12 75);
+
+  --xm-alert-critical-bg:     oklch(0.95 0.04 25);
+  --xm-alert-critical-border: oklch(0.80 0.10 25);
+  --xm-alert-critical-ink:    oklch(0.38 0.14 25);
+  --xm-alert-critical-chip:   oklch(0.78 0.13 25);
+
+  --xm-photo-overlay:     oklch(1 0 0 / 0.7);
+  --xm-photo-overlay-ink: oklch(0.22 0.01 60);
+
+  --xm-color-bubble-outline: oklch(0.86 0.014 85);
+
+  /* Card stack stays white in light theme — muted metadata is a dark ink. */
+  --xm-color-inverse-on-surface-muted: var(--x-ink-3);
+
+  /* Primary fill — light theme accent is already deep (L0.62); the fill role
+     drops to the strong tone so white ink clears AA on the cream canvas. */
+  --xm-color-primary-fill: oklch(0.50 0.115 38);
+
+  /* Disabled inks — dark ink on the cream canvas / white card. */
+  --xm-color-on-surface-disabled:         oklch(0.45 0.01 60);
+  --xm-color-inverse-on-surface-disabled: oklch(0.46 0.01 60);
+
+  --xm-state-disabled-container: var(--x-canvas-3);
+}

package/styles/index.css

@@ -0,0 +1,44 @@
+/* ============================================================
+   xmesh Design System — index.css
+
+   Single entry point. Components reference `--md-sys-*` (canonical
+   Material Design 3 system tokens) and `--xm-*` (xmesh extensions
+   for non-MD3 concepts). `--x-*` are primitives — never reference
+   from components.
+
+   Import order matters: MD3 layer must load before the legacy
+   `_semantic.css` alias layer (which maps `--c-*` → `--md-sys-*`
+   for back-compat during the migration).
+
+   Layered files, by responsibility:
+     _fonts.css                 Google Fonts import
+     _primitives.css            raw `--x-*` literals (palette source)
+     md3/_color.css             `--md-sys-color-*` roles
+     md3/_type.css              `--md-sys-typescale-*` roles
+     md3/_shape.css             `--md-sys-shape-corner-*` tokens
+     md3/_elevation.css         `--md-sys-elevation-level*` tokens
+     md3/_motion.css            `--md-sys-motion-*` tokens
+     md3/_state.css             `--md-sys-state-*` opacities
+     _xmesh-extensions.css      `--xm-*` non-MD3 tokens
+     _layout.css                `--xm-breakpoint-*` / `--xm-container-max` / `--xm-gutter-*`
+     _semantic.css              legacy `--c-*` aliases (deletes in Phase 10)
+     _type.css                  type role shorthands + .x-* helpers
+     _space.css                 `--r-*` / `--s-N` / `--m-*` aliases
+     _elevation.css             `--e-*` aliases
+     _scroll.css                `.scroll-canvas` / `.scroll-hidden`
+   ============================================================ */
+@import url("./_fonts.css");
+@import url("./_primitives.css");
+@import url("./md3/_color.css");
+@import url("./md3/_type.css");
+@import url("./md3/_shape.css");
+@import url("./md3/_elevation.css");
+@import url("./md3/_motion.css");
+@import url("./md3/_state.css");
+@import url("./_xmesh-extensions.css");
+@import url("./_layout.css");
+@import url("./_semantic.css");
+@import url("./_type.css");
+@import url("./_space.css");
+@import url("./_elevation.css");
+@import url("./_scroll.css");