@astryxdesign/theme-neutral 0.5.2 → 0.5.3

package/src/neutralTheme.ts

@@ -1,66 +1,75 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/**
- * Neutral Theme
- *
- * A pure grayscale spine with a from-scratch OKLCH-derived categorical
- * palette. Hues are placed at evenly-spaced positions on the OKLCH wheel,
- * chosen to keep each color recognizable at every tone (no red drift for
- * orange, no blue drift for purple) and well-separated from its neighbors.
- *
- * Core neutral palette: #fafafa, #f5f5f5, #e5e5e5, #737373, #262626, #0a0a0a
- *
- * Categorical hues (OKLCH; chroma = max-in-gamut at the saturated stop):
- *   Red H=25    Orange H=65    Yellow H=90    Green H=145
- *   Teal H=180  Cyan H=215     Blue H=250     Purple H=320  Pink H=355
- *
- * Saturated badge stops:
- *   • Cool/medium hues sit at OKLCH L=0.48–0.50 with white text (AA+)
- *   • Bright warm hues (orange L=0.68, yellow L=0.80) use dark text
- *
- * Token tonal stops:
- *   bg     = T90 (light) / T20 (dark)
- *   border = T80         / T30
- *   icon   = T30         / T80
- *   text   = T30         / T80
- *
- * All 9 saturated badge values pass WCAG AA against their label (>= 4.5:1);
- * `scripts/check-badge-contrast.test.mjs` holds every theme to that.
- *
- * Only overrides tokens that differ from the defaults.
- */
-
-import {defineTheme, defineSyntaxTheme} from '@astryxdesign/core/theme';
+import {
+  defineTheme,
+  defineSyntaxTheme,
+  type TokenValue,
+} from '@astryxdesign/core/theme';
 import {neutralIconRegistry} from './icons';
+import {neutralPaletteRefs} from './neutralPaletteRefs.generated';
+
+const {blue, cyan, green, neutral, orange, pink, purple, red, teal, yellow} =
+  neutralPaletteRefs;
+const withAlpha = (color: string, alpha: string) => `${color}${alpha}`;
 
-/**
- * Neutral syntax palette — pulled from the OKLCH T30 (light) / T80 (dark)
- * stops of the categorical ramps. Same colors used by --color-icon-* tokens.
- */
 const neutralSyntax = defineSyntaxTheme({
-  name: 'xds-neutral',
+  name: 'astryx-neutral',
   tokens: {
-    keyword: ['#700084', '#efa8ff'], // purple T30/T80
-    string: ['#005600', '#a6d2a2'], // green (sat T30 / pastel T80)
-    comment: ['#737373', '#a3a3a3'], // neutral
-    number: ['#6e3500', '#ffb37f'], // orange
-    function: ['#00458c', '#a0caff'], // blue T30/T80 H=255
-    type: ['#700084', '#efa8ff'], // purple
-    variable: ['#171717', '#e5e5e5'], // near-black / near-white
-    operator: ['#737373', '#a3a3a3'], // neutral
-    constant: ['#6e3500', '#ffb37f'], // orange
-    tag: ['#89001a', '#ffaeaa'], // red
-    attribute: ['#584400', '#eec12f'], // yellow
-    property: ['#005348', '#83dac9'], // teal
-    // #a3a3a3/#525252 (this pair's own disabled-text tone) failed WCAG AA
-    // against the syntax background: 2.42:1 light, 2.53:1 dark. #5386.
-    punctuation: ['#6e6e6e', '#a0a0a0'], // neutral, 4.89:1 / 7.57:1
-    background: ['#fafafa', '#0a0a0a'],
+    keyword: [purple.light[30], purple.light[80]],
+    string: [green.light[30], green.light[80]],
+    comment: [neutral.light[45], neutral.dark[65]],
+    number: [orange.light[30], orange.dark[80]],
+    function: [blue.light[30], blue.dark[80]],
+    type: [purple.light[30], purple.light[80]],
+    variable: [neutral.light[5], neutral.dark[90]],
+    operator: [neutral.light[45], neutral.dark[65]],
+    constant: [orange.light[30], orange.dark[80]],
+    tag: [red.light[30], red.dark[80]],
+    attribute: [yellow.light[30], yellow.light[80]],
+    property: [teal.light[30], teal.light[80]],
+    punctuation: [neutral.light[45], neutral.dark[65]],
+    background: [neutral.light[100], neutral.dark[5]],
   },
 });
 
