@ankhorage/surface 3.1.3 → 3.2.0

package/src/theme/colorEngine.ts

@@ -1,29 +1,21 @@
 import type {
-  ColorSwatch,
   GeneratedThemeModeColors,
   GeneratedThemeSwatches,
   HexColor,
   SemanticColorReferenceMap,
   SemanticColorToken,
+  ThemeColorMode,
 } from '@ankhorage/color-theory';
 import {
-  createDefaultSemanticStatusSwatches,
+  DARK_SEMANTIC_COLOR_REFERENCES,
   generateThemeModeColors,
-  getReadableForeground,
+  LIGHT_SEMANTIC_COLOR_REFERENCES,
   parseHexColorOrThrow,
 } from '@ankhorage/color-theory';
 import type { ThemeConfig } from '@ankhorage/contracts';
 
-import type {
-  ActionSemantics,
-  BorderSemantics,
-  ContentSemantics,
-  NeutralSemantics,
-  RoleSemantics,
-  SurfaceSemantics,
-  ThemeSemantics,
-  ThemeTokens,
-} from './types';
+import { resolveSurfaceSemanticModel } from './resolveSurfaceSemanticModel';
+import type { SurfaceColorDiagnostics, ThemeSemantics, ThemeTokens } from './types';
 
 /**
  * Surface semantic resolver: maps color-theory SemanticColorToken references
@@ -46,141 +38,44 @@ export function resolveSemanticColors(
   ) as SurfaceSemanticColors;
 }
 
-function buildNeutralSemantics(neutralSwatch: ColorSwatch, isDark: boolean): NeutralSemantics {
-  if (isDark) {
-    return {
-      bg: neutralSwatch[950],
-      bgSubtle: neutralSwatch[900],
-      surface: neutralSwatch[900],
-      surfaceHover: neutralSwatch[800],
-      surfaceActive: neutralSwatch[700],
-      border: neutralSwatch[800],
-      borderStrong: neutralSwatch[600],
-      divider: neutralSwatch[800],
-      text: neutralSwatch[50],
-      textMuted: neutralSwatch[200],
-      textSubtle: neutralSwatch[300],
-    };
-  }
-  return {
-    bg: neutralSwatch[50],
-    bgSubtle: neutralSwatch[100],
-    surface: neutralSwatch[100],
-    surfaceHover: neutralSwatch[200],
-    surfaceActive: neutralSwatch[300],
-    border: neutralSwatch[200],
-    borderStrong: neutralSwatch[300],
-    divider: neutralSwatch[200],
-    text: neutralSwatch[900],
-    textMuted: neutralSwatch[700],
-    textSubtle: neutralSwatch[600],
-  };
-}
-
-function buildRoleSemantics(swatch: ColorSwatch, isDark: boolean): RoleSemantics {
-  const base = swatch[500];
-  const { foreground: onSolidText } = getReadableForeground(base);
-
-  if (isDark) {
-    return {
-      base,
-      hover: swatch[400],
-      strong: swatch[300],
-      softBg: swatch[900],
-      softHover: swatch[800],
-      softActive: swatch[700],
-      outline: swatch[500],
-      onSolidText,
-    };
-  }
-
-  return {
-    base,
-    hover: swatch[600],
-    strong: swatch[700],
-    softBg: swatch[100],
-    softHover: swatch[200],
-    softActive: swatch[300],
-    outline: swatch[400],
-    onSolidText,
-  };
-}
-
 export function generatePalette(
   config: ThemeConfig,
-  mode: 'light' | 'dark' = 'light',
+  mode: ThemeColorMode = 'light',
 ): {
   colors: ThemeTokens['colors'];
   swatches: GeneratedThemeSwatches;
   semantics: ThemeSemantics;
+  colorDiagnostics: SurfaceColorDiagnostics;
 } {
   const modeConfig = mode === 'dark' ? config.dark : config.light;
   const isDark = mode === 'dark';
 
-  // Throws deterministically on invalid primary color
   parseHexColorOrThrow(modeConfig.primaryColor);
 
   const generated = generateThemeModeColors(modeConfig);
   const { swatches } = generated;
-  const neutralSwatch = swatches.neutral;
-
-  const neutral = buildNeutralSemantics(neutralSwatch, isDark);
-  const brand = buildRoleSemantics(swatches.primary, isDark);
-
-  // Fallback to primary swatch for missing ordinal roles
-  const secondarySwatch = swatches.secondary ?? swatches.primary;
-  const tertiarySwatch = swatches.tertiary ?? swatches.primary;
-  const quaternarySwatch = swatches.quaternary ?? swatches.primary;
-
-  const semanticStatusSwatches = createDefaultSemanticStatusSwatches().swatches;
-
-  const danger = buildRoleSemantics(semanticStatusSwatches.danger, isDark);
-  const success = buildRoleSemantics(semanticStatusSwatches.success, isDark);
-  const warning = buildRoleSemantics(semanticStatusSwatches.warning, isDark);
-  // Keep destructive action and feedback error aligned until a dedicated error status swatch is introduced.
-  const error = danger;
-  const info = buildRoleSemantics(secondarySwatch, isDark);
-  const inverseSurface = isDark ? neutralSwatch[50] : neutralSwatch[900];
-  const inverseOnSurface = isDark ? neutralSwatch[900] : neutralSwatch[50];
-
-  const surfaceSemantics: SurfaceSemantics = {
-    default: neutral.surface,
-    subtle: neutral.bgSubtle,
-    raised: neutral.surface,
-    inverse: inverseSurface,
-  };
-
-  const content: ContentSemantics = {
-    default: neutral.text,
-    muted: neutral.textMuted,
-    subtle: neutral.textSubtle,
-    inverse: inverseOnSurface,
-  };
-
-  const border: BorderSemantics = {
-    default: neutral.border,
-    strong: neutral.borderStrong,
-    focus: brand.outline,
-  };
-
-  const action: ActionSemantics = {
-    primary: brand,
-    neutral: buildRoleSemantics(neutralSwatch, isDark),
-    danger,
-  };
+  const references = isDark ? DARK_SEMANTIC_COLOR_REFERENCES : LIGHT_SEMANTIC_COLOR_REFERENCES;
+  const resolved = resolveSemanticColors(generated, references);
+  const { semantics, colorDiagnostics } = resolveSurfaceSemanticModel({
+    generated,
+    mode,
+    references,
+    resolved,
+  });
+  const { border, content, error, info, neutral, success, surface, warning } = semantics;
 
   const colors: ThemeTokens['colors'] = {
-    primary: brand.base,
-    secondary: secondarySwatch[500],
-    accent: tertiarySwatch[500],
-    highlight: quaternarySwatch[500],
-    tertiary: tertiarySwatch[500],
-    quaternary: quaternarySwatch[500],
+    primary: swatches.primary[500],
+    secondary: (swatches.secondary ?? swatches.primary)[500],
+    accent: (swatches.tertiary ?? swatches.primary)[500],
+    highlight: (swatches.quaternary ?? swatches.primary)[500],
+    tertiary: (swatches.tertiary ?? swatches.primary)[500],
+    quaternary: (swatches.quaternary ?? swatches.primary)[500],
     background: neutral.bg,
-    surface: neutral.surface,
-    text: neutral.text,
-    textSecondary: neutral.textMuted,
-    border: neutral.border,
+    surface: surface.default,
+    text: content.default,
+    textSecondary: content.muted,
+    border: border.default,
     error: error.base,
     success: success.base,
     warning: warning.base,
@@ -190,21 +85,7 @@ export function generatePalette(
   return {
     colors,
     swatches,
-    semantics: {
-      neutral,
-      brand,
-      secondary: buildRoleSemantics(secondarySwatch, isDark),
-      accent: buildRoleSemantics(tertiarySwatch, isDark),
-      highlight: buildRoleSemantics(quaternarySwatch, isDark),
-      danger,
-      success,
-      warning,
-      error,
-      info,
-      surface: surfaceSemantics,
-      content,
-      border,
-      action,
-    },
+    semantics,
+    colorDiagnostics,
   };
 }

package/src/theme/createSurfaceColorDiagnosticCollector.ts

@@ -0,0 +1,91 @@
+import type {
+  ColorContrastContext,
+  ColorSelectionTarget,
+  ColorSwatch,
+  ColorSwatchTiePolicy,
+  HexColor,
+} from '@ankhorage/color-theory';
+import {
+  getContrastRatio,
+  getReadableForeground,
+  selectColorSwatchStep,
+} from '@ankhorage/color-theory';
+
+import type { SurfaceColorSelectionDiagnostic, SurfaceContrastDiagnostic } from './types';
+
+/** Collect deterministic Color Theory evidence while Surface resolves semantic colors. */
+export function createSurfaceColorDiagnosticCollector() {
+  return new SurfaceColorDiagnosticCollector();
+}
+
+class SurfaceColorDiagnosticCollector {
+  readonly selections: SurfaceColorSelectionDiagnostic[] = [];
+  readonly contrasts: SurfaceContrastDiagnostic[] = [];
+
+  readonly measureForeground = (
+    id: string,
+    foreground: HexColor,
+    background: HexColor,
+    minimumContrast: number,
+  ): HexColor => {
+    const contrast = getContrastRatio(foreground, background);
+    this.contrasts.push({
+      id,
+      foreground,
+      background,
+      contrast,
+      minimumContrast,
+      passes: contrast >= minimumContrast,
+    });
+    return foreground;
+  };
+
+  readonly measureSurface = (
+    id: string,
+    foreground: HexColor,
+    background: HexColor,
+    minimumContrast: number,
+  ): SurfaceContrastDiagnostic => {
+    const contrast = getContrastRatio(foreground, background);
+    return {
+      id,
+      foreground,
+      background,
+      contrast,
+      minimumContrast,
+      passes: contrast >= minimumContrast,
+    };
+  };
+
+  readonly selectColor = (
+    id: string,
+    swatch: ColorSwatch,
+    target: ColorSelectionTarget,
+    contexts: readonly ColorContrastContext[],
+    tiePolicy: ColorSwatchTiePolicy,
+  ): HexColor => {
+    const result = selectColorSwatchStep(swatch, target, contexts, tiePolicy);
+    this.selections.push({ id, result });
+    if (!result.selected) {
+      throw new Error(`[surface] No '${id}' swatch step satisfies the required contrast.`);
+    }
+    return result.selected.hex;
+  };
+
+  readonly selectForeground = (
+    id: string,
+    background: HexColor,
+    minimumContrast: number,
+  ): HexColor => {
+    const selected = getReadableForeground(background);
+    this.contrasts.push({
+      id,
+      foreground: selected.foreground,
+      background,
+      contrast: selected.contrast,
+      minimumContrast,
+      passes: selected.contrast >= minimumContrast,
+    });
+    return selected.foreground;
+  };
+}

