@astryxdesign/theme-stone 0.7.3 → 0.7.4-canary.10b832e

package/src/stoneTheme.ts

@@ -4,65 +4,66 @@
  * Stone Theme
  *
  * A warm, earthy neutral theme inspired by natural stone and sandstone.
- * Core palette: #28282A, #84848B, #D8D8DB, #f3f3f5, #FFFFFF
+ * Colors reference the reviewed Stone palette generated from palette.config.json.
  * Montserrat for headings, Figtree for body, JetBrains Mono for code.
  */
 
 import {defineTheme, defineSyntaxTheme} from '@astryxdesign/core/theme';
 import {stoneIconRegistry} from './icons';
+import {stonePaletteRefs} from './stonePaletteRefs.generated';
+
+const {blue, cyan, green, neutral, orange, pink, purple, red, teal, yellow} =
+  stonePaletteRefs;
+
+const lightDark = (light: string, dark: string): string =>
+  `light-dark(${light}, ${dark})`;
+const withAlpha = (color: string, alpha: string): string => `${color}${alpha}`;
 
 /**
- * Input status border overrides (per-component, per-status). All 9 input
- * components share inputStatusBorderStyles in core, which read
- * --color-{success,warning,error} (T30 light / T80 dark = saturated text
- * tone). Stone redefines those vars inside each input's status scope to
- * T60 light / T70 dark so the border (and the matching status icon) reads
- * as a softer hue rim, in line with the gentle T90 status message bubble.
+ * Input status borders and icons use softer mid-ramp stops than status text.
+ * All supported input components share this one mapping so their status
+ * treatment remains consistent.
  */
 const INPUT_STATUS_VARS = {
   'status:success': {
-    '--color-success': 'light-dark(#7f977e, #99b298)', // Green T60 / T70
+    '--color-success': lightDark(green.light[55], green.dark[70]),
   },
   'status:warning': {
-    '--color-warning': 'light-dark(#9f8f68, #bbaa81)', // Yellow T60 / T70
+    '--color-warning': lightDark(yellow.light[55], yellow.dark[70]),
   },
   'status:error': {
-    '--color-error': 'light-dark(#a58b86, #c0a5a1)', // Red T60 / T70
+    '--color-error': lightDark(red.light[60], red.dark[70]),
   },
 } as const;
 
 /**
- * Stone syntax palette — light values snap to T40 / T45 stops on the
- * stone categorical ramps (per audit drawer); dark values stay at T70.
- *
- * `string` and `property` both land on Teal T40 — intentional; the audit
- * unified them since green and teal are visually adjacent at T40 and
- * the stone neutral palette doesn't carry a distinct green stop.
+ * Stone syntax uses mid-ramp colors in light mode and lighter stops in dark
+ * mode. Light strings and properties share Teal; dark strings use Green 70,
+ * while dark properties remain Teal.
  */
 const stoneSyntax = defineSyntaxTheme({
   name: 'astryx-stone',
   tokens: {
-    keyword: ['#645a72', '#b2a7c1'], // Purple T40 / T70
-    string: ['#4e6357', '#9bb19a'], // Teal T40 / Green T70
-    comment: ['#5e5e5e', '#ababb0'], // Stone Neutral T40 / T70
-    number: ['#755752', '#bea792'], // Red T40 / Orange T70
-    function: ['#506072', '#99adc6'], // Blue T40 / T70
-    type: ['#645a72', '#b2a7c1'], // Purple T40 / T70
-    variable: ['#5e5e5e', '#ababb0'], // Stone Neutral T40 / T70
-    operator: ['#5e5e5e', '#ababb0'], // Stone Neutral T40 / T70
-    constant: ['#755752', '#bea792'], // Red T40 / Orange T70
-    tag: ['#775751', '#c7a39d'], // Red T40 / T70
-    attribute: ['#79693f', '#b6aa90'], // Yellow T45 / T70
-    property: ['#4e6357', '#94b2a0'], // Teal T40 / T70
-    punctuation: ['#5e5e5e', '#ababb0'], // Stone Neutral T40 / T70
-    background: ['#f3f3f5', '#171719'],
-    // Diff rows: the muted green/red at 25% in light and 20% in dark keep
-    // every token at or above 4.5:1 on the tint; the markers are the tinted
-    // text tokens (8.1:1 light, 8.8:1 dark on their tints).
-    added: ['#d0e9ce40', '#b4cdb233'],
-    removed: ['#f9dcd740', '#dcc0bc33'],
-    'added-marker': ['#374c36', '#d0e9ce'],
-    'removed-marker': ['#58413e', '#f9dcd7'],
+    keyword: [purple.light[40], purple.dark[70]],
+    string: [teal.light[40], green.dark[70]],
+    comment: [neutral.light[40], neutral.dark[70]],
+    number: [red.light[40], orange.dark[70]],
+    function: [blue.light[40], blue.dark[70]],
+    type: [purple.light[40], purple.dark[70]],
+    variable: [neutral.light[40], neutral.dark[70]],
+    operator: [neutral.light[40], neutral.dark[70]],
+    constant: [red.light[40], orange.dark[70]],
+    tag: [red.light[40], red.dark[70]],
+    attribute: [yellow.light[40], yellow.dark[70]],
+    property: [teal.light[40], teal.dark[70]],
+    punctuation: [neutral.light[40], neutral.dark[70]],
+    background: [neutral.light[95], neutral.dark[5]],
+    // Translucent diff rows retain each token's contrast while the opaque
+    // markers carry the same Green and Red families as their row tint.
+    added: [withAlpha(green.light[90], '40'), withAlpha(green.dark[80], '33')],
+    removed: [withAlpha(red.light[90], '40'), withAlpha(red.dark[80], '33')],
+    'added-marker': [green.light[30], green.dark[90]],
+    'removed-marker': [red.light[30], red.dark[90]],
   },
 });
 
