Refactor base color ramp to fixed-lightness OKLCH with mode-adaptive interactions

CHANGELOG.md

@@ -4,6 +4,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## Unreleased
 
+### ⚠️ Breaking Changes
+- **tokens:** remove the six `base` relative shade aliases (`--sf-color-base-superlight`, `-xlight`, `-lighter`, `-darker`, `-xdark`, `-superdark`). `base` is an absolute scale, so direction-named aliases were misleading (e.g. `-lighter` resolved darker than a near-white base in light mode). Use the numeric ramp (`--sf-color-base-50`…`-950`) for fixed shades, or the surface tokens (`--sf-color-bg` / `-inset` / `-raised`) for mode-adaptive elevation. See `docs/migration.md`.
+
 ## [0.6.25] - 2026-06-29
 
 ### Features

badges/badge-optimal.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "label": "optimal",
-  "message": "17.6 kB gzip",
+  "message": "17.5 kB gzip",
   "color": "brightgreen",
   "namedLogo": "css3"
 }

configurator/src/data/api-index.generated.json

@@ -2,23 +2,23 @@
   "_sync": {
     "generatedBy": "configurator/scripts/sync-api.mjs",
     "source": "docs/api-index.json",
-    "tokensHash": "99d86a47c17a",
+    "tokensHash": "a6a2fe9aab66",
     "bundles": [
       "full",
       "optimal",
       "optimal-components",
       "optimal-utilities"
     ],
     "counts": {
-      "tokens": 691,
+      "tokens": 685,
       "byTier": {
-        "PUBLIC": 635,
+        "PUBLIC": 629,
         "PUBLIC-ADVANCED": 55,
         "INTERNAL": 1
       },
       "byCategory": {
         "Layout tokens": 54,
-        "Core tokens": 608,
+        "Core tokens": 602,
         "Macro tokens": 23,
         "Component tokens": 6
       }
@@ -2236,8 +2236,8 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Base color at pressed/active brightness.",
-      "value": "var(--sf-color-base-xdark)",
-      "aliasOf": "--sf-color-base-xdark",
+      "value": "oklch(from var(--sf-color-base) clamp(0.01, calc(l - 0.08 + var(--sf-is-dark) * 0.16), 0.99) c h)",
+      "aliasOf": null,
       "registered": false,
       "syntax": null,
       "fallbackOnly": false,
@@ -2259,8 +2259,8 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Base color at hover brightness.",
-      "value": "var(--sf-color-base-darker)",
-      "aliasOf": "--sf-color-base-darker",
+      "value": "oklch(from var(--sf-color-base) clamp(0.01, calc(l - 0.04 + var(--sf-is-dark) * 0.08), 0.99) c h)",
+      "aliasOf": null,
       "registered": false,
       "syntax": null,
       "fallbackOnly": false,
@@ -2282,7 +2282,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Very light base shade. Hover fills, badge backgrounds.",
-      "value": "color-mix(in oklab, var(--sf-color-text) var(--sf-palette-mix-100), var(--sf-color-base))",
+      "value": "oklch(from var(--sf-color-base) 0.94 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2305,7 +2305,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Light base shade.",
-      "value": "color-mix(in oklab, var(--sf-color-text) var(--sf-palette-mix-200), var(--sf-color-base))",
+      "value": "oklch(from var(--sf-color-base) 0.88 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2328,7 +2328,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Light-mid base shade. Borders on light backgrounds.",
-      "value": "color-mix(in oklab, var(--sf-color-text) var(--sf-palette-mix-300), var(--sf-color-base))",
+      "value": "oklch(from var(--sf-color-base) 0.78 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2351,7 +2351,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Mid-light base shade. Disabled fills.",
-      "value": "color-mix(in oklab, var(--sf-color-text) var(--sf-palette-mix-400), var(--sf-color-base))",
+      "value": "oklch(from var(--sf-color-base) 0.65 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2374,7 +2374,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Lightest base tint.",
-      "value": "color-mix(in oklab, var(--sf-color-text) var(--sf-palette-mix-50), var(--sf-color-base))",
+      "value": "oklch(from var(--sf-color-base) 0.97 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2397,8 +2397,8 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Mid base shade — the 'pure' hue.",
-      "value": "var(--sf-color-base)",
-      "aliasOf": "--sf-color-base",
+      "value": "oklch(from var(--sf-color-base) 0.50 c h)",
+      "aliasOf": null,
       "registered": false,
       "syntax": null,
       "fallbackOnly": false,
@@ -2420,7 +2420,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Mid-dark base shade. Text on light surfaces.",
-      "value": "color-mix(in oklab, var(--sf-color-base) var(--sf-palette-mix-600), var(--sf-color-text))",
+      "value": "oklch(from var(--sf-color-base) 0.37 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2443,7 +2443,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Dark base shade.",
-      "value": "color-mix(in oklab, var(--sf-color-base) var(--sf-palette-mix-700), var(--sf-color-text))",
+      "value": "oklch(from var(--sf-color-base) 0.27 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2466,7 +2466,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Very dark base shade.",
-      "value": "color-mix(in oklab, var(--sf-color-base) var(--sf-palette-mix-800), var(--sf-color-text))",
+      "value": "oklch(from var(--sf-color-base) 0.17 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2489,7 +2489,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Near-black base shade.",
-      "value": "color-mix(in oklab, var(--sf-color-base) var(--sf-palette-mix-900), var(--sf-color-text))",
+      "value": "oklch(from var(--sf-color-base) 0.11 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2512,7 +2512,7 @@
       "group": "base",
       "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
       "note": "Darkest base tint.",
-      "value": "color-mix(in oklab, var(--sf-color-base) var(--sf-palette-mix-950), var(--sf-color-text))",
+      "value": "oklch(from var(--sf-color-base) 0.06 c h)",
       "aliasOf": null,
       "registered": false,
       "syntax": null,
@@ -2641,29 +2641,6 @@
         "optimal-utilities"
       ]
     },
