refactor(tokens): DLT-3013 convert color system from HSL to OKLCH (#1060)

Author: francisrupert

.claude/rules/css-utilities.md

@@ -25,6 +25,16 @@ Color utilities use semantic tokens, not base palette stops:
 
 Prefer semantic equivalents over base color utilities (e.g., `d-fc-critical` instead of `d-fc-red-600`). The ESLint rule `deprecated-base-color-classes` flags base color utility usage.
 
+Generated color utilities use OKLCH relative color syntax for opacity support:
+
+```css
+.d-fc-primary { color: oklch(from var(--dt-color-foreground-primary) l c h / var(--fco, alpha)) !important; }
+```
+
+The `alpha` keyword preserves the source color's opacity when no opacity utility is applied. Opacity utilities (e.g., `d-fco50`) set the `--fco` / `--bgo` / `--bco` custom property to override it.
+
+HSL channel variables (`--dt-color-*-h`, `-s`, `-l`, `-hsl`, `-hsla`) no longer exist.
+
 ## Token References — Mandatory
 
 ALWAYS use `var(--dt-*)` custom properties. Never hardcode raw values.

.claude/rules/design-tokens.md

@@ -24,6 +24,10 @@ These produce CSS custom properties: `--dt-color-foreground-primary`, `--dt-spac
 All base colors use a standard 12-stop scale: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950, 1000.
 Irregular stops (250, 350, 425, etc.) were removed in the Feb 2026 migration. Do not create tokens referencing irregular stops.
 
+## Color Space
+
+Base color token values use OKLCH format: `oklch(L C H)` (e.g., `oklch(0.6464 0.1985 289.97)`). Previous hex/HSL values were refactored to OKLCH in Feb 2026. HSL channel decomposition variables (`-h`, `-s`, `-l`, `-hsl`, `-hsla` suffixes) no longer exist — do not reference them.
+
 ## Dark Mode
 
 Values in `dark.json` override `default.json`. When adding/editing a token, ensure `dark.json` has the corresponding override with the appropriate dark palette reference.

.claude/skills/component.md

@@ -31,6 +31,7 @@ export * from './<name>_constants';
 ```
 
 **Optional files for complex components:**
+
 - **`utils.js`** — Utility/helper functions specific to this component
 - **`validators.js`** — Custom prop or value validators
 - **`modules/`** — Directory for sub-components (e.g. emoji_picker has `emoji_search.vue`, `emoji_selector.vue`)

.claude/skills/dt-migrate.md

@@ -11,20 +11,25 @@ description: "Run Dialtone migration tools for token and utility renames. Use '/
 | `color-stops` | Renames irregular color stops (250, 350, 425, etc.) to standard 12-stop scale | `npx dialtone-migration-helper` → "color stops" |
 | `base-to-semantic` | Replaces base color utilities and CSS tokens with semantic equivalents | `npx dialtone-migration-helper` → "base to semantic" |
 | `space-to-size` | Renames `var(--dt-space-*)` to `var(--dt-size-*)` | `npx dialtone-migration-helper` → "space to size" |
+| `hsl-to-oklch` | Migrates consumer HSL channel variable patterns to OKLCH relative color syntax or plain `var()` | `npx dialtone-migration-helper` → "hsl to oklch" |
 
 ## Usage
 
 ### `/dt-migrate`
+
 List all available migrations with descriptions.
 
 ### `/dt-migrate <name>`
+
 Run the specified migration:
+
 1. Confirm the target directory with the user (default: `./src`)
 2. Run `npx dialtone-migration-helper --cwd <dir>` and select the named config
 3. Report the number of files changed and matches replaced
 4. Suggest running linters after migration to catch remaining manual fixes
 
 ### `/dt-migrate <name> --dry-run`
+
 Preview changes without applying them.
 
 ### `/dt-migrate color-stops --merge-from staging`
@@ -55,6 +60,7 @@ node scripts/merge-migrate-color-stops.mjs --merge-from staging --dry-run --verb
 > Note: `scripts/merge-migrate-color-stops.mjs` is a temporary script for the staging→next migration period. Delete it once the migration is complete.
 
 ## Migration Helper Location
+
 Configs: `packages/dialtone-css/lib/build/js/dialtone_migration_helper/configs/`
 Tests: `packages/dialtone-css/lib/build/js/dialtone_migration_helper/tests/`
 

.claude/skills/token.md

@@ -59,3 +59,4 @@ After creating or updating tokens:
 - If tokens are edited manually (not via Figma sync), `sync:tokens-to-figma` may be needed to push changes back to Figma
 - The `$metadata.json` file defines the build order for 137 token sets — do not modify this without understanding the dependency chain
 - Component tokens should reference semantic tokens, not base palette tokens directly, to ensure theme compatibility
+- Base color token values use OKLCH format (`oklch(L C H)`), not hex or HSL. HSL channel decomposition (`-h`, `-s`, `-l` suffix variables) was removed — tokens output only the base variable now.

.claude/skills/utility.md

@@ -70,3 +70,4 @@ After creating or updating a utility:
 - The CSS package ships as one monolithic file — every utility is included regardless of usage
 - PurgeCSS (shipped as a Dialtone PostCSS plugin) is the recommended approach for tree-shaking unused utilities in consuming projects
 - When adding utilities that pair with component styles, coordinate with the component skill to ensure consistency
+- Color utilities are generated using OKLCH relative color syntax (`oklch(from var(...) l c h / var(--opacity-var, alpha))`). When debugging color utility output, expect this format rather than raw `var()` references. See `postcss/dialtone-generators.cjs` for the generation logic.

apps/dialtone-documentation/docs/.vuepress/baseComponents/BaseColor.vue

@@ -1,63 +1,62 @@
 <template>
-  <dt-stack as="aside">
-    <dt-stack v-if="stops.length" as="header" direction="row" justify="between">
-      <h4
-        class="d-docsite--header-3 d-tt-capitalize"
+  <dt-stack as="aside" gap="300">
+    <dt-stack v-if="stops.length" as="header" direction="row" justify="between" align="baseline">
+      <dt-text
+        as="h4"
+        kind="headline"
+        size="lg"
+        class="d-tt-capitalize"
+        text-box-trim="start"
         tabindex="-1"
-        v-text="colorName"
-      />
+      >
+        {{ colorName }}
+      </dt-text>
+      <dt-text
+        v-dt-tooltip="`Lightness Contrast (APCA) against either pure white or black. 60 is considered AA accessible.`"
+        as="abbr"
+        tabindex="0"
+        text-box-trim="start"
+        class="d-px12 d-td-dotted d-c-help"
+      >
+        LC
+      </dt-text>
     </dt-stack>
-    <div
-      v-for="(stop, index) in stops"
-      :key="`${colorName}-${index}`"
-      :class="[
-        'd-d-flex d-jc-space-between d-ai-center d-px12 d-py8 d-code--sm',
-        {
-          'd-btr4': index === 0,
-          'd-bbr4': index === (stops.length - 1),
-        },
-      ]"
-      :style="`background-color: ${stop.value}`"
-    >
-      <div :class="fontColorClass(stop.primaryContrast, stop.invertedContrast)">
-        <strong v-text="`var(--dt-color-${colorName}-${stop.stop})`" />
-        <br>
-        <span v-text="stop.value" />
-      </div>
-      <dt-stack class="d-fs-100 d-lh2 d-fw-bold d-bar-sm d-px4 py2">
-        <span
-          v-if="stop.primaryContrast >= minAAContrastRatio"
-          :class="fontColorMap[mode].primary"
-          v-text="formattedContrast(stop.primaryContrast)"
-        />
-        <span
-          v-if="stop.invertedContrast >= minAAContrastRatio"
-          :class="fontColorMap[mode].inverted"
-          v-text="formattedContrast(stop.invertedContrast)"
-        />
+    <dt-stack>
+      <dt-stack
+        v-for="(stop, index) in stops"
+        :key="`${colorName}-${index}`"
+        direction="row"
+        align="center"
+        justify="space-between"
+        :class="[
+          'd-px12 d-py8 d-text-code--xs',
+          {
+            'd-btr4': index === 0,
+            'd-bbr4': index === (stops.length - 1),
+          },
+        ]"
+        :style="`background-color: ${stop.value}`"
+      >
+        <dt-stack gap="300" :class="fontColorClass(stop.lightness)">
+          <dt-text as="strong" class="d-us-all">
+            {{ `var(--dt-color-${colorName}-${stop.stop})` }}
+          </dt-text>
+          <dt-text class="d-o75 d-us-all">
+            {{ stop.value }}
+          </dt-text>
+        </dt-stack>
+        <dt-text
+          strength="bold"
+          :class="fontColorClass(stop.lightness)"
+        >
+          {{ formattedContrast(activeContrast(stop)) }}
+        </dt-text>
       </dt-stack>
