@ankhorage/surface 3.1.3 → 3.3.0

package/dist/theme/types.d.ts

@@ -1,4 +1,4 @@
-import type { GeneratedThemeSwatches } from '@ankhorage/color-theory';
+import type { ColorSwatchDiagnostics, ColorSwatchSelectionResult, DefaultSemanticStatusRole, GeneratedThemeModeColors, GeneratedThemeSwatches, HexColor, SemanticColorReferenceMap, ThemeColorMode } from '@ankhorage/color-theory';
 import type { ThemeConfig as ContractsThemeConfig } from '@ankhorage/contracts';
 export type { ColorHarmony, ColorSwatch, ColorSwatchStep, GeneratedColorRole, GeneratedThemeModeColors, GeneratedThemeSwatches, HexColor, SemanticColorReferenceMap, SemanticColorToken, } from '@ankhorage/color-theory';
 export type { ThemeConfig, ThemeModeConfig } from '@ankhorage/contracts';
@@ -14,6 +14,8 @@ export interface NeutralSemantics {
     text: string;
     textMuted: string;
     textSubtle: string;
+    disabledBg: string;
+    disabledText: string;
 }
 export interface RoleSemantics {
     base: string;
@@ -23,25 +25,48 @@ export interface RoleSemantics {
     softHover: string;
     softActive: string;
     outline: string;
+    onSurfaceText: string;
     onSolidText: string;
+    onHoverText: string;
+    onStrongText: string;
+    onSoftText: string;
+    onSoftHoverText: string;
+    onSoftActiveText: string;
+    disabledBg: string;
+    onDisabledText: string;
 }
 export interface SurfaceSemantics {
     default: string;
     subtle: string;
     raised: string;
+    sunken: string;
+    overlay: string;
+    scrim: string;
+    disabled: string;
     inverse: string;
 }
 export interface ContentSemantics {
     default: string;
     muted: string;
     subtle: string;
+    disabled: string;
+    icon: string;
+    link: string;
+    visited: string;
     inverse: string;
 }
 export interface BorderSemantics {
     default: string;
+    subtle: string;
     strong: string;
+    divider: string;
     focus: string;
 }
+export interface SelectionSemantics {
+    background: string;
+    content: string;
+    border: string;
+}
 export interface ActionSemantics {
     primary: RoleSemantics;
     neutral: RoleSemantics;
@@ -61,8 +86,32 @@ export interface ThemeSemantics {
     surface: SurfaceSemantics;
     content: ContentSemantics;
     border: BorderSemantics;
+    selection: SelectionSemantics;
     action: ActionSemantics;
 }
+export interface SurfaceContrastDiagnostic {
+    id: string;
+    foreground: HexColor;
+    background: HexColor;
+    contrast: number;
+    minimumContrast: number;
+    passes: boolean;
+}
+/** A Color Theory swatch selection together with its stable Surface purpose. */
+export interface SurfaceColorSelectionDiagnostic {
+    id: string;
+    result: ColorSwatchSelectionResult;
+}
+/** Owner-produced color evidence used to explain a resolved Surface theme. */
+export interface SurfaceColorDiagnostics {
+    mode: ThemeColorMode;
+    generated: GeneratedThemeModeColors;
+    semanticReferences: SemanticColorReferenceMap;
+    statusSwatches: Record<DefaultSemanticStatusRole, ColorSwatchDiagnostics>;
+    selections: readonly SurfaceColorSelectionDiagnostic[];
+    contrasts: readonly SurfaceContrastDiagnostic[];
+    surfaceSeparation: readonly SurfaceContrastDiagnostic[];
+}
 export type FontWeight = '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | 'bold' | 'normal';
 export interface ThemeTokens {
     colors: {
@@ -85,6 +134,8 @@ export interface ThemeTokens {
     };
     swatches: GeneratedThemeSwatches;
     semantics: ThemeSemantics;
+    /** Generated owner evidence; this is runtime output and is not persisted in ThemeConfig. */
+    colorDiagnostics: SurfaceColorDiagnostics;
     spacing: {
         none: 0;
         xs: number;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,IAAI,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,YAAY,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,QAAQ,EACR,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,MAAM,UAAU,GACpB,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5F,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,EAAE,MAAM,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACvB,CAAC;IACF,QAAQ,EAAE,sBAAsB,CAAC;IACjC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE;QACP,IAAI,EAAE,CAAC,CAAC;QACR,EAAE,EAAE,MAAM,CAAC;QACX,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,EAAE,EAAE,MAAM,CAAC;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACvB,CAAC;IACF,KAAK,EAAE;QACL,IAAI,EAAE,CAAC,CAAC;QACR,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,IAAI,EAAE,MAAM,CAAC;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACvB,CAAC;IACF,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CACd,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EACrB;YACE,IAAI,EAAE,MAAM,CAAC;YACb,UAAU,EAAE,MAAM,CAAC;YACnB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;SACpD,CACF,CAAC;QACF,KAAK,EAAE;YACL,EAAE,EAAE,MAAM,CAAC;YACX,CAAC,EAAE,MAAM,CAAC;YACV,CAAC,EAAE,MAAM,CAAC;YACV,CAAC,EAAE,MAAM,CAAC;YACV,EAAE,EAAE,MAAM,CAAC;YACX,GAAG,EAAE,MAAM,CAAC;YACZ,KAAK,EAAE,MAAM,CAAC;YACd,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;SACvB,CAAC;QACF,OAAO,EAAE;YACP,IAAI,EAAE,UAAU,CAAC;YACjB,UAAU,EAAE,UAAU,CAAC;YACvB,KAAK,EAAE,UAAU,CAAC;YAClB,OAAO,EAAE,UAAU,CAAC;YACpB,MAAM,EAAE,UAAU,CAAC;YACnB,QAAQ,EAAE,UAAU,CAAC;YACrB,IAAI,EAAE,UAAU,CAAC;YACjB,SAAS,EAAE,UAAU,CAAC;YACtB,KAAK,EAAE,UAAU,CAAC;SACnB,CAAC;QACF,KAAK,EAAE;YACL,wDAAwD;YACxD,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;YAC/C,wDAAwD;YACxD,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;SAChD,CAAC;KACH,CAAC;IACF,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,MAAM,EAAE,oBAAoB,CAAC;CAC9B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,QAAQ,EACR,yBAAyB,EACzB,cAAc,EACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,IAAI,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,YAAY,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,QAAQ,EACR,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,QAAQ,CAAC;IACrB,UAAU,EAAE,QAAQ,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,gFAAgF;AAChF,MAAM,WAAW,+BAA+B;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,0BAA0B,CAAC;CACpC;AAED,8EAA8E;AAC9E,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,wBAAwB,CAAC;IACpC,kBAAkB,EAAE,yBAAyB,CAAC;IAC9C,cAAc,EAAE,MAAM,CAAC,yBAAyB,EAAE,sBAAsB,CAAC,CAAC;IAC1E,UAAU,EAAE,SAAS,+BAA+B,EAAE,CAAC;IACvD,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAChD,iBAAiB,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACzD;AAED,MAAM,MAAM,UAAU,GACpB,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5F,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,EAAE,MAAM,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACvB,CAAC;IACF,QAAQ,EAAE,sBAAsB,CAAC;IACjC,SAAS,EAAE,cAAc,CAAC;IAC1B,4FAA4F;IAC5F,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,OAAO,EAAE;QACP,IAAI,EAAE,CAAC,CAAC;QACR,EAAE,EAAE,MAAM,CAAC;QACX,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,EAAE,EAAE,MAAM,CAAC;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACvB,CAAC;IACF,KAAK,EAAE;QACL,IAAI,EAAE,CAAC,CAAC;QACR,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,IAAI,EAAE,MAAM,CAAC;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACvB,CAAC;IACF,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CACd,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EACrB;YACE,IAAI,EAAE,MAAM,CAAC;YACb,UAAU,EAAE,MAAM,CAAC;YACnB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;SACpD,CACF,CAAC;QACF,KAAK,EAAE;YACL,EAAE,EAAE,MAAM,CAAC;YACX,CAAC,EAAE,MAAM,CAAC;YACV,CAAC,EAAE,MAAM,CAAC;YACV,CAAC,EAAE,MAAM,CAAC;YACV,EAAE,EAAE,MAAM,CAAC;YACX,GAAG,EAAE,MAAM,CAAC;YACZ,KAAK,EAAE,MAAM,CAAC;YACd,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;SACvB,CAAC;QACF,OAAO,EAAE;YACP,IAAI,EAAE,UAAU,CAAC;YACjB,UAAU,EAAE,UAAU,CAAC;YACvB,KAAK,EAAE,UAAU,CAAC;YAClB,OAAO,EAAE,UAAU,CAAC;YACpB,MAAM,EAAE,UAAU,CAAC;YACnB,QAAQ,EAAE,UAAU,CAAC;YACrB,IAAI,EAAE,UAAU,CAAC;YACjB,SAAS,EAAE,UAAU,CAAC;YACtB,KAAK,EAAE,UAAU,CAAC;SACnB,CAAC;QACF,KAAK,EAAE;YACL,wDAAwD;YACxD,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;YAC/C,wDAAwD;YACxD,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;SAChD,CAAC;KACH,CAAC;IACF,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,MAAM,EAAE,oBAAoB,CAAC;CAC9B"}

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  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' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | 'bold' | '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    [key: string]: 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 {\n  ColorSwatchDiagnostics,\n  ColorSwatchSelectionResult,\n  DefaultSemanticStatusRole,\n  GeneratedThemeModeColors,\n  GeneratedThemeSwatches,\n  HexColor,\n  SemanticColorReferenceMap,\n  ThemeColorMode,\n} 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  disabledBg: string;\n  disabledText: 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  onSurfaceText: string;\n  onSolidText: string;\n  onHoverText: string;\n  onStrongText: string;\n  onSoftText: string;\n  onSoftHoverText: string;\n  onSoftActiveText: string;\n  disabledBg: string;\n  onDisabledText: string;\n}\n\nexport interface SurfaceSemantics {\n  default: string;\n  subtle: string;\n  raised: string;\n  sunken: string;\n  overlay: string;\n  scrim: string;\n  disabled: string;\n  inverse: string;\n}\n\nexport interface ContentSemantics {\n  default: string;\n  muted: string;\n  subtle: string;\n  disabled: string;\n  icon: string;\n  link: string;\n  visited: string;\n  inverse: string;\n}\n\nexport interface BorderSemantics {\n  default: string;\n  subtle: string;\n  strong: string;\n  divider: string;\n  focus: string;\n}\n\nexport interface SelectionSemantics {\n  background: string;\n  content: string;\n  border: 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  selection: SelectionSemantics;\n  action: ActionSemantics;\n}\n\nexport interface SurfaceContrastDiagnostic {\n  id: string;\n  foreground: HexColor;\n  background: HexColor;\n  contrast: number;\n  minimumContrast: number;\n  passes: boolean;\n}\n\n/** A Color Theory swatch selection together with its stable Surface purpose. */\nexport interface SurfaceColorSelectionDiagnostic {\n  id: string;\n  result: ColorSwatchSelectionResult;\n}\n\n/** Owner-produced color evidence used to explain a resolved Surface theme. */\nexport interface SurfaceColorDiagnostics {\n  mode: ThemeColorMode;\n  generated: GeneratedThemeModeColors;\n  semanticReferences: SemanticColorReferenceMap;\n  statusSwatches: Record<DefaultSemanticStatusRole, ColorSwatchDiagnostics>;\n  selections: readonly SurfaceColorSelectionDiagnostic[];\n  contrasts: readonly SurfaceContrastDiagnostic[];\n  surfaceSeparation: readonly SurfaceContrastDiagnostic[];\n}\n\nexport type FontWeight =\n  '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | 'bold' | '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  /** Generated owner evidence; this is runtime output and is not persisted in ThemeConfig. */\n  colorDiagnostics: SurfaceColorDiagnostics;\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    [key: string]: 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": "3.1.3",
+  "version": "3.3.0",
   "description": "Stable UI foundation for React Native and React Native Web.",
   "homepage": "https://github.com/ankhorage/surface#readme",
   "bugs": {
@@ -56,6 +56,14 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./theme": {
+      "bun": "./src/theme/public.ts",
+      "react-native": "./src/theme/public.ts",
+      "browser": "./src/theme/public.ts",
+      "types": "./dist/theme/public.d.ts",
+      "import": "./dist/theme/public.js",
+      "default": "./dist/theme/public.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/components/navigation/helpers.test.ts

@@ -40,7 +40,7 @@ describe('navigation helpers', () => {
     });
 
     expect(resolved.backgroundColor).toBe(theme.semantics.action.primary.softHover);
-    expect(resolved.contentColor).toBe(theme.semantics.action.primary.base);
+    expect(resolved.contentColor).toBe(theme.semantics.action.primary.onSoftHoverText);
     expect(resolved.opacity).toBe(1);
   });
 
@@ -67,8 +67,8 @@ describe('navigation helpers', () => {
       state,
     });
 
-    expect(resolved.backgroundColor).toBe(theme.semantics.action.primary.softBg);
-    expect(resolved.contentColor).toBe(theme.semantics.content.muted);
-    expect(resolved.opacity).toBe(0.72);
+    expect(resolved.backgroundColor).toBe(theme.semantics.surface.disabled);
+    expect(resolved.contentColor).toBe(theme.semantics.content.disabled);
+    expect(resolved.opacity).toBe(1);
   });
 });

