@ankhorage/surface 2.1.0 → 2.2.0

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'\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    [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": "2.1.0",
+  "version": "2.2.0",
   "description": "Stable UI foundation for React Native and React Native Web.",
   "homepage": "https://github.com/ankhorage/surface#readme",
   "bugs": {
@@ -42,8 +42,8 @@
     }
   },
   "dependencies": {
-    "@ankhorage/color-theory": "^0.0.7",
-    "@ankhorage/contracts": "^2.1.0"
+    "@ankhorage/color-theory": "^0.0.8",
+    "@ankhorage/contracts": "^7.2.0"
   },
   "files": [
     "dist",
@@ -82,7 +82,7 @@
   },
   "devDependencies": {
     "@ankhorage/devtools": "^1.0.6",
-    "@ankhorage/paradox": "^0.1.7",
+    "@ankhorage/paradox": "^0.1.21",
     "@changesets/cli": "^2.31.0",
     "@expo/vector-icons": "^15.1.1",
     "@types/bun": "^1.3.13",

package/src/theme/colorEngine.ts

@@ -22,6 +22,7 @@ import type {
   RoleSemantics,
   SurfaceSemantics,
   ThemeSemantics,
+  ThemeTokens,
 } from './types';
 
 /**
@@ -109,7 +110,7 @@ export function generatePalette(
   config: ThemeConfig,
   mode: 'light' | 'dark' = 'light',
 ): {
-  colors: Record<string, string>;
+  colors: ThemeTokens['colors'];
   swatches: GeneratedThemeSwatches;
   semantics: ThemeSemantics;
 } {
@@ -168,7 +169,7 @@ export function generatePalette(
     danger,
   };
 
-  const colors: Record<string, string> = {
+  const colors: ThemeTokens['colors'] = {
     primary: brand.base,
     secondary: secondarySwatch[500],
     accent: tertiarySwatch[500],

package/src/theme/createTheme.ts

@@ -1,93 +1,27 @@
 import { generatePalette } from './colorEngine';
-import type { FontWeight, SurfaceTheme, ThemeConfig, ThemeTokens } from './types';
+import { resolveGlobalTokens } from './resolveGlobalTokens';
+import type { FontWeight, SurfaceTheme, ThemeConfig } from './types';
 
-export const DEFAULT_TOKENS: Omit<ThemeTokens, 'colors' | 'swatches' | 'semantics'> = {
-  spacing: {
-    none: 0,
-    xs: 4,
-    s: 8,
-    m: 16,
-    l: 24,
-    xl: 32,
-    xxl: 48,
-  },
-  radii: {
-    none: 0,
-    s: 4,
-    m: 8,
-    l: 16,
-    full: 9999,
-  },
-  typography: {
-    headings: {
-      1: { size: 32, lineHeight: 40, weight: 'bold' },
-      2: { size: 24, lineHeight: 32, weight: 'bold' },
-      3: { size: 20, lineHeight: 28, weight: 'bold' },
-      4: { size: 18, lineHeight: 24, weight: 'semiBold' },
-      5: { size: 16, lineHeight: 22, weight: 'semiBold' },
-      6: { size: 14, lineHeight: 20, weight: 'semiBold' },
-    },
-    sizes: {
-      xs: 12,
-      s: 14,
-      m: 16,
-      l: 18,
-      xl: 20,
-      xxl: 24,
-      '3xl': 30,
-      h1: 32,
-      h2: 24,
-      h3: 20,
-      h4: 18,
-      h5: 16,
-      h6: 14,
-    },
-    weights: {
-      thin: '100',
-      extraLight: '200',
-      light: '300',
-      regular: '400',
-      medium: '500',
-      semiBold: '600',
-      bold: '700',
-      extraBold: '800',
-      black: '900',
-    },
-    fonts: {
-      normal: {} as Record<FontWeight, string | undefined>,
-      italic: {} as Record<FontWeight, string | undefined>,
-    },
-  },
-  shadows: {
-    soft: 2,
-    medium: 4,
-    hard: 8,
-  },
-};
+export { DEFAULT_TOKENS } from './defaultTokens';
 
 export const DEFAULT_CONFIG: ThemeConfig = {
   id: 'default',
   name: 'Default',
-  light: {
-    primaryColor: '#3B82F6',
-    harmony: 'monochromatic',
-  },
-  dark: {
-    primaryColor: '#3B82F6',
-    harmony: 'monochromatic',
-  },
+  light: { primaryColor: '#3B82F6', harmony: 'monochromatic' },
+  dark: { primaryColor: '#3B82F6', harmony: 'monochromatic' },
 };
 
-/**
- * Normalizes font family name to PascalCase for consistent key generation
- * matches GoogleFontsPlugin logic.
- */
-function toPascalCase(str: string) {
-  return str
-    .split(/[- ]+/)
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join('');
-}
+const ACTIVE_FONT_WEIGHTS: readonly FontWeight[] = [
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+];
 
 export function createTheme(
   config: ThemeConfig = DEFAULT_CONFIG,
@@ -95,25 +29,31 @@ export function createTheme(
   activeFontId?: string | null,
 ): SurfaceTheme {
   const { colors, swatches, semantics } = generatePalette(config, mode);
-
-  const theme = {
-    ...DEFAULT_TOKENS,
-    colors: colors as SurfaceTheme['colors'],
+  const theme: SurfaceTheme = {
+    ...resolveGlobalTokens(config.tokens),
+    colors,
     swatches,
     semantics,
     config,
   };
 
-  if (activeFontId) {
-    const familyName = toPascalCase(activeFontId);
-    const weights: FontWeight[] = ['100', '200', '300', '400', '500', '600', '700', '800', '900'];
+  applyActiveFont(theme, activeFontId);
+  return theme;
+}
+
+function applyActiveFont(theme: SurfaceTheme, activeFontId: string | null | undefined): void {
+  if (!activeFontId) return;
 
-    weights.forEach((w) => {
-      // Convention from GoogleFonts plugin: Family_WeightRegular
-      theme.typography.fonts.normal[w] = `${familyName}_${w}Regular`;
-      theme.typography.fonts.italic[w] = `${familyName}_${w}Italic`;
-    });
+  const familyName = toPascalCase(activeFontId);
+  for (const weight of ACTIVE_FONT_WEIGHTS) {
+    theme.typography.fonts.normal[weight] = `${familyName}_${weight}Regular`;
+    theme.typography.fonts.italic[weight] = `${familyName}_${weight}Italic`;
   }
+}
 
-  return theme;
+function toPascalCase(value: string): string {
+  return value
+    .split(/[- ]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
 }

package/src/theme/createThemeOverrides.test.ts

@@ -0,0 +1,51 @@
+import type { ThemeConfig } from '@ankhorage/contracts';
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme, DEFAULT_CONFIG, DEFAULT_TOKENS } from './createTheme';
+
+describe('createTheme authored global tokens', () => {
+  it('preserves defaults when no authored overrides exist', () => {
+    const theme = createTheme(DEFAULT_CONFIG);
+
+    expect(theme.spacing).toEqual(DEFAULT_TOKENS.spacing);
+    expect(theme.radii).toEqual(DEFAULT_TOKENS.radii);
+    expect(theme.typography.sizes).toEqual(DEFAULT_TOKENS.typography.sizes);
+    expect(theme.typography.weights).toEqual(DEFAULT_TOKENS.typography.weights);
+    expect(theme.shadows).toEqual(DEFAULT_TOKENS.shadows);
+  });
+
+  it('merges authored global tokens without copying omitted defaults into config', () => {
+    const config: ThemeConfig = {
+      ...DEFAULT_CONFIG,
+      tokens: {
+        spacing: { m: 18, hero: 64 },
+        radii: { l: 20, pill: 999 },
+        typography: {
+          sizes: { m: 17, display: 44 },
+          weights: { medium: '600' },
+          headings: { '1': { size: 36, lineHeight: 44, weight: 'semiBold' } },
+        },
+        shadows: { soft: 3, floating: 12 },
+      },
+    };
+
+    const theme = createTheme(config);
+
+    expect(theme.spacing).toMatchObject({ xs: 4, m: 18, hero: 64 });
+    expect(theme.radii).toMatchObject({ m: 8, l: 20, pill: 999 });
+    expect(theme.typography.sizes).toMatchObject({ s: 14, m: 17, display: 44 });
+    expect(theme.typography.weights).toMatchObject({ regular: '400', medium: '600' });
+    expect(theme.typography.headings[1]).toEqual({ size: 36, lineHeight: 44, weight: 'semiBold' });
+    expect(theme.shadows).toMatchObject({ medium: 4, soft: 3, floating: 12 });
+    expect(theme.config.tokens).toEqual(config.tokens);
+  });
+
+  it('keeps module-derived font families isolated per resolved theme', () => {
+    const withFont = createTheme(DEFAULT_CONFIG, 'light', 'source-sans');
+    const withoutFont = createTheme(DEFAULT_CONFIG);
+
+    expect(withFont.typography.fonts.normal['400']).toBe('SourceSans_400Regular');
+    expect(withoutFont.typography.fonts.normal['400']).toBeUndefined();
+    expect(DEFAULT_TOKENS.typography.fonts.normal['400']).toBeUndefined();
+  });
+});

package/src/theme/createThemeValidation.test.ts

@@ -0,0 +1,50 @@
+import type { ThemeConfig, ThemeGlobalTokenOverrides } from '@ankhorage/contracts';
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme, DEFAULT_CONFIG } from './createTheme';
+
+describe('createTheme token validation', () => {
+  it('rejects negative or non-finite numeric tokens', () => {
+    expect(() => createTheme(withTokens({ spacing: { m: -1 } }))).toThrow(RangeError);
+    expect(() => createTheme(withTokens({ radii: { l: Number.NaN } }))).toThrow(RangeError);
+    expect(() => createTheme(withTokens({ shadows: { soft: Number.POSITIVE_INFINITY } }))).toThrow(
+      RangeError,
+    );
+  });
+
+  it('keeps reserved zero tokens canonical', () => {
+    expect(() => createTheme(withTokens({ spacing: { none: 1 } }))).toThrow('spacing.none');
+    expect(() => createTheme(withTokens({ radii: { none: 1 } }))).toThrow('radii.none');
+  });
+
+  it('requires positive typography dimensions', () => {
+    expect(() => createTheme(withTokens({ typography: { sizes: { m: 0 } } }))).toThrow(
+      'typography.sizes.m',
+    );
+    expect(() =>
+      createTheme(withTokens({ typography: { headings: { '1': { lineHeight: 0 } } } })),
+    ).toThrow('typography.headings.1.lineHeight');
+  });
+
+  it('rejects unknown heading and weight slots', () => {
+    expect(() =>
+      createTheme(withTokens({ typography: { headings: { hero: { size: 40 } } } })),
+    ).toThrow('Unknown typography heading token');
+    expect(() => createTheme(withTokens({ typography: { weights: { hero: '700' } } }))).toThrow(
+      'Unknown typography weight token',
+    );
+  });
+
+  it('rejects unsupported heading and font-weight values', () => {
+    expect(() =>
+      createTheme(withTokens({ typography: { headings: { '1': { weight: '900' } } } })),
+    ).toThrow('Invalid heading weight');
+    expect(() => createTheme(withTokens({ typography: { weights: { medium: '950' } } }))).toThrow(
+      'Invalid font weight',
+    );
+  });
+});
+
+function withTokens(tokens: ThemeGlobalTokenOverrides): ThemeConfig {
+  return { ...DEFAULT_CONFIG, tokens };
+}

package/src/theme/defaultTokens.ts

@@ -0,0 +1,58 @@
+import type { FontWeight, ThemeTokens } from './types';
+
+const EMPTY_FONT_MAP: Record<FontWeight, string | undefined> = {
+  '100': undefined,
+  '200': undefined,
+  '300': undefined,
+  '400': undefined,
+  '500': undefined,
+  '600': undefined,
+  '700': undefined,
+  '800': undefined,
+  '900': undefined,
+  bold: undefined,
+  normal: undefined,
+};
+
+export const DEFAULT_TOKENS: Omit<ThemeTokens, 'colors' | 'swatches' | 'semantics'> = {
+  spacing: { none: 0, xs: 4, s: 8, m: 16, l: 24, xl: 32, xxl: 48 },
+  radii: { none: 0, s: 4, m: 8, l: 16, full: 9999 },
+  typography: {
+    headings: {
+      1: { size: 32, lineHeight: 40, weight: 'bold' },
+      2: { size: 24, lineHeight: 32, weight: 'bold' },
+      3: { size: 20, lineHeight: 28, weight: 'bold' },
+      4: { size: 18, lineHeight: 24, weight: 'semiBold' },
+      5: { size: 16, lineHeight: 22, weight: 'semiBold' },
+      6: { size: 14, lineHeight: 20, weight: 'semiBold' },
+    },
+    sizes: {
+      xs: 12,
+      s: 14,
+      m: 16,
+      l: 18,
+      xl: 20,
+      xxl: 24,
+      '3xl': 30,
+      h1: 32,
+      h2: 24,
+      h3: 20,
+      h4: 18,
+      h5: 16,
+      h6: 14,
+    },
+    weights: {
+      thin: '100',
+      extraLight: '200',
+      light: '300',
+      regular: '400',
+      medium: '500',
+      semiBold: '600',
+      bold: '700',
+      extraBold: '800',
+      black: '900',
+    },
+    fonts: { normal: { ...EMPTY_FONT_MAP }, italic: { ...EMPTY_FONT_MAP } },
+  },
+  shadows: { soft: 2, medium: 4, hard: 8 },
+};

package/src/theme/resolveGlobalTokens.ts

@@ -0,0 +1,55 @@
+import type { ThemeGlobalTokenOverrides } from '@ankhorage/contracts';
+
+import { DEFAULT_TOKENS } from './defaultTokens';
+import { resolveHeadingTokenOverrides } from './resolveHeadingTokenOverrides';
+import { resolveNumericTokenOverrides } from './resolveNumericTokenOverrides';
+import { resolveWeightTokenOverrides } from './resolveWeightTokenOverrides';
+import type { ThemeTokens } from './types';
+
+type GlobalThemeTokens = Omit<ThemeTokens, 'colors' | 'swatches' | 'semantics'>;
+
+export function resolveGlobalTokens(overrides?: ThemeGlobalTokenOverrides): GlobalThemeTokens {
+  validateZeroTokens(overrides);
+  const typography = overrides?.typography;
+  return {
+    spacing: {
+      ...DEFAULT_TOKENS.spacing,
+      ...resolveNumericTokenOverrides('spacing', overrides?.spacing),
+    },
+    radii: {
+      ...DEFAULT_TOKENS.radii,
+      ...resolveNumericTokenOverrides('radii', overrides?.radii),
+    },
+    typography: {
+      headings: resolveHeadingTokenOverrides(
+        DEFAULT_TOKENS.typography.headings,
+        typography?.headings,
+      ),
+      sizes: {
+        ...DEFAULT_TOKENS.typography.sizes,
+        ...resolveNumericTokenOverrides('typography.sizes', typography?.sizes, true),
+      },
+      weights: {
+        ...DEFAULT_TOKENS.typography.weights,
+        ...resolveWeightTokenOverrides(typography?.weights),
+      },
+      fonts: {
+        normal: { ...DEFAULT_TOKENS.typography.fonts.normal },
+        italic: { ...DEFAULT_TOKENS.typography.fonts.italic },
+      },
+    },
+    shadows: {
+      ...DEFAULT_TOKENS.shadows,
+      ...resolveNumericTokenOverrides('shadows', overrides?.shadows),
+    },
+  };
+}
+
+function validateZeroTokens(overrides: ThemeGlobalTokenOverrides | undefined): void {
+  if (overrides?.spacing?.none !== undefined && overrides.spacing.none !== 0) {
+    throw new RangeError('Theme token spacing.none must remain 0.');
+  }
+  if (overrides?.radii?.none !== undefined && overrides.radii.none !== 0) {
+    throw new RangeError('Theme token radii.none must remain 0.');
+  }
+}

package/src/theme/resolveHeadingTokenOverrides.ts

@@ -0,0 +1,61 @@
+import type { ThemeTypographyHeadingOverrides } from '@ankhorage/contracts';
+
+import type { ThemeTokens } from './types';
+
+type HeadingTokens = ThemeTokens['typography']['headings'];
+type HeadingToken = HeadingTokens[1];
+type HeadingWeight = HeadingToken['weight'];
+
+const HEADING_KEYS = new Set<string>(['1', '2', '3', '4', '5', '6']);
+const HEADING_WEIGHTS = new Set<string>(['regular', 'medium', 'semiBold', 'bold']);
+
+export function resolveHeadingTokenOverrides(
+  defaults: HeadingTokens,
+  overrides: Readonly<Record<string, ThemeTypographyHeadingOverrides>> | undefined,
+): HeadingTokens {
+  validateHeadingKeys(overrides);
+  return {
+    1: resolveHeading('1', defaults[1], overrides?.['1']),
+    2: resolveHeading('2', defaults[2], overrides?.['2']),
+    3: resolveHeading('3', defaults[3], overrides?.['3']),
+    4: resolveHeading('4', defaults[4], overrides?.['4']),
+    5: resolveHeading('5', defaults[5], overrides?.['5']),
+    6: resolveHeading('6', defaults[6], overrides?.['6']),
+  };
+}
+
+function validateHeadingKeys(
+  overrides: Readonly<Record<string, ThemeTypographyHeadingOverrides>> | undefined,
+): void {
+  for (const key of Object.keys(overrides ?? {})) {
+    if (!HEADING_KEYS.has(key)) throw new RangeError(`Unknown typography heading token: ${key}.`);
+  }
+}
+
+function resolveHeading(
+  key: string,
+  fallback: HeadingToken,
+  override: ThemeTypographyHeadingOverrides | undefined,
+): HeadingToken {
+  const size = override?.size ?? fallback.size;
+  const lineHeight = override?.lineHeight ?? fallback.lineHeight;
+  const weight = override?.weight ?? fallback.weight;
+  if (!Number.isFinite(size) || size <= 0) {
+    throw new RangeError(
+      `Theme token typography.headings.${key}.size must be a finite positive number.`,
+    );
+  }
+  if (!Number.isFinite(lineHeight) || lineHeight <= 0) {
+    throw new RangeError(
+      `Theme token typography.headings.${key}.lineHeight must be a finite positive number.`,
+    );
+  }
+  if (!isHeadingWeight(weight)) {
+    throw new RangeError(`Invalid heading weight for typography.headings.${key}: ${weight}.`);
+  }
+  return { size, lineHeight, weight };
+}
+
+function isHeadingWeight(value: string): value is HeadingWeight {
+  return HEADING_WEIGHTS.has(value);
+}

package/src/theme/resolveNumericTokenOverrides.ts

@@ -0,0 +1,19 @@
+export function resolveNumericTokenOverrides(
+  family: string,
+  overrides: Readonly<Record<string, number>> | undefined,
+  requirePositive = false,
+): Readonly<Record<string, number>> {
+  if (overrides === undefined) return {};
+
+  for (const [token, value] of Object.entries(overrides)) {
+    const invalid = !Number.isFinite(value) || (requirePositive ? value <= 0 : value < 0);
+    if (invalid) {
+      const expectation = requirePositive
+        ? 'a finite positive number'
+        : 'a finite non-negative number';
+      throw new RangeError(`Theme token ${family}.${token} must be ${expectation}.`);
+    }
+  }
+
+  return { ...overrides };
+}

package/src/theme/resolveWeightTokenOverrides.ts

@@ -0,0 +1,48 @@
+import type { FontWeight } from './types';
+
+const WEIGHT_TOKEN_KEYS = new Set<string>([
+  'thin',
+  'extraLight',
+  'light',
+  'regular',
+  'medium',
+  'semiBold',
+  'bold',
+  'extraBold',
+  'black',
+]);
+const FONT_WEIGHT_VALUES = new Set<string>([
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+  'bold',
+  'normal',
+]);
+
+export function resolveWeightTokenOverrides(
+  overrides: Readonly<Record<string, string>> | undefined,
+): Readonly<Record<string, FontWeight>> {
+  if (overrides === undefined) return {};
+
+  const resolved: Record<string, FontWeight> = {};
+  for (const [token, value] of Object.entries(overrides)) {
+    if (!WEIGHT_TOKEN_KEYS.has(token)) {
+      throw new RangeError(`Unknown typography weight token: ${token}.`);
+    }
+    if (!isFontWeight(value)) {
+      throw new RangeError(`Invalid font weight for typography.weights.${token}: ${value}.`);
+    }
+    resolved[token] = value;
+  }
+  return resolved;
+}
+
+function isFontWeight(value: string): value is FontWeight {
+  return FONT_WEIGHT_VALUES.has(value);
+}

package/src/theme/types.ts

@@ -132,6 +132,7 @@ export interface ThemeTokens {
     m: number;
     l: number;
     full: number;
+    [key: string]: number;
   };
   typography: {
     headings: Record<