package/src/theme/createSurfaceSemanticPolicy.ts

@@ -0,0 +1,174 @@
+import type {
+  ColorContrastContext,
+  ColorSelectionTarget,
+  ColorSwatch,
+  ColorSwatchTiePolicy,
+  HexColor,
+  SemanticColorToken,
+} from '@ankhorage/color-theory';
+import { parseHexColorOrThrow } from '@ankhorage/color-theory';
+
+import { SURFACE_COLOR_POLICY } from './surfaceColorPolicy';
+import type {
+  ContentSemantics,
+  NeutralSemantics,
+  SurfaceContrastDiagnostic,
+  SurfaceSemantics,
+} from './types';
+
+type ResolvedSemanticColors = Record<SemanticColorToken, HexColor>;
+
+interface SurfaceSemanticMeasurements {
+  measureForeground: (
+    id: string,
+    foreground: HexColor,
+    background: HexColor,
+    minimumContrast: number,
+  ) => HexColor;
+  measureSurface: (
+    id: string,
+    foreground: HexColor,
+    background: HexColor,
+    minimumContrast: number,
+  ) => SurfaceContrastDiagnostic;
+}
+
+/** Create the canonical Surface policy for selecting and measuring semantic colors. */
+export function createSurfaceSemanticPolicy(
+  resolved: ResolvedSemanticColors,
+  isDark: boolean,
+  measurements: SurfaceSemanticMeasurements,
+) {
+  return new SurfaceSemanticPolicy(resolved, isDark, measurements);
+}
+
+class SurfaceSemanticPolicy {
+  readonly adjacentSurfaceContexts: readonly ColorContrastContext[];
+  readonly textSurfaceContexts: readonly ColorContrastContext[];
+  readonly tiePolicy: ColorSwatchTiePolicy;
+
+  constructor(
+    private readonly resolved: ResolvedSemanticColors,
+    private readonly isDark: boolean,
+    private readonly measurements: SurfaceSemanticMeasurements,
+  ) {
+    this.adjacentSurfaceContexts = this.createSurfaceContexts(SURFACE_COLOR_POLICY.uiContrast);
+    this.textSurfaceContexts = this.createSurfaceContexts(SURFACE_COLOR_POLICY.textContrast);
+    this.tiePolicy = isDark ? 'lower-step' : 'higher-step';
+  }
+
+  buildNeutral(neutralSwatch: ColorSwatch): NeutralSemantics {
+    return {
+      bg: this.resolved.background,
+      bgSubtle: this.resolved.surface,
+      surface: this.resolved.surface,
+      surfaceHover: this.isDark ? neutralSwatch[800] : neutralSwatch[200],
+      surfaceActive: this.isDark ? neutralSwatch[700] : neutralSwatch[300],
+      border: this.resolved.border,
+      borderStrong: this.isDark ? neutralSwatch[600] : neutralSwatch[300],
+      divider: this.resolved.divider,
+      text: this.resolved.text,
+      textMuted: this.resolved.textMuted,
+      textSubtle: this.isDark ? neutralSwatch[300] : neutralSwatch[600],
+      disabledBg: this.resolved.disabledBg,
+      disabledText: this.resolved.disabledText,
+    };
+  }
+
+  buildSurface(inverse: HexColor): SurfaceSemantics {
+    return {
+      default: this.resolved.surface,
+      subtle: this.resolved.background,
+      raised: this.resolved.surfaceRaised,
+      sunken: this.resolved.background,
+      overlay: this.resolved.surfaceRaised,
+      scrim: '#0000008f',
+      disabled: this.resolved.disabledBg,
+      inverse,
+    };
+  }
+
+  measureContent(content: ContentSemantics, surface: SurfaceSemantics): void {
+    const pairs = [
+      [
+        'content.default/background',
+        content.default,
+        surface.sunken,
+        SURFACE_COLOR_POLICY.textContrast,
+      ],
+      [
+        'content.default/surface',
+        content.default,
+        surface.default,
+        SURFACE_COLOR_POLICY.textContrast,
+      ],
+      ['content.muted/surface', content.muted, surface.default, SURFACE_COLOR_POLICY.textContrast],
+      [
+        'content.subtle/surface',
+        content.subtle,
+        surface.default,
+        SURFACE_COLOR_POLICY.textContrast,
+      ],
+      [
+        'content.disabled/disabled',
+        content.disabled,
+        surface.disabled,
+        SURFACE_COLOR_POLICY.disabledContrast,
+      ],
+      [
+        'content.inverse/inverse',
+        content.inverse,
+        surface.inverse,
+        SURFACE_COLOR_POLICY.textContrast,
+      ],
+    ] as const;
+    for (const [id, foreground, background, minimumContrast] of pairs) {
+      this.measurements.measureForeground(
+        id,
+        parseHexColorOrThrow(foreground),
+        parseHexColorOrThrow(background),
+        minimumContrast,
+      );
+    }
+  }
+
+  measureSurfaceSeparation(surface: SurfaceSemantics): SurfaceContrastDiagnostic[] {
+    return [
+      this.measureSurface('surface.default', surface.default),
+      this.measureSurface('surface.raised', surface.raised),
+      this.measureSurface('surface.disabled', surface.disabled),
+    ];
+  }
+
+  neutralTarget(): ColorSelectionTarget {
+    return { lightness: this.isDark ? 0.65 : 0.55, chroma: 0.02 };
+  }
+
+  roleTarget(): ColorSelectionTarget {
+    return { lightness: this.isDark ? 0.65 : 0.5, chroma: 0.15 };
+  }
+
+  strongNeutralTarget(): ColorSelectionTarget {
+    return { lightness: this.isDark ? 0.8 : 0.4, chroma: 0.02 };
+  }
+
+  textTarget(): ColorSelectionTarget {
+    return { lightness: this.isDark ? 0.75 : 0.45, chroma: 0.15 };
+  }
+
+  private createSurfaceContexts(minimumContrast: number): readonly ColorContrastContext[] {
+    return [
+      { id: 'background', against: this.resolved.background, minimumContrast },
+      { id: 'surface', against: this.resolved.surface, minimumContrast },
+    ];
+  }
+
+  private measureSurface(id: string, foreground: string): SurfaceContrastDiagnostic {
+    return this.measurements.measureSurface(
+      id,
+      parseHexColorOrThrow(foreground),
+      this.resolved.background,
+      SURFACE_COLOR_POLICY.surfaceSeparation,
+    );
+  }
+}