package/src/components/navigation/helpers.ts

@@ -41,12 +41,21 @@ export function resolveNavigationItemPresentation(
 ): ResolvedNavigationItemPresentation {
   const interactionState = disabled ? { ...state, hovered: false, pressed: false } : state;
 
-  const opacity = disabled ? 0.72 : 1;
-  const contentColor = disabled
-    ? theme.semantics.content.muted
-    : active
-      ? theme.semantics.action.primary.base
-      : theme.semantics.content.default;
+  if (disabled) {
+    return {
+      backgroundColor: theme.semantics.surface.disabled,
+      contentColor: theme.semantics.content.disabled,
+      opacity: 1,
+    };
+  }
+
+  const contentColor = active
+    ? interactionState.pressed
+      ? theme.semantics.action.primary.onSoftActiveText
+      : interactionState.hovered
+        ? theme.semantics.action.primary.onSoftHoverText
+        : theme.semantics.action.primary.onSoftText
+    : theme.semantics.content.default;
 
   if (active) {
     return {
@@ -56,7 +65,7 @@ export function resolveNavigationItemPresentation(
           ? theme.semantics.action.primary.softHover
           : theme.semantics.action.primary.softBg,
       contentColor,
-      opacity,
+      opacity: 1,
     };
   }
 
@@ -67,6 +76,6 @@ export function resolveNavigationItemPresentation(
         ? theme.semantics.neutral.surfaceHover
         : 'transparent',
     contentColor,
-    opacity,
+    opacity: 1,
   };
 }

package/src/index.test.ts

@@ -2,6 +2,9 @@ import { readFileSync } from 'node:fs';
 
 import { describe, expect, it } from 'bun:test';
 
+import type { SelectionSemantics, SurfaceColorDiagnostics } from './index';
+import { createTheme } from './theme/createTheme';
+
 const indexSource = readFileSync(new URL('./index.ts', import.meta.url), 'utf8');
 const packageJson = JSON.parse(
   readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
@@ -67,6 +70,14 @@ describe('public package contract', () => {
         import: './dist/index.js',
         types: './dist/index.d.ts',
       },
+      './theme': {
+        bun: './src/theme/public.ts',
+        'react-native': './src/theme/public.ts',
+        browser: './src/theme/public.ts',
+        default: './dist/theme/public.js',
+        import: './dist/theme/public.js',
+        types: './dist/theme/public.d.ts',
+      },
       './package.json': './package.json',
     });
   });