-    {
-      "name": "--sf-color-base-darker",
-      "tier": "PUBLIC",
-      "role": "consumption",
-      "namespace": "color",
-      "category": "Core tokens",
-      "group": "base",
-      "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
-      "note": "Deep base shade.",
-      "value": "var(--sf-color-base-600)",
-      "aliasOf": "--sf-color-base-600",
-      "registered": false,
-      "syntax": null,
-      "fallbackOnly": false,
-      "optional": false,
-      "layer": "slashed.tokens",
-      "bundles": [
-        "full",
-        "optimal",
-        "optimal-components",
-        "optimal-utilities"
-      ]
-    },
     {
       "name": "--sf-color-base-ghost",
       "tier": "PUBLIC",
@@ -2687,29 +2664,6 @@
         "optimal-utilities"
       ]
     },
-    {
-      "name": "--sf-color-base-lighter",
-      "tier": "PUBLIC",
-      "role": "consumption",
-      "namespace": "color",
-      "category": "Core tokens",
-      "group": "base",
-      "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
-      "note": "Light base shade.",
-      "value": "var(--sf-color-base-400)",
-      "aliasOf": "--sf-color-base-400",
-      "registered": false,
-      "syntax": null,
-      "fallbackOnly": false,
-      "optional": false,
-      "layer": "slashed.tokens",
-      "bundles": [
-        "full",
-        "optimal",
-        "optimal-components",
-        "optimal-utilities"
-      ]
-    },
     {
       "name": "--sf-color-base-muted",
       "tier": "PUBLIC",
@@ -2802,98 +2756,6 @@
         "optimal-utilities"
       ]
     },
-    {
-      "name": "--sf-color-base-superdark",
-      "tier": "PUBLIC",
-      "role": "consumption",
-      "namespace": "color",
-      "category": "Core tokens",
-      "group": "base",
-      "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
-      "note": "Near-black base shade.",
-      "value": "var(--sf-color-base-950)",
-      "aliasOf": "--sf-color-base-950",
-      "registered": false,
-      "syntax": null,
-      "fallbackOnly": false,
-      "optional": false,
-      "layer": "slashed.tokens",
-      "bundles": [
-        "full",
-        "optimal",
-        "optimal-components",
-        "optimal-utilities"
-      ]
-    },
-    {
-      "name": "--sf-color-base-superlight",
-      "tier": "PUBLIC",
-      "role": "consumption",
-      "namespace": "color",
-      "category": "Core tokens",
-      "group": "base",
-      "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
-      "note": "Near-white base shade.",
-      "value": "var(--sf-color-base-50)",
-      "aliasOf": "--sf-color-base-50",
-      "registered": false,
-      "syntax": null,
-      "fallbackOnly": false,
-      "optional": false,
-      "layer": "slashed.tokens",
-      "bundles": [
-        "full",
-        "optimal",
-        "optimal-components",
-        "optimal-utilities"
-      ]
-    },
-    {
-      "name": "--sf-color-base-xdark",
-      "tier": "PUBLIC",
-      "role": "consumption",
-      "namespace": "color",
-      "category": "Core tokens",
-      "group": "base",
-      "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
-      "note": "Extra-dark base shade.",
-      "value": "var(--sf-color-base-800)",
-      "aliasOf": "--sf-color-base-800",
-      "registered": false,
-      "syntax": null,
-      "fallbackOnly": false,
-      "optional": false,
-      "layer": "slashed.tokens",
-      "bundles": [
-        "full",
-        "optimal",
-        "optimal-components",
-        "optimal-utilities"
-      ]
-    },
-    {
-      "name": "--sf-color-base-xlight",
-      "tier": "PUBLIC",
-      "role": "consumption",
-      "namespace": "color",
-      "category": "Core tokens",
-      "group": "base",
-      "description": "Semantic base-color scale derived from --sf-color-base. Covers fills, hover/active states, and ghost variants for secondary interactive elements.",
-      "note": "Extra-light base shade.",
-      "value": "var(--sf-color-base-200)",
-      "aliasOf": "--sf-color-base-200",
-      "registered": false,
-      "syntax": null,
-      "fallbackOnly": false,
-      "optional": false,
-      "layer": "slashed.tokens",
-      "bundles": [
-        "full",
-        "optimal",
-        "optimal-components",
-        "optimal-utilities"
-      ]
-    },
     {
       "name": "--sf-color-bg",
       "tier": "PUBLIC",

configurator/src/data/token-registry.generated.json

@@ -449,7 +449,8 @@
     },
     {
       "id": 110,
-      "name": "--sf-color-base-darker"
+      "name": "--sf-color-base-darker",
+      "removed": true
     },
     {
       "id": 111,
@@ -461,7 +462,8 @@
     },
     {
       "id": 113,
-      "name": "--sf-color-base-lighter"
+      "name": "--sf-color-base-lighter",
+      "removed": true
     },
     {
       "id": 114,
@@ -473,19 +475,23 @@
     },
     {
       "id": 116,
-      "name": "--sf-color-base-superdark"
+      "name": "--sf-color-base-superdark",
+      "removed": true
     },
     {
       "id": 117,
-      "name": "--sf-color-base-superlight"
+      "name": "--sf-color-base-superlight",
+      "removed": true
     },
     {
       "id": 118,
-      "name": "--sf-color-base-xdark"
+      "name": "--sf-color-base-xdark",
+      "removed": true
     },
     {
       "id": 119,
-      "name": "--sf-color-base-xlight"
+      "name": "--sf-color-base-xlight",
+      "removed": true
     },
     {
       "id": 120,