-    </div>
+    </dt-stack>
   </dt-stack>
 </template>
 
 <script setup>
-const minAAContrastRatio = 4;
-const minAAAContrastRatio = 7;
-
-// Using neutral colors instead of primary, primary-inverted to make it easier to
-// implement this, as the primary color change based on theme, it was being pretty complex
-// to keep the text colors matching.
-const fontColorMap = {
-  light: {
-    primary: 'd-fc-neutral-black',
-    inverted: 'd-fc-neutral-white',
-  },
-  dark: {
-    primary: 'd-fc-neutral-white',
-    inverted: 'd-fc-neutral-black',
-  },
-};
-
 const props = defineProps({
   stops: {
     type: Array,
@@ -73,13 +72,23 @@ const props = defineProps({
   },
 });
 
-function fontColorClass (primaryContrast, invertedContrast) {
-  return primaryContrast > invertedContrast
-    ? fontColorMap[props.mode].primary
-    : fontColorMap[props.mode].inverted;
+const LIGHTNESS_THRESHOLD = 0.65;
+
+function fontColorClass (lightness) {
+  return lightness >= LIGHTNESS_THRESHOLD
+    ? 'd-fc-neutral-black'
+    : 'd-fc-neutral-white';
+}
+function activeContrast (stop) {
+  const useBlackText = stop.lightness >= LIGHTNESS_THRESHOLD;
+  // In light mode: primary = black contrast, inverted = white contrast
+  // In dark mode: primary = white contrast, inverted = black contrast
+  if (props.mode === 'light') {
+    return useBlackText ? stop.primaryContrast : stop.invertedContrast;
+  }
+  return useBlackText ? stop.invertedContrast : stop.primaryContrast;
 }
 function formattedContrast (contrast) {
-  const contrastGrade = contrast >= minAAAContrastRatio ? 'AAA' : (contrast >= minAAContrastRatio ? 'AA' : 'A');
-  return `${contrastGrade} ${contrast}`;
+  return `${Math.ceil(contrast)}`;
 }
 </script>

apps/dialtone-documentation/docs/.vuepress/common/utilities.js

@@ -71,9 +71,10 @@ export function extractUtilityClasses (utilityClassDocs, prefix) {
 }
 
 export function extractCSSVariableName (propValue) {
-  const variable = Object.values(propValue.values)[0].value;
-  if (!variable.startsWith('var(')) return;
-  return variable.replace('var(', '').replace(/(-[hsla])?\).*/, '');
+  const value = Object.values(propValue.values)[0].value;
+  const match = value.match(/var\((--[\w-]+)\)/);
+  if (!match) return;
+  return match[1].replace(/(-(h|s|c|l|a|hsl|hsla|oklch|oklcha))$/, '');
 }
 
 /**

apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less

@@ -558,7 +558,7 @@ code {
 
     &:hover,
     .dialtone-icon-card[data-selected='yes'] & {
-      background-color: hsl(var(--dt-color-neutral-black-h), var(--dt-color-neutral-black-s), var(--dt-color-neutral-black-l), 0.8);
+      background-color: oklch(from var(--dt-color-neutral-black) l c h / 0.8);
     }
 
     .dialtone-icon-card__name {
@@ -571,7 +571,7 @@ code {
 
     &:hover,
     .dialtone-icon-card[data-selected='yes'] & {
-      background-color: hsl(0deg, 0%, 91.37%, 0.4);
+      background-color: oklch(0.934 0 0deg / 0.4);
     }
 
     .dialtone-icon-card__name {
@@ -584,7 +584,7 @@ code {
 
     &:hover,
     .dialtone-icon-card[data-selected='yes'] & {
-      background-color: hsl(var(--dt-color-black-900-h), var(--dt-color-black-900-s), var(--dt-color-black-900-l), 0.8);
+      background-color: oklch(from var(--dt-color-black-900) l c h / 0.8);
     }
 
     .dialtone-icon-card__name {
@@ -710,6 +710,7 @@ code {
 .dialtone-page-title {
   font: var(--dt-text-headline-3xl);
   margin-block-end: var(--dt-size-400);
+  text-wrap: pretty;
 }
 
 //  ============================================================================