@mindlogic-ai/logician-ui 3.1.0-alpha.10 → 3.1.0-alpha.11

package/dist/theme/colors.d.ts

@@ -33,32 +33,6 @@
  * @see https://www.w3.org/TR/WCAG21/#contrast-minimum
  * @version 3.0.0
  */
-/**
- * Semantic color tokens that map primitive colors to UI intent.
- *
- * Use these tokens in components instead of raw color values:
- * - `primary.*`: Buttons, links, focus states
- * - `secondary.*`: Accent elements, highlights
- * - `success.*`: Success messages, confirmations
- * - `warning.*`: Warning messages, caution states
- * - `danger.*`: Error messages, destructive actions
- *
- * Each category includes:
- * - `lightest`: Lightest backgrounds (ghost states, very subtle fills)
- * - `extralight`: Extra-light backgrounds (badges, subtle fills)
- * - `lighter`: Light backgrounds (toast backgrounds, subtle fills)
- * - `light`: Medium backgrounds (hover states, medium fills)
- * - `main`: Primary color (buttons, text, icons)
- * - `dark`: Dark variant (text on light backgrounds)
- * - `darker`: Darkest variant (high-contrast text)
- *
- * @example
- * ```tsx
- * <Button bgColor="primary.main" />
- * <Alert bgColor="danger.lighter" color="danger.dark" />
- * <Badge bgColor="success.lightest" color="success.dark" />
- * ```
- */
 export declare const semanticTokens: {
     readonly colors: {
         /**
@@ -117,6 +91,18 @@ export declare const semanticTokens: {
                     readonly _dark: "{colors.blue.100}";
                 };
             };
+            readonly fill: {
+                readonly value: {
+                    readonly base: "{colors.blue.500}";
+                    readonly _dark: "{colors.blue.700}";
+                };
+            };
+            readonly fillStrong: {
+                readonly value: {
+                    readonly base: "{colors.blue.700}";
+                    readonly _dark: "{colors.blue.800}";
+                };
+            };
         };
         /**
          * Secondary colors (Violet-based)
@@ -329,6 +315,130 @@ export declare const semanticTokens: {
                 };
             };
         };
+        /**
+         * Neutral tone ramp — a mode-aware companion to the raw `gray.*` primitives.
+         *
+         * Each `slate.N` resolves to `gray.N` in light and to the desaturated
+         * counterpart of the *mirrored* step in dark, so a single token carries the
+         * same visual role in both modes (e.g. `slate.300` is a light divider in
+         * light and the equivalent dark divider in dark — no `_dark={{…}}` needed at
+         * the call site).
+         *
+         * @deprecated **Migration shim, not a blessed vocabulary.** `slate.*` exists
+         * to give code currently styling neutrals with a raw mode-aware ramp a
+         * lossless landing spot, and to be codemodded onto the `fg`/`bg`/`border`
+         * role tokens (e.g. `slate.200`→`border.subtle`, `slate.900`→`fg.muted`,
+         * `slate.800`→`fg.default`). **Do not reach for `slate.*` in new code** —
+         * use a role token. This ramp is slated for removal once consumers migrate.
+         *
+         * `600`/`700` are lifted off the straight mirror (#8E939F/#7C818D) so the
+         * secondary/muted text they most often carry clears WCAG AA 4.5:1 on the
+         * dark canvas/surface — the straight mirrors measured ~3.0–3.9 there.
+         */
+        readonly slate: {
+            readonly 0: {
+                readonly value: {
+                    readonly base: "{colors.gray.0}";
+                    readonly _dark: "#0E1014";
+                };
+            };
+            readonly 50: {
+                readonly value: {
+                    readonly base: "{colors.gray.50}";
+                    readonly _dark: "#181A20";
+                };
+            };
+            readonly 100: {
+                readonly value: {
+                    readonly base: "{colors.gray.100}";
+                    readonly _dark: "#23262E";
+                };
+            };
+            readonly 200: {
+                readonly value: {
+                    readonly base: "{colors.gray.200}";
+                    readonly _dark: "#30343C";
+                };
+            };
+            readonly 300: {
+                readonly value: {
+                    readonly base: "{colors.gray.300}";
+                    readonly _dark: "#3C404B";
+                };
+            };
+            readonly 400: {
+                readonly value: {
+                    readonly base: "{colors.gray.400}";
+                    readonly _dark: "#4A4E5A";
+                };
+            };
+            readonly 500: {
+                readonly value: {
+                    readonly base: "{colors.gray.500}";
+                    readonly _dark: "#595E6B";
+                };
+            };
+            readonly 600: {
+                readonly value: {
+                    readonly base: "{colors.gray.600}";
+                    readonly _dark: "#898E99";
+                };
+            };
+            readonly 700: {
+                readonly value: {
+                    readonly base: "{colors.gray.700}";
+                    readonly _dark: "#8D919D";
+                };
+            };
+            readonly 800: {
+                readonly value: {
+                    readonly base: "{colors.gray.800}";
+                    readonly _dark: "#8E939F";
+                };
+            };
+            readonly 900: {
+                readonly value: {
+                    readonly base: "{colors.gray.900}";
+                    readonly _dark: "#A2A6B1";
+                };
+            };
+            readonly 1000: {
+                readonly value: {
+                    readonly base: "{colors.gray.1000}";
+                    readonly _dark: "#B6BAC3";
+                };
+            };
+            readonly 1100: {
+                readonly value: {
+                    readonly base: "{colors.gray.1100}";
+                    readonly _dark: "#D2D5DB";
+                };
+            };
+            readonly 1200: {
+                readonly value: {
+                    readonly base: "{colors.gray.1200}";
+                    readonly _dark: "#E5E8EC";
+                };
+            };
+            readonly 1300: {
+                readonly value: {
+                    readonly base: "{colors.gray.1300}";
+                    readonly _dark: "#F2F4F7";
+                };
+            };
+            readonly 1400: {
+                readonly value: {
+                    readonly base: "{colors.gray.1400}";
+                    readonly _dark: "#F8F9FB";
+                };
+            };
+            readonly 1500: {
+                readonly value: {
+                    readonly base: "{colors.gray.1500}";
+                    readonly _dark: "#FEFEFF";
+                };
+            };
+        };
         /**
          * Neutral background tokens — map onto the gray.0–1500 scale.
          * Use for: page/canvas, raised surfaces (cards, menus), subtle/muted fills,
@@ -341,46 +451,58 @@ export declare const semanticTokens: {
          * - inverse: high-contrast surface (flips to light in dark mode)
          */
         readonly bg: {
+            readonly DEFAULT: {
+                readonly value: {
+                    readonly _light: "{colors.white}";
+                    readonly _dark: "#0E1014";
+                };
+            };
             readonly canvas: {
                 readonly value: {
                     readonly base: "{colors.gray.0}";
-                    readonly _dark: "{colors.gray.1500}";
+                    readonly _dark: "#0E1014";
                 };
             };
             readonly surface: {
                 readonly value: {
                     readonly base: "{colors.white}";
-                    readonly _dark: "{colors.gray.1400}";
+                    readonly _dark: "#181A20";
                 };
             };
             readonly raised: {
                 readonly value: {
                     readonly base: "{colors.white}";
-                    readonly _dark: "{colors.gray.1100}";
+                    readonly _dark: "#3C404B";
                 };
             };
             readonly subtle: {
                 readonly value: {
                     readonly base: "{colors.gray.50}";
-                    readonly _dark: "{colors.gray.1300}";
+                    readonly _dark: "#23262E";
                 };
             };
             readonly muted: {
                 readonly value: {
                     readonly base: "{colors.gray.100}";
-                    readonly _dark: "{colors.gray.1200}";
+                    readonly _dark: "#30343C";
                 };
             };
             readonly inverse: {
                 readonly value: {
                     readonly base: "{colors.gray.1300}";
-                    readonly _dark: "{colors.gray.50}";
+                    readonly _dark: "#F8F9FB";
+                };
+            };
+            readonly sunken: {
+                readonly value: {
+                    readonly base: "{colors.gray.50}";
+                    readonly _dark: "#0E1014";
                 };
             };
             readonly panel: {
                 readonly value: {
                     readonly base: "{colors.white}";
-                    readonly _dark: "{colors.gray.1400}";
+                    readonly _dark: "#181A20";
                 };
             };
             /**
@@ -423,28 +545,40 @@ export declare const semanticTokens: {
          * - inverse: text on inverse surfaces (flips with mode)
          */
         readonly fg: {
-            readonly default: {
+            readonly DEFAULT: {
+                readonly value: {
+                    readonly _light: "{colors.black}";
+                    readonly _dark: "#F8F9FB";
+                };
+            };
+            readonly emphasized: {
                 readonly value: {
                     readonly base: "{colors.gray.1300}";
-                    readonly _dark: "{colors.gray.200}";
+                    readonly _dark: "#E5E8EC";
+                };
+            };
+            readonly default: {
+                readonly value: {
+                    readonly base: "{colors.gray.1000}";
+                    readonly _dark: "#D2D5DB";
                 };
             };
             readonly muted: {
                 readonly value: {
                     readonly base: "{colors.gray.900}";
-                    readonly _dark: "{colors.gray.300}";
+                    readonly _dark: "#B6BAC3";
                 };
             };
             readonly subtle: {
                 readonly value: {
                     readonly base: "{colors.gray.700}";
-                    readonly _dark: "{colors.gray.600}";
+                    readonly _dark: "#989DA9";
                 };
             };
             readonly inverse: {
                 readonly value: {
                     readonly base: "{colors.gray.0}";
-                    readonly _dark: "{colors.gray.1400}";
+                    readonly _dark: "#181A20";
                 };
             };
         };
@@ -456,22 +590,28 @@ export declare const semanticTokens: {
          * - strong: high-emphasis borders, focus outlines on neutral
          */
         readonly border: {
+            readonly DEFAULT: {
+                readonly value: {
+                    readonly _light: "{colors.gray.200}";
+                    readonly _dark: "#6A6F7C";
+                };
+            };
             readonly default: {
                 readonly value: {
                     readonly base: "{colors.gray.300}";
-                    readonly _dark: "{colors.gray.1100}";
+                    readonly _dark: "#3C404B";
                 };
             };
             readonly subtle: {
                 readonly value: {
                     readonly base: "{colors.gray.200}";
-                    readonly _dark: "{colors.gray.1300}";
+                    readonly _dark: "#23262E";
                 };
             };
             readonly strong: {
                 readonly value: {
                     readonly base: "{colors.gray.500}";
-                    readonly _dark: "{colors.gray.900}";
+                    readonly _dark: "#595E6B";
                 };
             };
         };
@@ -485,11 +625,12 @@ export declare const semanticTokens: {
  * by reviewers. It is intentionally hand-maintained alongside `semanticTokens`
  * so a rename here is a visible, reviewable diff.
  *
- * Note: `bg.panel` is deliberately omitted — it is an internal realignment of a
- * Chakra default (for overlay surfaces), not part of the public migration
- * contract. App code should use `bg.surface`/`bg.canvas`.
+ * Note: `bg.panel` and the bare `bg`/`fg`/`border` DEFAULT tokens are
+ * deliberately omitted — they are internal realignments of Chakra defaults
+ * (overlay surfaces and html-level globals), not part of the public migration
+ * contract. App code should use `bg.surface`/`bg.canvas`, `fg.default`, etc.
  */
-export type SemanticColorToken = `bg.${'canvas' | 'surface' | 'raised' | 'subtle' | 'muted' | 'inverse' | 'selected' | 'highlighted'}` | 'bg.invalid.subtle' | `fg.${'default' | 'muted' | 'subtle' | 'inverse'}` | `border.${'default' | 'subtle' | 'strong'}` | `${'primary' | 'secondary' | 'danger' | 'success' | 'warning'}.${'lightest' | 'extralight' | 'lighter' | 'light' | 'main' | 'dark' | 'darker'}`;
+export type SemanticColorToken = `bg.${'canvas' | 'surface' | 'raised' | 'subtle' | 'muted' | 'sunken' | 'inverse' | 'selected' | 'highlighted'}` | 'bg.invalid.subtle' | `fg.${'emphasized' | 'default' | 'muted' | 'subtle' | 'inverse'}` | `border.${'default' | 'subtle' | 'strong'}` | `slate.${0 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 1000 | 1100 | 1200 | 1300 | 1400 | 1500}` | `primary.${'fill' | 'fillStrong'}` | `${'primary' | 'secondary' | 'danger' | 'success' | 'warning'}.${'lightest' | 'extralight' | 'lighter' | 'light' | 'main' | 'dark' | 'darker'}`;
 /**
  * Primitive color palette following the Golden Ratio system.
  *

package/dist/theme/colors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../src/theme/colors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,cAAc;;QAEvB;;;;;;;;;;;;WAYG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyBH;;;;;;;WAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA6BH;;;;;;;WAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyBH;;;;;;;WAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyBH;;;;;;;;;;WAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyBH;;;;;;;;;;WAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAoCD;;;;;;;;;eASG;;;;;;;;;;;;;;;;;;;;;;QAcL;;;;;;;WAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyBH;;;;;;WAMG;;;;;;;;;;;;;;;;;;;;;;CAaG,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAC1B,MACI,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,SAAS,GACT,UAAU,GACV,aAAa,EAAE,GACnB,mBAAmB,GACnB,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,EAAE,GAClD,UAAU,SAAS,GAAG,QAAQ,GAAG,QAAQ,EAAE,GAC3C,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,IACzD,UAAU,GACV,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,EAAE,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,MAAM;IACjB;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;;;;;;;;OAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAqBH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAaH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAaH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgBJ,CAAC"}
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../src/theme/colors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA2DH,eAAO,MAAM,cAAc;;QAEvB;;;;;;;;;;;;WAYG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAqCH;;;;;;;WAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA6BH;;;;;;;WAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyBH;;;;;;;WAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyBH;;;;;;;;;;WAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyBH;;;;;;;;;;;;;;;;;;;WAmBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA+CH;;;;;;;;;;WAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAoDD;;;;;;;;;eASG;;;;;;;;;;;;;;;;;;;;;;QAcL;;;;;;;WAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAyCH;;;;;;WAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoBG,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,GAC1B,MACI,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,SAAS,GACT,UAAU,GACV,aAAa,EAAE,GACnB,mBAAmB,GACnB,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,EAAE,GACjE,UAAU,SAAS,GAAG,QAAQ,GAAG,QAAQ,EAAE,GAI3C,SACI,CAAC,GACD,EAAE,GACF,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,EAAE,GACV,WAAW,MAAM,GAAG,YAAY,EAAE,GAClC,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,IACzD,UAAU,GACV,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,EAAE,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,MAAM;IACjB;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcH;;;;;;;;;;OAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAqBH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAaH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAaH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgBJ,CAAC"}

package/dist/theme/colors.js

@@ -62,6 +62,35 @@
  * <Badge bgColor="success.lightest" color="success.dark" />
  * ```
  */
+/**
+ * Halved-saturation counterpart of each primitive `gray.N` — same hue and
+ * lightness, HSL saturation cut by ~50% (e.g. `gray.1300` #1E2433 @ 26% →
+ * #23262E @ 13%). The blue-tinted `gray` ramp reads as the right neutral in
+ * light mode but turns muddy/over-chromatic as a dark surface, so every
+ * dark-mode neutral below (`slate.*`, and the `_dark` of `bg`/`fg`/`border`)
+ * resolves to this desaturated mirror instead of the raw `gray` step. Light
+ * mode is untouched — it keeps referencing `{colors.gray.*}` verbatim.
+ *
+ * Single source of truth: change a dark neutral here, not at each token.
+ */
+const desaturatedGray = {
+    0: '#FEFEFF',
+    50: '#F8F9FB',
+    100: '#F2F4F7',
+    200: '#E5E8EC',
+    300: '#D2D5DB',
+    400: '#B6BAC3',
+    500: '#A2A6B1',
+    600: '#8E939F',
+    800: '#6A6F7C',
+    900: '#595E6B',
+    1000: '#4A4E5A',
+    1100: '#3C404B',
+    1200: '#30343C',
+    1300: '#23262E',
+    1400: '#181A20',
+    1500: '#0E1014',
+};
 const semanticTokens = {
     colors: {
         /**
@@ -99,6 +128,18 @@ const semanticTokens = {
             darker: {
                 value: { base: '{colors.blue.900}', _dark: '{colors.blue.100}' },
             }, // high-contrast text
+            // Solid brand-blue *fills* for surfaces with white text/icons on top
+            // (modal headers, hero/banner gradients, brand badges). `primary.main`/
+            // `primary.dark` lighten ~2 stops in dark — right for foreground, too
+            // light as a fill — so these stay a deep blue in dark instead. `base`
+            // repeats the old main/dark values, so light is unchanged. Bare accents
+            // (dots, progress bars) keep `primary.main`.
+            fill: {
+                value: { base: '{colors.blue.500}', _dark: '{colors.blue.700}' },
+            },
+            fillStrong: {
+                value: { base: '{colors.blue.700}', _dark: '{colors.blue.800}' },
+            },
         },
         /**
          * Secondary colors (Violet-based)
@@ -231,6 +272,71 @@ const semanticTokens = {
                 value: { base: '{colors.gold.900}', _dark: '{colors.gold.100}' },
             },
         },
+        /**
+         * Neutral tone ramp — a mode-aware companion to the raw `gray.*` primitives.
+         *
+         * Each `slate.N` resolves to `gray.N` in light and to the desaturated
+         * counterpart of the *mirrored* step in dark, so a single token carries the
+         * same visual role in both modes (e.g. `slate.300` is a light divider in
+         * light and the equivalent dark divider in dark — no `_dark={{…}}` needed at
+         * the call site).
+         *
+         * @deprecated **Migration shim, not a blessed vocabulary.** `slate.*` exists
+         * to give code currently styling neutrals with a raw mode-aware ramp a
+         * lossless landing spot, and to be codemodded onto the `fg`/`bg`/`border`
+         * role tokens (e.g. `slate.200`→`border.subtle`, `slate.900`→`fg.muted`,
+         * `slate.800`→`fg.default`). **Do not reach for `slate.*` in new code** —
+         * use a role token. This ramp is slated for removal once consumers migrate.
+         *
+         * `600`/`700` are lifted off the straight mirror (#8E939F/#7C818D) so the
+         * secondary/muted text they most often carry clears WCAG AA 4.5:1 on the
+         * dark canvas/surface — the straight mirrors measured ~3.0–3.9 there.
+         */
+        slate: {
+            0: { value: { base: '{colors.gray.0}', _dark: desaturatedGray[1500] } },
+            50: { value: { base: '{colors.gray.50}', _dark: desaturatedGray[1400] } },
+            100: {
+                value: { base: '{colors.gray.100}', _dark: desaturatedGray[1300] },
+            },
+            200: {
+                value: { base: '{colors.gray.200}', _dark: desaturatedGray[1200] },
+            },
+            300: {
+                value: { base: '{colors.gray.300}', _dark: desaturatedGray[1100] },
+            },
+            400: {
+                value: { base: '{colors.gray.400}', _dark: desaturatedGray[1000] },
+            },
+            500: {
+                value: { base: '{colors.gray.500}', _dark: desaturatedGray[900] },
+            },
+            600: { value: { base: '{colors.gray.600}', _dark: '#898E99' } },
+            700: { value: { base: '{colors.gray.700}', _dark: '#8D919D' } },
+            800: {
+                value: { base: '{colors.gray.800}', _dark: desaturatedGray[600] },
+            },
+            900: {
+                value: { base: '{colors.gray.900}', _dark: desaturatedGray[500] },
+            },
+            1000: {
+                value: { base: '{colors.gray.1000}', _dark: desaturatedGray[400] },
+            },
+            1100: {
+                value: { base: '{colors.gray.1100}', _dark: desaturatedGray[300] },
+            },
+            1200: {
+                value: { base: '{colors.gray.1200}', _dark: desaturatedGray[200] },
+            },
+            1300: {
+                value: { base: '{colors.gray.1300}', _dark: desaturatedGray[100] },
+            },
+            1400: {
+                value: { base: '{colors.gray.1400}', _dark: desaturatedGray[50] },
+            },
+            1500: {
+                value: { base: '{colors.gray.1500}', _dark: desaturatedGray[0] },
+            },
+        },
         /**
          * Neutral background tokens — map onto the gray.0–1500 scale.
          * Use for: page/canvas, raised surfaces (cards, menus), subtle/muted fills,
@@ -243,11 +349,19 @@ const semanticTokens = {
          * - inverse: high-contrast surface (flips to light in dark mode)
          */
         bg: {
+            // Chakra's own global css paints `html { background: bg }` — the *plain*
+            // `bg` token, not `bg.canvas` — so this is the actual page background
+            // wherever no component paints over it. `_light` is pure white (Chakra's
+            // value, so light is untouched); `_dark` rejoins our neutral floor instead
+            // of Chakra's off-palette black.
+            DEFAULT: {
+                value: { _light: '{colors.white}', _dark: desaturatedGray[1500] },
+            },
             canvas: {
-                value: { base: '{colors.gray.0}', _dark: '{colors.gray.1500}' },
+                value: { base: '{colors.gray.0}', _dark: desaturatedGray[1500] },
             },
             surface: {
-                value: { base: '{colors.white}', _dark: '{colors.gray.1400}' },
+                value: { base: '{colors.white}', _dark: desaturatedGray[1400] },
             },
             // Strongly-raised neutral surface — one level above `surface` (e.g. the
             // selected thumb of a SegmentedControl). In dark this is the *lightest*
@@ -259,23 +373,31 @@ const semanticTokens = {
             // cannot be overridden via semanticTokens in this setup (it keeps
             // resolving to Chakra's own gray.200), whereas a fresh name is honoured.
             raised: {
-                value: { base: '{colors.white}', _dark: '{colors.gray.1100}' },
+                value: { base: '{colors.white}', _dark: desaturatedGray[1100] },
             },
             subtle: {
-                value: { base: '{colors.gray.50}', _dark: '{colors.gray.1300}' },
+                value: { base: '{colors.gray.50}', _dark: desaturatedGray[1300] },
             },
             muted: {
-                value: { base: '{colors.gray.100}', _dark: '{colors.gray.1200}' },
+                value: { base: '{colors.gray.100}', _dark: desaturatedGray[1200] },
             },
             inverse: {
-                value: { base: '{colors.gray.1300}', _dark: '{colors.gray.50}' },
+                value: { base: '{colors.gray.1300}', _dark: desaturatedGray[50] },
+            },
+            // Sunken page wash for list/overview surfaces: a gray floor in light so
+            // `bg.surface` cards read as raised above it. In dark the `bg.*` ramp is
+            // compressed (`subtle` sits *lighter* than `surface`), which would invert
+            // that elevation — so the dark value drops to the canvas floor instead.
+            // Component-level fills (hover, chips, inner blocks) keep using `bg.subtle`.
+            sunken: {
+                value: { base: '{colors.gray.50}', _dark: desaturatedGray[1500] },
             },
             // Override Chakra's default `bg.panel` (whose `_dark` resolves to Chakra's
             // own gray.950 = #111111, off our slate palette). Light value is white —
             // identical to Chakra's default — so this only realigns dark overlay
             // surfaces (Menu / Modal / Popover / Toast) onto our gray scale.
             panel: {
-                value: { base: '{colors.white}', _dark: '{colors.gray.1400}' },
+                value: { base: '{colors.white}', _dark: desaturatedGray[1400] },
             },
             /**
              * Row/selection state tints. Use these for selected rows,
@@ -308,26 +430,42 @@ const semanticTokens = {
          * - inverse: text on inverse surfaces (flips with mode)
          */
         fg: {
+            // Plain `fg` is Chakra's html-level text color (`html { color: fg }`).
+            // `_light` repeats Chakra's value (black); `_dark` rejoins our desaturated
+            // neutral so legacy html-level text tracks `fg.default`.
+            DEFAULT: {
+                value: { _light: '{colors.black}', _dark: desaturatedGray[50] },
+            },
+            // Strongest text — headings, titles, key figures, emphasis. This is the
+            // near-black step that `fg.default` used to be; `default` is now re-pegged
+            // to a lighter body weight (see below), so reach for `emphasized` when you
+            // specifically want maximum contrast.
+            emphasized: {
+                value: { base: '{colors.gray.1300}', _dark: desaturatedGray[200] },
+            },
             default: {
-                // _dark is gray.200 (not gray.50): near-white text on the dark canvas
-                // ran ~18:1 — brighter than the light baseline (~15:1) and close to pure
-                // white, which causes glare/halation. gray.200 matches the light
-                // contrast (~15.4:1) while staying AAA.
-                value: { base: '{colors.gray.1300}', _dark: '{colors.gray.200}' },
+                // Primary *body* text. Re-pegged from gray.1300 → gray.1000: near-black
+                // (gray.1300, ~14:1 on white) is unusually heavy for running copy, and
+                // real product usage clustered well below it. gray.1000 (~9:1) is a
+                // comfortable AAA body weight; the old near-black step lives on as
+                // `fg.emphasized`. _dark drops one step from emphasized for hierarchy.
+                value: { base: '{colors.gray.1000}', _dark: desaturatedGray[300] },
             },
             muted: {
-                // _dark lifts gray.400 → gray.300: secondary text read as too dim on the
-                // dark canvas next to fg.default (gray.200). gray.300 sits one step under
-                // default — restoring the light-mode hierarchy gap — while staying well
-                // clear of AA (~12.8:1 on bg.canvas, ~11.7:1 on bg.surface). Light value
-                // (gray.900) is unchanged.
-                value: { base: '{colors.gray.900}', _dark: '{colors.gray.300}' },
+                // Secondary text. _dark sits one step below `default` (~9.5:1 on the dark
+                // canvas) to keep the default→muted hierarchy gap. Light value (gray.900)
+                // is unchanged.
+                value: { base: '{colors.gray.900}', _dark: desaturatedGray[400] },
             },
             subtle: {
-                value: { base: '{colors.gray.700}', _dark: '{colors.gray.600}' },
+                // Tertiary / placeholder / icon text. _dark a11y-bumped from the straight
+                // mirror (desaturatedGray[600] #8E939F, ~4.06:1 on bg.muted) to #989DA9
+                // (~4.6:1) so it clears AA while staying below fg.muted. Light value
+                // (gray.700) is unchanged.
+                value: { base: '{colors.gray.700}', _dark: '#989DA9' },
             },
             inverse: {
-                value: { base: '{colors.gray.0}', _dark: '{colors.gray.1400}' },
+                value: { base: '{colors.gray.0}', _dark: desaturatedGray[1400] },
             },
         },
         /**
@@ -338,14 +476,21 @@ const semanticTokens = {
          * - strong: high-emphasis borders, focus outlines on neutral
          */
         border: {
+            // Plain `border` feeds Chakra's `--global-color-border` (the implicit
+            // default border color). Not a text color, so its `_dark` takes the
+            // straight halved-saturation mirror (no a11y bump). `_light` repeats
+            // Chakra's value so light is untouched.
+            DEFAULT: {
+                value: { _light: '{colors.gray.200}', _dark: desaturatedGray[800] },
+            },
             default: {
-                value: { base: '{colors.gray.300}', _dark: '{colors.gray.1100}' },
+                value: { base: '{colors.gray.300}', _dark: desaturatedGray[1100] },
             },
             subtle: {
-                value: { base: '{colors.gray.200}', _dark: '{colors.gray.1300}' },
+                value: { base: '{colors.gray.200}', _dark: desaturatedGray[1300] },
             },
             strong: {
-                value: { base: '{colors.gray.500}', _dark: '{colors.gray.900}' },
+                value: { base: '{colors.gray.500}', _dark: desaturatedGray[900] },
             },
         },
     },