@chipmobilesdk/rn-theme 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.2.0 - 2026-06-06
+
+### Added
+
+- Documented single-entrypoint public API for reusable theme generation and token types.
+- Added consumer setup guidance for host dependencies, setup order, Android/iOS expectations, and theme-start strategy.
+- Added package validation coverage for theme generation, config validation, public API imports, and package manifest readiness.
+- Added package publish-readiness metadata and dry-run validation expectations.
+
+### Changed
+
+- Classified host integrations as peer dependencies and kept runtime color generation in package dependencies.
+- Kept app-specific brand colors and typography outside the package.
+
+### Migration
+
+- This is a backward-compatible minor release for existing workspace consumers importing from `@chipmobilesdk/rn-theme`.
+- Consumers importing private subpaths must migrate to the package root entrypoint.
+
+### Deprecations
+
+- Private subpath imports are unsupported and should not be used by consuming apps.

package/README.md

@@ -0,0 +1,159 @@
+# @chipmobilesdk/rn-theme
+
+Reusable React Native theme generation and token contracts for ChipMobileSdk-family mobile apps.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: `0.2.0`
+- **Entrypoint**: `@chipmobilesdk/rn-theme`
+- **Demo**: `src/screens/ExampleScreen.tsx`
+
+## Install
+
+Install the package from the public npm registry, then install the host styling dependencies in the consuming app:
+
+```bash
+npm install @chipmobilesdk/rn-theme react-native-unistyles
+```
+
+The host app owns `react`, `react-native`, and `react-native-unistyles`. If the app uses a safe-area shell like the ChipMobileSdk demo, install `react-native-safe-area-context` in the app as an app dependency. The theme package itself does not import safe-area APIs.
+
+## Compatibility
+
+The current ChipMobileSdk demo validates against:
+
+- React `19.2.3`
+- React Native `0.85.3`
+- React Native Unistyles `^3.2.5`
+- TypeScript `^5.8.3`
+- Node.js `>=22.11.0`
+- Android and iOS host apps supported by the current React Native/Unistyles setup
+
+The package is TypeScript-only and does not include native Android or iOS code, permissions, entitlements, analytics, tracking, billing, storage, or network behavior.
+
+## Setup Order
+
+Create app-owned brand values:
+
+```ts
+import type { BrandColors, TypographyConfig } from '@chipmobilesdk/rn-theme';
+
+export const BRAND_COLORS: BrandColors = {
+  primary: '#046b63',
+  secondary: '#625b71',
+  tertiary: '#7d5260',
+};
+
+export const BRAND_TYPOGRAPHY: TypographyConfig = {
+  fontFamily: 'System',
+  baseFontSize: 16,
+  fontScale: 1,
+};
+```
+
+Configure Unistyles before any themed component renders:
+
+```ts
+import { StyleSheet } from 'react-native-unistyles';
+import { createUnistylesConfig } from '@chipmobilesdk/rn-theme';
+import type { UnistylesThemeFromBrand } from '@chipmobilesdk/rn-theme';
+import { BRAND_COLORS, BRAND_TYPOGRAPHY } from './brand';
+
+declare module 'react-native-unistyles' {
+  export interface UnistylesThemes extends UnistylesThemeFromBrand {}
+}
+
+StyleSheet.configure(
+  createUnistylesConfig(
+    {
+      brandColors: BRAND_COLORS,
+      typographyConfig: BRAND_TYPOGRAPHY,
+    },
+    { initialTheme: 'dark' },
+  ),
+);
+```
+
+Import the setup module first in the app entrypoint.
+
+## Theme Start Strategy
+
+Choose exactly one startup strategy.
+
+Manual initial theme:
+
+```ts
+createUnistylesConfig(config, { initialTheme: 'light' });
+```
+
+System adaptive themes:
+
+```ts
+createUnistylesConfig(config, { adaptiveThemes: true });
+```
+
+Using `initialTheme` and `adaptiveThemes: true` together is invalid. Persisting a user theme preference, if needed, belongs in the consuming app.
+
+## Public Runtime Exports
+
+- `createUnistylesConfig(config, options?)`
+- `generateLightPalette(brandColors)`
+- `generateDarkPalette(brandColors)`
+
+## Public Type Exports
+
+- `BrandColors`
+- `ThemeColors`
+- `TypographyConfig`
+- `TypographyToken`
+- `Typography`
+- `SpacingTokens`
+- `RadiusTokens`
+- `ShadowToken`
+- `ShadowTokens`
+- `ZIndexTokens`
+- `DeepPartial`
+- `StyleConfig`
+- `StyleTheme`
+- `UnistylesThemes`
+- `UnistylesConfigOptions`
+- `UnistylesConfig`
+- `UnistylesThemeFromBrand`
+
+## Private Modules
+
+Only `@chipmobilesdk/rn-theme` is public. Imports from `@chipmobilesdk/rn-theme/src/...`, `@chipmobilesdk/rn-theme/utils/...`, `@chipmobilesdk/rn-theme/tokens/...`, `@chipmobilesdk/rn-theme/types/...`, or `@chipmobilesdk/rn-theme/unistyles/...` are unsupported.
+
+## Configuration Validation
+
+The package validates required brand colors, positive typography values, valid color strings, and invalid theme-start combinations before returning a Unistyles config. Missing optional typography fields use documented defaults.
+
+## Dependency Classification
+
+- `dependencies`: runtime implementation packages imported by package code, currently `tinycolor2`.
+- `peerDependencies`: host framework/integration packages supplied by each app: `react`, `react-native`, and `react-native-unistyles`.
+- `devDependencies`: package-local type and validation tooling such as `@types/tinycolor2`.
+- `react-native-safe-area-context`: app/demo dependency only, because the package does not import it.
+
+## Release Validation
+
+Run from the repository root:
+
+```bash
+npm run lint
+npm test
+npm run typecheck
+npm run typecheck:theme
+npm run pack:theme
+```
+
+Record Android and iOS demo evidence under `specs/001-enhance-theme-package/validation/` before another app adopts the package.
+
+## Semver and Migration
+
+- Patch: internal fix with no public shape or behavior change.
+- Minor: backward-compatible public additions or documentation/package metadata improvements.
+- Major: removed export, renamed token, changed token shape, changed default semantics, or changed required consumer setup.
+
+Breaking changes require migration notes and a deprecation decision before release.

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@chipmobilesdk/rn-theme",
+	"version": "0.2.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/tokens",
+		"src/types",
+		"src/unistyles",
+		"src/utils",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"dependencies": {
+		"tinycolor2": "^1.6.0"
+	},
+	"devDependencies": {
+		"@types/tinycolor2": "^1.4.6"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-unistyles": ">=3.2"
+	},
+	"peerDependenciesMeta": {
+		"react-native-unistyles": {
+			"optional": false
+		}
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// ─── Color utilities (advanced use / custom palette overrides) ──────────────
+export { generateLightPalette, generateDarkPalette } from './utils/colorGeneration';
+
+// ─── Unistyles helpers ──────────────────────────────────────────────────────
+export { createUnistylesConfig } from './unistyles/createUnistylesConfig';
+export type {
+	UnistylesThemes,
+	UnistylesConfigOptions,
+	UnistylesConfig,
+} from './unistyles/createUnistylesConfig';
+export type { UnistylesThemeFromBrand } from './unistyles/types';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+export type { BrandColors } from './types/brand';
+export type { ThemeColors } from './types/colors';
+export type { TypographyConfig, TypographyToken, Typography } from './types/typography';
+export type {
+	SpacingTokens,
+	RadiusTokens,
+	ShadowToken,
+	ShadowTokens,
+	ZIndexTokens,
+} from './types/tokens';
+export type { DeepPartial, StyleConfig, StyleTheme } from './types/style';

package/src/tokens/defaults.ts

@@ -0,0 +1,52 @@
+import type { SpacingTokens, RadiusTokens, ShadowTokens, ZIndexTokens } from '../types/tokens';
+
+export const DEFAULT_SPACING: SpacingTokens = {
+	xs: 4,
+	sm: 8,
+	md: 16,
+	lg: 24,
+	xl: 32,
+	xxl: 48,
+};
+
+export const DEFAULT_RADIUS: RadiusTokens = {
+	sm: 4,
+	md: 8,
+	lg: 16,
+	xl: 24,
+	full: 9999,
+};
+
+export function buildShadows(shadowColor: string): ShadowTokens {
+	return {
+		sm: {
+			shadowColor,
+			shadowOffset: { width: 0, height: 1 },
+			shadowOpacity: 0.12,
+			shadowRadius: 2,
+			elevation: 2,
+		},
+		md: {
+			shadowColor,
+			shadowOffset: { width: 0, height: 2 },
+			shadowOpacity: 0.16,
+			shadowRadius: 6,
+			elevation: 4,
+		},
+		lg: {
+			shadowColor,
+			shadowOffset: { width: 0, height: 4 },
+			shadowOpacity: 0.22,
+			shadowRadius: 12,
+			elevation: 8,
+		},
+	};
+}
+
+export const DEFAULT_Z_INDEX: ZIndexTokens = {
+	base: 0,
+	raised: 10,
+	modal: 100,
+	overlay: 200,
+	toast: 300,
+};

package/src/tokens/typography.ts

@@ -0,0 +1,64 @@
+import type {
+	TypographyConfig,
+	TypographyToken,
+	Typography,
+	RawTypography,
+} from '../types/typography';
+
+interface ScaleEntry {
+	size: number;
+	weight: TypographyToken['fontWeight'];
+	lineHeightRatio: number;
+	letterSpacing?: number;
+}
+
+const DEFAULT_BODY_SIZE = 16;
+
+const SCALE: Record<keyof RawTypography, ScaleEntry> = {
+	display: {
+		size: 57,
+		weight: '700',
+		lineHeightRatio: 1.12,
+		letterSpacing: -0.25,
+	},
+	headline: { size: 32, weight: '600', lineHeightRatio: 1.25 },
+	title: { size: 22, weight: '600', lineHeightRatio: 1.27 },
+	body: { size: 16, weight: '400', lineHeightRatio: 1.5 },
+	label: { size: 14, weight: '500', lineHeightRatio: 1.43, letterSpacing: 0.1 },
+	caption: {
+		size: 12,
+		weight: '400',
+		lineHeightRatio: 1.33,
+		letterSpacing: 0.4,
+	},
+};
+
+export function buildTypography(config?: TypographyConfig): Typography {
+	const fontFamily = config?.fontFamily ?? 'System';
+	const baseScale =
+		(config?.baseFontSize ?? DEFAULT_BODY_SIZE) / DEFAULT_BODY_SIZE;
+	const scale = baseScale * (config?.fontScale ?? 1);
+
+	function makeToken(entry: ScaleEntry): TypographyToken {
+		const fontSize = Math.round(entry.size * scale);
+		return {
+			fontSize,
+			fontWeight: entry.weight,
+			lineHeight: Math.round(fontSize * entry.lineHeightRatio),
+			fontFamily,
+			...(entry.letterSpacing != null && {
+				letterSpacing: entry.letterSpacing,
+			}),
+		};
+	}
+
+	return {
+		fontFamily,
+		display: makeToken(SCALE.display),
+		headline: makeToken(SCALE.headline),
+		title: makeToken(SCALE.title),
+		body: makeToken(SCALE.body),
+		label: makeToken(SCALE.label),
+		caption: makeToken(SCALE.caption),
+	};
+}

package/src/types/brand.ts

@@ -0,0 +1,5 @@
+export interface BrandColors {
+	primary: string;
+	secondary: string;
+	tertiary: string;
+}

package/src/types/colors.ts

@@ -0,0 +1,23 @@
+export interface ThemeColors {
+	primary: string;
+	primaryContainer: string;
+	onPrimary: string;
+	secondary: string;
+	secondaryContainer: string;
+	onSecondary: string;
+	tertiary: string;
+	tertiaryContainer: string;
+	onTertiary: string;
+	background: string;
+	surface: string;
+	surfaceVariant: string;
+	onBackground: string;
+	onSurface: string;
+	border: string;
+	error: string;
+	success: string;
+	warning: string;
+	info: string;
+	disabled: string;
+	shadow: string;
+}

package/src/types/index.ts

@@ -0,0 +1,11 @@
+export type { BrandColors } from './brand';
+export type { ThemeColors } from './colors';
+export type { TypographyConfig, TypographyToken, Typography } from './typography';
+export type {
+	SpacingTokens,
+	RadiusTokens,
+	ShadowToken,
+	ShadowTokens,
+	ZIndexTokens,
+} from './tokens';
+export type { DeepPartial, StyleConfig, StyleTheme } from './style';

package/src/types/style.ts

@@ -0,0 +1,26 @@
+import type { BrandColors } from './brand';
+import type { ThemeColors } from './colors';
+import type { RadiusTokens, ShadowTokens, SpacingTokens, ZIndexTokens } from './tokens';
+import type { Typography, TypographyConfig } from './typography';
+
+export type DeepPartial<T> = {
+	[K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+export interface StyleTheme {
+	color: ThemeColors;
+	typography: Typography;
+	spacing: SpacingTokens;
+	radius: RadiusTokens;
+	shadow: ShadowTokens;
+	zIndex: ZIndexTokens;
+}
+
+export interface StyleConfig {
+	brandColors: BrandColors;
+	typographyConfig?: TypographyConfig;
+	overrides?: {
+		light?: DeepPartial<StyleTheme>;
+		dark?: DeepPartial<StyleTheme>;
+	};
+}

package/src/types/tokens.ts

@@ -0,0 +1,38 @@
+export interface SpacingTokens {
+	xs: number;
+	sm: number;
+	md: number;
+	lg: number;
+	xl: number;
+	xxl: number;
+}
+
+export interface RadiusTokens {
+	sm: number;
+	md: number;
+	lg: number;
+	xl: number;
+	full: number;
+}
+
+export interface ShadowToken {
+	shadowColor: string;
+	shadowOffset: { width: number; height: number };
+	shadowOpacity: number;
+	shadowRadius: number;
+	elevation: number;
+}
+
+export interface ShadowTokens {
+	sm: ShadowToken;
+	md: ShadowToken;
+	lg: ShadowToken;
+}
+
+export interface ZIndexTokens {
+	base: number;
+	raised: number;
+	modal: number;
+	overlay: number;
+	toast: number;
+}

package/src/types/typography.ts

@@ -0,0 +1,26 @@
+export interface TypographyConfig {
+	fontFamily?: string;
+	baseFontSize?: number;
+	fontScale?: number;
+}
+
+export interface TypographyToken {
+	fontSize: number;
+	fontWeight: '400' | '500' | '600' | '700' | '800' | '900';
+	lineHeight: number;
+	fontFamily?: string;
+	letterSpacing?: number;
+}
+
+export interface RawTypography {
+	display: TypographyToken;
+	headline: TypographyToken;
+	title: TypographyToken;
+	body: TypographyToken;
+	label: TypographyToken;
+	caption: TypographyToken;
+}
+
+export interface Typography extends RawTypography {
+	fontFamily: string;
+}

package/src/unistyles/createUnistylesConfig.ts

@@ -0,0 +1,177 @@
+import {
+	generateDarkPalette,
+	generateLightPalette,
+} from '../utils/colorGeneration';
+import type { DeepPartial, StyleConfig, StyleTheme } from '../types';
+import {
+	buildShadows,
+	DEFAULT_RADIUS,
+	DEFAULT_SPACING,
+	DEFAULT_Z_INDEX,
+} from '../tokens/defaults';
+import { buildTypography } from '../tokens/typography';
+import {
+	validateStyleConfig,
+	validateThemeOptions,
+} from './validateThemeConfig';
+
+export interface UnistylesThemes {
+	light: StyleTheme;
+	dark: StyleTheme;
+}
+
+type ThemeName = keyof UnistylesThemes;
+
+interface UnistylesBaseSettings {
+	CSSVars?: boolean;
+	nativeBreakpointsMode?: 'pixels' | 'points';
+}
+
+export type UnistylesConfigOptions = UnistylesBaseSettings &
+	(
+		| {
+			/** Which theme should be active on first launch. Defaults to 'light'. */
+			initialTheme?: ThemeName | (() => ThemeName);
+			adaptiveThemes?: false;
+		}
+		| {
+			/** Let Unistyles switch between light/dark from the system color scheme. */
+			adaptiveThemes: boolean;
+			initialTheme?: never;
+		}
+	);
+
+type UnistylesThemeSettings =
+	| {
+		initialTheme: ThemeName | (() => ThemeName);
+		adaptiveThemes?: false;
+	}
+	| {
+		adaptiveThemes: true;
+		initialTheme?: never;
+	};
+
+type UnistylesSettings = UnistylesBaseSettings & UnistylesThemeSettings;
+
+export interface UnistylesConfig {
+	themes: UnistylesThemes;
+	settings: UnistylesSettings;
+}
+
+/**
+ * Generates a unistyles-compatible configuration object from brand colors.
+ *
+ * Usage in your app (e.g. src/unistyles/setup.ts):
+ * ```ts
+ * import { StyleSheet } from 'react-native-unistyles';
+ * import { createUnistylesConfig } from '@chipmobilesdk/rn-theme';
+ * StyleSheet.configure(createUnistylesConfig(BRAND_COLORS));
+ * ```
+ *
+ * Use `initialTheme` for manual theme switching via `UnistylesRuntime.setTheme()`,
+ * or `adaptiveThemes` when Unistyles should follow the system color scheme.
+ */
+export function createUnistylesConfig(
+	config: StyleConfig,
+	options?: UnistylesConfigOptions,
+): UnistylesConfig {
+	validateStyleConfig(config);
+	validateThemeOptions(options);
+
+	const lightPalette = generateLightPalette(config.brandColors);
+	const darkPalette = generateDarkPalette(config.brandColors);
+	const defaultStyling = {
+		typography: buildTypography(config.typographyConfig),
+		spacing: DEFAULT_SPACING,
+		radius: DEFAULT_RADIUS,
+		zIndex: DEFAULT_Z_INDEX,
+	};
+
+	const lightTheme = mergeTheme(
+		{
+			color: lightPalette,
+			shadow: buildShadows(lightPalette.shadow),
+			...defaultStyling,
+		},
+		config.overrides?.light,
+	);
+
+	const darkTheme = mergeTheme(
+		{
+			color: darkPalette,
+			shadow: buildShadows(darkPalette.shadow),
+			...defaultStyling,
+		},
+		config.overrides?.dark,
+	);
+
+	return {
+		themes: {
+			light: lightTheme,
+			dark: darkTheme,
+		},
+		settings: createSettings(options),
+	};
+}
+
+function createSettings(options?: UnistylesConfigOptions): UnistylesSettings {
+	const baseSettings = {
+		...(options?.CSSVars != null && { CSSVars: options.CSSVars }),
+		...(options?.nativeBreakpointsMode != null && {
+			nativeBreakpointsMode: options.nativeBreakpointsMode,
+		}),
+	};
+
+	if (options?.adaptiveThemes === true) {
+		return {
+			...baseSettings,
+			adaptiveThemes: options.adaptiveThemes,
+		};
+	}
+
+	return {
+		...baseSettings,
+		initialTheme: options?.initialTheme ?? 'light',
+	};
+}
+
+function mergeTheme(
+	theme: StyleTheme,
+	overrides?: DeepPartial<StyleTheme>,
+): StyleTheme {
+	if (!overrides) {
+		return theme;
+	}
+
+	return mergeDeep(theme, overrides);
+}
+
+function mergeDeep<T>(base: T, overrides: DeepPartial<T>): T {
+	const result = { ...base } as Record<PropertyKey, unknown>;
+
+	for (const key of Object.keys(overrides) as Array<keyof T>) {
+		const overrideValue = overrides[key];
+
+		if (overrideValue == null) {
+			continue;
+		}
+
+		const baseValue = base[key];
+
+		if (isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+			result[key] = mergeDeep(
+				baseValue,
+				overrideValue as DeepPartial<typeof baseValue>,
+			);
+			continue;
+		}
+
+		result[key] = overrideValue;
+	}
+
+	return result as T;
+}
+
+function isPlainObject(value: unknown): value is Record<PropertyKey, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/unistyles/types.ts

@@ -0,0 +1,24 @@
+import 'react-native-unistyles';
+import type { StyleTheme } from '../types';
+
+/**
+ * Use this interface for module augmentation in your host application
+ * so that react-native-unistyles is aware of the theme token shapes.
+ *
+ * Example (src/unistyles/setup.ts):
+ * ```ts
+ * import type { UnistylesThemeFromBrand } from '@chipmobilesdk/rn-theme';
+ *
+ * declare module 'react-native-unistyles' {
+ *   export interface UnistylesThemes extends UnistylesThemeFromBrand {}
+ * }
+ * ```
+ */
+export interface UnistylesThemeFromBrand {
+	light: StyleTheme;
+	dark: StyleTheme;
+}
+
+declare module 'react-native-unistyles' {
+	export interface UnistylesThemes extends UnistylesThemeFromBrand { }
+}

package/src/unistyles/validateThemeConfig.ts

@@ -0,0 +1,154 @@
+import tinycolor from 'tinycolor2';
+import type { BrandColors } from '../types/brand';
+import type { StyleConfig } from '../types/style';
+import type { TypographyConfig } from '../types/typography';
+
+const BRAND_COLOR_KEYS = ['primary', 'secondary', 'tertiary'] as const;
+
+type ThemeName = 'light' | 'dark';
+
+interface ThemeOptionsShape {
+	CSSVars?: unknown;
+	nativeBreakpointsMode?: unknown;
+	initialTheme?: unknown;
+	adaptiveThemes?: unknown;
+}
+
+export function validateStyleConfig(config: StyleConfig): void {
+	if (!isRecord(config)) {
+		throw new Error('Theme config must be an object.');
+	}
+
+	validateBrandColors(config.brandColors);
+	validateTypographyConfig(config.typographyConfig);
+}
+
+export function validateBrandColors(brandColors: BrandColors): void {
+	if (!isRecord(brandColors)) {
+		throw new Error('Theme config must include brandColors.');
+	}
+
+	for (const key of BRAND_COLOR_KEYS) {
+		const color = brandColors[key];
+
+		if (typeof color !== 'string' || color.trim().length === 0) {
+			throw new Error(`brandColors.${key} must be a non-empty color string.`);
+		}
+
+		if (!tinycolor(color).isValid()) {
+			throw new Error(`brandColors.${key} must be a valid color string.`);
+		}
+	}
+}
+
+export function validateTypographyConfig(config?: TypographyConfig): void {
+	if (config == null) {
+		return;
+	}
+
+	if (!isRecord(config)) {
+		throw new Error('typographyConfig must be an object when provided.');
+	}
+	const typographyConfig = config as {
+		fontFamily?: unknown;
+		baseFontSize?: unknown;
+		fontScale?: unknown;
+	};
+
+	if (typographyConfig.fontFamily != null) {
+		if (
+			typeof typographyConfig.fontFamily !== 'string' ||
+			typographyConfig.fontFamily.trim().length === 0
+		) {
+			throw new Error(
+				'typographyConfig.fontFamily must be a non-empty string.',
+			);
+		}
+	}
+
+	if (typographyConfig.baseFontSize != null) {
+		assertPositiveFiniteNumber(
+			typographyConfig.baseFontSize,
+			'typographyConfig.baseFontSize',
+		);
+	}
+
+	if (typographyConfig.fontScale != null) {
+		assertPositiveFiniteNumber(
+			typographyConfig.fontScale,
+			'typographyConfig.fontScale',
+		);
+	}
+}
+
+export function validateThemeOptions(options?: ThemeOptionsShape): void {
+	if (options == null) {
+		return;
+	}
+
+	if (!isRecord(options)) {
+		throw new Error('Theme options must be an object when provided.');
+	}
+
+	const hasInitialTheme = options.initialTheme != null;
+	const hasAdaptiveThemes = options.adaptiveThemes === true;
+
+	if (hasInitialTheme && hasAdaptiveThemes) {
+		throw new Error('Use either initialTheme or adaptiveThemes, not both.');
+	}
+
+	if (options.initialTheme != null) {
+		validateInitialTheme(options.initialTheme);
+	}
+
+	if (
+		options.adaptiveThemes != null &&
+		typeof options.adaptiveThemes !== 'boolean'
+	) {
+		throw new Error('adaptiveThemes must be a boolean when provided.');
+	}
+
+	if (options.CSSVars != null && typeof options.CSSVars !== 'boolean') {
+		throw new Error('CSSVars must be a boolean when provided.');
+	}
+
+	if (
+		options.nativeBreakpointsMode != null &&
+		options.nativeBreakpointsMode !== 'pixels' &&
+		options.nativeBreakpointsMode !== 'points'
+	) {
+		throw new Error("nativeBreakpointsMode must be 'pixels' or 'points'.");
+	}
+}
+
+function validateInitialTheme(initialTheme: unknown): void {
+	if (typeof initialTheme === 'function') {
+		const resolvedTheme = initialTheme();
+
+		if (!isThemeName(resolvedTheme)) {
+			throw new Error("initialTheme resolver must return 'light' or 'dark'.");
+		}
+
+		return;
+	}
+
+	if (!isThemeName(initialTheme)) {
+		throw new Error(
+			"initialTheme must be 'light', 'dark', or a resolver function.",
+		);
+	}
+}
+
+function assertPositiveFiniteNumber(value: unknown, fieldName: string): void {
+	if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+		throw new Error(`${fieldName} must be a positive finite number.`);
+	}
+}
+
+function isThemeName(value: unknown): value is ThemeName {
+	return value === 'light' || value === 'dark';
+}
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/utils/colorGeneration.ts

@@ -0,0 +1,87 @@
+import type { BrandColors } from '../types/brand';
+import type { ThemeColors } from '../types/colors';
+import {
+	getContrastColor,
+	adjustLightness,
+	adjustSaturation,
+	toContainerColor,
+} from './colorMath';
+
+export function generateLightPalette(brand: BrandColors): ThemeColors {
+	const primaryContainer = toContainerColor(brand.primary, false);
+	const secondaryContainer = toContainerColor(brand.secondary, false);
+	const tertiaryContainer = toContainerColor(brand.tertiary, false);
+
+	return {
+		primary: brand.primary,
+		primaryContainer,
+		onPrimary: getContrastColor(brand.primary),
+
+		secondary: brand.secondary,
+		secondaryContainer,
+		onSecondary: getContrastColor(brand.secondary),
+
+		tertiary: brand.tertiary,
+		tertiaryContainer,
+		onTertiary: getContrastColor(brand.tertiary),
+
+		background: '#F8F9FA',
+		surface: '#FFFFFF',
+		surfaceVariant: adjustSaturation(adjustLightness(brand.primary, 48), -20),
+
+		onBackground: '#1A1A1A',
+		onSurface: '#1A1A1A',
+
+		border: '#E0E0E0',
+
+		// Semantic — WCAG-compliant accessible values for light backgrounds
+		error: '#B3261E',
+		success: '#2E7D32',
+		warning: '#E65100',
+		info: '#0277BD',
+		disabled: '#9E9E9E',
+		shadow: '#000000',
+	};
+}
+
+export function generateDarkPalette(brand: BrandColors): ThemeColors {
+	// Brighten brand colors slightly so they read clearly on dark backgrounds
+	const darkPrimary = adjustLightness(brand.primary, 10);
+	const darkSecondary = adjustLightness(brand.secondary, 10);
+	const darkTertiary = adjustLightness(brand.tertiary, 10);
+
+	const primaryContainer = toContainerColor(brand.primary, true);
+	const secondaryContainer = toContainerColor(brand.secondary, true);
+	const tertiaryContainer = toContainerColor(brand.tertiary, true);
+
+	return {
+		primary: darkPrimary,
+		primaryContainer,
+		onPrimary: getContrastColor(darkPrimary),
+
+		secondary: darkSecondary,
+		secondaryContainer,
+		onSecondary: getContrastColor(darkSecondary),
+
+		tertiary: darkTertiary,
+		tertiaryContainer,
+		onTertiary: getContrastColor(darkTertiary),
+
+		background: '#121212',
+		surface: '#1E1E1E',
+		surfaceVariant: '#2D2D2D',
+
+		onBackground: '#E6E6E6',
+		onSurface: '#E6E6E6',
+
+		border: '#3A3A3A',
+
+		// Semantic — dark surfaces that keep light text readable
+		error: '#8C1D18',
+		success: '#1B5E20',
+		warning: '#8A4B00',
+		info: '#01579B',
+		disabled: '#4A4A4A',
+		shadow: '#000000',
+	};
+}

package/src/utils/colorMath.ts

@@ -0,0 +1,55 @@
+import tinycolor from 'tinycolor2';
+
+/** Returns the relative luminance of a color (0–1). */
+export function getLuminance(color: string): number {
+	return tinycolor(color).getLuminance();
+}
+
+/**
+ * Returns '#FFFFFF' or '#000000' — whichever has higher contrast
+ * against the given background color (WCAG AA).
+ */
+export function getContrastColor(background: string): '#FFFFFF' | '#000000' {
+	return tinycolor.isReadable('#FFFFFF', background, { level: 'AA', size: 'small' })
+		? '#FFFFFF'
+		: '#000000';
+}
+
+/**
+ * Adjusts lightness.
+ * Positive delta = lighten, negative delta = darken.
+ */
+export function adjustLightness(color: string, delta: number): string {
+	const tc = tinycolor(color);
+	return delta >= 0
+		? tc.lighten(delta).toHexString()
+		: tc.darken(Math.abs(delta)).toHexString();
+}
+
+/**
+ * Adjusts saturation.
+ * Positive delta = saturate, negative delta = desaturate.
+ */
+export function adjustSaturation(color: string, delta: number): string {
+	const tc = tinycolor(color);
+	return delta >= 0
+		? tc.saturate(delta).toHexString()
+		: tc.desaturate(Math.abs(delta)).toHexString();
+}
+
+/** Returns whether two colors meet WCAG AA contrast requirements. */
+export function isReadable(foreground: string, background: string): boolean {
+	return tinycolor.isReadable(foreground, background, { level: 'AA', size: 'small' });
+}
+
+/**
+ * Produces a container shade from a brand color.
+ * For dark themes: darkens + desaturates.
+ * For light themes: lightens + desaturates.
+ */
+export function toContainerColor(color: string, isDark: boolean): string {
+	const tc = tinycolor(color);
+	return isDark
+		? tc.darken(25).desaturate(10).toHexString()
+		: tc.lighten(35).desaturate(15).toHexString();
+}