@ankhorage/surface 2.0.1 → 2.0.3

package/dist/theme/colorEngine.js

@@ -85,16 +85,19 @@ export function generatePalette(config, mode = 'light') {
     // 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 = {
         default: neutral.surface,
         subtle: neutral.bgSubtle,
         raised: neutral.surface,
+        inverse: inverseSurface,
     };
     const content = {
         default: neutral.text,
         muted: neutral.textMuted,
         subtle: neutral.textSubtle,
-        inverse: brand.onSolidText,
+        inverse: inverseOnSurface,
     };
     const border = {
         default: neutral.border,

package/dist/theme/colorEngine.js.map

@@ -1 +1 @@
-{"version":3,"file":"colorEngine.js","sourceRoot":"","sources":["../../src/theme/colorEngine.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ColorSwatch,\n  GeneratedThemeModeColors,\n  GeneratedThemeSwatches,\n  HexColor,\n  SemanticColorReferenceMap,\n  SemanticColorToken,\n} from '@ankhorage/color-theory';\nimport {\n  createDefaultSemanticStatusSwatches,\n  generateThemeModeColors,\n  getReadableForeground,\n  parseHexColorOrThrow,\n} from '@ankhorage/color-theory';\nimport type { ThemeConfig } from '@ankhorage/contracts';\n\nimport type {\n  ActionSemantics,\n  BorderSemantics,\n  ContentSemantics,\n  NeutralSemantics,\n  RoleSemantics,\n  SurfaceSemantics,\n  ThemeSemantics,\n} from './types';\n\n/**\n * Surface semantic resolver: maps color-theory SemanticColorToken references\n * to hex values from the generated swatches.\n */\nexport type SurfaceSemanticColors = Record<SemanticColorToken, HexColor>;\n\nexport function resolveSemanticColors(\n  generated: GeneratedThemeModeColors,\n  references: SemanticColorReferenceMap,\n): SurfaceSemanticColors {\n  return Object.fromEntries(\n    Object.entries(references).map(([token, ref]) => {\n      const swatch = generated.swatches[ref.role];\n      if (!swatch) {\n        throw new Error(`Missing swatch for role '${ref.role}' (token: '${token}')`);\n      }\n      return [token, swatch[ref.step]];\n    }),\n  ) as SurfaceSemanticColors;\n}\n\nfunction buildNeutralSemantics(neutralSwatch: ColorSwatch, isDark: boolean): NeutralSemantics {\n  if (isDark) {\n    return {\n      bg: neutralSwatch[950],\n      bgSubtle: neutralSwatch[900],\n      surface: neutralSwatch[900],\n      surfaceHover: neutralSwatch[800],\n      surfaceActive: neutralSwatch[700],\n      border: neutralSwatch[800],\n      borderStrong: neutralSwatch[600],\n      divider: neutralSwatch[800],\n      text: neutralSwatch[50],\n      textMuted: neutralSwatch[200],\n      textSubtle: neutralSwatch[300],\n    };\n  }\n  return {\n    bg: neutralSwatch[50],\n    bgSubtle: neutralSwatch[100],\n    surface: neutralSwatch[100],\n    surfaceHover: neutralSwatch[200],\n    surfaceActive: neutralSwatch[300],\n    border: neutralSwatch[200],\n    borderStrong: neutralSwatch[300],\n    divider: neutralSwatch[200],\n    text: neutralSwatch[900],\n    textMuted: neutralSwatch[700],\n    textSubtle: neutralSwatch[600],\n  };\n}\n\nfunction buildRoleSemantics(swatch: ColorSwatch, isDark: boolean): RoleSemantics {\n  const base = swatch[500];\n  const { foreground: onSolidText } = getReadableForeground(base);\n\n  if (isDark) {\n    return {\n      base,\n      hover: swatch[400],\n      strong: swatch[300],\n      softBg: swatch[900],\n      softHover: swatch[800],\n      softActive: swatch[700],\n      outline: swatch[500],\n      onSolidText,\n    };\n  }\n\n  return {\n    base,\n    hover: swatch[600],\n    strong: swatch[700],\n    softBg: swatch[100],\n    softHover: swatch[200],\n    softActive: swatch[300],\n    outline: swatch[400],\n    onSolidText,\n  };\n}\n\nexport function generatePalette(\n  config: ThemeConfig,\n  mode: 'light' | 'dark' = 'light',\n): {\n  colors: Record<string, string>;\n  swatches: GeneratedThemeSwatches;\n  semantics: ThemeSemantics;\n} {\n  const modeConfig = mode === 'dark' ? config.dark : config.light;\n  const isDark = mode === 'dark';\n\n  // Throws deterministically on invalid primary color\n  parseHexColorOrThrow(modeConfig.primaryColor);\n\n  const generated = generateThemeModeColors(modeConfig);\n\n  const { swatches } = generated;\n  const neutralSwatch = swatches.neutral;\n\n  const neutral = buildNeutralSemantics(neutralSwatch, isDark);\n  const brand = buildRoleSemantics(swatches.primary, isDark);\n\n  // Fallback to primary swatch for missing ordinal roles\n  const secondarySwatch = swatches.secondary ?? swatches.primary;\n  const tertiarySwatch = swatches.tertiary ?? swatches.primary;\n  const quaternarySwatch = swatches.quaternary ?? swatches.primary;\n\n  const semanticStatusSwatches = createDefaultSemanticStatusSwatches().swatches;\n\n  const danger = buildRoleSemantics(semanticStatusSwatches.danger, isDark);\n  const success = buildRoleSemantics(semanticStatusSwatches.success, isDark);\n  const warning = buildRoleSemantics(semanticStatusSwatches.warning, isDark);\n  // Keep destructive action and feedback error aligned until a dedicated error status swatch is introduced.\n  const error = danger;\n  const info = buildRoleSemantics(secondarySwatch, isDark);\n\n  const surfaceSemantics: SurfaceSemantics = {\n    default: neutral.surface,\n    subtle: neutral.bgSubtle,\n    raised: neutral.surface,\n  };\n\n  const content: ContentSemantics = {\n    default: neutral.text,\n    muted: neutral.textMuted,\n    subtle: neutral.textSubtle,\n    inverse: brand.onSolidText,\n  };\n\n  const border: BorderSemantics = {\n    default: neutral.border,\n    strong: neutral.borderStrong,\n    focus: brand.outline,\n  };\n\n  const action: ActionSemantics = {\n    primary: brand,\n    neutral: buildRoleSemantics(neutralSwatch, isDark),\n    danger,\n  };\n\n  const colors: Record<string, string> = {\n    primary: brand.base,\n    secondary: secondarySwatch[500],\n    accent: tertiarySwatch[500],\n    highlight: quaternarySwatch[500],\n    tertiary: tertiarySwatch[500],\n    quaternary: quaternarySwatch[500],\n    background: neutral.bg,\n    surface: neutral.surface,\n    text: neutral.text,\n    textSecondary: neutral.textMuted,\n    border: neutral.border,\n    error: error.base,\n    success: success.base,\n    warning: warning.base,\n    info: info.base,\n  };\n\n  return {\n    colors,\n    swatches,\n    semantics: {\n      neutral,\n      brand,\n      secondary: buildRoleSemantics(secondarySwatch, isDark),\n      accent: buildRoleSemantics(tertiarySwatch, isDark),\n      highlight: buildRoleSemantics(quaternarySwatch, isDark),\n      danger,\n      success,\n      warning,\n      error,\n      info,\n      surface: surfaceSemantics,\n      content,\n      border,\n      action,\n    },\n  };\n}\n"]}
+{"version":3,"file":"colorEngine.js","sourceRoot":"","sources":["../../src/theme/colorEngine.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ColorSwatch,\n  GeneratedThemeModeColors,\n  GeneratedThemeSwatches,\n  HexColor,\n  SemanticColorReferenceMap,\n  SemanticColorToken,\n} from '@ankhorage/color-theory';\nimport {\n  createDefaultSemanticStatusSwatches,\n  generateThemeModeColors,\n  getReadableForeground,\n  parseHexColorOrThrow,\n} from '@ankhorage/color-theory';\nimport type { ThemeConfig } from '@ankhorage/contracts';\n\nimport type {\n  ActionSemantics,\n  BorderSemantics,\n  ContentSemantics,\n  NeutralSemantics,\n  RoleSemantics,\n  SurfaceSemantics,\n  ThemeSemantics,\n} from './types';\n\n/**\n * Surface semantic resolver: maps color-theory SemanticColorToken references\n * to hex values from the generated swatches.\n */\nexport type SurfaceSemanticColors = Record<SemanticColorToken, HexColor>;\n\nexport function resolveSemanticColors(\n  generated: GeneratedThemeModeColors,\n  references: SemanticColorReferenceMap,\n): SurfaceSemanticColors {\n  return Object.fromEntries(\n    Object.entries(references).map(([token, ref]) => {\n      const swatch = generated.swatches[ref.role];\n      if (!swatch) {\n        throw new Error(`Missing swatch for role '${ref.role}' (token: '${token}')`);\n      }\n      return [token, swatch[ref.step]];\n    }),\n  ) as SurfaceSemanticColors;\n}\n\nfunction buildNeutralSemantics(neutralSwatch: ColorSwatch, isDark: boolean): NeutralSemantics {\n  if (isDark) {\n    return {\n      bg: neutralSwatch[950],\n      bgSubtle: neutralSwatch[900],\n      surface: neutralSwatch[900],\n      surfaceHover: neutralSwatch[800],\n      surfaceActive: neutralSwatch[700],\n      border: neutralSwatch[800],\n      borderStrong: neutralSwatch[600],\n      divider: neutralSwatch[800],\n      text: neutralSwatch[50],\n      textMuted: neutralSwatch[200],\n      textSubtle: neutralSwatch[300],\n    };\n  }\n  return {\n    bg: neutralSwatch[50],\n    bgSubtle: neutralSwatch[100],\n    surface: neutralSwatch[100],\n    surfaceHover: neutralSwatch[200],\n    surfaceActive: neutralSwatch[300],\n    border: neutralSwatch[200],\n    borderStrong: neutralSwatch[300],\n    divider: neutralSwatch[200],\n    text: neutralSwatch[900],\n    textMuted: neutralSwatch[700],\n    textSubtle: neutralSwatch[600],\n  };\n}\n\nfunction buildRoleSemantics(swatch: ColorSwatch, isDark: boolean): RoleSemantics {\n  const base = swatch[500];\n  const { foreground: onSolidText } = getReadableForeground(base);\n\n  if (isDark) {\n    return {\n      base,\n      hover: swatch[400],\n      strong: swatch[300],\n      softBg: swatch[900],\n      softHover: swatch[800],\n      softActive: swatch[700],\n      outline: swatch[500],\n      onSolidText,\n    };\n  }\n\n  return {\n    base,\n    hover: swatch[600],\n    strong: swatch[700],\n    softBg: swatch[100],\n    softHover: swatch[200],\n    softActive: swatch[300],\n    outline: swatch[400],\n    onSolidText,\n  };\n}\n\nexport function generatePalette(\n  config: ThemeConfig,\n  mode: 'light' | 'dark' = 'light',\n): {\n  colors: Record<string, string>;\n  swatches: GeneratedThemeSwatches;\n  semantics: ThemeSemantics;\n} {\n  const modeConfig = mode === 'dark' ? config.dark : config.light;\n  const isDark = mode === 'dark';\n\n  // Throws deterministically on invalid primary color\n  parseHexColorOrThrow(modeConfig.primaryColor);\n\n  const generated = generateThemeModeColors(modeConfig);\n  const { swatches } = generated;\n  const neutralSwatch = swatches.neutral;\n\n  const neutral = buildNeutralSemantics(neutralSwatch, isDark);\n  const brand = buildRoleSemantics(swatches.primary, isDark);\n\n  // Fallback to primary swatch for missing ordinal roles\n  const secondarySwatch = swatches.secondary ?? swatches.primary;\n  const tertiarySwatch = swatches.tertiary ?? swatches.primary;\n  const quaternarySwatch = swatches.quaternary ?? swatches.primary;\n\n  const semanticStatusSwatches = createDefaultSemanticStatusSwatches().swatches;\n\n  const danger = buildRoleSemantics(semanticStatusSwatches.danger, isDark);\n  const success = buildRoleSemantics(semanticStatusSwatches.success, isDark);\n  const warning = buildRoleSemantics(semanticStatusSwatches.warning, isDark);\n  // Keep destructive action and feedback error aligned until a dedicated error status swatch is introduced.\n  const error = danger;\n  const info = buildRoleSemantics(secondarySwatch, isDark);\n  const inverseSurface = isDark ? neutralSwatch[50] : neutralSwatch[900];\n  const inverseOnSurface = isDark ? neutralSwatch[900] : neutralSwatch[50];\n\n  const surfaceSemantics: SurfaceSemantics = {\n    default: neutral.surface,\n    subtle: neutral.bgSubtle,\n    raised: neutral.surface,\n    inverse: inverseSurface,\n  };\n\n  const content: ContentSemantics = {\n    default: neutral.text,\n    muted: neutral.textMuted,\n    subtle: neutral.textSubtle,\n    inverse: inverseOnSurface,\n  };\n\n  const border: BorderSemantics = {\n    default: neutral.border,\n    strong: neutral.borderStrong,\n    focus: brand.outline,\n  };\n\n  const action: ActionSemantics = {\n    primary: brand,\n    neutral: buildRoleSemantics(neutralSwatch, isDark),\n    danger,\n  };\n\n  const colors: Record<string, string> = {\n    primary: brand.base,\n    secondary: secondarySwatch[500],\n    accent: tertiarySwatch[500],\n    highlight: quaternarySwatch[500],\n    tertiary: tertiarySwatch[500],\n    quaternary: quaternarySwatch[500],\n    background: neutral.bg,\n    surface: neutral.surface,\n    text: neutral.text,\n    textSecondary: neutral.textMuted,\n    border: neutral.border,\n    error: error.base,\n    success: success.base,\n    warning: warning.base,\n    info: info.base,\n  };\n\n  return {\n    colors,\n    swatches,\n    semantics: {\n      neutral,\n      brand,\n      secondary: buildRoleSemantics(secondarySwatch, isDark),\n      accent: buildRoleSemantics(tertiarySwatch, isDark),\n      highlight: buildRoleSemantics(quaternarySwatch, isDark),\n      danger,\n      success,\n      warning,\n      error,\n      info,\n      surface: surfaceSemantics,\n      content,\n      border,\n      action,\n    },\n  };\n}\n"]}

package/dist/theme/types.d.ts

@@ -29,6 +29,7 @@ export interface SurfaceSemantics {
     default: string;
     subtle: string;
     raised: string;
+    inverse: string;
 }
 export interface ContentSemantics {
     default: string;

package/dist/theme/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"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"}

package/dist/theme/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { GeneratedThemeSwatches } from '@ankhorage/color-theory';\nimport type { ThemeConfig as ContractsThemeConfig } from '@ankhorage/contracts';\n\nexport type {\n  ColorHarmony,\n  ColorSwatch,\n  ColorSwatchStep,\n  GeneratedColorRole,\n  GeneratedThemeModeColors,\n  GeneratedThemeSwatches,\n  HexColor,\n  SemanticColorReferenceMap,\n  SemanticColorToken,\n} from '@ankhorage/color-theory';\nexport type { ThemeConfig, ThemeModeConfig } from '@ankhorage/contracts';\n\nexport interface NeutralSemantics {\n  bg: string;\n  bgSubtle: string;\n  surface: string;\n  surfaceHover: string;\n  surfaceActive: string;\n  border: string;\n  borderStrong: string;\n  divider: string;\n  text: string;\n  textMuted: string;\n  textSubtle: string;\n}\n\nexport interface RoleSemantics {\n  base: string;\n  hover: string;\n  strong: string;\n  softBg: string;\n  softHover: string;\n  softActive: string;\n  outline: string;\n  onSolidText: string;\n}\n\nexport interface SurfaceSemantics {\n  default: string;\n  subtle: string;\n  raised: string;\n}\n\nexport interface ContentSemantics {\n  default: string;\n  muted: string;\n  subtle: string;\n  inverse: string;\n}\n\nexport interface BorderSemantics {\n  default: string;\n  strong: string;\n  focus: string;\n}\n\nexport interface ActionSemantics {\n  primary: RoleSemantics;\n  neutral: RoleSemantics;\n  danger: RoleSemantics;\n}\n\nexport interface ThemeSemantics {\n  neutral: NeutralSemantics;\n  brand: RoleSemantics;\n  secondary: RoleSemantics;\n  accent: RoleSemantics;\n  highlight: RoleSemantics;\n  danger: RoleSemantics;\n  success: RoleSemantics;\n  warning: RoleSemantics;\n  error: RoleSemantics;\n  info: RoleSemantics;\n  surface: SurfaceSemantics;\n  content: ContentSemantics;\n  border: BorderSemantics;\n  action: ActionSemantics;\n}\n\nexport type FontWeight =\n  | '100'\n  | '200'\n  | '300'\n  | '400'\n  | '500'\n  | '600'\n  | '700'\n  | '800'\n  | '900'\n  | 'bold'\n  | 'normal';\n\nexport interface ThemeTokens {\n  colors: {\n    primary: string;\n    secondary: string;\n    accent: string;\n    highlight: string;\n    tertiary: string;\n    quaternary: string;\n    background: string;\n    surface: string;\n    text: string;\n    textSecondary: string;\n    border: string;\n    error: string;\n    success: string;\n    warning: string;\n    info: string;\n    [key: string]: string;\n  };\n  swatches: GeneratedThemeSwatches;\n  semantics: ThemeSemantics;\n  spacing: {\n    none: 0;\n    xs: number;\n    s: number;\n    m: number;\n    l: number;\n    xl: number;\n    xxl: number;\n    [key: string]: number;\n  };\n  radii: {\n    none: 0;\n    s: number;\n    m: number;\n    l: number;\n    full: number;\n  };\n  typography: {\n    headings: Record<\n      1 | 2 | 3 | 4 | 5 | 6,\n      {\n        size: number;\n        lineHeight: number;\n        weight: 'regular' | 'medium' | 'semiBold' | 'bold';\n      }\n    >;\n    sizes: {\n      xs: number;\n      s: number;\n      m: number;\n      l: number;\n      xl: number;\n      xxl: number;\n      '3xl': number;\n      h1: number;\n      h2: number;\n      h3: number;\n      h4: number;\n      h5: number;\n      h6: number;\n      [key: string]: number;\n    };\n    weights: {\n      thin: FontWeight;\n      extraLight: FontWeight;\n      light: FontWeight;\n      regular: FontWeight;\n      medium: FontWeight;\n      semiBold: FontWeight;\n      bold: FontWeight;\n      extraBold: FontWeight;\n      black: FontWeight;\n    };\n    fonts: {\n      /** Map of weight -> fontFamily name for normal style */\n      normal: Record<FontWeight, string | undefined>;\n      /** Map of weight -> fontFamily name for italic style */\n      italic: Record<FontWeight, string | undefined>;\n    };\n  };\n  shadows: {\n    soft: number;\n    medium: number;\n    hard: number;\n    [key: string]: number;\n  };\n}\n\nexport interface SurfaceTheme extends ThemeTokens {\n  config: ContractsThemeConfig;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { GeneratedThemeSwatches } from '@ankhorage/color-theory';\nimport type { ThemeConfig as ContractsThemeConfig } from '@ankhorage/contracts';\n\nexport type {\n  ColorHarmony,\n  ColorSwatch,\n  ColorSwatchStep,\n  GeneratedColorRole,\n  GeneratedThemeModeColors,\n  GeneratedThemeSwatches,\n  HexColor,\n  SemanticColorReferenceMap,\n  SemanticColorToken,\n} from '@ankhorage/color-theory';\nexport type { ThemeConfig, ThemeModeConfig } from '@ankhorage/contracts';\n\nexport interface NeutralSemantics {\n  bg: string;\n  bgSubtle: string;\n  surface: string;\n  surfaceHover: string;\n  surfaceActive: string;\n  border: string;\n  borderStrong: string;\n  divider: string;\n  text: string;\n  textMuted: string;\n  textSubtle: string;\n}\n\nexport interface RoleSemantics {\n  base: string;\n  hover: string;\n  strong: string;\n  softBg: string;\n  softHover: string;\n  softActive: string;\n  outline: string;\n  onSolidText: string;\n}\n\nexport interface SurfaceSemantics {\n  default: string;\n  subtle: string;\n  raised: string;\n  inverse: string;\n}\n\nexport interface ContentSemantics {\n  default: string;\n  muted: string;\n  subtle: string;\n  inverse: string;\n}\n\nexport interface BorderSemantics {\n  default: string;\n  strong: string;\n  focus: string;\n}\n\nexport interface ActionSemantics {\n  primary: RoleSemantics;\n  neutral: RoleSemantics;\n  danger: RoleSemantics;\n}\n\nexport interface ThemeSemantics {\n  neutral: NeutralSemantics;\n  brand: RoleSemantics;\n  secondary: RoleSemantics;\n  accent: RoleSemantics;\n  highlight: RoleSemantics;\n  danger: RoleSemantics;\n  success: RoleSemantics;\n  warning: RoleSemantics;\n  error: RoleSemantics;\n  info: RoleSemantics;\n  surface: SurfaceSemantics;\n  content: ContentSemantics;\n  border: BorderSemantics;\n  action: ActionSemantics;\n}\n\nexport type FontWeight =\n  | '100'\n  | '200'\n  | '300'\n  | '400'\n  | '500'\n  | '600'\n  | '700'\n  | '800'\n  | '900'\n  | 'bold'\n  | 'normal';\n\nexport interface ThemeTokens {\n  colors: {\n    primary: string;\n    secondary: string;\n    accent: string;\n    highlight: string;\n    tertiary: string;\n    quaternary: string;\n    background: string;\n    surface: string;\n    text: string;\n    textSecondary: string;\n    border: string;\n    error: string;\n    success: string;\n    warning: string;\n    info: string;\n    [key: string]: string;\n  };\n  swatches: GeneratedThemeSwatches;\n  semantics: ThemeSemantics;\n  spacing: {\n    none: 0;\n    xs: number;\n    s: number;\n    m: number;\n    l: number;\n    xl: number;\n    xxl: number;\n    [key: string]: number;\n  };\n  radii: {\n    none: 0;\n    s: number;\n    m: number;\n    l: number;\n    full: number;\n  };\n  typography: {\n    headings: Record<\n      1 | 2 | 3 | 4 | 5 | 6,\n      {\n        size: number;\n        lineHeight: number;\n        weight: 'regular' | 'medium' | 'semiBold' | 'bold';\n      }\n    >;\n    sizes: {\n      xs: number;\n      s: number;\n      m: number;\n      l: number;\n      xl: number;\n      xxl: number;\n      '3xl': number;\n      h1: number;\n      h2: number;\n      h3: number;\n      h4: number;\n      h5: number;\n      h6: number;\n      [key: string]: number;\n    };\n    weights: {\n      thin: FontWeight;\n      extraLight: FontWeight;\n      light: FontWeight;\n      regular: FontWeight;\n      medium: FontWeight;\n      semiBold: FontWeight;\n      bold: FontWeight;\n      extraBold: FontWeight;\n      black: FontWeight;\n    };\n    fonts: {\n      /** Map of weight -> fontFamily name for normal style */\n      normal: Record<FontWeight, string | undefined>;\n      /** Map of weight -> fontFamily name for italic style */\n      italic: Record<FontWeight, string | undefined>;\n    };\n  };\n  shadows: {\n    soft: number;\n    medium: number;\n    hard: number;\n    [key: string]: number;\n  };\n}\n\nexport interface SurfaceTheme extends ThemeTokens {\n  config: ContractsThemeConfig;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/surface",
   "type": "module",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Stable UI foundation for React Native and React Native Web.",
   "homepage": "https://github.com/ankhorage/surface#readme",
   "bugs": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@ankhorage/color-theory": "^0.0.7",
-    "@ankhorage/contracts": "^1.7.0"
+    "@ankhorage/contracts": "^2.1.0"
   },
   "files": [
     "dist",
@@ -69,6 +69,7 @@
     "build": "rm -rf dist tsconfig.tsbuildinfo && bun x tsc -p tsconfig.json",
     "changeset": "changeset",
     "changeset:status": "changeset status --since=origin/main",
+    "docs": "paradox",
     "knip": "ankhorage-knip",
     "lint": "ankhorage-eslint . --max-warnings=0",
     "lint:fix": "ankhorage-eslint . --fix --max-warnings=0",
@@ -76,10 +77,12 @@
     "format:check": "ankhorage-prettier --check .",
     "prepack": "bun run build",
     "test": "bun test src",
+    "typecheck": "bun x tsc --noEmit -p tsconfig.json",
     "version-packages": "changeset version"
   },
   "devDependencies": {
     "@ankhorage/devtools": "^1.0.6",
+    "@ankhorage/paradox": "^0.1.7",
     "@changesets/cli": "^2.31.0",
     "@expo/vector-icons": "^15.1.1",
     "@types/bun": "^1.3.13",

package/src/components/menu/Menu.tsx

@@ -5,12 +5,12 @@ import { FocusScope } from '../../internal/focus/FocusScope';
 import { useFocusManager } from '../../internal/focus/useFocusManager';
 import { Portal } from '../../internal/overlay/Portal';
 import { resolveOverlayAnimation } from '../../internal/resolvers';
-import { Box, Surface } from '../../layout';
+import { Box, Inline, Stack, Surface } from '../../layout';
 import { ButtonBase } from '../../primitives/button-base';
 import { Text } from '../../primitives/text';
 import { useTheme } from '../../theme/ThemeContext';
 import { resolveNextMenuIndex } from './navigation';
-import type { MenuProps } from './types';
+import type { MenuAction, MenuProps } from './types';
 
 interface MeasurableNode {
   measureInWindow?: (
@@ -25,7 +25,35 @@ function measureNode(node: unknown, callback: (layout: LayoutRectangle) => void)
   });
 }
 
-export function Menu({ trigger, items, onDismiss, closeOnSelect = true, testID }: MenuProps) {
+function renderActionContent(action: MenuAction, active: boolean) {
+  const titleColor =
+    action.intent === 'danger' ? 'danger' : active || action.selected ? 'neutral' : undefined;
+
+  return (
+    <Inline align="center" gap="s" justify="space-between" wrap="nowrap">
+      {action.leading ? <Box>{action.leading}</Box> : null}
+      <Box flex={1}>
+        <Stack gap="xxs">
+          <Text
+            color={titleColor}
+            variant="bodySmall"
+            weight={action.selected ? 'semiBold' : 'medium'}
+          >
+            {action.title}
+          </Text>
+          {action.description ? (
+            <Text emphasis="muted" variant="caption">
+              {action.description}
+            </Text>
+          ) : null}
+        </Stack>
+      </Box>
+      {action.trailing ? <Box>{action.trailing}</Box> : null}
+    </Inline>
+  );
+}
+
+export function Menu({ trigger, actions, dismiss, closeOnSelect = true, testID }: MenuProps) {
   const { theme } = useTheme();
   const { bindKeydown } = useFocusManager();
   const animation = resolveOverlayAnimation('menu');
@@ -36,15 +64,34 @@ export function Menu({ trigger, items, onDismiss, closeOnSelect = true, testID }
 
   const closeMenu = React.useCallback(() => {
     setOpen(false);
-    onDismiss?.();
-  }, [onDismiss]);
+    if (dismiss) {
+      dismiss();
+    }
+  }, [dismiss]);
+
+  const activateAction = React.useCallback(
+    (action: MenuAction) => {
+      if (action.disabled) {
+        return;
+      }
+
+      if (action.activate) {
+        action.activate();
+      }
+
+      if (closeOnSelect) {
+        closeMenu();
+      }
+    },
+    [closeMenu, closeOnSelect],
+  );
 
   const openMenu = React.useCallback(() => {
     measureNode(anchorRef.current, setLayout);
-    const firstEnabledIndex = items.findIndex((item) => !item.disabled);
+    const firstEnabledIndex = actions.findIndex((action) => !action.disabled);
     setActiveIndex(firstEnabledIndex === -1 ? 0 : firstEnabledIndex);
     setOpen(true);
-  }, [items]);
+  }, [actions]);
 
   React.useEffect(() => {
     if (!open) {
@@ -55,17 +102,14 @@ export function Menu({ trigger, items, onDismiss, closeOnSelect = true, testID }
       const { key } = event;
       if (key === 'ArrowDown' || key === 'ArrowUp' || key === 'Home' || key === 'End') {
         event.preventDefault();
-        setActiveIndex((current) => resolveNextMenuIndex(items, current, key));
+        setActiveIndex((current) => resolveNextMenuIndex(actions, current, key));
       }
 
       if (event.key === 'Enter') {
         event.preventDefault();
-        const activeItem = items[activeIndex];
-        if (activeItem && !activeItem.disabled) {
-          activeItem.onPress?.();
-          if (closeOnSelect) {
-            closeMenu();
-          }
+        const activeAction = actions[activeIndex];
+        if (activeAction) {
+          activateAction(activeAction);
         }
       }
 
@@ -74,7 +118,7 @@ export function Menu({ trigger, items, onDismiss, closeOnSelect = true, testID }
         closeMenu();
       }
     });
-  }, [activeIndex, bindKeydown, closeMenu, closeOnSelect, items, open]);
+  }, [activateAction, actions, activeIndex, bindKeydown, closeMenu, open]);
 
   return (
     <View collapsable={false} ref={anchorRef}>
@@ -117,7 +161,7 @@ export function Menu({ trigger, items, onDismiss, closeOnSelect = true, testID }
                 accessibilityRole="menu"
                 p="xs"
                 style={{
-                  minWidth: Math.max(layout?.width ?? 0, 180),
+                  minWidth: Math.max(layout?.width ?? 0, 220),
                   shadowOpacity: 0.12,
                   shadowRadius: 12,
                   shadowOffset: { width: 0, height: 6 },
@@ -125,40 +169,31 @@ export function Menu({ trigger, items, onDismiss, closeOnSelect = true, testID }
                 testID={testID}
                 variant="raised"
               >
-                {items.map((item, index) => {
-                  const selected = index === activeIndex;
+                {actions.map((action, index) => {
+                  const active = index === activeIndex;
+                  const selected = action.selected ?? active;
 
                   return (
                     <Pressable
                       accessibilityRole="menuitem"
-                      accessibilityState={{ disabled: item.disabled, selected }}
-                      disabled={item.disabled}
-                      key={item.id}
-                      onPress={() => {
-                        if (item.disabled) {
-                          return;
-                        }
-
-                        item.onPress?.();
-                        if (closeOnSelect) {
-                          closeMenu();
-                        }
-                      }}
+                      accessibilityState={{ disabled: action.disabled, selected }}
+                      disabled={action.disabled}
+                      key={action.id}
+                      onPress={() => activateAction(action)}
                     >
                       <Box
                         px="m"
                         py="s"
+                        radius="s"
                         style={{
                           backgroundColor: selected
                             ? theme.semantics.action.neutral.softBg
                             : 'transparent',
-                          opacity: item.disabled ? 0.56 : 1,
+                          opacity: action.disabled ? 0.56 : 1,
                         }}
-                        testID={testID ? `${testID}-item-${item.id}` : undefined}
+                        testID={testID ? `${testID}-item-${action.id}` : undefined}
                       >
-                        <Text color={selected ? 'neutral' : undefined} variant="bodySmall">
-                          {item.label}
-                        </Text>
+                        {renderActionContent(action, active)}
                       </Box>
                     </Pressable>
                   );

package/src/components/menu/index.ts

@@ -1,2 +1,2 @@
 export { Menu } from './Menu';
-export type { MenuItem, MenuProps } from './types';
+export type { MenuAction, MenuActionIntent, MenuAction as MenuItem, MenuProps } from './types';

package/src/components/menu/navigation.ts

@@ -1,5 +1,5 @@
 export function resolveNextMenuIndex(
-  items: { disabled?: boolean }[],
+  items: readonly { disabled?: boolean }[],
   currentIndex: number,
   key: 'ArrowDown' | 'ArrowUp' | 'Home' | 'End',
 ): number {

package/src/components/menu/types.ts

@@ -1,16 +1,23 @@
 import type React from 'react';
 
-export interface MenuItem {
+export type MenuActionIntent = 'default' | 'danger';
+
+export interface MenuAction {
   id: string;
-  label: React.ReactNode;
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  leading?: React.ReactNode;
+  trailing?: React.ReactNode;
+  intent?: MenuActionIntent;
   disabled?: boolean;
-  onPress?: (() => void) | undefined;
+  selected?: boolean;
+  activate?: () => void;
 }
 
 export interface MenuProps {
   trigger?: React.ReactNode;
-  items: MenuItem[];
-  onDismiss?: (() => void) | undefined;
+  actions: readonly MenuAction[];
+  dismiss?: () => void;
   closeOnSelect?: boolean;
   testID?: string;
 }

package/src/components/tooltip/Tooltip.tsx

@@ -93,7 +93,7 @@ export function Tooltip({
           <Surface
             p="s"
             style={{
-              backgroundColor: theme.semantics.neutral.text,
+              backgroundColor: theme.semantics.surface.inverse,
             }}
             testID={testID}
             variant="raised"

package/src/examples/DocsExamples.tsx

@@ -1,77 +1,91 @@
 import React from 'react';
 
-import {
-  Badge,
-  Box,
-  Button,
-  Checkbox,
-  Drawer,
-  Field,
-  HelperText,
-  Label,
-  Menu,
-  Modal,
-  Radio,
-  Stack,
-  Switch,
-  Tab,
-  TabList,
-  TabPanel,
-  Tabs,
-  Text,
-  Textarea,
-  TextInput,
-  ThemeProvider,
-} from '../index';
+import { Button } from '../components/button';
+import { Card } from '../components/card';
+import { Checkbox } from '../components/checkbox';
+import { Drawer } from '../components/drawer';
+import { Field } from '../components/field';
+import { HelperText } from '../components/helper-text';
+import { Menu } from '../components/menu';
+import { Modal } from '../components/modal';
+import { Tab, TabList, TabPanel, Tabs } from '../components/tabs';
+import { TextInput } from '../components/text-input';
+import { ToastProvider, useToast } from '../components/toast';
+import { Tooltip } from '../components/tooltip';
+import { Box, Stack } from '../layout';
+import { Text } from '../primitives/text';
+import { ThemeProvider } from '../theme';
+import type { ThemeConfig } from '../theme/types';
 
-const docsThemeConfig = {
-  id: 'docs-example',
-  name: 'Docs Example',
-  light: {
-    harmony: 'monochromatic' as const,
-    primaryColor: '#2563eb',
-  },
-  dark: {
-    harmony: 'monochromatic' as const,
-    primaryColor: '#2563eb',
-  },
+const docsThemeConfig: ThemeConfig = {
+  id: 'docs',
+  name: 'Docs',
+  light: { primaryColor: '#2563EB', harmony: 'analogous' },
+  dark: { primaryColor: '#60A5FA', harmony: 'analogous' },
 };
 
-export function ProviderExample() {
+export function FormExample() {
   return (
     <ThemeProvider initialConfig={docsThemeConfig}>
       <Stack gap="m" p="l">
-        <Text variant="body">Surface starter</Text>
-        <Badge color="success" content="Foundation" />
-        <Button color="warning" variant="soft">
-          Continue
-        </Button>
+        <Field helperText="Use your work email." label="Email" required>
+          <TextInput placeholder="you@example.com" />
+        </Field>
+        <Checkbox checked>Accept terms</Checkbox>
+        <HelperText emphasis="muted">Looks good.</HelperText>
       </Stack>
     </ThemeProvider>
   );
 }
 
-export function FormAndOverlayExample() {
+function ToastButton() {
+  const { showToast } = useToast();
+  return (
+    <Button
+      onPress={() =>
+        showToast({ description: 'Your changes were saved.', status: 'success', title: 'Saved' })
+      }
+    >
+      Show toast
+    </Button>
+  );
+}
+
+export function FeedbackExample() {
   return (
     <ThemeProvider initialConfig={docsThemeConfig}>
-      <Stack gap="m" p="l">
-        <Field helperText="We only use this for sign-in." label="Email">
-          <TextInput placeholder="name@example.com" />
-        </Field>
-        <Field errorText="Bio is required." invalid label="Bio">
-          <Textarea placeholder="Tell us a little about yourself" />
-        </Field>
-        <Stack gap="s">
-          <Label required>Preferences</Label>
-          <Checkbox defaultChecked>Weekly updates</Checkbox>
-          <Radio>Product announcements</Radio>
-          <Switch readOnly>Read-only setting</Switch>
-          <HelperText color="error">Invalid fields should reuse the same error color.</HelperText>
+      <ToastProvider>
+        <Stack gap="m" p="l">
+          <Tooltip content="Helpful contextual information">
+            <Text>Hover for tooltip</Text>
+          </Tooltip>
+          <ToastButton />
         </Stack>
-        <Modal visible={false}>
-          <Text>Modal content</Text>
+      </ToastProvider>
+    </ThemeProvider>
+  );
+}
+
+export function OverlayExample() {
+  const [modalVisible, setModalVisible] = React.useState(false);
+  const [drawerVisible, setDrawerVisible] = React.useState(false);
+
+  return (
+    <ThemeProvider initialConfig={docsThemeConfig}>
+      <Stack gap="m" p="l">
+        <Button onPress={() => setModalVisible(true)}>Open modal</Button>
+        <Button onPress={() => setDrawerVisible(true)}>Open drawer</Button>
+        <Modal onDismiss={() => setModalVisible(false)} visible={modalVisible}>
+          <Card>
+            <Stack gap="s">
+              <Text variant="label" weight="semiBold">
+                Modal title
+              </Text>
+              <Text>Modal content</Text>
+            </Stack>
+          </Card>
         </Modal>
-        <Drawer visible={false}>
+        <Drawer onDismiss={() => setDrawerVisible(false)} visible={drawerVisible}>
           <Text>Drawer content</Text>
         </Drawer>
       </Stack>
@@ -99,9 +113,9 @@ export function NavigationExample() {
           </TabPanel>
         </Tabs>
         <Menu
-          items={[
-            { id: 'edit', label: 'Edit' },
-            { disabled: true, id: 'archive', label: 'Archive' },
+          actions={[
+            { id: 'edit', title: 'Edit' },
+            { disabled: true, id: 'archive', title: 'Archive' },
           ]}
           trigger={<Text>Open menu</Text>}
         />

package/src/index.ts

@@ -20,7 +20,7 @@ export type { LabelProps } from './components/label';
 export { Label } from './components/label';
 export type { ListItemProps } from './components/list-item';
 export { ListItem } from './components/list-item';
-export type { MenuItem, MenuProps } from './components/menu';
+export type { MenuAction, MenuActionIntent, MenuItem, MenuProps } from './components/menu';
 export { Menu } from './components/menu';
 export type { ModalProps } from './components/modal';
 export { Modal } from './components/modal';

package/src/theme/colorEngine.test.ts

@@ -67,10 +67,11 @@ describe('colorEngine', () => {
   });
 
   it('generates a valid palette for dark mode', () => {
-    const { colors, semantics } = generatePalette(mockConfig, 'dark');
+    const { colors, swatches, semantics } = generatePalette(mockConfig, 'dark');
 
     expect(colors.background).toBe(semantics.neutral.bg);
-    expect(semantics.content.inverse).toBe(semantics.brand.onSolidText);
+    expect(semantics.surface.inverse).toBe(swatches.neutral[50]);
+    expect(semantics.content.inverse).toBe(swatches.neutral[900]);
   });
 
   it('uses the color-theory default semantic status seeds', () => {

package/src/theme/colorEngine.ts

@@ -120,7 +120,6 @@ export function generatePalette(
   parseHexColorOrThrow(modeConfig.primaryColor);
 
   const generated = generateThemeModeColors(modeConfig);
-
   const { swatches } = generated;
   const neutralSwatch = swatches.neutral;
 
@@ -140,18 +139,21 @@ export function generatePalette(
   // 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: brand.onSolidText,
+    inverse: inverseOnSurface,
   };
 
   const border: BorderSemantics = {