@ankhorage/surface 9.1.116 → 9.2.0

package/src/features/theme/domain/projectInvertedTheme.ts

@@ -0,0 +1,300 @@
+import type {
+  ColorContrastContext,
+  ColorSelectionTarget,
+  ColorSwatch,
+  ColorSwatchTiePolicy,
+  HexColor,
+} from '@ankhorage/color-theory';
+import {
+  createDefaultSemanticStatusSwatches,
+  parseHexColorOrThrow,
+  selectColorSwatchStep,
+} from '@ankhorage/color-theory';
+
+import type {
+  BorderSemantics,
+  ContentSemantics,
+  NeutralSemantics,
+  RoleSemantics,
+  SurfaceSemantics,
+  SurfaceTheme,
+  ThemeSemantics,
+} from '../../../types/theme';
+import { SURFACE_COLOR_POLICY } from '../constants';
+import { createSurfaceColorDiagnosticCollector } from './createSurfaceColorDiagnosticCollector';
+import { resolveInverseSurface } from './resolveInverseSurface';
+
+type Collector = ReturnType<typeof createSurfaceColorDiagnosticCollector>;
+
+interface InverseSelection {
+  collector: Collector;
+  contexts: readonly ColorContrastContext[];
+  tiePolicy: ColorSwatchTiePolicy;
+  textTarget: ColorSelectionTarget;
+  mutedTarget: ColorSelectionTarget;
+  subtleTarget: ColorSelectionTarget;
+  borderTarget: ColorSelectionTarget;
+  neutral: ColorSwatch;
+}
+
+/*** Project normal canonical theme semantics onto the opposite surface polarity. */
+export function projectInvertedTheme(theme: SurfaceTheme): SurfaceTheme {
+  const collector = createSurfaceColorDiagnosticCollector();
+  const lightSurface = theme.colorDiagnostics.mode === 'dark';
+  const { neutral } = theme.swatches;
+  const { surface, surfaceSeparation } = resolveInverseSurface(theme, lightSurface, collector);
+  const selection = createInverseSelection(collector, surface, neutral, lightSurface);
+  const content = resolveInverseContent(theme, selection);
+  const border = resolveInverseBorder(theme, selection);
+  const roles = resolveInverseRoles(theme, selection);
+  const { neutralAction, ...semanticRoles } = roles;
+  const semantics: ThemeSemantics = {
+    ...theme.semantics,
+    neutral: resolveInverseNeutral(theme, surface, content, border, neutral, lightSurface),
+    surface,
+    content,
+    border,
+    ...semanticRoles,
+    error: roles.danger,
+    selection: {
+      background: roles.brand.softBg,
+      content: roles.brand.onSoftText,
+      border: border.focus,
+    },
+    action: { primary: roles.brand, neutral: neutralAction, danger: roles.danger },
+  };
+
+  return {
+    ...theme,
+    inverted: true,
+    semantics,
+    colors: {
+      ...theme.colors,
+      background: surface.sunken,
+      surface: surface.default,
+      text: content.default,
+      textSecondary: content.muted,
+      border: border.default,
+    },
+    colorDiagnostics: {
+      ...theme.colorDiagnostics,
+      selections: [...theme.colorDiagnostics.selections, ...collector.selections],
+      contrasts: [...theme.colorDiagnostics.contrasts, ...collector.contrasts],
+      surfaceSeparation,
+    },
+  };
+}
+
+/*** Select swatch steps against both inverse surface levels. */
+function createInverseSelection(
+  collector: Collector,
+  surface: SurfaceSemantics,
+  neutral: ColorSwatch,
+  lightSurface: boolean,
+): InverseSelection {
+  return {
+    collector,
+    neutral,
+    contexts: [
+      {
+        id: 'inverse-surface',
+        against: parseHexColorOrThrow(surface.default),
+        minimumContrast: SURFACE_COLOR_POLICY.textContrast,
+      },
+      {
+        id: 'inverse-subtle',
+        against: parseHexColorOrThrow(surface.subtle),
+        minimumContrast: SURFACE_COLOR_POLICY.textContrast,
+      },
+      {
+        id: 'inverse-sunken',
+        against: parseHexColorOrThrow(surface.sunken),
+        minimumContrast: SURFACE_COLOR_POLICY.textContrast,
+      },
+    ],
+    tiePolicy: lightSurface ? 'higher-step' : 'lower-step',
+    textTarget: { lightness: lightSurface ? 0.2 : 0.9, chroma: 0.02 },
+    mutedTarget: { lightness: lightSurface ? 0.35 : 0.75, chroma: 0.02 },
+    subtleTarget: { lightness: lightSurface ? 0.4 : 0.7, chroma: 0.02 },
+    borderTarget: { lightness: lightSurface ? 0.45 : 0.65, chroma: 0.02 },
+  };
+}
+
+/*** Resolve all surface-relative content colors against inverse backgrounds. */
+function resolveInverseContent(theme: SurfaceTheme, selection: InverseSelection): ContentSemantics {
+  const { neutral, primary } = theme.swatches;
+  const secondary = theme.swatches.secondary ?? primary;
+  return {
+    default: selectText('content.default', neutral, selection.textTarget, selection),
+    muted: selectText('content.muted', neutral, selection.mutedTarget, selection),
+    subtle: selectText('content.subtle', neutral, selection.subtleTarget, selection),
+    disabled: selectText(
+      'content.disabled',
+      neutral,
+      selection.subtleTarget,
+      selection,
+      SURFACE_COLOR_POLICY.disabledContrast,
+    ),
+    icon: selectText('content.icon', neutral, selection.textTarget, selection),
+    link: selectText('content.link', primary, selection.textTarget, selection),
+    visited: selectText('content.visited', secondary, selection.textTarget, selection),
+    inverse: theme.semantics.content.default,
+  };
+}
+
+/*** Resolve separators and focus chrome against inverse backgrounds. */
+function resolveInverseBorder(theme: SurfaceTheme, selection: InverseSelection): BorderSemantics {
+  const { neutral } = theme.swatches;
+  const outline = selection.borderTarget;
+  return {
+    default: selectOutline('border.default', neutral, outline, selection),
+    subtle: selectOutline('border.subtle', neutral, outline, selection),
+    strong: selectOutline('border.strong', neutral, outline, selection),
+    divider: selectOutline('border.divider', neutral, outline, selection),
+    focus: selectOutline('border.focus', theme.swatches.primary, selection.textTarget, selection),
+  };
+}
+
+/*** Project only surface-relative role fields and preserve self-owned color pairs. */
+function resolveInverseRoles(theme: SurfaceTheme, selection: InverseSelection) {
+  const status = createDefaultSemanticStatusSwatches().swatches;
+  const { semantics } = theme;
+  return {
+    brand: projectRole('brand', semantics.brand, theme.swatches.primary, selection),
+    secondary: projectRole(
+      'secondary',
+      semantics.secondary,
+      theme.swatches.secondary ?? theme.swatches.primary,
+      selection,
+    ),
+    accent: projectRole(
+      'accent',
+      semantics.accent,
+      theme.swatches.tertiary ?? theme.swatches.primary,
+      selection,
+    ),
+    highlight: projectRole(
+      'highlight',
+      semantics.highlight,
+      theme.swatches.quaternary ?? theme.swatches.primary,
+      selection,
+    ),
+    danger: projectRole('danger', semantics.danger, status.danger, selection),
+    success: projectRole('success', semantics.success, status.success, selection),
+    warning: projectRole('warning', semantics.warning, status.warning, selection),
+    info: projectRole('info', semantics.info, status.info, selection),
+    neutralAction: projectRole(
+      'neutral',
+      semantics.action.neutral,
+      theme.swatches.neutral,
+      selection,
+    ),
+  };
+}
+
+/*** Keep opaque and soft role pairs intact while selecting inverse-safe transparent colors. */
+function projectRole(
+  id: string,
+  role: RoleSemantics,
+  swatch: ColorSwatch,
+  selection: InverseSelection,
+): RoleSemantics {
+  return {
+    ...role,
+    onSurfaceText: selectText(`${id}.onSurfaceText`, swatch, selection.textTarget, selection),
+    outline: selectOutline(`${id}.outline`, swatch, selection.borderTarget, selection),
+  };
+}
+
+/*** Keep direct neutral semantic reads aligned with active surface polarity. */
+function resolveInverseNeutral(
+  theme: SurfaceTheme,
+  surface: SurfaceSemantics,
+  content: ContentSemantics,
+  border: BorderSemantics,
+  swatch: ColorSwatch,
+  lightSurface: boolean,
+): NeutralSemantics {
+  return {
+    ...theme.semantics.neutral,
+    bg: surface.sunken,
+    bgSubtle: surface.subtle,
+    surface: surface.default,
+    surfaceHover: lightSurface ? swatch[200] : swatch[700],
+    surfaceActive: lightSurface ? swatch[300] : swatch[600],
+    border: border.default,
+    borderStrong: border.strong,
+    divider: border.divider,
+    text: content.default,
+    textMuted: content.muted,
+    textSubtle: content.subtle,
+    disabledBg: surface.disabled,
+    disabledText: content.disabled,
+  };
+}
+
+/*** Select and measure inverse-surface text through Color Theory. */
+function selectText(
+  id: string,
+  swatch: ColorSwatch,
+  target: ColorSelectionTarget,
+  selection: InverseSelection,
+  minimumContrast: number = SURFACE_COLOR_POLICY.textContrast,
+): HexColor {
+  const contexts = selection.contexts.map((context) => ({ ...context, minimumContrast }));
+  const color = selectInverseColor(id, swatch, target, contexts, selection);
+  for (const context of contexts) {
+    selection.collector.measureForeground(
+      `inverse.${id}/${context.id}`,
+      color,
+      context.against,
+      minimumContrast,
+    );
+  }
+  return color;
+}
+
+/*** Select inverse-surface outlines with the UI contrast policy. */
+function selectOutline(
+  id: string,
+  swatch: ColorSwatch,
+  target: ColorSelectionTarget,
+  selection: InverseSelection,
+): HexColor {
+  const contexts = selection.contexts.map((context) => ({
+    ...context,
+    minimumContrast: SURFACE_COLOR_POLICY.uiContrast,
+  }));
+  const color = selectInverseColor(id, swatch, target, contexts, selection);
+  for (const context of contexts) {
+    selection.collector.measureForeground(
+      `inverse.${id}/${context.id}`,
+      color,
+      context.against,
+      SURFACE_COLOR_POLICY.uiContrast,
+    );
+  }
+  return color;
+}
+
+/*** Keep inverse contrast safe when a chromatic swatch cannot meet the policy. */
+function selectInverseColor(
+  id: string,
+  swatch: ColorSwatch,
+  target: ColorSelectionTarget,
+  contexts: readonly ColorContrastContext[],
+  selection: InverseSelection,
+): HexColor {
+  const result = selectColorSwatchStep(swatch, target, contexts, selection.tiePolicy);
+  selection.collector.selections.push({ id: `inverse.${id}`, result });
+  return (
+    result.selected?.hex ??
+    selection.collector.selectColor(
+      `inverse.${id}.neutralFallback`,
+      selection.neutral,
+      target,
+      contexts,
+      selection.tiePolicy,
+    )
+  );
+}

