@ankhorage/zora 0.15.1 → 0.15.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.15.4
+
+### Patch Changes
+
+- 32e7814: chore(release): trigger
+
+## 0.15.3
+
+### Patch Changes
+
+- 4751b68: feat(theme): add internal semantic color token selection from role scales
+
+## 0.15.2
+
+### Patch Changes
+
+- e91aaf1: update @ankhorage/contracts
+
 ## 0.15.1
 
 ### Patch Changes

package/dist/internal/color/index.d.ts

@@ -5,5 +5,6 @@ export { resolveModePrimaryColor } from './primary';
 export { assignZoraHarmonyRoleHues, getZoraHueRoleAssignment, type ZoraComputedHueRoles, type ZoraHueRoleAssignment, type ZoraHueRoleId, } from './roleHues';
 export { createZoraRoleColorScales, getZoraRoleColorScale, ZORA_COLOR_SCALE_ROLE_ORDER, type ZoraColorScaleRoleId, type ZoraComputedRoleColorScales, type ZoraRoleColorScale, } from './roleScales';
 export { createZoraColorScale, type CreateZoraColorScaleOptions, type CreateZoraHueScaleOptions, createZoraNeutralScale, createZoraPrimaryScale, type ZoraHueScaleRoleId, } from './scales';
+export { createZoraSemanticColorTokens, getReadableTextColor, type ZoraSemanticColorTokens, } from './semanticTokens';
 export { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/internal/color/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,gCAAgC,EAChC,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,GACpC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,sBAAsB,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,gCAAgC,EAChC,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,GACpC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,KAAK,uBAAuB,GAC7B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC"}

package/dist/internal/color/index.js

@@ -5,5 +5,6 @@ export { resolveModePrimaryColor } from './primary';
 export { assignZoraHarmonyRoleHues, getZoraHueRoleAssignment, } from './roleHues';
 export { createZoraRoleColorScales, getZoraRoleColorScale, ZORA_COLOR_SCALE_ROLE_ORDER, } from './roleScales';
 export { createZoraColorScale, createZoraNeutralScale, createZoraPrimaryScale, } from './scales';
+export { createZoraSemanticColorTokens, getReadableTextColor, } from './semanticTokens';
 export { ZORA_COLOR_SCALE_STEPS } from './types';
 //# sourceMappingURL=index.js.map

package/dist/internal/color/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,gCAAgC,GAIjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,GAInB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,wBAAwB,GAIzB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,GAI5B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EAGpB,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,sBAAsB,EAAgD,MAAM,SAAS,CAAC","sourcesContent":["export {\n  getZoraColorToneRecipe,\n  getZoraColorToneRoleChromaFactor,\n  type ZoraColorToneLaneRecipe,\n  type ZoraColorToneRecipe,\n  type ZoraColorToneRoleChromaFactors,\n} from './colorToneRecipes';\nexport {\n  computeZoraHarmony,\n  type ZoraComputedHarmony,\n  type ZoraHarmonySlot,\n  type ZoraHarmonySlotId,\n} from './harmony';\nexport { parseHexToOklch } from './oklch';\nexport { resolveModePrimaryColor } from './primary';\nexport {\n  assignZoraHarmonyRoleHues,\n  getZoraHueRoleAssignment,\n  type ZoraComputedHueRoles,\n  type ZoraHueRoleAssignment,\n  type ZoraHueRoleId,\n} from './roleHues';\nexport {\n  createZoraRoleColorScales,\n  getZoraRoleColorScale,\n  ZORA_COLOR_SCALE_ROLE_ORDER,\n  type ZoraColorScaleRoleId,\n  type ZoraComputedRoleColorScales,\n  type ZoraRoleColorScale,\n} from './roleScales';\nexport {\n  createZoraColorScale,\n  type CreateZoraColorScaleOptions,\n  type CreateZoraHueScaleOptions,\n  createZoraNeutralScale,\n  createZoraPrimaryScale,\n  type ZoraHueScaleRoleId,\n} from './scales';\nexport { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,gCAAgC,GAIjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,GAInB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,wBAAwB,GAIzB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,GAI5B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EAGpB,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,GAErB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAgD,MAAM,SAAS,CAAC","sourcesContent":["export {\n  getZoraColorToneRecipe,\n  getZoraColorToneRoleChromaFactor,\n  type ZoraColorToneLaneRecipe,\n  type ZoraColorToneRecipe,\n  type ZoraColorToneRoleChromaFactors,\n} from './colorToneRecipes';\nexport {\n  computeZoraHarmony,\n  type ZoraComputedHarmony,\n  type ZoraHarmonySlot,\n  type ZoraHarmonySlotId,\n} from './harmony';\nexport { parseHexToOklch } from './oklch';\nexport { resolveModePrimaryColor } from './primary';\nexport {\n  assignZoraHarmonyRoleHues,\n  getZoraHueRoleAssignment,\n  type ZoraComputedHueRoles,\n  type ZoraHueRoleAssignment,\n  type ZoraHueRoleId,\n} from './roleHues';\nexport {\n  createZoraRoleColorScales,\n  getZoraRoleColorScale,\n  ZORA_COLOR_SCALE_ROLE_ORDER,\n  type ZoraColorScaleRoleId,\n  type ZoraComputedRoleColorScales,\n  type ZoraRoleColorScale,\n} from './roleScales';\nexport {\n  createZoraColorScale,\n  type CreateZoraColorScaleOptions,\n  type CreateZoraHueScaleOptions,\n  createZoraNeutralScale,\n  createZoraPrimaryScale,\n  type ZoraHueScaleRoleId,\n} from './scales';\nexport {\n  createZoraSemanticColorTokens,\n  getReadableTextColor,\n  type ZoraSemanticColorTokens,\n} from './semanticTokens';\nexport { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';\n"]}

package/dist/internal/color/semanticTokens.d.ts

@@ -0,0 +1,28 @@
+import type { ZoraColorTone, ZoraHexColor, ZoraThemeMode } from '../../theme/types';
+import { type ZoraComputedRoleColorScales } from './roleScales';
+export interface ZoraSemanticColorTokens {
+    background: ZoraHexColor;
+    surface: ZoraHexColor;
+    surfaceRaised: ZoraHexColor;
+    surfaceTint: ZoraHexColor;
+    border: ZoraHexColor;
+    text: ZoraHexColor;
+    textMuted: ZoraHexColor;
+    primary: ZoraHexColor;
+    secondary: ZoraHexColor;
+    accent: ZoraHexColor;
+    highlight: ZoraHexColor;
+    onPrimary: ZoraHexColor;
+    onAccent: ZoraHexColor;
+}
+/**
+ * Selects the more readable of two candidate hex colors against a given background,
+ * using OKLCH lightness as a simple contrast proxy.
+ */
+export declare function getReadableTextColor(background: ZoraHexColor, candidates: readonly [ZoraHexColor, ZoraHexColor]): ZoraHexColor;
+export declare function createZoraSemanticColorTokens(options: {
+    roleScales: ZoraComputedRoleColorScales;
+    mode: ZoraThemeMode;
+    colorTone: ZoraColorTone;
+}): ZoraSemanticColorTokens;
+//# sourceMappingURL=semanticTokens.d.ts.map

package/dist/internal/color/semanticTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticTokens.d.ts","sourceRoot":"","sources":["../../../src/internal/color/semanticTokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEpF,OAAO,EAAyB,KAAK,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAEvF,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,YAAY,CAAC;IACzB,OAAO,EAAE,YAAY,CAAC;IACtB,aAAa,EAAE,YAAY,CAAC;IAC5B,WAAW,EAAE,YAAY,CAAC;IAC1B,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,YAAY,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,YAAY,CAAC;IACxB,SAAS,EAAE,YAAY,CAAC;IACxB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,YAAY,EACxB,UAAU,EAAE,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC,GAChD,YAAY,CAMd;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE;IACrD,UAAU,EAAE,2BAA2B,CAAC;IACxC,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,aAAa,CAAC;CAC1B,GAAG,uBAAuB,CA0E1B"}

package/dist/internal/color/semanticTokens.js

@@ -0,0 +1,84 @@
+import { parseHexToOklch } from './oklch';
+import { getZoraRoleColorScale } from './roleScales';
+/**
+ * Selects the more readable of two candidate hex colors against a given background,
+ * using OKLCH lightness as a simple contrast proxy.
+ */
+export function getReadableTextColor(background, candidates) {
+    const bgL = parseHexToOklch(background).l;
+    const [a, b] = candidates;
+    const diffA = Math.abs(parseHexToOklch(a).l - bgL);
+    const diffB = Math.abs(parseHexToOklch(b).l - bgL);
+    return diffA >= diffB ? a : b;
+}
+export function createZoraSemanticColorTokens(options) {
+    // colorTone is accepted now and reserved for future per-tone step overrides
+    // (e.g. obsidian/pastel may shift surface selections differently).
+    const { roleScales, mode } = options;
+    const neutral = getZoraRoleColorScale(roleScales, 'neutral').scale;
+    const surfaceTintScale = getZoraRoleColorScale(roleScales, 'surfaceTint').scale;
+    const primaryScale = getZoraRoleColorScale(roleScales, 'primary').scale;
+    const secondaryScale = getZoraRoleColorScale(roleScales, 'secondary').scale;
+    const accentScale = getZoraRoleColorScale(roleScales, 'accent').scale;
+    const highlightScale = getZoraRoleColorScale(roleScales, 'highlight').scale;
+    if (mode === 'light') {
+        const background = neutral[50];
+        const surface = neutral[100];
+        const surfaceRaised = neutral[50];
+        const surfaceTint = surfaceTintScale[100];
+        const border = neutral[200];
+        const text = neutral[900];
+        const textMuted = neutral[700];
+        const primary = primaryScale[600];
+        const secondary = secondaryScale[600];
+        const accent = accentScale[600];
+        const highlight = highlightScale[600];
+        const onPrimary = getReadableTextColor(primary, [neutral[50], neutral[950]]);
+        const onAccent = getReadableTextColor(accent, [neutral[50], neutral[950]]);
+        return {
+            background,
+            surface,
+            surfaceRaised,
+            surfaceTint,
+            border,
+            text,
+            textMuted,
+            primary,
+            secondary,
+            accent,
+            highlight,
+            onPrimary,
+            onAccent,
+        };
+    }
+    // dark mode
+    const background = neutral[950];
+    const surface = neutral[900];
+    const surfaceRaised = neutral[800];
+    const surfaceTint = surfaceTintScale[900];
+    const border = neutral[700];
+    const text = neutral[50];
+    const textMuted = neutral[300];
+    const primary = primaryScale[400];
+    const secondary = secondaryScale[400];
+    const accent = accentScale[400];
+    const highlight = highlightScale[400];
+    const onPrimary = getReadableTextColor(primary, [neutral[50], neutral[950]]);
+    const onAccent = getReadableTextColor(accent, [neutral[50], neutral[950]]);
+    return {
+        background,
+        surface,
+        surfaceRaised,
+        surfaceTint,
+        border,
+        text,
+        textMuted,
+        primary,
+        secondary,
+        accent,
+        highlight,
+        onPrimary,
+        onAccent,
+    };
+}
+//# sourceMappingURL=semanticTokens.js.map

package/dist/internal/color/semanticTokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticTokens.js","sourceRoot":"","sources":["../../../src/internal/color/semanticTokens.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ZoraColorTone, ZoraHexColor, ZoraThemeMode } from '../../theme/types';\nimport { parseHexToOklch } from './oklch';\nimport { getZoraRoleColorScale, type ZoraComputedRoleColorScales } from './roleScales';\n\nexport interface ZoraSemanticColorTokens {\n  background: ZoraHexColor;\n  surface: ZoraHexColor;\n  surfaceRaised: ZoraHexColor;\n  surfaceTint: ZoraHexColor;\n  border: ZoraHexColor;\n  text: ZoraHexColor;\n  textMuted: ZoraHexColor;\n  primary: ZoraHexColor;\n  secondary: ZoraHexColor;\n  accent: ZoraHexColor;\n  highlight: ZoraHexColor;\n  onPrimary: ZoraHexColor;\n  onAccent: ZoraHexColor;\n}\n\n/**\n * Selects the more readable of two candidate hex colors against a given background,\n * using OKLCH lightness as a simple contrast proxy.\n */\nexport function getReadableTextColor(\n  background: ZoraHexColor,\n  candidates: readonly [ZoraHexColor, ZoraHexColor],\n): ZoraHexColor {\n  const bgL = parseHexToOklch(background).l;\n  const [a, b] = candidates;\n  const diffA = Math.abs(parseHexToOklch(a).l - bgL);\n  const diffB = Math.abs(parseHexToOklch(b).l - bgL);\n  return diffA >= diffB ? a : b;\n}\n\nexport function createZoraSemanticColorTokens(options: {\n  roleScales: ZoraComputedRoleColorScales;\n  mode: ZoraThemeMode;\n  colorTone: ZoraColorTone;\n}): ZoraSemanticColorTokens {\n  // colorTone is accepted now and reserved for future per-tone step overrides\n  // (e.g. obsidian/pastel may shift surface selections differently).\n  const { roleScales, mode } = options;\n\n  const neutral = getZoraRoleColorScale(roleScales, 'neutral').scale;\n  const surfaceTintScale = getZoraRoleColorScale(roleScales, 'surfaceTint').scale;\n  const primaryScale = getZoraRoleColorScale(roleScales, 'primary').scale;\n  const secondaryScale = getZoraRoleColorScale(roleScales, 'secondary').scale;\n  const accentScale = getZoraRoleColorScale(roleScales, 'accent').scale;\n  const highlightScale = getZoraRoleColorScale(roleScales, 'highlight').scale;\n\n  if (mode === 'light') {\n    const background = neutral[50];\n    const surface = neutral[100];\n    const surfaceRaised = neutral[50];\n    const surfaceTint = surfaceTintScale[100];\n    const border = neutral[200];\n    const text = neutral[900];\n    const textMuted = neutral[700];\n    const primary = primaryScale[600];\n    const secondary = secondaryScale[600];\n    const accent = accentScale[600];\n    const highlight = highlightScale[600];\n    const onPrimary = getReadableTextColor(primary, [neutral[50], neutral[950]]);\n    const onAccent = getReadableTextColor(accent, [neutral[50], neutral[950]]);\n\n    return {\n      background,\n      surface,\n      surfaceRaised,\n      surfaceTint,\n      border,\n      text,\n      textMuted,\n      primary,\n      secondary,\n      accent,\n      highlight,\n      onPrimary,\n      onAccent,\n    };\n  }\n\n  // dark mode\n  const background = neutral[950];\n  const surface = neutral[900];\n  const surfaceRaised = neutral[800];\n  const surfaceTint = surfaceTintScale[900];\n  const border = neutral[700];\n  const text = neutral[50];\n  const textMuted = neutral[300];\n  const primary = primaryScale[400];\n  const secondary = secondaryScale[400];\n  const accent = accentScale[400];\n  const highlight = highlightScale[400];\n  const onPrimary = getReadableTextColor(primary, [neutral[50], neutral[950]]);\n  const onAccent = getReadableTextColor(accent, [neutral[50], neutral[950]]);\n\n  return {\n    background,\n    surface,\n    surfaceRaised,\n    surfaceTint,\n    border,\n    text,\n    textMuted,\n    primary,\n    secondary,\n    accent,\n    highlight,\n    onPrimary,\n    onAccent,\n  };\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "0.15.1",
+  "version": "0.15.4",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -43,7 +43,7 @@
     }
   },
   "dependencies": {
-    "@ankhorage/surface": "^0.2.1",
+    "@ankhorage/surface": "^0.2.2",
     "culori": "^4.0.2"
   },
   "files": [

package/src/internal/color/index.ts

@@ -36,4 +36,9 @@ export {
   createZoraPrimaryScale,
   type ZoraHueScaleRoleId,
 } from './scales';
+export {
+  createZoraSemanticColorTokens,
+  getReadableTextColor,
+  type ZoraSemanticColorTokens,
+} from './semanticTokens';
 export { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';

package/src/internal/color/semanticTokens.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraColorTone, ZoraHexColor } from '../../theme/types';
+import {
+  assignZoraHarmonyRoleHues,
+  computeZoraHarmony,
+  createZoraRoleColorScales,
+  createZoraSemanticColorTokens,
+  getReadableTextColor,
+  type ZoraComputedRoleColorScales,
+  type ZoraSemanticColorTokens,
+} from './index';
+
+function isSixDigitLowercaseHex(value: string): value is ZoraHexColor {
+  return /^#[0-9a-f]{6}$/.test(value);
+}
+
+function getLightness(hex: ZoraHexColor): number {
+  // Intentionally a simple RGB average rather than OKLCH — serves as a
+  // perceptual proxy for test assertions only. The production implementation
+  // in getReadableTextColor uses OKLCH lightness via parseHexToOklch.
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+  return (r + g + b) / 3;
+}
+
+function buildRoleScales(colorTone: ZoraColorTone = 'jewel'): ZoraComputedRoleColorScales {
+  const seed: ZoraHexColor = '#0f766e';
+  const harmony = computeZoraHarmony(seed, 'tetradic');
+  const hueRoles = assignZoraHarmonyRoleHues(harmony);
+  return createZoraRoleColorScales({ colorTone, hueRoles, seed });
+}
+
+function buildLight(colorTone: ZoraColorTone = 'jewel'): ZoraSemanticColorTokens {
+  return createZoraSemanticColorTokens({
+    roleScales: buildRoleScales(colorTone),
+    mode: 'light',
+    colorTone,
+  });
+}
+
+function buildDark(colorTone: ZoraColorTone = 'jewel'): ZoraSemanticColorTokens {
+  return createZoraSemanticColorTokens({
+    roleScales: buildRoleScales(colorTone),
+    mode: 'dark',
+    colorTone,
+  });
+}
+
+describe('createZoraSemanticColorTokens', () => {
+  test('all output values are lowercase 6-digit hex', () => {
+    const light = buildLight();
+    const dark = buildDark();
+
+    for (const tokens of [light, dark]) {
+      for (const key of Object.keys(tokens) as (keyof ZoraSemanticColorTokens)[]) {
+        const value = tokens[key];
+        expect(isSixDigitLowercaseHex(value), `${key} must be lowercase 6-digit hex`).toBe(true);
+      }
+    }
+  });
+
+  test('light mode background is lighter than dark mode background', () => {
+    const light = buildLight();
+    const dark = buildDark();
+
+    expect(getLightness(light.background)).toBeGreaterThan(getLightness(dark.background));
+  });
+
+  test('text has opposite lightness direction from background (light mode)', () => {
+    const light = buildLight();
+
+    expect(getLightness(light.text)).toBeLessThan(getLightness(light.background));
+  });
+
+  test('text has opposite lightness direction from background (dark mode)', () => {
+    const dark = buildDark();
+
+    expect(getLightness(dark.text)).toBeGreaterThan(getLightness(dark.background));
+  });
+
+  test('primary, accent, and highlight are distinct from background and surface (light)', () => {
+    const light = buildLight();
+
+    for (const token of [light.primary, light.accent, light.highlight] as const) {
+      expect(token).not.toBe(light.background);
+      expect(token).not.toBe(light.surface);
+    }
+  });
+
+  test('primary, accent, and highlight are distinct from background and surface (dark)', () => {
+    const dark = buildDark();
+
+    for (const token of [dark.primary, dark.accent, dark.highlight] as const) {
+      expect(token).not.toBe(dark.background);
+      expect(token).not.toBe(dark.surface);
+    }
+  });
+
+  test('onPrimary is readable against primary (light mode)', () => {
+    const light = buildLight();
+    const primaryL = getLightness(light.primary);
+    const onPrimaryL = getLightness(light.onPrimary);
+
+    expect(Math.abs(primaryL - onPrimaryL)).toBeGreaterThan(0.3);
+  });
+
+  test('onPrimary is readable against primary (dark mode)', () => {
+    const dark = buildDark();
+    const primaryL = getLightness(dark.primary);
+    const onPrimaryL = getLightness(dark.onPrimary);
+
+    expect(Math.abs(primaryL - onPrimaryL)).toBeGreaterThan(0.3);
+  });
+
+  test('onAccent is readable against accent (light mode)', () => {
+    const light = buildLight();
+    const accentL = getLightness(light.accent);
+    const onAccentL = getLightness(light.onAccent);
+
+    expect(Math.abs(accentL - onAccentL)).toBeGreaterThan(0.3);
+  });
+
+  test('colorTone changes at least one output token between neutral and fluorescent', () => {
+    const lightNeutral = buildLight('neutral');
+    const lightFluorescent = buildLight('fluorescent');
+
+    const tokens: (keyof ZoraSemanticColorTokens)[] = [
+      'primary',
+      'secondary',
+      'accent',
+      'highlight',
+    ];
+
+    const anyChanged = tokens.some((k) => lightNeutral[k] !== lightFluorescent[k]);
+    expect(anyChanged).toBe(true);
+  });
+
+  test('output is deterministic for same input', () => {
+    const first = buildLight();
+    const second = buildLight();
+
+    expect(first).toEqual(second);
+  });
+
+  test('surface is distinct from surfaceRaised in dark mode', () => {
+    const dark = buildDark();
+
+    expect(dark.surface).not.toBe(dark.surfaceRaised);
+  });
+});
+
+describe('getReadableTextColor', () => {
+  test('returns the candidate with greater lightness difference from background', () => {
+    const background: ZoraHexColor = '#ffffff';
+    const dark: ZoraHexColor = '#111111';
+    const light: ZoraHexColor = '#eeeeee';
+
+    expect(getReadableTextColor(background, [dark, light])).toBe(dark);
+  });
+
+  test('returns the lighter candidate when background is dark', () => {
+    const background: ZoraHexColor = '#111111';
+    const dark: ZoraHexColor = '#333333';
+    const light: ZoraHexColor = '#eeeeee';
+
+    expect(getReadableTextColor(background, [dark, light])).toBe(light);
+  });
+});

package/src/internal/color/semanticTokens.ts

@@ -0,0 +1,114 @@
+import type { ZoraColorTone, ZoraHexColor, ZoraThemeMode } from '../../theme/types';
+import { parseHexToOklch } from './oklch';
+import { getZoraRoleColorScale, type ZoraComputedRoleColorScales } from './roleScales';
+
+export interface ZoraSemanticColorTokens {
+  background: ZoraHexColor;
+  surface: ZoraHexColor;
+  surfaceRaised: ZoraHexColor;
+  surfaceTint: ZoraHexColor;
+  border: ZoraHexColor;
+  text: ZoraHexColor;
+  textMuted: ZoraHexColor;
+  primary: ZoraHexColor;
+  secondary: ZoraHexColor;
+  accent: ZoraHexColor;
+  highlight: ZoraHexColor;
+  onPrimary: ZoraHexColor;
+  onAccent: ZoraHexColor;
+}
+
+/**
+ * Selects the more readable of two candidate hex colors against a given background,
+ * using OKLCH lightness as a simple contrast proxy.
+ */
+export function getReadableTextColor(
+  background: ZoraHexColor,
+  candidates: readonly [ZoraHexColor, ZoraHexColor],
+): ZoraHexColor {
+  const bgL = parseHexToOklch(background).l;
+  const [a, b] = candidates;
+  const diffA = Math.abs(parseHexToOklch(a).l - bgL);
+  const diffB = Math.abs(parseHexToOklch(b).l - bgL);
+  return diffA >= diffB ? a : b;
+}
+
+export function createZoraSemanticColorTokens(options: {
+  roleScales: ZoraComputedRoleColorScales;
+  mode: ZoraThemeMode;
+  colorTone: ZoraColorTone;
+}): ZoraSemanticColorTokens {
+  // colorTone is accepted now and reserved for future per-tone step overrides
+  // (e.g. obsidian/pastel may shift surface selections differently).
+  const { roleScales, mode } = options;
+
+  const neutral = getZoraRoleColorScale(roleScales, 'neutral').scale;
+  const surfaceTintScale = getZoraRoleColorScale(roleScales, 'surfaceTint').scale;
+  const primaryScale = getZoraRoleColorScale(roleScales, 'primary').scale;
+  const secondaryScale = getZoraRoleColorScale(roleScales, 'secondary').scale;
+  const accentScale = getZoraRoleColorScale(roleScales, 'accent').scale;
+  const highlightScale = getZoraRoleColorScale(roleScales, 'highlight').scale;
+
+  if (mode === 'light') {
+    const background = neutral[50];
+    const surface = neutral[100];
+    const surfaceRaised = neutral[50];
+    const surfaceTint = surfaceTintScale[100];
+    const border = neutral[200];
+    const text = neutral[900];
+    const textMuted = neutral[700];
+    const primary = primaryScale[600];
+    const secondary = secondaryScale[600];
+    const accent = accentScale[600];
+    const highlight = highlightScale[600];
+    const onPrimary = getReadableTextColor(primary, [neutral[50], neutral[950]]);
+    const onAccent = getReadableTextColor(accent, [neutral[50], neutral[950]]);
+
+    return {
+      background,
+      surface,
+      surfaceRaised,
+      surfaceTint,
+      border,
+      text,
+      textMuted,
+      primary,
+      secondary,
+      accent,
+      highlight,
+      onPrimary,
+      onAccent,
+    };
+  }
+
+  // dark mode
+  const background = neutral[950];
+  const surface = neutral[900];
+  const surfaceRaised = neutral[800];
+  const surfaceTint = surfaceTintScale[900];
+  const border = neutral[700];
+  const text = neutral[50];
+  const textMuted = neutral[300];
+  const primary = primaryScale[400];
+  const secondary = secondaryScale[400];
+  const accent = accentScale[400];
+  const highlight = highlightScale[400];
+  const onPrimary = getReadableTextColor(primary, [neutral[50], neutral[950]]);
+  const onAccent = getReadableTextColor(accent, [neutral[50], neutral[950]]);
+
+  return {
+    background,
+    surface,
+    surfaceRaised,
+    surfaceTint,
+    border,
+    text,
+    textMuted,
+    primary,
+    secondary,
+    accent,
+    highlight,
+    onPrimary,
+    onAccent,
+  };
+}