@newtonedev/components 0.1.5 → 0.1.6

package/src/tokens/computeTokens.ts

@@ -1,7 +1,119 @@
-import { getColor, getColorByContrast } from 'newtone';
+import { getColor } from 'newtone';
 import type { PaletteConfig } from 'newtone';
-import type { ColorSystemConfig, ColorMode, ThemeMapping, ElevationLevel, FontConfig } from '../theme/types';
-import type { ResolvedTokens } from './types';
+import type { ColorSystemConfig, ColorMode, ElevationLevel, FontConfig, TokenOverrides } from '../theme/types';
+import type { ResolvedTokens, PaletteTokens } from './types';
+
+/**
+ * Per-mode fallback defaults shape shared by all palette defaults.
+ */
+export type PaletteDefaults = {
+  readonly light: {
+    readonly background: { readonly elevated: number; readonly ground: number; readonly sunken: number };
+    readonly text: { readonly primary: number; readonly secondary: number; readonly tertiary: number; readonly disabled: number };
+    readonly action: { readonly enabled: number; readonly hovered: number; readonly pressed: number };
+    readonly border: { readonly enabled: number; readonly focused: number; readonly filled: number };
+  };
+  readonly dark: {
+    readonly background: { readonly elevated: number; readonly ground: number; readonly sunken: number };
+    readonly text: { readonly primary: number; readonly secondary: number; readonly tertiary: number; readonly disabled: number };
+    readonly action: { readonly enabled: number; readonly hovered: number; readonly pressed: number };
+    readonly border: { readonly enabled: number; readonly focused: number; readonly filled: number };
+  };
+};
+
+/**
+ * Per-mode fallback defaults for the neutral palette (normalized scale).
+ * Single source of truth — consumed by computeTokens and the admin Token Tuner.
+ *
+ * Light: 0 = lightest, 1 = darkest. Dark: 0 = darkest, 1 = lightest.
+ * Structured by token group so all per-palette defaults follow the same shape.
+ */
+export const NEUTRAL_DEFAULTS: PaletteDefaults = {
+  light: {
+    background: { elevated: 0, ground: 0.03, sunken: 0.06 },
+    text: { primary: 0.9, secondary: 0.7, tertiary: 0.5, disabled: 0.3 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+  dark: {
+    background: { elevated: 0.24, ground: 0.20, sunken: 0.16 },
+    text: { primary: 1.0, secondary: 0.85, tertiary: 0.7, disabled: 0.55 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+};
+
+/**
+ * Accent palette defaults. Initial values match neutral — will be tuned per-palette later.
+ */
+export const ACCENT_DEFAULTS: PaletteDefaults = {
+  light: {
+    background: { elevated: 0, ground: 0.03, sunken: 0.06 },
+    text: { primary: 0.9, secondary: 0.7, tertiary: 0.5, disabled: 0.3 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+  dark: {
+    background: { elevated: 0.24, ground: 0.20, sunken: 0.16 },
+    text: { primary: 1.0, secondary: 0.85, tertiary: 0.7, disabled: 0.55 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+};
+
+/**
+ * Success palette defaults. Initial values match neutral — will be tuned per-palette later.
+ */
+export const SUCCESS_DEFAULTS: PaletteDefaults = {
+  light: {
+    background: { elevated: 0, ground: 0.03, sunken: 0.06 },
+    text: { primary: 0.9, secondary: 0.7, tertiary: 0.5, disabled: 0.3 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+  dark: {
+    background: { elevated: 0.24, ground: 0.20, sunken: 0.16 },
+    text: { primary: 1.0, secondary: 0.85, tertiary: 0.7, disabled: 0.55 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+};
+
+/**
+ * Warning palette defaults. Initial values match neutral — will be tuned per-palette later.
+ */
+export const WARNING_DEFAULTS: PaletteDefaults = {
+  light: {
+    background: { elevated: 0, ground: 0.03, sunken: 0.06 },
+    text: { primary: 0.9, secondary: 0.7, tertiary: 0.5, disabled: 0.3 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+  dark: {
+    background: { elevated: 0.24, ground: 0.20, sunken: 0.16 },
+    text: { primary: 1.0, secondary: 0.85, tertiary: 0.7, disabled: 0.55 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+};
+
+/**
+ * Error palette defaults. Initial values match neutral — will be tuned per-palette later.
+ */
+export const ERROR_DEFAULTS: PaletteDefaults = {
+  light: {
+    background: { elevated: 0, ground: 0.03, sunken: 0.06 },
+    text: { primary: 0.9, secondary: 0.7, tertiary: 0.5, disabled: 0.3 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+  dark: {
+    background: { elevated: 0.24, ground: 0.20, sunken: 0.16 },
+    text: { primary: 1.0, secondary: 0.85, tertiary: 0.7, disabled: 0.55 },
+    action: { enabled: 0.04, hovered: 0.06, pressed: 0.08 },
+    border: { enabled: 0.08, focused: 0.16, filled: 0.24 },
+  },
+};
 
 /**
  * Convert FontConfig to CSS font-family string
@@ -11,6 +123,104 @@ function fontConfigToFamily(font: FontConfig): string {
   return `${family}, ${font.fallback}`;
 }
 
+const clamp = (n: number) => Math.max(0, Math.min(1, n));
+
+/**
+ * Compute the complete PaletteTokens for a non-neutral palette.
+ *
+ * Uses the palette's hue/saturation with positions from the palette's defaults,
+ * plus fill tokens at the palette's key NV position.
+ *
+ * @param palette - The palette config (hue, saturation, key NV, etc.)
+ * @param defaults - Per-mode defaults for this palette (positions + offsets)
+ * @param mode - Current color mode
+ * @param elevation - Current elevation level
+ * @param dynamicRange - Global dynamic range
+ * @param elevationDelta - Compensation delta (current surface vs elevated reference)
+ * @param effectiveTextMode - Derived from actual background lightness
+ * @param autoAccentNv - Auto-derived key NV fallback
+ * @param neutralTextPrimary - Neutral textPrimary for onFill (dark text on light fills)
+ * @param neutralBgElevated - Neutral backgroundElevated for onFill (light text on dark fills)
+ */
+function computePaletteTokens(
+  palette: PaletteConfig,
+  defaults: PaletteDefaults,
+  mode: ColorMode,
+  elevation: ElevationLevel,
+  dynamicRange: { readonly lightest: number; readonly darkest: number },
+  elevationDelta: number,
+  effectiveTextMode: ColorMode,
+  autoAccentNv: number,
+  neutralTextPrimary: ReturnType<typeof getColor>,
+  neutralBgElevated: ReturnType<typeof getColor>,
+): PaletteTokens {
+  const modeDefaults = defaults[mode];
+  const toEngineNv = (nv: number) => mode === 'light' ? 1 - nv : nv;
+  const textToEngineNv = (nv: number) => effectiveTextMode === 'light' ? 1 - nv : nv;
+
+  const colorAt = (engineNv: number) => getColor(
+    palette.hue, palette.saturation, dynamicRange,
+    clamp(engineNv), palette.desaturation, palette.paletteHueGrading
+  );
+
+  // --- Fill: key color (user-chosen or auto-derived), elevation-compensated ---
+  const resolveKeyNv = (p: PaletteConfig): number | undefined =>
+    mode === 'dark' ? p.keyNormalizedValueDark : p.keyNormalizedValue;
+
+  const keyNv = resolveKeyNv(palette);
+  const fillBaseNv = keyNv ?? autoAccentNv;
+  const fillNv = clamp(fillBaseNv + elevationDelta);
+  const fill = colorAt(fillNv);
+
+  const hoverDir = effectiveTextMode === 'light' ? -modeDefaults.action.hovered : modeDefaults.action.hovered;
+  const activeDir = effectiveTextMode === 'light' ? -modeDefaults.action.pressed : modeDefaults.action.pressed;
+  const fillHover = colorAt(clamp(fillNv + hoverDir));
+  const fillActive = colorAt(clamp(fillNv + activeDir));
+
+  // onFill: high-contrast text on the fill color
+  const onFill = fill.oklch.L > 0.6 ? neutralTextPrimary : neutralBgElevated;
+
+  // --- Surface: palette-tinted backgrounds at standard positions ---
+  const bgNormalized = elevation === 2
+    ? modeDefaults.background.elevated
+    : elevation === 1
+    ? modeDefaults.background.ground
+    : modeDefaults.background.sunken;
+  const bgNv = clamp(toEngineNv(bgNormalized));
+  const background = colorAt(bgNv);
+  const backgroundElevated = colorAt(clamp(toEngineNv(modeDefaults.background.elevated)));
+  const backgroundSunken = colorAt(clamp(toEngineNv(modeDefaults.background.sunken)));
+
+  // --- Interactive surface: offset from palette background ---
+  const interactiveOffset = modeDefaults.action.enabled;
+  const interactiveNv = clamp(bgNv + (effectiveTextMode === 'light' ? -interactiveOffset : interactiveOffset));
+  const backgroundInteractive = colorAt(interactiveNv);
+
+  const hoverShift = modeDefaults.action.hovered;
+  const activeShift = modeDefaults.action.pressed;
+  const backgroundInteractiveHover = colorAt(clamp(interactiveNv + (effectiveTextMode === 'light' ? -hoverShift : hoverShift)));
+  const backgroundInteractiveActive = colorAt(clamp(interactiveNv + (effectiveTextMode === 'light' ? -activeShift : activeShift)));
+
+  // --- Text: palette-hued text at standard positions, elevation-compensated ---
+  const textPrimary = colorAt(clamp(textToEngineNv(modeDefaults.text.primary) + elevationDelta));
+  const textSecondary = colorAt(clamp(textToEngineNv(modeDefaults.text.secondary) + elevationDelta));
+  const textTertiary = colorAt(clamp(textToEngineNv(modeDefaults.text.tertiary) + elevationDelta));
+  const textDisabled = colorAt(clamp(textToEngineNv(modeDefaults.text.disabled) + elevationDelta));
+
+  // --- Border: offset from palette background ---
+  const borderOffset = modeDefaults.border.enabled;
+  const borderNv = effectiveTextMode === 'light' ? bgNv - borderOffset : bgNv + borderOffset;
+  const border = colorAt(clamp(borderNv));
+
+  return {
+    fill, fillHover, fillActive, onFill,
+    background, backgroundElevated, backgroundSunken,
+    backgroundInteractive, backgroundInteractiveHover, backgroundInteractiveActive,
+    textPrimary, textSecondary, textTertiary, textDisabled,
+    border,
+  };
+}
+
 /**
  * Compute design tokens for a specific mode/theme/elevation combination.
  *
@@ -18,11 +228,13 @@ function fontConfigToFamily(font: FontConfig): string {
  * based on the current theme context. All colors are computed on-demand using
  * the pure functions from the engine.
  *
+ * Background surfaces use absolute positions from NEUTRAL_DEFAULTS (or tokenOverrides
+ * when present). Elevation compensation is derived from the difference between
+ * the current surface and the elevated reference surface.
+ *
  * @param config - Complete color system configuration (dynamic range + palettes)
  * @param mode - Current color mode ('light' or 'dark')
- * @param themeMapping - Theme configuration (which palette and NV to use)
  * @param elevation - Elevation level (0=sunken, 1=default, 2=elevated)
- * @param elevationOffsets - NV offsets for each elevation level
  * @param spacing - Spacing scale for paddings, gaps, and margins
  * @param radius - Border radius scale for component roundness
  * @param typography - Typography configuration with fonts and scales
@@ -34,9 +246,7 @@ function fontConfigToFamily(font: FontConfig): string {
  * const tokens = computeTokens(
  *   config.colorSystem,
  *   'light',
- *   config.themes.neutral,
  *   1,
- *   config.elevation.offsets,
  *   config.spacing,
  *   config.radius,
  *   config.typography,
@@ -48,9 +258,7 @@ function fontConfigToFamily(font: FontConfig): string {
 export function computeTokens(
   config: ColorSystemConfig,
   mode: ColorMode,
-  themeMapping: ThemeMapping,
   elevation: ElevationLevel,
-  elevationOffsets: readonly [number, number, number],
   spacing: { readonly '00': number; readonly '02': number; readonly '04': number; readonly '06': number; readonly '08': number; readonly '10': number; readonly '12': number; readonly '16': number; readonly '20': number; readonly '24': number; readonly '32': number; readonly '40': number; readonly '48': number },
   radius: { readonly none: number; readonly sm: number; readonly md: number; readonly lg: number; readonly xl: number; readonly pill: 999 },
   typography: {
@@ -63,19 +271,44 @@ export function computeTokens(
     readonly variant: 'outlined' | 'rounded' | 'sharp';
     readonly weight: 100 | 200 | 300 | 400 | 500 | 600 | 700;
     readonly autoGrade: boolean;
-  }
+  },
+  tokenOverrides?: TokenOverrides
 ): ResolvedTokens {
   const { dynamicRange, palettes } = config;
-  const palette = palettes[themeMapping.paletteIndex];
+  const palette = palettes[0]; // Always neutral palette for backgrounds
 
   if (!palette) {
-    throw new Error(`Palette at index ${themeMapping.paletteIndex} not found`);
+    throw new Error('Neutral palette (index 0) not found');
   }
 
-  // Determine base NV for this mode + elevation
-  const baseNv = mode === 'light' ? themeMapping.lightModeNv : themeMapping.darkModeNv;
-  const elevationOffset = elevationOffsets[elevation];
-  const backgroundNv = Math.max(0, Math.min(1, baseNv + elevationOffset));
+  const neutralDefaults = NEUTRAL_DEFAULTS[mode];
+
+  // --- Mode-specific normalized field resolution ---
+  const toEngineNv = (nv: number) => mode === 'light' ? 1 - nv : nv;
+  const bgElevatedNorm = mode === 'light' ? tokenOverrides?.backgroundElevated : tokenOverrides?.backgroundElevatedDark;
+  const bgDefaultNorm = mode === 'light' ? tokenOverrides?.backgroundDefault : tokenOverrides?.backgroundDefaultDark;
+  const bgSunkenNorm = mode === 'light' ? tokenOverrides?.backgroundSunken : tokenOverrides?.backgroundSunkenDark;
+  const textPrimaryNorm = mode === 'light' ? tokenOverrides?.textPrimaryNormalized : tokenOverrides?.textPrimaryNormalizedDark;
+  const textSecondaryNorm = mode === 'light' ? tokenOverrides?.textSecondaryNormalized : tokenOverrides?.textSecondaryNormalizedDark;
+  const textTertiaryNorm = mode === 'light' ? tokenOverrides?.textTertiaryNormalized : tokenOverrides?.textTertiaryNormalizedDark;
+  const textDisabledNorm = mode === 'light' ? tokenOverrides?.textDisabledNormalized : tokenOverrides?.textDisabledNormalizedDark;
+
+  // --- Background NV resolution ---
+  // Absolute positions from tokenOverrides or NEUTRAL_DEFAULTS.
+  // Ground = Background/01 (elevated). Everything diverges from there.
+  const bgNormalized = elevation === 2
+    ? (bgElevatedNorm ?? neutralDefaults.background.elevated)
+    : elevation === 1
+    ? (bgDefaultNorm ?? neutralDefaults.background.ground)
+    : (bgSunkenNorm ?? neutralDefaults.background.sunken);
+  const backgroundNv = clamp(toEngineNv(bgNormalized));
+  const elevatedNv = clamp(toEngineNv(bgElevatedNorm ?? neutralDefaults.background.elevated));
+  const sunkenNv = clamp(toEngineNv(bgSunkenNorm ?? neutralDefaults.background.sunken));
+
+  // Elevation compensation: how far the current surface is from the reference (bg01/elevated).
+  // Tokens designed at bg01 shift by this delta on deeper surfaces to preserve perceptual contrast.
+  // Always 0 on bg01. Negative on bg02/bg03 in both modes (surface is darker → tokens darken too).
+  const elevationDelta = backgroundNv - elevatedNv;
 
   // Derive effective text mode from actual background lightness.
   // This handles inverted themes (e.g., strong: dark bg in light mode)
@@ -92,8 +325,7 @@ export function computeTokens(
     palette.paletteHueGrading
   );
 
-  // Compute elevated surface (always at elevation 2 offset)
-  const elevatedNv = Math.max(0, Math.min(1, baseNv + elevationOffsets[2]));
+  // Compute elevated surface
   const backgroundElevated = getColor(
     palette.hue,
     palette.saturation,
@@ -103,8 +335,7 @@ export function computeTokens(
     palette.paletteHueGrading
   );
 
-  // Compute sunken surface (always at elevation 0 offset)
-  const sunkenNv = Math.max(0, Math.min(1, baseNv + elevationOffsets[0]));
+  // Compute sunken surface
   const backgroundSunken = getColor(
     palette.hue,
     palette.saturation,
@@ -114,12 +345,26 @@ export function computeTokens(
     palette.paletteHueGrading
   );
 
-  // Compute interactive component background (FIXED -0.035 NV offset from current elevation)
+  // --- Tunable constants (overridable via tokenOverrides, per-mode) ---
+  // All values are magnitudes — direction auto-inverts per effectiveTextMode
+  // (darker in light mode, lighter in dark mode)
+  const INTERACTIVE_COMPONENT_OFFSET = mode === 'light'
+    ? (tokenOverrides?.interactiveComponentOffset ?? neutralDefaults.action.enabled)
+    : (tokenOverrides?.interactiveComponentOffsetDark ?? neutralDefaults.action.enabled);
+  const HOVER_SHIFT = mode === 'light'
+    ? (tokenOverrides?.hoverShift ?? neutralDefaults.action.hovered)
+    : (tokenOverrides?.hoverShiftDark ?? neutralDefaults.action.hovered);
+  const ACTIVE_SHIFT = mode === 'light'
+    ? (tokenOverrides?.activeShift ?? neutralDefaults.action.pressed)
+    : (tokenOverrides?.activeShiftDark ?? neutralDefaults.action.pressed);
+  const BORDER_OFFSET = mode === 'light'
+    ? (tokenOverrides?.borderOffset ?? neutralDefaults.border.enabled)
+    : (tokenOverrides?.borderOffsetDark ?? neutralDefaults.border.enabled);
+  // Compute interactive component background (FIXED NV offset from current elevation)
   // Unlike backgroundElevated/backgroundSunken which use discrete levels, this uses a fixed
   // luminosity offset to ensure CONSISTENT visual contrast across all elevations (-2 to 2).
   // Used by: Button (neutral primary variant) and future components with neutral filled backgrounds.
-  const INTERACTIVE_COMPONENT_OFFSET = -0.035; // Slightly darker than container for depth
-  const interactiveComponentNv = Math.max(0, Math.min(1, backgroundNv + INTERACTIVE_COMPONENT_OFFSET));
+  const interactiveComponentNv = clamp(backgroundNv + (effectiveTextMode === 'light' ? -INTERACTIVE_COMPONENT_OFFSET : INTERACTIVE_COMPONENT_OFFSET));
   const backgroundInteractive = getColor(
     palette.hue,
     palette.saturation,
@@ -129,141 +374,118 @@ export function computeTokens(
     palette.paletteHueGrading
   );
 
-  // Compute text colors with WCAG contrast against actual background
-  // Primary text: WCAG AA (4.5:1 for body text)
-  const textPrimary = getColorByContrast(
+  // Neutral hover/active: shift from interactive component base (same direction as accent hover/active)
+  const neutralHoverNv = clamp(interactiveComponentNv + (effectiveTextMode === 'light' ? -HOVER_SHIFT : HOVER_SHIFT));
+  const backgroundInteractiveHover = getColor(
     palette.hue,
     palette.saturation,
     dynamicRange,
-    4.5,
-    effectiveTextMode,
+    neutralHoverNv,
     palette.desaturation,
-    palette.paletteHueGrading,
-    background,
+    palette.paletteHueGrading
   );
 
-  // Secondary text: Lower contrast (3.0:1 for captions)
-  const textSecondary = getColorByContrast(
+  const neutralActiveNv = clamp(interactiveComponentNv + (effectiveTextMode === 'light' ? -ACTIVE_SHIFT : ACTIVE_SHIFT));
+  const backgroundInteractiveActive = getColor(
     palette.hue,
     palette.saturation,
     dynamicRange,
-    3.0,
-    effectiveTextMode,
+    neutralActiveNv,
     palette.desaturation,
-    palette.paletteHueGrading,
-    background,
+    palette.paletteHueGrading
   );
 
-  // Interactive colors: Use accent palette (index 1)
-  const accentPalette = palettes[1];
+  // --- Text color resolution (elevation-compensated) ---
+  // Normalized positions define text contrast at bg01 (elevated). On deeper surfaces,
+  // elevationDelta shifts text toward the background to preserve the same contrast distance.
+  // Uses effectiveTextMode for NV conversion so inverted themes (e.g., strong: dark bg in
+  // light mode) auto-correct text direction — light text on dark bg, dark text on light bg.
+  const textToEngineNv = (nv: number) => effectiveTextMode === 'light' ? 1 - nv : nv;
 
-  if (!accentPalette) {
-    throw new Error('Accent palette (index 1) not found');
-  }
+  const textPrimary = getColor(palette.hue, palette.saturation, dynamicRange,
+      clamp(textToEngineNv(textPrimaryNorm ?? neutralDefaults.text.primary) + elevationDelta),
+      palette.desaturation, palette.paletteHueGrading);
 
-  // Resolve per-mode key color: light mode uses keyNormalizedValue, dark uses keyNormalizedValueDark
-  const resolveKeyNv = (p: PaletteConfig): number | undefined =>
-    mode === 'dark' ? p.keyNormalizedValueDark : p.keyNormalizedValue;
+  const textSecondary = getColor(palette.hue, palette.saturation, dynamicRange,
+      clamp(textToEngineNv(textSecondaryNorm ?? neutralDefaults.text.secondary) + elevationDelta),
+      palette.desaturation, palette.paletteHueGrading);
 
-  // Interactive base: use user-chosen key color or auto WCAG AA contrast
-  const accentKeyNv = resolveKeyNv(accentPalette);
-  const interactive = accentKeyNv !== undefined
-    ? getColor(
-        accentPalette.hue,
-        accentPalette.saturation,
-        dynamicRange,
-        accentKeyNv,
-        accentPalette.desaturation,
-        accentPalette.paletteHueGrading
-      )
-    : getColorByContrast(
-        accentPalette.hue,
-        accentPalette.saturation,
-        dynamicRange,
-        4.5,
-        effectiveTextMode,
-        accentPalette.desaturation,
-        accentPalette.paletteHueGrading,
-        background,
-      );
-
-  // Hover/active states: Shift NV slightly from interactive base
-  // In light mode (light bg), go darker; in dark mode (dark bg), go lighter
-  const interactiveNv = accentKeyNv ?? (effectiveTextMode === 'light' ? 0.3 : 0.7);
-
-  const interactiveHover = getColor(
-    accentPalette.hue,
-    accentPalette.saturation,
-    dynamicRange,
-    interactiveNv + (effectiveTextMode === 'light' ? -0.05 : 0.05),
-    accentPalette.desaturation,
-    accentPalette.paletteHueGrading
-  );
+  const textTertiary = getColor(palette.hue, palette.saturation, dynamicRange,
+      clamp(textToEngineNv(textTertiaryNorm ?? neutralDefaults.text.tertiary) + elevationDelta),
+      palette.desaturation, palette.paletteHueGrading);
 
-  const interactiveActive = getColor(
-    accentPalette.hue,
-    accentPalette.saturation,
-    dynamicRange,
-    interactiveNv + (effectiveTextMode === 'light' ? -0.1 : 0.1),
-    accentPalette.desaturation,
-    accentPalette.paletteHueGrading
-  );
+  const textDisabled = getColor(palette.hue, palette.saturation, dynamicRange,
+      clamp(textToEngineNv(textDisabledNorm ?? neutralDefaults.text.disabled) + elevationDelta),
+      palette.desaturation, palette.paletteHueGrading);
 
   // Border: Subtle contrast from background
-  const borderNv = effectiveTextMode === 'light' ? backgroundNv - 0.1 : backgroundNv + 0.1;
+  const borderNv = effectiveTextMode === 'light' ? backgroundNv - BORDER_OFFSET : backgroundNv + BORDER_OFFSET;
   const border = getColor(
     palette.hue,
     palette.saturation,
     dynamicRange,
-    Math.max(0, Math.min(1, borderNv)),
+    clamp(borderNv),
     palette.desaturation,
     palette.paletteHueGrading
   );
 
-  // Semantic status colors: success (palette 2), warning (palette 3), error (palette 4)
-  // Each computed at WCAG AA contrast against actual background
+  // --- Per-palette token computation ---
+  // Auto accent NV: derived from text primary position (used when no explicit key color is set)
+  const autoAccentNv = clamp(textToEngineNv(textPrimaryNorm ?? neutralDefaults.text.primary));
+
+  const accentPalette = palettes[1];
+  if (!accentPalette) {
+    throw new Error('Accent palette (index 1) not found');
+  }
+
+  const accent = computePaletteTokens(
+    accentPalette, ACCENT_DEFAULTS, mode, elevation, dynamicRange,
+    elevationDelta, effectiveTextMode, autoAccentNv,
+    textPrimary, backgroundElevated,
+  );
+
   const successPalette = palettes[2];
   const warningPalette = palettes[3];
   const errorPalette = palettes[4];
 
-  const successKeyNv = successPalette ? resolveKeyNv(successPalette) : undefined;
+  // Semantic palettes: fall back to accent palette if not present
   const success = successPalette
-    ? (successKeyNv !== undefined
-        ? getColor(successPalette.hue, successPalette.saturation, dynamicRange,
-            successKeyNv, successPalette.desaturation, successPalette.paletteHueGrading)
-        : getColorByContrast(successPalette.hue, successPalette.saturation, dynamicRange,
-            4.5, effectiveTextMode, successPalette.desaturation, successPalette.paletteHueGrading, background))
-    : interactive;
-
-  const warningKeyNv = warningPalette ? resolveKeyNv(warningPalette) : undefined;
+    ? computePaletteTokens(
+        successPalette, SUCCESS_DEFAULTS, mode, elevation, dynamicRange,
+        elevationDelta, effectiveTextMode, autoAccentNv,
+        textPrimary, backgroundElevated,
+      )
+    : accent;
+
   const warning = warningPalette
-    ? (warningKeyNv !== undefined
-        ? getColor(warningPalette.hue, warningPalette.saturation, dynamicRange,
-            warningKeyNv, warningPalette.desaturation, warningPalette.paletteHueGrading)
-        : getColorByContrast(warningPalette.hue, warningPalette.saturation, dynamicRange,
-            4.5, effectiveTextMode, warningPalette.desaturation, warningPalette.paletteHueGrading, background))
-    : interactive;
-
-  const errorKeyNv = errorPalette ? resolveKeyNv(errorPalette) : undefined;
+    ? computePaletteTokens(
+        warningPalette, WARNING_DEFAULTS, mode, elevation, dynamicRange,
+        elevationDelta, effectiveTextMode, autoAccentNv,
+        textPrimary, backgroundElevated,
+      )
+    : accent;
+
   const error = errorPalette
-    ? (errorKeyNv !== undefined
-        ? getColor(errorPalette.hue, errorPalette.saturation, dynamicRange,
-            errorKeyNv, errorPalette.desaturation, errorPalette.paletteHueGrading)
-        : getColorByContrast(errorPalette.hue, errorPalette.saturation, dynamicRange,
-            4.5, effectiveTextMode, errorPalette.desaturation, errorPalette.paletteHueGrading, background))
-    : interactive;
+    ? computePaletteTokens(
+        errorPalette, ERROR_DEFAULTS, mode, elevation, dynamicRange,
+        elevationDelta, effectiveTextMode, autoAccentNv,
+        textPrimary, backgroundElevated,
+      )
+    : accent;
 
   return {
     background,
     backgroundElevated,
     backgroundSunken,
     backgroundInteractive,
+    backgroundInteractiveHover,
+    backgroundInteractiveActive,
     textPrimary,
     textSecondary,
-    interactive,
-    interactiveHover,
-    interactiveActive,
+    textTertiary,
+    textDisabled,
     border,
+    accent,
     success,
     warning,
     error,