package/src/features/theme/domain/resolveInverseSurface.ts

@@ -0,0 +1,55 @@
+import { parseHexColorOrThrow } from '@ankhorage/color-theory';
+
+import type {
+  SurfaceContrastDiagnostic,
+  SurfaceSemantics,
+  SurfaceTheme,
+} from '../../../types/theme';
+import { SURFACE_COLOR_POLICY } from '../constants';
+import type { createSurfaceColorDiagnosticCollector } from './createSurfaceColorDiagnosticCollector';
+
+type Collector = ReturnType<typeof createSurfaceColorDiagnosticCollector>;
+
+/*** Resolve inverted surface levels and measure their effective separation. */
+export function resolveInverseSurface(
+  theme: SurfaceTheme,
+  lightSurface: boolean,
+  collector: Collector,
+): { surface: SurfaceSemantics; surfaceSeparation: SurfaceContrastDiagnostic[] } {
+  const { neutral } = theme.swatches;
+  const base = theme.semantics.surface.inverse;
+  const adjacent = lightSurface ? neutral[100] : neutral[800];
+  const sunken = lightSurface ? neutral[200] : neutral[950];
+  const surface: SurfaceSemantics = {
+    ...theme.semantics.surface,
+    default: base,
+    subtle: adjacent,
+    raised: adjacent,
+    sunken,
+    overlay: adjacent,
+    disabled: adjacent,
+    inverse: theme.semantics.surface.default,
+  };
+  return { surface, surfaceSeparation: measureInverseSurfaceSeparation(surface, collector) };
+}
+
+/*** Measure the returned surface levels against their shared sunken background. */
+function measureInverseSurfaceSeparation(
+  surface: SurfaceSemantics,
+  collector: Collector,
+): SurfaceContrastDiagnostic[] {
+  const background = parseHexColorOrThrow(surface.sunken);
+  const surfaces = [
+    ['surface.default', surface.default],
+    ['surface.raised', surface.raised],
+    ['surface.disabled', surface.disabled],
+  ] as const;
+  return surfaces.map(([id, foreground]) =>
+    collector.measureSurface(
+      id,
+      parseHexColorOrThrow(foreground),
+      background,
+      SURFACE_COLOR_POLICY.surfaceSeparation,
+    ),
+  );
+}