@@ -75,4 +86,13 @@ describe('public package contract', () => {
     expect(packageJson.peerDependencies['react-native']).toBe('0.86.x');
     expect(packageJson.devDependencies['react-native']).toBe('0.86.3');
   });
+
+  it('exports the resolved semantic and diagnostic contracts from the public root', () => {
+    const theme = createTheme();
+    const selection: SelectionSemantics = theme.semantics.selection;
+    const diagnostics: SurfaceColorDiagnostics = theme.colorDiagnostics;
+
+    expect(selection.background).toBeDefined();
+    expect(diagnostics.generated.swatches).toBe(theme.swatches);
+  });
 });

package/src/internal/resolvers/resolveInteractiveColors.test.ts

@@ -32,6 +32,7 @@ describe('resolveInteractiveColors', () => {
     expect(solid.contentColor).toBe(theme.semantics.action.primary.onSolidText);
     expect(outline.borderColor).toBe(theme.semantics.action.danger.outline);
     expect(outline.backgroundColor).toBe(theme.semantics.action.danger.softHover);
+    expect(outline.contentColor).toBe(theme.semantics.action.danger.onSurfaceText);
   });
 
   it('derives input colors from interaction and validation state', () => {

package/src/internal/resolvers/resolveInteractiveColors.ts

@@ -27,10 +27,9 @@ export function resolveButtonColors(
 ): ResolvedInteractiveColors {
   if (state.disabled) {
     return {
-      backgroundColor: theme.semantics.neutral.surface,
-      borderColor: theme.semantics.neutral.divider,
-      contentColor: theme.semantics.content.muted,
-      opacity: 0.72,
+      backgroundColor: theme.semantics.surface.disabled,
+      borderColor: theme.semantics.border.subtle,
+      contentColor: theme.semantics.content.disabled,
     };
   }
 
@@ -45,7 +44,7 @@ export function resolveButtonColors(
             ? semanticTone.softHover
             : 'transparent',
         borderColor: semanticTone.outline,
-        contentColor: semanticTone.base,
+        contentColor: semanticTone.onSurfaceText,
       };
     case 'ghost':
       return {
@@ -55,7 +54,7 @@ export function resolveButtonColors(
             ? semanticTone.softHover
             : 'transparent',
         borderColor: 'transparent',
-        contentColor: semanticTone.base,
+        contentColor: semanticTone.onSurfaceText,
       };
     case 'soft':
       return {
@@ -65,7 +64,11 @@ export function resolveButtonColors(
             ? semanticTone.softHover
             : semanticTone.softBg,
         borderColor: 'transparent',
-        contentColor: semanticTone.base,
+        contentColor: state.pressed
+          ? semanticTone.onSoftActiveText
+          : state.hovered
+            ? semanticTone.onSoftHoverText
+            : semanticTone.onSoftText,
       };
     case 'solid':
     default:
@@ -76,7 +79,11 @@ export function resolveButtonColors(
             ? semanticTone.hover
             : semanticTone.base,
         borderColor: semanticTone.base,
-        contentColor: semanticTone.onSolidText,
+        contentColor: state.pressed
+          ? semanticTone.onStrongText
+          : state.hovered
+            ? semanticTone.onHoverText
+            : semanticTone.onSolidText,
       };
   }
 }
@@ -87,11 +94,10 @@ export function resolveInputColors(
 ): ResolvedInteractiveColors & { placeholderColor: string } {
   if (fieldState.disabled) {
     return {
-      backgroundColor: theme.semantics.surface.subtle,
-      borderColor: theme.semantics.border.default,
-      contentColor: theme.semantics.content.muted,
-      placeholderColor: theme.semantics.content.subtle,
-      opacity: 0.72,
+      backgroundColor: theme.semantics.surface.disabled,
+      borderColor: theme.semantics.border.subtle,
+      contentColor: theme.semantics.content.disabled,
+      placeholderColor: theme.semantics.content.disabled,
     };
   }
 

package/src/internal/resolvers/resolveSelectionControlColors.test.ts

@@ -38,7 +38,8 @@ describe('resolveSelectionControlColors', () => {
       color: 'danger',
     });
 
-    expect(colors.labelColor).toBe(theme.semantics.content.muted);
-    expect(colors.opacity).toBe(0.72);
+    expect(colors.backgroundColor).toBe(theme.semantics.surface.disabled);
+    expect(colors.labelColor).toBe(theme.semantics.content.disabled);
+    expect(colors.opacity).toBeUndefined();
   });
 });