@@ -151,145 +152,135 @@ export const stoneTheme = defineTheme({
   syntax: stoneSyntax,
 
   tokens: {
-    // =========================================================================
-    // Colors — warm stone palette
-    // Core: #28282A, #84848B, #D8D8DB, #f3f3f5, #FFFFFF
-    // =========================================================================
-
-    // Core semantic — all neutrals H=291
-    // Stone 900 T=16 C=1.4, Stone 500 T=55 C=4, Stone 300 T=86 C=1.6, Stone 100 T=96 C=1
-    '--color-accent': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
-    '--color-accent-muted': ['#25252a14', '#f3f3f520'], // light: Stone Neutral T15 · 8% / dark: T96 · 12.5%
-    '--color-neutral': ['#25252a0f', '#f3f3f51a'], // light: Stone Neutral T15 · 6% / dark: T96 · 10%
-    '--color-background-surface': ['#ffffff', '#1b1b1f'], // dark: Stone Neutral T10
-    '--color-background-body': ['#f3f3f5', '#111015'], // dark: Stone Neutral T5
-    '--color-overlay': ['#25252a80', '#28282acc'], // light: Stone Neutral T15 · 50% / dark: 80%
-    '--color-overlay-hover': ['#25252a0d', '#f3f3f50d'], // light: Stone Neutral T15 · 5% / dark: T96 · 5%
-    '--color-overlay-pressed': ['#25252a1a', '#f3f3f51a'], // light: Stone Neutral T15 · 10% / dark: T96 · 10%
-    '--color-background-muted': ['#e2e2e8', '#3b3b3f'], // light: Stone Neutral T90
-
-    // Text — H=291
-    '--color-text-primary': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
-    // T40/T70 keeps normal secondary text above AA on every stone surface,
-    // including the muted and tinted fills that components pair it with.
-    '--color-text-secondary': ['#5e5e63', '#ababb0'], // Stone Neutral T40 / T70
-    '--color-text-disabled': ['#d7d7da', '#5e5e61'], // T86 C=1.6 / T40 C=2
-    '--color-text-accent': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
-    '--color-on-dark': '#FFFFFF',
-    '--color-on-light': ['#25252a', '#28282a'], // light: Stone Neutral T15
-    '--color-on-accent': ['#ffffff', '#25252a'], // dark: Stone Neutral T15
-    // Text on top of matching status surface (badge fill, banner content).
-    '--color-on-success': ['#374c36', '#d0e9ce'], // Green T30 / T90
-    '--color-on-error': ['#58413e', '#f9dcd7'], // Red T30 / T90
-    '--color-on-warning': ['#524622', '#f4e1b7'], // Yellow T30 / T90
-
-    // Icon — H=291
-    '--color-icon-accent': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
-    '--color-icon-primary': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
-    '--color-icon-secondary': ['#83838a', '#9d9da3'], // T55 C=4 / T65 C=3
-    '--color-icon-disabled': ['#d7d7da', '#5e5e61'], // T86 C=1.6 / T40 C=2
-
-    // Surface variants — H=291
-    '--color-background-card': ['#FFFFFF', '#242325'], // T14
-    '--color-background-popover': ['#ffffff', '#25252a'], // dark: Stone Neutral T15
-    '--color-background-inverted': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
-
-    // Status / Sentiment — T50 from palette for icons/borders (visible color)
-    '--color-success': ['#374c36', '#b4cdb2'], // Green T30 / T80
-    '--color-success-muted': ['#d0e9ce', '#b4cdb2'], // Green T90 / T80
-    '--color-error': ['#58413e', '#dcc0bc'], // Red T30 / T80
-    '--color-error-muted': ['#f9dcd7', '#dcc0bc'], // Red T90 / T80
-    '--color-warning': ['#524622', '#d7c59c'], // Yellow T30 / T80
-    '--color-warning-muted': ['#f4e1b7', '#d7c59c'], // Yellow T90 / T80
-
-    // Border — H=291
-    '--color-border': ['#e2e2e8', '#f3f3f51a'], // light: Stone Neutral T90 / dark: T96 · 10%
-    '--color-border-emphasized': ['#83838a', '#5e5e61'], // T55 C=4 / T40 C=2
-
-    // Effects — H=291
-    '--color-skeleton': ['#d4d4da', '#5e5e64'], // T85 / T40 from H=291 C=3
-    '--color-shadow': ['#25252a1a', '#0000004d'], // light: Stone Neutral T15 · 10% / dark: 30%
-    '--color-tint-hover': ['black', 'white'],
+    // Core neutrals
+    '--color-accent': [neutral.light[15], neutral.dark[95]],
+    '--color-accent-muted': [
+      withAlpha(neutral.light[15], '14'),
+      withAlpha(neutral.dark[95], '20'),
+    ],
+    '--color-neutral': [
+      withAlpha(neutral.light[15], '0f'),
+      withAlpha(neutral.dark[95], '1a'),
+    ],
+    '--color-background-surface': [neutral.light[100], neutral.dark[10]],
+    '--color-background-body': [neutral.light[95], neutral.dark[5]],
+    '--color-overlay': [
+      withAlpha(neutral.light[15], '80'),
+      withAlpha(neutral.dark[15], 'cc'),
+    ],
+    '--color-overlay-hover': [
+      withAlpha(neutral.light[15], '0d'),
+      withAlpha(neutral.dark[95], '0d'),
+    ],
+    '--color-overlay-pressed': [
+      withAlpha(neutral.light[15], '1a'),
+      withAlpha(neutral.dark[95], '1a'),
+    ],
+    '--color-background-muted': [neutral.light[90], neutral.dark[25]],
+
+    // Text
+    '--color-text-primary': [neutral.light[15], neutral.dark[95]],
+    // These stops keep normal secondary text readable on Stone's body,
+    // muted, and categorical surfaces.
+    '--color-text-secondary': [neutral.light[40], neutral.dark[70]],
+    '--color-text-disabled': [neutral.light[85], neutral.dark[40]],
+    '--color-text-accent': [neutral.light[15], neutral.dark[95]],
+    '--color-on-dark': neutral.light[100],
+    '--color-on-light': [neutral.light[15], neutral.dark[15]],
+    '--color-on-accent': [neutral.light[100], neutral.dark[15]],
+    '--color-on-success': [green.light[30], green.dark[90]],
+    '--color-on-error': [red.light[30], red.dark[90]],
+    '--color-on-warning': [yellow.light[30], yellow.dark[90]],
+
+    // Icon
+    '--color-icon-accent': [neutral.light[15], neutral.dark[95]],
+    '--color-icon-primary': [neutral.light[15], neutral.dark[95]],
+    '--color-icon-secondary': [neutral.light[55], neutral.dark[65]],
+    '--color-icon-disabled': [neutral.light[85], neutral.dark[40]],
+
+    // Surface variants
+    '--color-background-card': [neutral.light[100], neutral.dark[15]],
+    '--color-background-popover': [neutral.light[100], neutral.dark[20]],
+    '--color-background-inverted': [neutral.light[15], neutral.dark[95]],
+
+    // Status / sentiment
+    '--color-success': [green.light[30], green.dark[80]],
+    '--color-success-muted': [green.light[90], green.dark[80]],
+    '--color-error': [red.light[30], red.dark[80]],
+    '--color-error-muted': [red.light[90], red.dark[80]],
+    '--color-warning': [yellow.light[30], yellow.dark[80]],
+    '--color-warning-muted': [yellow.light[90], yellow.dark[80]],
+
+    // Border
+    '--color-border': [neutral.light[90], withAlpha(neutral.dark[95], '1a')],
+    '--color-border-emphasized': [neutral.light[55], neutral.dark[40]],
+
+    // Effects
+    '--color-skeleton': [neutral.light[85], neutral.dark[40]],
+    '--color-shadow': [
+      withAlpha(neutral.light[15], '1a'),
+      withAlpha(neutral.dark[0], '4d'),
+    ],
+    '--color-tint-hover': [neutral.light[0], neutral.dark[100]],
 
     // Typography override
     '--text-supporting-size': '12px',
 
-    // Categorical hues
-    //   Light: T90 solid bg + T30 text (pastel surface, dark text)
-    //   Dark:  T35 solid bg + T90 text — snaps to canonical palette stops
-    //          per theming-infra.mdc §7. T90 dark text is the SAME hex as
-    //          the light-mode bg pastel — clean palette symmetry, ~6–9:1
-    //          contrast on the T35 surface across all hues (passes AA Body).
-    // Borders: light T85 / dark T25 — one step inward from surface in both
-    //          modes, matching the light-mode T90/T85 spacing.
-
-    // Categorical — Blue H=265 C=10
-    '--color-background-blue': ['#d7e4f5', '#485362'], // light T90 / dark T35
-    '--color-border-blue': ['#c9d6e7', '#313c4a'], // light T85 / dark T25
-    '--color-icon-blue': ['#3c4856', '#d7e4f5'], // light T30 / dark T90
-    '--color-text-blue': ['#3c4856', '#d7e4f5'],
-
-    // Categorical — Cyan H=190 C=10
-    '--color-background-cyan': ['#cce8e5', '#3e5755'],
-    '--color-border-cyan': ['#bedad7', '#28403e'],
-    '--color-icon-cyan': ['#334b49', '#cce8e5'],
-    '--color-text-cyan': ['#334b49', '#cce8e5'],
-
-    // Categorical — Gray (pure neutral, C=0). Same T35/T25/T90 pattern from
-    // the neutral H=291 C=3 ramp.
-    '--color-background-gray': ['#e2e2e8', '#525257'], // light: Stone Neutral T90
-    '--color-border-gray': ['#d4d4da', '#3b3b3f'], // light: Stone Neutral T85
-    '--color-icon-gray': ['#46464b', '#e2e2e8'], // light: Stone Neutral T30
-    '--color-text-gray': ['#46464b', '#e2e2e8'], // light: Stone Neutral T30
-
-    // Categorical — Green H=142 C=17
-    '--color-background-green': ['#d0e9ce', '#425841'],
-    '--color-border-green': ['#c2dbc0', '#2b402b'],
-    '--color-icon-green': ['#374c36', '#d0e9ce'],
-    '--color-text-green': ['#374c36', '#d0e9ce'],
-
-    // Categorical — Orange H=70 C=22
-    '--color-background-orange': ['#ffdcbb', '#684d32'],
-    '--color-border-orange': ['#f1ceae', '#4f361c'],
-    '--color-icon-orange': ['#5b4227', '#ffdcbb'],
-    '--color-text-orange': ['#5b4227', '#ffdcbb'],
-
-    // Categorical — Pink H=340 C=9
-    '--color-background-pink': ['#f0dde8', '#5e4e57'],
-    '--color-border-pink': ['#e2cfda', '#463740'],
-    '--color-icon-pink': ['#52424c', '#f0dde8'],
-    '--color-text-pink': ['#52424c', '#f0dde8'],
-
-    // Categorical — Purple H=307 C=11
-    '--color-background-purple': ['#e8dff3', '#564f60'],
-    '--color-border-purple': ['#d9d1e5', '#3f3949'],
-    '--color-icon-purple': ['#4b4454', '#e8dff3'],
-    '--color-text-purple': ['#4b4454', '#e8dff3'],
-
-    // Categorical — Red H=33 C=11
-    '--color-background-red': ['#f9dcd7', '#644d49'],
-    '--color-border-red': ['#ebcec9', '#4c3633'],
-    '--color-icon-red': ['#58413e', '#f9dcd7'],
-    '--color-text-red': ['#58413e', '#f9dcd7'],
-
-    // Categorical — Teal H=158 C=9
-    '--color-background-teal': ['#d4e7dc', '#46564d'],
-    '--color-border-teal': ['#c6d9ce', '#303f36'],
-    '--color-icon-teal': ['#3b4a41', '#d4e7dc'],
-    '--color-text-teal': ['#3b4a41', '#d4e7dc'],
-
-    // Categorical — Yellow H=90 C=23
-    '--color-background-yellow': ['#f4e1b7', '#5e512d'],
-    '--color-border-yellow': ['#e5d3a9', '#463a18'],
-    '--color-icon-yellow': ['#524622', '#f4e1b7'],
-    '--color-text-yellow': ['#524622', '#f4e1b7'],
-
-    // =========================================================================
-    // Radius — clean and subtle
-    //   --radius-none and --radius-full are always fixed and must never be
-    //   scaled by a theme (see defineTheme's radius config docs) — 0 and
-    //   9999px respectively, matching @astryxdesign/core's own defaults.
-    // =========================================================================
+    // Categorical
+    // Light mode pairs pastel stop 90 surfaces with stop 30 foregrounds.
+    // Dark mode pairs stop 35 surfaces with stop 90 foregrounds; borders move
+    // one step inward in both modes.
+    '--color-background-blue': [blue.light[90], blue.dark[35]],
+    '--color-border-blue': [blue.light[85], blue.dark[25]],
+    '--color-icon-blue': [blue.light[30], blue.dark[90]],
+    '--color-text-blue': [blue.light[30], blue.dark[90]],
+
+    '--color-background-cyan': [cyan.light[90], cyan.dark[35]],
+    '--color-border-cyan': [cyan.light[85], cyan.dark[25]],
+    '--color-icon-cyan': [cyan.light[30], cyan.dark[90]],
+    '--color-text-cyan': [cyan.light[30], cyan.dark[90]],
+
+    '--color-background-gray': [neutral.light[90], neutral.dark[35]],
+    '--color-border-gray': [neutral.light[85], neutral.dark[25]],
+    '--color-icon-gray': [neutral.light[30], neutral.dark[90]],
+    '--color-text-gray': [neutral.light[30], neutral.dark[90]],
+
+    '--color-background-green': [green.light[90], green.dark[35]],
+    '--color-border-green': [green.light[85], green.dark[25]],
+    '--color-icon-green': [green.light[30], green.dark[90]],
+    '--color-text-green': [green.light[30], green.dark[90]],
+
+    '--color-background-orange': [orange.light[90], orange.dark[35]],
+    '--color-border-orange': [orange.light[85], orange.dark[25]],
+    '--color-icon-orange': [orange.light[30], orange.dark[90]],
+    '--color-text-orange': [orange.light[30], orange.dark[90]],
+
+    '--color-background-pink': [pink.light[90], pink.dark[35]],
+    '--color-border-pink': [pink.light[85], pink.dark[25]],
+    '--color-icon-pink': [pink.light[30], pink.dark[90]],
+    '--color-text-pink': [pink.light[30], pink.dark[90]],
+
+    '--color-background-purple': [purple.light[90], purple.dark[35]],
+    '--color-border-purple': [purple.light[85], purple.dark[25]],
+    '--color-icon-purple': [purple.light[30], purple.dark[90]],
+    '--color-text-purple': [purple.light[30], purple.dark[90]],
+
+    '--color-background-red': [red.light[90], red.dark[35]],
+    '--color-border-red': [red.light[85], red.dark[25]],
+    '--color-icon-red': [red.light[30], red.dark[90]],
+    '--color-text-red': [red.light[30], red.dark[90]],
+
+    '--color-background-teal': [teal.light[90], teal.dark[35]],
+    '--color-border-teal': [teal.light[85], teal.dark[25]],
+    '--color-icon-teal': [teal.light[30], teal.dark[90]],
+    '--color-text-teal': [teal.light[30], teal.dark[90]],
+
+    '--color-background-yellow': [yellow.light[90], yellow.dark[35]],
+    '--color-border-yellow': [yellow.light[85], yellow.dark[25]],
+    '--color-icon-yellow': [yellow.light[30], yellow.dark[90]],
+    '--color-text-yellow': [yellow.light[30], yellow.dark[90]],
+
+    // Radius
     '--radius-none': '0px',
     '--radius-inner': '0.25rem',
     '--radius-element': '0.5rem',
@@ -297,17 +288,15 @@ export const stoneTheme = defineTheme({
     '--radius-page': '1.5rem',
     '--radius-full': '9999px',
 
-    // =========================================================================
     // Shadows
-    // =========================================================================
-    '--shadow-low': '0 2px 4px #28282A0D, 0 4px 8px #28282A1A',
-    '--shadow-med': '0 2px 4px #28282A0D, 0 4px 12px #28282A1A',
-    '--shadow-high': '0 4px 6px #28282A1A, 0 12px 24px #28282A26',
-    '--shadow-inset-hover': 'inset 0px 0px 0px 2px #28282A30',
-    '--shadow-inset-selected': 'inset 0px 0px 0px 2px #28282A50',
-    '--shadow-inset-success': 'inset 0px 0px 0px 2px #83838a30',
-    '--shadow-inset-warning': 'inset 0px 0px 0px 2px #83838a30',
-    '--shadow-inset-error': 'inset 0px 0px 0px 2px #83838a30',
+    '--shadow-low': `0 2px 4px ${withAlpha(neutral.light[15], '0d')}, 0 4px 8px ${withAlpha(neutral.light[15], '1a')}`,
+    '--shadow-med': `0 2px 4px ${withAlpha(neutral.light[15], '0d')}, 0 4px 12px ${withAlpha(neutral.light[15], '1a')}`,
+    '--shadow-high': `0 4px 6px ${withAlpha(neutral.light[15], '1a')}, 0 12px 24px ${withAlpha(neutral.light[15], '26')}`,
+    '--shadow-inset-hover': `inset 0 0 0 2px ${withAlpha(neutral.light[15], '30')}`,
+    '--shadow-inset-selected': `inset 0 0 0 2px ${withAlpha(neutral.light[15], '50')}`,
+    '--shadow-inset-success': `inset 0 0 0 2px ${withAlpha(neutral.light[55], '30')}`,
+    '--shadow-inset-warning': `inset 0 0 0 2px ${withAlpha(neutral.light[55], '30')}`,
+    '--shadow-inset-error': `inset 0 0 0 2px ${withAlpha(neutral.light[55], '30')}`,
   },
 
   components: {
@@ -322,7 +311,8 @@ export const stoneTheme = defineTheme({
       },
     },
 
-    // Semantic variants point at categorical hue tokens — single source of truth.
+    // Badges, banners, and field status messages share the categorical
+    // surfaces and foregrounds so each semantic state has one visual source.
     badge: {
       'variant:info': {
         backgroundColor: 'var(--color-background-blue)',
@@ -346,10 +336,8 @@ export const stoneTheme = defineTheme({
       },
     },
 
-    // StyleX paints the banner surface from @layer priority4 (above
-    // @layer astryx-theme), so a direct backgroundColor override loses the
-    // cascade. Redefine the muted token instead so StyleX's var() resolves
-    // to the categorical bg in our scope.
+    // Banner surface declarations live above the theme layer, so redirect the
+    // semantic variables here instead of attempting a losing direct fill.
     banner: {
       'status:info': {
         '--color-accent-muted': 'var(--color-background-blue)',
@@ -377,44 +365,38 @@ export const stoneTheme = defineTheme({
       },
     },
 
-    // Fill: light = T90 (same hex as banner/badge surface — fill reads as
-    // the same color family as the matching status surface). Dark = T70.
-    // Hexes from the preview Tonal Palettes ramp. accent (default) +
-    // indeterminate both route to blue for the in-progress / loading look.
+    // Progress fills use the same family as their matching status surface;
+    // the darker stop in dark mode keeps the channel visible on dark tracks.
     'progress-bar-fill': {
       'variant:accent': {
-        backgroundColor: 'light-dark(#d7e4f5, #a0acbc)', // Blue T90 / T70
+        backgroundColor: lightDark(blue.light[90], blue.dark[70]),
       },
       'variant:success': {
-        backgroundColor: 'light-dark(#d0e9ce, #9ab298)', // Green T90 / T70
+        backgroundColor: lightDark(green.light[90], green.dark[70]),
       },
       'variant:warning': {
-        backgroundColor: 'light-dark(#f4e1b7, #bbaa82)', // Yellow T90 / T70
+        backgroundColor: lightDark(yellow.light[90], yellow.dark[70]),
       },
       'variant:error': {
-        backgroundColor: 'light-dark(#f9dcd7, #c0a5a0)', // Red T90 / T70
+        backgroundColor: lightDark(red.light[90], red.dark[70]),
       },
     },
 
-    // Track default --color-background-muted reads near-body in stone;
-    // redirect to --color-skeleton so the channel stays visible.
+    // The default muted track is too close to Stone's body surface.
     'progress-bar-track': {
       base: {
         backgroundColor: 'var(--color-skeleton)',
       },
     },
 
-    // Switch off-state track reads --color-background-gray by default.
-    // Redefine it inside the switch scope to --color-skeleton, matching
-    // the ProgressBar track. The on-state reads --color-accent (unaffected);
-    // disabled-off also picks up --color-skeleton for consistency.
+    // Match the Switch off-state track to the visible ProgressBar track.
     switch: {
       base: {
         '--color-background-gray': 'var(--color-skeleton)',
       },
     },
 
-    // FieldStatus surface matches badge — see badge override above.
+    // FieldStatus surfaces match the corresponding badge and banner family.
     'field-status': {
       'type:success': {
         backgroundColor: 'var(--color-background-green)',
@@ -427,8 +409,7 @@ export const stoneTheme = defineTheme({
       },
     },
 
-    // Input status borders + icons across all 9 input components share the
-    // same softer T60/T70 redirection. See INPUT_STATUS_VARS above.
+    // Every input status border and icon uses INPUT_STATUS_VARS above.
     'text-input': INPUT_STATUS_VARS,
     'text-area': INPUT_STATUS_VARS,
     'number-input': INPUT_STATUS_VARS,
@@ -460,9 +441,11 @@ export const stoneTheme = defineTheme({
 });
 
 /**
- * Raw tonal palettes — every color at every tone step (0–100 in 5s).
- * Same hue and chroma used to derive all theme tokens.
- * Use these for custom components or data visualization.
+ * Frozen released compatibility palettes. These values preserve the public
+ * `stonePalettes` numeric stops, `hue`, and `chroma` for existing consumers;
+ * the maintained theme renders selected stops from
+ * `stonePalettes.generated.ts` instead. Components should consume semantic
+ * theme tokens, and charts should use the data-visualization color API.
  */
 export const stonePalettes = {
   neutral: {