+const neutralLocalTokens: Record<string, TokenValue> = {
+  '--astryx-theme-neutral-color-status-fill-accent': ['#0074e2', '#6d9cfe'],
+  '--astryx-theme-neutral-color-status-fill-success': ['#198100', '#64af4c'],
+  '--astryx-theme-neutral-color-status-fill-warning': '#ffce2f',
+  '--astryx-theme-neutral-color-status-fill-error': ['#c9303a', '#ff705d'],
+  '--astryx-theme-neutral-color-status-muted-accent': [
+    blue.light[85],
+    withAlpha(blue.dark[75], '3D'),
+  ],
+  '--astryx-theme-neutral-color-on-tint-neutral': ['#fafafa4D', '#0a0a0a4D'],
+  '--astryx-theme-neutral-color-on-tint-overlay-hover': [
+    '#fafafa1A',
+    '#0a0a0a1A',
+  ],
+  '--astryx-theme-neutral-color-on-tint-overlay-pressed': [
+    '#fafafa33',
+    '#0a0a0a33',
+  ],
+  '--astryx-theme-neutral-color-destructive-overlay-hover': [
+    withAlpha(red.light[70], '0D'),
+    withAlpha(red.dark[65], '0D'),
+  ],
+  '--astryx-theme-neutral-color-destructive-overlay-pressed': [
+    withAlpha(red.light[70], '1A'),
+    withAlpha(red.dark[65], '1A'),
+  ],
+};
+
+const statusFill = {
+  accent: 'var(--astryx-theme-neutral-color-status-fill-accent)',
+  success: 'var(--astryx-theme-neutral-color-status-fill-success)',
+  warning: 'var(--astryx-theme-neutral-color-status-fill-warning)',
+  error: 'var(--astryx-theme-neutral-color-status-fill-error)',
+} as const;
+
 export const neutralTheme = defineTheme({
   name: 'neutral',
+  localTokens: neutralLocalTokens,
 
   // Typography: Figtree across body, heading, and display sizes (display
   // size tokens inherit from heading.family). Monospace stays as the
@@ -94,235 +103,124 @@ export const neutralTheme = defineTheme({
   syntax: neutralSyntax,
 
   tokens: {
-    // =========================================================================
-    // Core — pure grayscale spine (Tailwind neutral)
-    // 50:#fafafa 100:#f5f5f5 200:#e5e5e5 300:#d4d4d4 400:#a3a3a3
-    // 500:#737373 600:#525252 700:#404040 800:#262626 900:#171717 950:#0a0a0a
-    // =========================================================================
-
-    // =========================================================================
-    // Backgrounds — Figma-style flat with a single lifted surface.
-    //
-    // Dark mode collapses card / popover / muted to body T10. Cards and
-    // popovers lift purely via shadow + inset highlight (see --shadow-*
-    // below) — they don't need a distinct tone.
-    //
-    // Surface is the exception: it's tonally LIGHTER than body (T15) so
-    // interactive components that sit on top of body have a clear,
-    // differentiated foreground. Real consumers of --color-background-surface
-    // are: switches, radios, checkboxes, multi-selectors, dialogs, app
-    // shells, sections — all things that need to lift above the canvas.
-    //
-    //   surface  T15 #262626  — interactive surfaces lifted above body
-    //   body     T10 #1b1b1b  — main canvas
-    //   card     T10 #1b1b1b  — same as body, lifts via --shadow-low
-    //   popover  T10 #1b1b1b  — same as body, lifts via --shadow-med
-    //   muted    T10 #1b1b1b  — same as body
-    //
-    // Light mode keeps the standard ladder (white surfaces float on tinted
-    // body; shadows do most of the lifting):
-    //   surface  T100 #ffffff
-    //   body     T95  #f1f1f1
-    //   card     T100 #ffffff
-    //   popover  T100 #ffffff
-    //   muted    T95  #f1f1f1
-    //
-    // All values use the OKLCH Neutral tonal palette (chroma=0).
-    // =========================================================================
-    '--color-background-surface': ['#ffffff', '#262626'],
-    '--color-background-body': ['#f1f1f1', '#1b1b1b'],
-    '--color-background-card': ['#ffffff', '#1b1b1b'],
-    '--color-background-popover': ['#ffffff', '#1b1b1b'],
-    '--color-background-muted': ['#f1f1f1', '#1b1b1b'],
-
-    // Accent + neutral surface tints (sit alongside backgrounds)
-    '--color-accent': ['#262626', '#ebebeb'],
-    '--color-accent-muted': ['#f1f1f1', '#262626'],
-    '--color-neutral': ['#0000000F', '#FFFFFF1A'],
+    '--color-background-surface': [neutral.light[100], neutral.dark[15]],
+    '--color-background-body': [neutral.light[95], neutral.dark[10]],
+    '--color-background-card': [neutral.light[100], neutral.dark[10]],
+    '--color-background-popover': [neutral.light[100], neutral.dark[10]],
+    '--color-background-muted': [neutral.light[95], neutral.dark[10]],
+
+    '--color-accent': [neutral.light[15], neutral.dark[95]],
+    '--color-accent-muted': [neutral.light[95], neutral.dark[15]],
+    '--color-neutral': [
+      withAlpha(neutral.light[0], '0F'),
+      withAlpha(neutral.dark[100], '1A'),
+    ],
 
     // Overlays (modal scrims, hover/pressed tints)
-    '--color-overlay': ['#00000080', '#000000CC'],
-    '--color-overlay-hover': ['#0000000D', '#FFFFFF0D'],
-    '--color-overlay-pressed': ['#0000001A', '#FFFFFF1A'],
+    '--color-overlay': [
+      withAlpha(neutral.light[0], '80'),
+      withAlpha(neutral.dark[0], 'CC'),
+    ],
+    '--color-overlay-hover': [
+      withAlpha(neutral.light[0], '0D'),
+      withAlpha(neutral.dark[100], '0D'),
+    ],
+    '--color-overlay-pressed': [
+      withAlpha(neutral.light[0], '1A'),
+      withAlpha(neutral.dark[100], '1A'),
+    ],
 
     // Text
-    '--color-text-primary': ['#171717', '#fafafa'],
-    // Light secondary is neutral-600 (#525252), not 500 (#737373): 500 only
-    // reaches 4.19:1 on the T95 body (#f1f1f1), just under WCAG AA 4.5:1.
-    // 600 clears it (6.9:1 on body, 7.8:1 on card). Dark stays neutral-400.
-    '--color-text-secondary': ['#525252', '#a3a3a3'],
-    '--color-text-disabled': ['#a3a3a3', '#525252'],
-    '--color-text-accent': ['#262626', '#ebebeb'],
-    '--color-on-dark': '#ffffff',
-    '--color-on-light': '#171717',
-    // Contrast: neutral accent is near-black (L) / near-white (D)
-    '--color-on-accent': ['#ffffff', '#171717'],
-    '--color-on-success': ['#ffffff', '#171717'],
-    '--color-on-error': ['#ffffff', '#171717'],
-    '--color-on-warning': '#171717',
+    '--color-text-primary': [neutral.light[5], neutral.dark[100]],
+    '--color-text-secondary': [neutral.light[35], neutral.dark[65]],
+    '--color-text-disabled': [neutral.light[65], neutral.dark[35]],
+    '--color-text-accent': [neutral.light[15], neutral.dark[95]],
+    '--color-on-dark': neutral.light[100],
+    '--color-on-light': neutral.light[5],
+    '--color-on-accent': [neutral.light[100], neutral.dark[5]],
+    '--color-on-success': [neutral.light[100], neutral.dark[5]],
+    '--color-on-error': [neutral.light[100], neutral.dark[5]],
+    '--color-on-warning': neutral.light[5],
 
     // Icon
-    '--color-icon-accent': ['#262626', '#ebebeb'],
-    '--color-icon-primary': ['#171717', '#fafafa'],
-    '--color-icon-secondary': ['#737373', '#a3a3a3'],
-    '--color-icon-disabled': ['#a3a3a3', '#525252'],
-
-    // Status / Sentiment — dark mode follows the issue #2150 rubric:
-    //
-    //   Light mode: pastel T90 banner bg + dark T30/T40 text/icon. Locked
-    //               light values for cards/banners/inputs/destructive btn.
-    //   Dark mode : tinted-dark T20 bg + light pastel T80 text. INVERTED
-    //               from light. Avoids the §5 "pastel-in-both-modes"
-    //               anti-pattern (locked pastels glow against a dark body).
-    //
-    //   --color-X         = "saturated text/icon stop":
-    //                         light = T40 dark colored (sits on light pastel)
-    //                         dark  = T80 light pastel  (sits on dark tinted bg)
-    //                       Used by destructive button text, input border/icon
-    //                       (in light), banner-status-* text overrides.
-    //   --color-X-muted   = "muted bg stop":
-    //                         light = T90 light pastel
-    //                         dark  = hue-tinted alpha overlay (T70 stop @ 24%)
-    //                       Used by banner bg, status-input message bg,
-    //                       destructive button bg. Dark mode uses an alpha
-    //                       overlay rather than a solid T20 tinted bg so
-    //                       the surface composes onto whatever sits behind
-    //                       it (body, card, popover) rather than reading
-    //                       as a hard colored panel.
-    //
-    //   24% alpha = '3D' suffix. Hue values match --color-icon-{X} dark
-    //   slots (palette T70). Composited onto body #1b1b1b, the effective
-    //   bg luminance hits ~1.65-1.70:1 vs body — visible colored surface
-    //   without the heaviness of a solid T20 panel.
-    '--color-success': ['#007004', '#9fe59b'],
-    '--color-error': ['#a50c25', '#ffc6c1'],
-    '--color-warning': ['#745b00', '#fdcf4f'],
-    '--color-success-muted': ['#c5e5c0', '#84c9803D'],
-    '--color-error-muted': ['#facecb', '#ff9e973D'],
-    '--color-warning-muted': ['#f8da9d', '#deb4333D'],
-
-    // Border
-    '--color-border': ['#00000014', '#FFFFFF1A'],
-    '--color-border-emphasized': ['#d4d4d4', '#525252'],
+    '--color-icon-accent': [neutral.light[15], neutral.dark[95]],
+    '--color-icon-primary': [neutral.light[5], neutral.dark[100]],
+    '--color-icon-secondary': [neutral.light[50], neutral.dark[65]],
+    '--color-icon-disabled': [neutral.light[65], neutral.dark[35]],
+
+    '--color-success': [green.light[40], green.light[80]],
+    '--color-error': [red.light[35], red.dark[85]],
+    '--color-warning': [yellow.light[40], yellow.light[85]],
+    '--color-success-muted': [green.dark[85], withAlpha(green.light[75], '3D')],
+    '--color-error-muted': [red.light[85], withAlpha(red.dark[75], '3D')],
+    '--color-warning-muted': [
+      yellow.dark[90],
+      withAlpha(yellow.light[75], '3D'),
+    ],
+
+    '--color-border': [
+      withAlpha(neutral.light[0], '14'),
+      withAlpha(neutral.dark[100], '1A'),
+    ],
+    '--color-border-emphasized': [neutral.light[85], neutral.dark[35]],
 
     // Effects
-    '--color-skeleton': ['#ebebeb', '#525252'],
-    '--color-shadow': ['#0000001A', '#0000004D'],
+    '--color-skeleton': [neutral.light[95], neutral.dark[35]],
+    '--color-shadow': [
+      withAlpha(neutral.light[0], '1A'),
+      withAlpha(neutral.dark[0], '4D'),
+    ],
     '--color-tint-hover': ['black', 'white'],
 
-    // =========================================================================
-    // Categorical — light mode uses pastel surfaces + dark colored text;
-    //               dark mode INVERTS to a hue-tinted alpha overlay surface +
-    //               light pastel text (per #2150 rubric §3 — pick the tone
-    //               that satisfies required contrast against every surface
-    //               the token touches).
-    //
-    // Per-token tone choice (CIELab L*):
-    //   bg     light=T87-T90 pastel       dark=T70 hue @ 24% alpha overlay
-    //                                       (composites onto body to ~1.65:1
-    //                                        vs body — colored surface that
-    //                                        feels lighter than a solid T20
-    //                                        panel; same hue as --color-icon-X
-    //                                        dark slot, just at lower opacity)
-    //   border light=T80 pastel           dark=T60 mid-bright (>=5.8:1 vs body)
-    //   icon   light=T30 dark colored     dark=T70 light pastel
-    //   text   light=T30 dark colored     dark=T80 light pastel (>=7:1 on bg)
-    //
-    // Light pastels still use the per-hue chroma table (red/blue C=0.05,
-    // orange/green/purple/pink C=0.06, teal/cyan C=0.07, yellow H=85 C=0.10)
-    // for equal PERCEIVED saturation. Dark stops (T60/T70/T80) come from
-    // the dark-mode tonal palette (chroma×0.85, +5 tone lift tapering 80-95).
-    // =========================================================================
-
-    // Each row's dark slots are HCT-derived from the source hex listed in
-    // apps/sandbox/src/app/(fullscreen)/pages/neutral-palette/page.tsx via
-    // the canonical dark-ramp transform (chroma×0.85, +5 tone-lift taper)
-    // — same algorithm the Tonal Palettes preview renders. Border=T60,
-    // icon=T70, text=T80. Background uses the T70 hue at 24% alpha so the
-    // overlay surface composites onto body to ~1.65:1 luminance.
-
-    // Red  H=22 — source #eb183a
-    '--color-background-red': ['#facecb', '#ff9e973D'],
-    '--color-border-red': ['#e6bab8', '#ff6f6c'],
-    '--color-icon-red': ['#89001a', '#ff9e97'],
-    '--color-text-red': ['#89001a', '#ffc6c1'],
-
-    // Orange  H=55 — source #d57113
-    '--color-background-orange': ['#fad0b5', '#ffa2583D'],
-    '--color-border-orange': ['#e6bda2', '#e2883e'],
-    '--color-icon-orange': ['#6e3500', '#ffa258'],
-    '--color-text-orange': ['#6e3500', '#ffc9a2'],
-
-    // Yellow  H=90 — source #f8c723
-    // Light-mode butter-yellow pastel at H=85 C=0.085 L=0.90 — yellow
-    // sits at the green-cyan luminance peak so it feels louder than the
-    // other status hues at the same canonical L. Picker decision: pull
-    // L down one step (0.91→0.90) and C down to its identity floor
-    // (0.10→0.085, just above the bronze threshold) so it sits closer
-    // to red/blue's perceived brightness without losing yellow identity.
-    // Dark-mode comes from the canonical H=90 ramp for tonal-palette
-    // consistency.
-    '--color-background-yellow': ['#f8da9d', '#deb4333D'],
-    '--color-border-yellow': ['#e4c279', '#c0990e'],
-    '--color-icon-yellow': ['#584400', '#deb433'],
-    '--color-text-yellow': ['#584400', '#fdcf4f'],
-
-    // Green  H=144 — source #358a3a
-    '--color-background-green': ['#c5e5c0', '#84c9803D'],
-    '--color-border-green': ['#b2d1ac', '#69ad67'],
-    '--color-icon-green': ['#0c5700', '#84c980'],
-    '--color-text-green': ['#0c5700', '#9fe59b'],
-
-    // Teal  H=180 — source #0c7365
-    // Light pastel uses L=0.87 C=0.065 (a step darker + less chroma than
-    // the L=0.888 C=0.07 used by other hues) to compensate for the
-    // green-cyan luminance overshoot — at the same OKLCH L, teal/cyan read
-    // ~5% brighter than red/blue because the eye's luminance response
-    // peaks in this band. Dropping L+C brings perceived brightness in
-    // line with the rest of the palette without losing hue identity.
-    '--color-background-teal': ['#a5e3d6', '#7ec6b83D'],
-    '--color-border-teal': ['#94d6c8', '#63ab9d'],
-    '--color-icon-teal': ['#005348', '#7ec6b8'],
-    '--color-text-teal': ['#005348', '#99e2d3'],
-
-    // Cyan  H=215 — source #0c6f82
-    // Same L=0.87 C=0.065 pastel as teal (luminance overshoot compensation).
-    '--color-background-cyan': ['#a3e0ef', '#83c2d43D'],
-    '--color-border-cyan': ['#91d3e3', '#67a7b8'],
-    '--color-icon-cyan': ['#00505f', '#83c2d4'],
-    '--color-text-cyan': ['#00505f', '#9edef0'],
-
-    // Blue  H=255 — source #0074e2
-    //   T50 #0074e2 reserved for filled Info badge / progressbar / inset hover.
-    '--color-background-blue': ['#c4ddfb', '#9eb7ff3D'],
-    '--color-border-blue': ['#b1c9e7', '#6d9cfe'],
-    '--color-icon-blue': ['#00458c', '#9eb7ff'],
-    '--color-text-blue': ['#00458c', '#c7d3ff'],
-
-    // Purple  H=320 — source #980fb2
-    '--color-background-purple': ['#eccef3', '#f297ff3D'],
-    '--color-border-purple': ['#d8bbdf', '#dd74f0'],
-    '--color-icon-purple': ['#700084', '#f297ff'],
-    '--color-text-purple': ['#700084', '#fac1ff'],
-
-    // Pink  H=355 — source #b10e69
-    '--color-background-pink': ['#fccadc', '#ff99c33D'],
-    '--color-border-pink': ['#e7b7c8', '#f273aa'],
-    '--color-icon-pink': ['#83004b', '#ff99c3'],
-    '--color-text-pink': ['#83004b', '#ffc3da'],
-
-    // Gray (categorical neutral, chroma 0)
-    //   Light: #e5e5e5 (Neutral 200) so it's visibly distinct from the
-    //          lighter body / muted surface (both #f5f5f5).
-    //   Dark : var(--color-neutral) — semi-transparent white wash
-    //          (#FFFFFF1A, 10%). Matches the same treatment the gray
-    //          badge uses; clearly distinct from the body T10 #1b1b1b
-    //          while staying chroma-0 neutral. Solid T15 #1c1c1c was
-    //          indistinguishable from --color-background-muted.
-    '--color-background-gray': ['#e5e5e5', 'var(--color-neutral)'],
-    '--color-border-gray': ['#d4d4d4', '#262626'],
-    '--color-icon-gray': ['#525252', '#a3a3a3'],
-    '--color-text-gray': ['#262626', '#e5e5e5'],
+    '--color-background-red': [red.light[85], red.dark[25]],
+    '--color-border-red': [red.light[80], red.light[65]],
+    '--color-icon-red': [red.light[30], red.dark[75]],
+    '--color-text-red': [red.light[30], red.dark[80]],
+
+    '--color-background-orange': [orange.light[85], orange.dark[25]],
+    '--color-border-orange': [orange.light[85], orange.dark[65]],
+    '--color-icon-orange': [orange.light[30], orange.light[75]],
+    '--color-text-orange': [orange.light[30], orange.dark[80]],
+
+    '--color-background-yellow': [yellow.dark[90], yellow.dark[25]],
+    '--color-border-yellow': [yellow.dark[80], yellow.light[65]],
+    '--color-icon-yellow': [yellow.light[30], yellow.light[75]],
+    '--color-text-yellow': [yellow.light[30], yellow.light[80]],
+
+    '--color-background-green': [green.dark[85], green.dark[25]],
+    '--color-border-green': [green.dark[80], green.light[65]],
+    '--color-icon-green': [green.light[30], green.light[75]],
+    '--color-text-green': [green.light[30], green.light[75]],
+
+    '--color-background-teal': [teal.light[85], teal.dark[25]],
+    '--color-border-teal': [teal.light[80], teal.dark[65]],
+    '--color-icon-teal': [teal.light[30], teal.dark[75]],
+    '--color-text-teal': [teal.light[30], teal.light[80]],
+
+    '--color-background-cyan': [cyan.dark[85], cyan.dark[25]],
+    '--color-border-cyan': [cyan.dark[80], cyan.dark[65]],
+    '--color-icon-cyan': [cyan.light[30], cyan.dark[75]],
+    '--color-text-cyan': [cyan.light[30], cyan.dark[80]],
+
+    '--color-background-blue': [blue.light[85], blue.dark[25]],
+    '--color-border-blue': [blue.light[80], blue.dark[65]],
+    '--color-icon-blue': [blue.light[30], blue.dark[75]],
+    '--color-text-blue': [blue.light[30], blue.dark[80]],
+
+    '--color-background-purple': [purple.light[90], purple.dark[25]],
+    '--color-border-purple': [purple.light[85], purple.light[70]],
+    '--color-icon-purple': [purple.light[30], purple.light[75]],
+    '--color-text-purple': [purple.light[30], purple.dark[80]],
+
+    '--color-background-pink': [pink.light[85], pink.dark[25]],
+    '--color-border-pink': [pink.light[85], pink.light[70]],
+    '--color-icon-pink': [pink.light[30], pink.dark[75]],
+    '--color-text-pink': [pink.light[30], pink.dark[80]],
+
+    '--color-background-gray': [neutral.light[90], neutral.dark[20]],
+    '--color-border-gray': [neutral.light[85], neutral.dark[15]],
+    '--color-icon-gray': [neutral.light[35], neutral.dark[65]],
+    '--color-text-gray': [neutral.light[15], neutral.dark[85]],
 
     // =========================================================================
     // Radius — slightly larger than default (kept as-is)
@@ -367,92 +265,47 @@ export const neutralTheme = defineTheme({
       '0 4px 6px light-dark(oklch(0 0 0 / 10%), oklch(0 0 0 / 50%)), ' +
       '0 12px 24px light-dark(oklch(0 0 0 / 15%), oklch(0 0 0 / 70%)), ' +
       'inset 0 0 0 1px light-dark(transparent, oklch(1 0 0 / 15%))',
-    '--shadow-inset-hover': 'inset 0px 0px 0px 2px #0074e24D',
-    '--shadow-inset-selected': 'inset 0px 0px 0px 2px #0074e280',
-    '--shadow-inset-success': 'inset 0px 0px 0px 2px #1981004D',
-    '--shadow-inset-warning': 'inset 0px 0px 0px 2px #ffce2f4D',
-    '--shadow-inset-error': 'inset 0px 0px 0px 2px #e33f4a4D',
+    '--shadow-inset-hover': `inset 0px 0px 0px 2px ${withAlpha(blue.light[50], '4D')}`,
+    '--shadow-inset-selected': `inset 0px 0px 0px 2px ${withAlpha(blue.light[50], '80')}`,
+    '--shadow-inset-success': `inset 0px 0px 0px 2px ${withAlpha(green.light[45], '4D')}`,
+    '--shadow-inset-warning': `inset 0px 0px 0px 2px ${withAlpha(yellow.light[85], '4D')}`,
+    '--shadow-inset-error': `inset 0px 0px 0px 2px ${withAlpha(red.light[55], '4D')}`,
   },
 
   components: {
-    // =========================================================================
-    // Button — primary gets white text, secondary gets a border, destructive
-    // uses the OKLCH red filled treatment.
-    // =========================================================================
     button: {
       'variant:destructive': {
-        backgroundColor: 'var(--color-error-muted)', // locked pastel red bg
-        color: 'var(--color-error)', // locked T30 red — matches banner/input error text
+        backgroundColor: 'var(--color-error-muted)',
+        color: 'var(--color-error)',
+        '--color-overlay-hover':
+          'var(--astryx-theme-neutral-color-destructive-overlay-hover)',
+        '--color-overlay-pressed':
+          'var(--astryx-theme-neutral-color-destructive-overlay-pressed)',
       },
     },
 
-    // =========================================================================
-    // Badge —
-    //   Semantic (info/success/warning/error): filled saturated T50 + contrasting
-    //     text (white, or dark on yellow). The filled-button rule from #2150
-    //     §3 — text contrast locks the bg tone, so this stays at T50 in
-    //     BOTH modes, unlike pastel surfaces which invert by mode.
-    //   Categorical (blue/green/red/orange/etc.): pastel-tinted hue surface +
-    //     colored text — light mode = soft T87-T90 + dark T30 text; dark mode
-    //     = T20 tinted + T80 light pastel text (sources: --color-background-X
-    //     and --color-text-X tokens).
-    //   Neutral: light gray bg + dark text (or inverted in dark mode).
-    // =========================================================================
     badge: {
-      // Semantic — filled saturated bg + contrasting text.
-      //   Light: vivid T45-T55 from the OKLCH palette + white text
-      //          (~4.5-5:1 — Material/Linear/Vercel pop).
-      //   Dark : T60 stop from the dark-mode tonal palette (chroma×0.85,
-      //          +5 tone-lift taper from issue #2150 §4) + DARK text.
-      //          T60+white fails AA-large (~2.7:1); T60+dark hits 6.6-7:1
-      //          and tames the §4 vibration. Same dark-text-on-bright-bg
-      //          treatment that warning yellow uses in both modes.
       'variant:info': {
-        // Light: T50 #0074e2 (palette saturated stop)
-        // Dark : T60 stop from dark-mode tonal palette of source #0074e2
-        backgroundColor: 'light-dark(#0074e2, #6d9cfe)',
-        color: 'light-dark(#ffffff, #171717)',
+        backgroundColor: statusFill.accent,
+        color: 'var(--color-on-accent)',
       },
       'variant:neutral': {
-        // Mirrors the gray categorical badge — same neutral chip treatment
-        // (Neutral 200 light / semi-transparent white wash dark) sourced
-        // from the gray hue tokens, so a single change at the token layer
-        // updates both variants.
         backgroundColor: 'var(--color-background-gray)',
         color: 'var(--color-text-gray)',
       },
       'variant:success': {
-        // Light: T45 #198100 (palette saturated stop)
-        // Dark : T60 stop from dark-mode tonal palette of source #198100
-        backgroundColor: 'light-dark(#198100, #64af4c)',
-        color: 'light-dark(#ffffff, #171717)',
+        backgroundColor: statusFill.success,
+        color: 'var(--color-on-success)',
       },
       'variant:warning': {
-        // Yellow stays at the same hex in both modes — chroma reduction
-        // is barely visible at T85, and dark text on yellow doesn't
-        // suffer from the §4 vibration concern.
-        backgroundColor: '#ffce2f',
-        color: '#171717',
+        backgroundColor: statusFill.warning,
+        color: 'var(--color-on-warning)',
       },
       'variant:error': {
-        // Light: T58 #c9303a. The T55 stop #e33f4a pairs with white at only
-        //        4.14:1 — the label is 12px/500, so AA wants 4.5, not the 3:1
-        //        large-text allowance. One tonal step down holds the hue
-        //        (OKLCH H 21.9 -> 22.8, C 0.200 -> 0.189) and reaches 5.29:1.
-        // Dark : T60 stop from dark-mode tonal palette of Tailwind red-600
-        //        source #dc2626 (kept on H=27 alarm-red rather than coral).
-        //        Dark text on it is 6.60:1 and unchanged.
-        backgroundColor: 'light-dark(#c9303a, #ff705d)',
-        color: 'light-dark(#ffffff, #171717)',
-      },
-
-      // Categorical — bg + text reference the per-hue tokens, so behavior
-      // tracks the categorical palette automatically:
-      //   Light: pastel T87-T90 bg + dark T30 colored text (low-key chip)
-      //   Dark : tinted T20 bg + light T80 colored text (per #2150 §5,
-      //          inverted from light to avoid the "pastel-in-both-modes"
-      //          anti-pattern that makes locked light pastels glow on a
-      //          dark body)
+        backgroundColor: statusFill.error,
+        color: 'var(--color-on-error)',
+      },
+
       'variant:red': {
         backgroundColor: 'var(--color-background-red)',
         color: 'var(--color-text-red)',
@@ -495,64 +348,55 @@ export const neutralTheme = defineTheme({
       },
     },
 
-    // =========================================================================
-    // StatusDot — fill uses the SAME vivid stops as the filled semantic Badge
-    // (and ProgressBar), so a dot and its badge read as one status language.
-    //
-    // The default component maps each variant to a raw semantic token
-    // (--color-success / --color-error / --color-warning / --color-icon-
-    // secondary), which in light mode are the dark T30/T40 stops meant to
-    // sit as TEXT on a pastel surface — as a solid dot they read muddy
-    // (dark green / maroon / brown). Redirect them to the badge fills.
-    //
-    //   success → badge success bg  (green T45 / dark-ramp T60)
-    //   warning → badge warning bg  (yellow T85, same hex both modes)
-    //   error   → badge error bg    (red T58 / dark-ramp T60)
-    //   accent  → badge info bg     (blue T50 / dark-ramp T60) — the
-    //             StatusDot "accent" is the info/attention color, so it
-    //             pairs with the info badge rather than --color-accent
-    //             (near-black #262626, the darkest offender).
-    //
-    // `neutral` is intentionally NOT overridden: the neutral badge bg is a
-    // near-invisible light gray (--color-background-gray #e5e5e5 / 10% white
-    // wash), fine as a large pill but unreadable as an 8px dot. It keeps the
-    // component default's visible mid-gray (--color-icon-secondary), which is
-    // not among the "too dark" cases.
-    // =========================================================================
     statusdot: {
-      'variant:success': {backgroundColor: 'light-dark(#198100, #64af4c)'},
-      'variant:warning': {backgroundColor: '#ffce2f'},
-      'variant:error': {backgroundColor: 'light-dark(#c9303a, #ff705d)'},
-      'variant:accent': {backgroundColor: 'light-dark(#0074e2, #6d9cfe)'},
+      'variant:success': {backgroundColor: statusFill.success},
+      'variant:warning': {backgroundColor: statusFill.warning},
+      'variant:error': {backgroundColor: statusFill.error},
+      'variant:accent': {backgroundColor: statusFill.accent},
+    },
+
+    'avatar-status-dot': {
+      'variant:success': {backgroundColor: statusFill.success},
+      'variant:error': {backgroundColor: statusFill.error},
+    },
+
+    // Give the Neutral segmented control a roomier inset without changing its
+    // outside height. The selected item stays flat against the tinted track.
+    'segmented-control': {
+      base: {
+        padding: 'var(--spacing-1)',
+      },
+    },
+    'segmented-control-item': {
+      'size:sm': {
+        height: 'calc(var(--size-element-sm) - 8px)',
+      },
+      'size:md': {
+        height: 'calc(var(--size-element-md) - 8px)',
+      },
+      'size:lg': {
+        height: 'calc(var(--size-element-lg) - 8px)',
+      },
+      selected: {
+        boxShadow: 'none',
+      },
     },
 
-    // =========================================================================
-    // Banner — sits on a hue-tinted surface with colored text/icon:
-    //   Light: pastel T90 bg (pulled from --color-{X}-muted / --color-background-blue)
-    //          + dark T30 colored text (--color-text-{hue}).
-    //   Dark : tinted T20 bg (same tokens, dark slot) + light T80 colored text.
-    //          Per #2150 §5 — large hue-tinted surfaces in dark mode invert
-    //          to a deep tinted bg + light text rather than locking the
-    //          light-mode pastel.
-    //
-    // The inner-header *-muted token carries the tinted background for every
-    // status, info included. A theme override that sets a plain CSS property
-    // instead lands in @layer astryx-theme, which StyleX's @layer priority4
-    // outranks, so `backgroundColor` here would silently do nothing and the
-    // info banner would paint no background at all.
-    //
-    // Status overrides reference --color-text-{hue} so text/icon colors
-    // stay in sync with the palette anchors automatically.
     banner: {
+      base: {
+        '--color-neutral': 'var(--astryx-theme-neutral-color-on-tint-neutral)',
+        '--color-overlay-hover':
+          'var(--astryx-theme-neutral-color-on-tint-overlay-hover)',
+        '--color-overlay-pressed':
+          'var(--astryx-theme-neutral-color-on-tint-overlay-pressed)',
+      },
       'status:info': {
-        '--color-accent-muted': 'var(--color-background-blue)',
+        '--color-accent-muted':
+          'var(--astryx-theme-neutral-color-status-muted-accent)',
         '--color-text-primary': 'var(--color-text-blue)',
         '--color-text-secondary': 'var(--color-text-blue)',
         '--color-accent': 'var(--color-text-blue)',
       },
-      // success/warning/error banner bgs come from --color-{X}-muted, which
-      // already carries the correct light/dark tinted values. We only need
-      // to redirect the text/icon to the palette colored stop.
       'status:success': {
         '--color-text-primary': 'var(--color-text-green)',
         '--color-text-secondary': 'var(--color-text-green)',
@@ -570,23 +414,13 @@ export const neutralTheme = defineTheme({
       },
     },
 
-    // =========================================================================
-    // TextInput — no per-status overrides needed. The global tokens
-    // --color-{success,error,warning} carry the correct values in both
-    // modes (light=T40 dark colored, dark=T80 light pastel) for both
-    // surfaces the input border/icon touches: the input surface
-    // (white/T15-dark) and the status message bubble (light pastel T90 /
-    // dark T20). Verified all six combinations clear AA non-text 3:1.
-    // =========================================================================
+    'step-indicator': {
+      'status:accent': {'--color-accent': statusFill.accent},
+      'status:success': {'--color-success': statusFill.success},
+      'status:warning': {'--color-warning': statusFill.warning},
+      'status:error': {'--color-error': statusFill.error},
+    },
 
-    // =========================================================================
-    // Switch — off-state track uses the same lifted-neutral surface as the
-    // ProgressBar track (--color-border-emphasized). Aligns the two
-    // "channel-on-body" components so their off-states share one visual
-    // language: light T85 #d4d4d4 sits one step darker than the body T95
-    // bg, dark T35 #525252 sits one step lighter than the body T10. Each
-    // is a defined channel, not a wash that blends in.
-    // =========================================================================
     switch: {
       base: {
         '--color-background-gray': 'var(--color-border-emphasized)',
@@ -595,46 +429,28 @@ export const neutralTheme = defineTheme({
 
     progressbar: {
       base: {
-        // Track uses --color-background-muted; override it to
-        // --color-border-emphasized (Neutral T85 #d4d4d4 in light mode) so
-        // the track is clearly darker than the body bg (Neutral T95 #f1f1f1)
-        // and reads as a defined channel rather than blending in. Dark
-        // mode inherits T35 #525252 — same one-step-lighter behavior.
         '--color-background-muted': 'var(--color-border-emphasized)',
       },
-      // Vivid stops match the filled semantic badge colors (info/success/
-      // warning/error variants in the badge override above). Same hex
-      // values; documented per role with palette provenance.
       'variant:accent': {
-        // Blue T50 saturated stop (= variant:info badge bg)
-        '--color-accent': '#0074e2',
+        '--color-accent': statusFill.accent,
       },
       'variant:success': {
-        // Green T45 saturated stop (= variant:success badge bg)
-        '--color-success': '#198100',
+        '--color-success': statusFill.success,
       },
       'variant:warning': {
-        // Yellow T85 saturated stop (= variant:warning badge bg)
-        '--color-warning': '#ffce2f',
+        '--color-warning': statusFill.warning,
       },
       'variant:error': {
-        // Red T58 saturated stop (= variant:error badge bg)
-        '--color-error': '#c9303a',
+        '--color-error': statusFill.error,
       },
     },
 
-    // =========================================================================
-    // Card — tighter padding via public card padding token
-    // =========================================================================
     card: {
       base: {
         padding: 'var(--spacing-3)',
       },
     },
 
-    // =========================================================================
-    // Section — tighter padding via public section padding token
-    // =========================================================================
     section: {
       base: {
         padding: 'var(--spacing-3)',