package/src/internal/resolvers/resolveSelectionControlColors.ts

@@ -35,15 +35,12 @@ export function resolveSelectionControlColors(
 
   if (isMuted) {
     return {
-      backgroundColor: checked
-        ? theme.semantics.neutral.surfaceActive
-        : theme.semantics.surface.subtle,
-      borderColor: theme.semantics.border.default,
-      indicatorColor: checked ? theme.semantics.content.muted : 'transparent',
-      labelColor: theme.semantics.content.muted,
-      trackColor: checked ? theme.semantics.neutral.surfaceActive : theme.semantics.neutral.border,
+      backgroundColor: theme.semantics.surface.disabled,
+      borderColor: theme.semantics.border.subtle,
+      indicatorColor: checked ? theme.semantics.content.disabled : 'transparent',
+      labelColor: theme.semantics.content.disabled,
+      trackColor: theme.semantics.surface.disabled,
       thumbColor: theme.semantics.surface.default,
-      opacity: 0.72,
     };
   }
 
@@ -71,12 +68,24 @@ export function resolveSelectionControlColors(
   return {
     backgroundColor: checked ? checkedBackgroundColor : uncheckedBackgroundColor,
     borderColor: checked ? semanticTone.base : uncheckedBorderColor,
-    indicatorColor: checked ? semanticTone.onSolidText : 'transparent',
+    indicatorColor: checked
+      ? pressed
+        ? semanticTone.onStrongText
+        : hovered
+          ? semanticTone.onHoverText
+          : semanticTone.onSolidText
+      : 'transparent',
     labelColor: isInteractiveReadOnly
       ? theme.semantics.content.muted
       : theme.semantics.content.default,
     trackColor: checked ? checkedTrackColor : uncheckedBorderColor,
-    thumbColor: checked ? semanticTone.onSolidText : theme.semantics.surface.default,
+    thumbColor: checked
+      ? pressed
+        ? semanticTone.onStrongText
+        : hovered
+          ? semanticTone.onHoverText
+          : semanticTone.onSolidText
+      : theme.semantics.surface.default,
     opacity: isInteractiveReadOnly ? 0.88 : 1,
   };
 }

package/src/primitives/icon/PortableIcon.web.test.tsx

@@ -60,13 +60,8 @@ describe('portable icon rendering', () => {
 
 describe('portable icon contract', () => {
   test('publishes the intentional provider inventory', () => {
-    expect(SUPPORTED_ICON_PROVIDERS).toEqual([
-      'Ionicons',
-      'FontAwesome',
-      'FontAwesome5',
-      'FontAwesome6',
-      'MaterialDesignIcons',
-    ]);
+    expect(SUPPORTED_ICON_PROVIDERS.length).toBeGreaterThan(0);
+    expect(new Set(SUPPORTED_ICON_PROVIDERS).size).toBe(SUPPORTED_ICON_PROVIDERS.length);
   });
 });
 

package/src/surfaceColor.test.ts

@@ -20,16 +20,14 @@ describe('surfaceColor public exports', () => {
     const indexSource = readFileSync(new URL('./index.ts', import.meta.url), 'utf8');
 
     expect(indexSource).toContain("from './surfaceColor';");
-    expect(SURFACE_PALETTE_COLORS).toEqual([
-      'primary',
-      'secondary',
-      'tertiary',
-      'quaternary',
-      'neutral',
-    ]);
-    expect(SURFACE_STATUS_COLORS).toEqual(['success', 'warning', 'error', 'info']);
-    expect(SURFACE_COLORS).toEqual([...SURFACE_PALETTE_COLORS, ...SURFACE_STATUS_COLORS, 'danger']);
-    expect(SURFACE_EMPHASES).toEqual(['default', 'muted', 'subtle', 'inverse']);
+    expect(SURFACE_PALETTE_COLORS.length).toBeGreaterThan(0);
+    expect(SURFACE_STATUS_COLORS.length).toBeGreaterThan(0);
+    expect(SURFACE_EMPHASES.length).toBeGreaterThan(0);
+    expect(new Set(SURFACE_COLORS).size).toBe(SURFACE_COLORS.length);
+    expect(new Set(SURFACE_EMPHASES).size).toBe(SURFACE_EMPHASES.length);
+    for (const color of [...SURFACE_PALETTE_COLORS, ...SURFACE_STATUS_COLORS]) {
+      expect(SURFACE_COLORS).toContain(color);
+    }
   });
 
   it('keeps root-imported type contracts aligned with runtime lists', () => {

package/src/theme/colorEngine.test.ts

@@ -1,6 +1,8 @@
 import type { SemanticColorToken } from '@ankhorage/color-theory';
 import {
+  COLOR_HARMONIES,
   DARK_SEMANTIC_COLOR_REFERENCES,
+  DEFAULT_SEMANTIC_STATUS_COLOR_SEEDS,
   LIGHT_SEMANTIC_COLOR_REFERENCES,
 } from '@ankhorage/color-theory';
 import type { ThemeConfig } from '@ankhorage/contracts';
@@ -22,23 +24,18 @@ const mockConfig: ThemeConfig = {
   },
 };
 
-function expectRequiredSemanticRoles(semantics: ThemeSemantics) {
-  expect(semantics.neutral.bg).toBeDefined();
-  expect(semantics.neutral.surface).toBeDefined();
-  expect(semantics.neutral.text).toBeDefined();
-  expect(semantics.brand.base).toBeDefined();
-  expect(semantics.secondary.base).toBeDefined();
-  expect(semantics.danger.base).toBeDefined();
-  expect(semantics.success.base).toBeDefined();
-  expect(semantics.warning.base).toBeDefined();
-  expect(semantics.error.base).toBeDefined();
-  expect(semantics.info.base).toBeDefined();
-  expect(semantics.surface.default).toBeDefined();
-  expect(semantics.content.default).toBeDefined();
-  expect(semantics.border.default).toBeDefined();
-  expect(semantics.action.primary.base).toBeDefined();
-  expect(semantics.action.neutral.base).toBeDefined();
-  expect(semantics.action.danger.base).toBeDefined();
+function expectCompleteSemanticValues(semantics: ThemeSemantics) {
+  visitSemanticValues(semantics);
+}
+
+function visitSemanticValues(value: object): void {
+  for (const entry of Object.values(value)) {
+    if (typeof entry === 'string') {
+      expect(entry.length).toBeGreaterThan(0);
+    } else {
+      visitSemanticValues(entry as object);
+    }
+  }
 }
 
 describe('colorEngine', () => {
@@ -74,21 +71,30 @@ describe('colorEngine', () => {
     expect(semantics.content.inverse).toBe(swatches.neutral[900]);
   });
 
-  it('uses the color-theory default semantic status seeds', () => {
-    const light = generatePalette(mockConfig, 'light');
-    const dark = generatePalette(mockConfig, 'dark');
+  it('uses the Color Theory status owner independently from brand harmony', () => {
+    const statusConfig: ThemeConfig = {
+      ...mockConfig,
+      light: { primaryColor: '#dc2626', harmony: 'monochromatic' },
+      dark: { primaryColor: '#dc2626', harmony: 'monochromatic' },
+    };
+    const light = generatePalette(statusConfig, 'light');
+    const dark = generatePalette(statusConfig, 'dark');
 
     expect(light.semantics.danger.base).toBe('#ef4444');
     expect(light.semantics.success.base).toBe('#22c55e');
     expect(light.semantics.warning.base).toBe('#f59e0b');
     expect(light.semantics.error.base).toBe(light.semantics.danger.base);
-    expect(light.semantics.info.base).toBeDefined();
+    expect(light.semantics.info.base).toBe(DEFAULT_SEMANTIC_STATUS_COLOR_SEEDS.info);
+    expect(light.semantics.info.base).not.toBe(light.semantics.brand.base);
 
     expect(dark.semantics.danger.base).toBe('#ef4444');
     expect(dark.semantics.success.base).toBe('#22c55e');
     expect(dark.semantics.warning.base).toBe('#f59e0b');
     expect(dark.semantics.error.base).toBe(dark.semantics.danger.base);
-    expect(dark.semantics.info.base).toBeDefined();
+    expect(dark.semantics.info.base).toBe(DEFAULT_SEMANTIC_STATUS_COLOR_SEEDS.info);
+    expect(dark.semantics.info.base).not.toBe(dark.semantics.brand.base);
+    expect(light.semantics.error).toBe(light.semantics.danger);
+    expect(dark.semantics.error).toBe(dark.semantics.danger);
   });
 
   it('uses mode-aware role semantics for dark mode soft states', () => {
@@ -136,16 +142,7 @@ describe('colorEngine', () => {
   });
 
   it('emits required semantic roles for all harmonies', () => {
-    const harmonies = [
-      'monochromatic',
-      'analogous',
-      'complementary',
-      'triadic',
-      'tetradic',
-      'splitComplementary',
-    ] as const;
-
-    for (const harmony of harmonies) {
+    for (const harmony of COLOR_HARMONIES) {
       const config = {
         ...mockConfig,
         light: { ...mockConfig.light, harmony },
@@ -153,11 +150,65 @@ describe('colorEngine', () => {
       };
       const light = generatePalette(config, 'light');
       const dark = generatePalette(config, 'dark');
-      expectRequiredSemanticRoles(light.semantics);
-      expectRequiredSemanticRoles(dark.semantics);
+      expectCompleteSemanticValues(light.semantics);
+      expectCompleteSemanticValues(dark.semantics);
+    }
+  });
+
+  it('resolves canonical semantic references and returns their selected steps', () => {
+    const light = generatePalette(mockConfig, 'light');
+    const dark = generatePalette(mockConfig, 'dark');
+
+    expect(light.colorDiagnostics.semanticReferences).toBe(LIGHT_SEMANTIC_COLOR_REFERENCES);
+    expect(dark.colorDiagnostics.semanticReferences).toBe(DARK_SEMANTIC_COLOR_REFERENCES);
+    expect(light.colorDiagnostics.generated.swatches).toBe(light.swatches);
+    expect(dark.colorDiagnostics.generated.swatches).toBe(dark.swatches);
+  });
+
+  it('returns measured selections and contrast diagnostics for both modes', () => {
+    for (const mode of ['light', 'dark'] as const) {
+      const palette = generatePalette(mockConfig, mode);
+
+      expect(palette.colorDiagnostics.selections.length).toBeGreaterThan(0);
+      expect(
+        palette.colorDiagnostics.selections.every(({ result }) => result.selected !== null),
+      ).toBe(true);
+      expect(palette.colorDiagnostics.contrasts.length).toBeGreaterThan(0);
+      expect(palette.colorDiagnostics.contrasts.every(({ passes }) => passes)).toBe(true);
+      expect(palette.colorDiagnostics.surfaceSeparation.length).toBeGreaterThan(0);
     }
   });
 
+  it('reports neutral and surface-separation evidence without hiding failed separation', () => {
+    const palette = generatePalette(mockConfig, 'light');
+    const failedSeparation = palette.colorDiagnostics.surfaceSeparation.find(
+      ({ passes }) => !passes,
+    );
+
+    expect(palette.colorDiagnostics.generated.neutral.neutralKeyColor).toBe(
+      palette.swatches.neutral[500],
+    );
+    expect(palette.colorDiagnostics.generated.neutral.diagnostics.isUsable).toBeBoolean();
+    expect(failedSeparation).toBeDefined();
+    expect(failedSeparation?.contrast).toBeLessThan(failedSeparation?.minimumContrast ?? 0);
+  });
+
+  it('preserves owner diagnostics for achromatic and low-chroma inputs', () => {
+    const achromaticConfig: ThemeConfig = {
+      ...mockConfig,
+      light: { primaryColor: '#777777', harmony: 'square' },
+    };
+    const palette = generatePalette(achromaticConfig, 'light');
+
+    expect(palette.colorDiagnostics.generated.harmonyRoleColors.diagnostics.isHueReliable).toBe(
+      false,
+    );
+    expect(
+      palette.colorDiagnostics.generated.harmonyRoleColors.diagnostics.warnings.length,
+    ).toBeGreaterThan(0);
+    expect(palette.colorDiagnostics.generated.neutral.diagnostics).toBeDefined();
+  });
+
   it('generates ordinal chromatic role swatches (no accent/highlight as swatch keys)', () => {
     const { swatches } = generatePalette(mockConfig, 'light');
     const keys = Object.keys(swatches);