package/src/theme/createTheme.ts

@@ -28,12 +28,13 @@ export function createTheme(
   mode: 'light' | 'dark' = 'light',
   activeFontId?: string | null,
 ): SurfaceTheme {
-  const { colors, swatches, semantics } = generatePalette(config, mode);
+  const { colors, swatches, semantics, colorDiagnostics } = generatePalette(config, mode);
   const theme: SurfaceTheme = {
     ...resolveGlobalTokens(config.tokens),
     colors,
     swatches,
     semantics,
+    colorDiagnostics,
     config,
   };
 

package/src/theme/defaultTokens.ts

@@ -14,7 +14,10 @@ const EMPTY_FONT_MAP: Record<FontWeight, string | undefined> = {
   normal: undefined,
 };
 
-export const DEFAULT_TOKENS: Omit<ThemeTokens, 'colors' | 'swatches' | 'semantics'> = {
+export const DEFAULT_TOKENS: Omit<
+  ThemeTokens,
+  'colors' | 'swatches' | 'semantics' | 'colorDiagnostics'
+> = {
   spacing: { none: 0, xs: 4, s: 8, m: 16, l: 24, xl: 32, xxl: 48 },
   radii: { none: 0, s: 4, m: 8, l: 16, full: 9999 },
   typography: {

package/src/theme/resolveGlobalTokens.ts

@@ -6,7 +6,10 @@ import { resolveNumericTokenOverrides } from './resolveNumericTokenOverrides';
 import { resolveWeightTokenOverrides } from './resolveWeightTokenOverrides';
 import type { ThemeTokens } from './types';
 
-type GlobalThemeTokens = Omit<ThemeTokens, 'colors' | 'swatches' | 'semantics'>;
+type GlobalThemeTokens = Omit<
+  ThemeTokens,
+  'colors' | 'swatches' | 'semantics' | 'colorDiagnostics'
+>;
 
 export function resolveGlobalTokens(overrides?: ThemeGlobalTokenOverrides): GlobalThemeTokens {
   validateZeroTokens(overrides);

package/src/theme/resolveRoleSemantics.ts

@@ -0,0 +1,96 @@
+import type { ColorSwatch, HexColor } from '@ankhorage/color-theory';
+
+import { SURFACE_COLOR_POLICY } from './surfaceColorPolicy';
+import type { RoleSemantics } from './types';
+
+interface ResolveRoleSemanticsInput {
+  base?: HexColor;
+  disabledBg: HexColor;
+  disabledText: HexColor;
+  hover?: HexColor;
+  id: string;
+  isDark: boolean;
+  measureForeground: (
+    id: string,
+    foreground: HexColor,
+    background: HexColor,
+    minimumContrast: number,
+  ) => HexColor;
+  onSurfaceText: HexColor;
+  outline: HexColor;
+  selectForeground: (id: string, background: HexColor, minimumContrast: number) => HexColor;
+  swatch: ColorSwatch;
+}
+
+interface RoleStateColors {
+  base: HexColor;
+  hover: HexColor;
+  softActive: HexColor;
+  softBg: HexColor;
+  softHover: HexColor;
+  strong: HexColor;
+}
+
+/** Resolve every filled role state together with its measured foreground. */
+export function resolveRoleSemantics({
+  base,
+  disabledBg,
+  disabledText,
+  hover,
+  id,
+  isDark,
+  measureForeground,
+  onSurfaceText,
+  outline,
+  selectForeground,
+  swatch,
+}: ResolveRoleSemanticsInput): RoleSemantics {
+  const states = resolveRoleStateColors(swatch, isDark, base, hover);
+
+  return {
+    ...states,
+    outline,
+    onSurfaceText,
+    onSolidText: selectForeground(`${id}.base`, states.base, SURFACE_COLOR_POLICY.textContrast),
+    onHoverText: selectForeground(`${id}.hover`, states.hover, SURFACE_COLOR_POLICY.textContrast),
+    onStrongText: selectForeground(
+      `${id}.strong`,
+      states.strong,
+      SURFACE_COLOR_POLICY.textContrast,
+    ),
+    onSoftText: selectForeground(`${id}.soft`, states.softBg, SURFACE_COLOR_POLICY.textContrast),
+    onSoftHoverText: selectForeground(
+      `${id}.softHover`,
+      states.softHover,
+      SURFACE_COLOR_POLICY.textContrast,
+    ),
+    onSoftActiveText: selectForeground(
+      `${id}.softActive`,
+      states.softActive,
+      SURFACE_COLOR_POLICY.textContrast,
+    ),
+    disabledBg,
+    onDisabledText: measureForeground(
+      `${id}.disabled`,
+      disabledText,
+      disabledBg,
+      SURFACE_COLOR_POLICY.disabledContrast,
+    ),
+  };
+}
+
+function resolveRoleStateColors(
+  swatch: ColorSwatch,
+  isDark: boolean,
+  base?: HexColor,
+  hover?: HexColor,
+): RoleStateColors {
+  return {
+    base: base ?? swatch[500],
+    hover: hover ?? (isDark ? swatch[400] : swatch[600]),
+    strong: isDark ? swatch[300] : swatch[700],
+    softBg: isDark ? swatch[900] : swatch[100],
+    softHover: isDark ? swatch[800] : swatch[200],
+    softActive: isDark ? swatch[700] : swatch[300],
+  };
+}