package/src/features/typography/adapters/inbound/Text.tsx

@@ -17,6 +17,7 @@ export function Text({
   italic = false,
   numberOfLines,
   testID,
+  style,
 }: TextProps) {
   const { theme } = useTheme();
   const content = children ?? i18nKey ?? null;
@@ -28,6 +29,7 @@ export function Text({
       style={[
         resolveTextStyles(theme, { align, italic, variant, weight }),
         { color: resolveTextColor(theme, emphasis, color) },
+        style,
       ]}
     >
       {content}

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

@@ -32,7 +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);
+    expect(outline.contentColor).toBe(theme.semantics.action.danger.onSoftHoverText);
   });
 
   it('derives input colors from interaction and validation state', () => {

package/src/internal/resolvers/resolveInteractiveColors.ts

@@ -43,7 +43,7 @@ export function resolveButtonColors(
             ? semanticTone.softHover
             : 'transparent',
         borderColor: semanticTone.outline,
-        contentColor: semanticTone.onSurfaceText,
+        contentColor: resolveTransparentContentColor(semanticTone, state),
       };
     case 'ghost':
       return {
@@ -53,7 +53,7 @@ export function resolveButtonColors(
             ? semanticTone.softHover
             : 'transparent',
         borderColor: 'transparent',
-        contentColor: semanticTone.onSurfaceText,
+        contentColor: resolveTransparentContentColor(semanticTone, state),
       };
     case 'soft':
       return {
@@ -87,6 +87,16 @@ export function resolveButtonColors(
   }
 }
 
+/*** Pair hovered and pressed transparent controls with their own soft fill. */
+function resolveTransparentContentColor(
+  role: ReturnType<typeof resolveSurfaceColor>,
+  state: InteractionState,
+): string {
+  if (state.pressed) return role.onSoftActiveText;
+  if (state.hovered) return role.onSoftHoverText;
+  return role.onSurfaceText;
+}
+
 export function resolveInputColors(
   theme: SurfaceTheme,
   fieldState: FieldState,

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

@@ -4,6 +4,11 @@ import { createTheme } from '../../features/theme/application/use-cases/createTh
 import { resolveTextColor } from './resolveTextColor';
 
 describe('resolveTextColor', () => {
+  it('uses inverse-surface role foregrounds for semantic text inside inverted scopes', () => {
+    const theme = createTheme(undefined, 'light', undefined, true);
+    expect(resolveTextColor(theme, 'default', 'primary')).toBe(theme.semantics.brand.onSurfaceText);
+    expect(resolveTextColor(theme, 'inverse', 'primary')).toBe(theme.semantics.brand.onSolidText);
+  });
   it('maps semantic text emphases through content aliases', () => {
     const theme = createTheme();
 

package/src/internal/resolvers/resolveTextColor.ts

@@ -12,7 +12,8 @@ export function resolveTextColor(
       return resolveSurfaceColor(theme, color).onSolidText;
     }
 
-    return resolveSurfaceColor(theme, color).base;
+    const role = resolveSurfaceColor(theme, color);
+    return theme.inverted ? role.onSurfaceText : role.base;
   }
 
   switch (emphasis) {

package/src/invertedThemeAcceptance.test.ts

@@ -0,0 +1,204 @@
+import { getContrastRatio, parseHexColorOrThrow } from '@ankhorage/color-theory';
+import { expect, it } from 'bun:test';
+
+import { createTheme } from './features/theme/application/use-cases/createTheme';
+import { SURFACE_COLOR_POLICY } from './features/theme/constants';
+import {
+  resolveButtonColors,
+  resolveInputColors,
+} from './internal/resolvers/resolveInteractiveColors';
+
+const idle = { disabled: false, focused: false, hovered: false, pressed: false };
+const modes: ('light' | 'dark')[] = ['light', 'dark'];
+
+it.each(modes)('%s inversion keeps mode and self-owned role pairs', (mode) => {
+  const normal = createTheme(undefined, mode);
+  const inverted = createTheme(undefined, mode, undefined, true);
+  expect(inverted.colorDiagnostics.mode).toBe(mode);
+  expect(inverted.semantics.surface.default).toBe(normal.semantics.surface.inverse);
+  expect(inverted.semantics.content.default).not.toBe(normal.semantics.content.default);
+  expect(inverted.semantics.brand.base).toBe(normal.semantics.brand.base);
+  expect(inverted.semantics.brand.onSolidText).toBe(normal.semantics.brand.onSolidText);
+  expect(inverted.semantics.brand.softBg).toBe(normal.semantics.brand.softBg);
+  expect(inverted.semantics.brand.onSoftText).toBe(normal.semantics.brand.onSoftText);
+  expect(inverted.colors.background).toBe(inverted.semantics.surface.sunken);
+  expect(inverted.semantics.neutral.bg).toBe(inverted.semantics.surface.sunken);
+});
+
+it.each(modes)('%s inversion selects readable content and border semantics', (mode) => {
+  const inverted = createTheme(undefined, mode, undefined, true);
+  const surface = parseHexColorOrThrow(inverted.semantics.surface.default);
+  const { content, border } = inverted.semantics;
+  for (const foreground of [content.default, content.muted, content.subtle, content.icon]) {
+    expect(getContrastRatio(parseHexColorOrThrow(foreground), surface)).toBeGreaterThanOrEqual(
+      SURFACE_COLOR_POLICY.textContrast,
+    );
+  }
+  expect(getContrastRatio(parseHexColorOrThrow(border.divider), surface)).toBeGreaterThanOrEqual(
+    SURFACE_COLOR_POLICY.uiContrast,
+  );
+  expect(
+    inverted.colorDiagnostics.contrasts
+      .filter((entry) => entry.id.startsWith('inverse.'))
+      .every((entry) => entry.passes),
+  ).toBe(true);
+});
+
+it.each(modes)(
+  '%s inversion diagnostics describe projected surfaces and disabled content',
+  (mode) => {
+    const theme = createTheme(undefined, mode, undefined, true);
+    const disabled = theme.colorDiagnostics.contrasts.filter((entry) =>
+      entry.id.startsWith('inverse.content.disabled/'),
+    );
+    expect(disabled).toHaveLength(3);
+    expect(
+      disabled.every((entry) => entry.minimumContrast === SURFACE_COLOR_POLICY.disabledContrast),
+    ).toBe(true);
+    expect(disabled.every((entry) => entry.passes)).toBe(true);
+    expect(
+      theme.colorDiagnostics.surfaceSeparation.map((entry) => String(entry.foreground)),
+    ).toEqual([
+      theme.semantics.surface.default,
+      theme.semantics.surface.raised,
+      theme.semantics.surface.disabled,
+    ]);
+    expect(
+      theme.colorDiagnostics.surfaceSeparation.every(
+        (entry) => entry.background === theme.semantics.surface.sunken,
+      ),
+    ).toBe(true);
+    expect(theme.semantics.surface.default).not.toBe(theme.semantics.surface.sunken);
+    expect(theme.colorDiagnostics.surfaceSeparation.every((entry) => entry.passes)).toBe(true);
+  },
+);
+
+it.each(modes)('%s inversion keeps selection semantics paired', (mode) => {
+  const theme = createTheme(undefined, mode, undefined, true);
+  const { brand, border, selection } = theme.semantics;
+  expect(selection.background).toBe(brand.softBg);
+  expect(selection.content).toBe(brand.onSoftText);
+  expect(selection.border).toBe(border.focus);
+  expect(
+    getContrastRatio(
+      parseHexColorOrThrow(selection.content),
+      parseHexColorOrThrow(selection.background),
+    ),
+  ).toBeGreaterThanOrEqual(SURFACE_COLOR_POLICY.textContrast);
+});
+
+it.each(modes)('%s disabled controls use the disabled contrast policy', (mode) => {
+  const theme = createTheme(undefined, mode, undefined, true);
+  const button = resolveButtonColors(theme, {
+    color: 'primary',
+    variant: 'ghost',
+    state: { ...idle, disabled: true },
+  });
+  const input = resolveInputColors(theme, {
+    name: 'disabled',
+    disabled: true,
+    focused: false,
+    invalid: false,
+    readOnly: false,
+  });
+  for (const control of [button, input]) {
+    expect(
+      getContrastRatio(
+        parseHexColorOrThrow(control.contentColor),
+        parseHexColorOrThrow(control.backgroundColor),
+      ),
+    ).toBeGreaterThanOrEqual(SURFACE_COLOR_POLICY.disabledContrast);
+  }
+});
+
+it.each(modes)('%s inversion keeps transparent controls and input readable', (mode) => {
+  const normal = createTheme(undefined, mode);
+  const inverted = createTheme(undefined, mode, undefined, true);
+  const surface = parseHexColorOrThrow(inverted.semantics.surface.default);
+  for (const color of ['primary', 'neutral'] as const) {
+    for (const variant of ['ghost', 'outline'] as const) {
+      const colors = resolveButtonColors(inverted, { color, variant, state: idle });
+      expect(
+        getContrastRatio(parseHexColorOrThrow(colors.contentColor), surface),
+      ).toBeGreaterThanOrEqual(SURFACE_COLOR_POLICY.textContrast);
+      if (variant === 'outline') {
+        expect(
+          getContrastRatio(parseHexColorOrThrow(colors.borderColor), surface),
+        ).toBeGreaterThanOrEqual(SURFACE_COLOR_POLICY.uiContrast);
+      }
+    }
+  }
+  const solid = resolveButtonColors(inverted, { color: 'primary', variant: 'solid', state: idle });
+  const normalSolid = resolveButtonColors(normal, {
+    color: 'primary',
+    variant: 'solid',
+    state: idle,
+  });
+  expect(solid).toEqual(normalSolid);
+  const input = resolveInputColors(inverted, {
+    name: 'default',
+    disabled: false,
+    focused: false,
+    invalid: false,
+    readOnly: false,
+  });
+  expect(
+    getContrastRatio(
+      parseHexColorOrThrow(input.contentColor),
+      parseHexColorOrThrow(input.backgroundColor),
+    ),
+  ).toBeGreaterThanOrEqual(SURFACE_COLOR_POLICY.textContrast);
+});
+
+it.each([false, true])(
+  'transparent actions pair hover and press fills (inverted=%p)',
+  (inverted) => {
+    for (const mode of modes) {
+      const theme = createTheme(undefined, mode, undefined, inverted);
+      for (const color of ['primary', 'neutral'] as const) {
+        for (const variant of ['ghost', 'outline'] as const) {
+          for (const interaction of ['hovered', 'pressed'] as const) {
+            const colors = resolveButtonColors(theme, {
+              color,
+              variant,
+              state: { ...idle, [interaction]: true },
+            });
+            const role =
+              color === 'primary' ? theme.semantics.action.primary : theme.semantics.action.neutral;
+            expect(colors.contentColor).toBe(
+              interaction === 'hovered' ? role.onSoftHoverText : role.onSoftActiveText,
+            );
+            expect(
+              getContrastRatio(
+                parseHexColorOrThrow(colors.contentColor),
+                parseHexColorOrThrow(colors.backgroundColor),
+              ),
+            ).toBeGreaterThanOrEqual(SURFACE_COLOR_POLICY.textContrast);
+          }
+        }
+      }
+    }
+  },
+);
+
+it.each([
+  ['light', '#000000'],
+  ['dark', '#FFFFFF'],
+] as const)('%s inversion retains contrast for extreme brand seeds', (mode, primaryColor) => {
+  const config = {
+    id: 'extreme',
+    name: 'Extreme',
+    light: { primaryColor, harmony: 'monochromatic' as const },
+    dark: { primaryColor, harmony: 'monochromatic' as const },
+  };
+  const theme = createTheme(config, mode, undefined, true);
+  expect(
+    theme.colorDiagnostics.contrasts
+      .filter((entry) => entry.id.startsWith('inverse.'))
+      .every((entry) => entry.passes),
+  ).toBe(true);
+  expect(
+    theme.colorDiagnostics.selections.some((entry) => entry.id.endsWith('neutralFallback')),
+  ).toBe(true);
+  expect(theme.colorDiagnostics.surfaceSeparation.every((entry) => entry.passes)).toBe(true);
+});

package/src/types/theme.ts

@@ -229,6 +229,7 @@ export interface ThemeTokens {
 
 export interface SurfaceTheme extends ThemeTokens {
   config: ContractsThemeConfig;
+  inverted?: boolean;
 }
 
 export type ThemeMode = 'light' | 'dark';
@@ -236,6 +237,7 @@ export type ThemeMode = 'light' | 'dark';
 export interface ThemeRuntime {
   theme: SurfaceTheme;
   mode: ThemeMode;
+  inverted?: boolean;
   setThemeConfig: (config: Partial<ContractsThemeConfig>) => void;
   setMode: (mode: ThemeMode) => void;
 }
@@ -250,4 +252,5 @@ export interface ThemeScopeProps {
   children: ReactNode;
   themeConfig?: Partial<ContractsThemeConfig>;
   mode?: ThemeMode;
+  inverted?: boolean;
 }

package/src/types/typography.ts

@@ -32,4 +32,5 @@ export interface TextProps {
   italic?: boolean;
   numberOfLines?: number;
   testID?: string;
+  style?: TextStyle;
 }