@chipmobilesdk/rn-theme 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @chipmobilesdk/rn-theme
 
+## 1.2.0
+
+### Minor Changes
+
+- An override that names a group the theme does not have is refused with a `ThemeConfigError` instead of being dropped. `overrides.light.radii` or `colors` had no effect and said nothing, which is exactly what the documented contract promised it would not do. The list of groups is derived from the generated theme, so a token group added later cannot be left out of it. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  A colour override now reaches everything derived from it. `color` is merged before `shadow` and `tone.neutral` are built, so pinning `color.onSurface` or `color.shadow` changes the neutral tone and the shadows too — they used to keep the generated value while the text presets followed the override, leaving a theme that disagreed with itself. The accent tones and `categorical` still come from the tonal palettes, which the README and the migration table now say.
+
+  A custom tone may not take a standard tone's name (`neutral`, `primary`, `info`, `success`, `warning`, `error`), and an `extend` that returns a group the theme already has (`spacing`, say) is refused: both used to replace the real thing at runtime, unvalidated, taking the contrast guarantees with them.
+
+  `createUnistylesConfig(undefined)` reports a `ThemeConfigError` with a path rather than a `TypeError`. `color.disabled` is derived from `opacity.disabledContent` rather than a second copy of the figure, and the vendored colour utilities no longer export a function nothing uses.
+
+## 1.1.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+### Patch Changes
+
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 1.0.1
 
 ### Patch Changes
@@ -56,7 +131,7 @@ extension, and style presets. See `specs/014-rn-theme-v1/spec.md` in the source
 | `color.disabled` used as muted text | `color.onSurfaceVariant` or `text.bodyMuted` / `text.labelMuted` |
 | `color.disabled` for inactive UI | unchanged meaning; now `onSurface` at 38 % opacity, contrast-exempt |
 | `color.error`/`success`/`warning`/`info` as fills | `color.errorContainer` … with `onErrorContainer` …, or `tone.*.fill` / `onFill` |
-| `color.primary` equal to the brand hex | tone-mapped; override `color.primary` to pin a hex |
+| `color.primary` equal to the brand hex | tone-mapped; override `color.primary` to pin a hex (the accent tones and `categorical` stay on the palette) |
 | `shadow.md.shadowColor` … `elevation` | `shadow.md.boxShadow` |
 | App tokens spread into the theme + cast | `extend: ({ theme }) => ({ ... })` |
 | `overrides` adding unknown keys | rejected — use `extend` |

package/README.md

@@ -9,7 +9,6 @@ Native apps, configured for `react-native-unistyles` 3.
 
 - **Version**: see [CHANGELOG](CHANGELOG.md)
 - **Entrypoint**: `@chipmobilesdk/rn-theme`
-- **Demo**: `src/screens/ExampleScreen.tsx`
 
 ## Install
 
@@ -23,8 +22,9 @@ runtime dependency, no native code, and renders no components.
 ## Compatibility
 
 Validated in the ChipMobileSdk demo against React `19.2.3`, React Native `0.85.3`,
-React Native Unistyles `^3.2.5`, TypeScript `^5.8.3` and Node.js `>=22.11.0`, on Android and
-iOS. Shadows use React Native's cross-platform `boxShadow` (New Architecture).
+React Native Unistyles `^3.2.5`, TypeScript `^5.8.3` and Node.js `>=22.11.0`. **Android is
+device-validated; iOS is pending** (the package has no native code, and shadows use React
+Native's cross-platform `boxShadow` on the New Architecture).
 
 ## Setup Order
 
@@ -90,6 +90,7 @@ applyThemeMode('dark');   // fixed; survives later OS scheme changes
 
 `applyThemeMode` switches adaptive themes off before setting a manual theme — in the other
 order the next OS change overrides the user's choice. Persisting the preference is the app's.
+Unistyles is loaded the first time a mode is applied, never when the package is imported.
 
 ## Colour System
 
@@ -215,12 +216,24 @@ createUnistylesConfig({
 });
 ```
 
-Extensions may not reuse a base group name. Override keys must already exist — new tokens
-belong in `extend`.
+Extensions may not reuse a base group name, and a custom tone may not take a standard
+tone's name (`neutral`, `primary`, `info`, `success`, `warning`, `error`); both are
+refused with a `ThemeConfigError`. Override keys must already exist, at every level — a
+group the theme does not have, such as `radii` or `colors`, is refused rather than
+ignored. New tokens belong in `extend`.
+
+An override of `color.X` reaches everything derived from it: the text and surface presets,
+`shadow`, and `tone.neutral`, which is built from the neutral roles. The accent tones
+(`tone.primary` and the rest) and `categorical` come from the tonal palettes, so pinning
+`color.primary` to a hex does not change them — override `tone.primary` or the brand seed
+for that.
 
 ## Integrations
 
-- `buildThemes(config)` — the same themes without Unistyles, e.g. for tests or other libraries.
+- `buildThemes(config, options?)` — the same themes without Unistyles, e.g. for tests, other
+  libraries or a token export. It needs no React Native either: pass `platform` and
+  `hairlineWidth`, or they default to the running platform and
+  `StyleSheet.hairlineWidth` (1 where React Native is not loaded).
 - `toNavigationTheme(theme, scheme)` — a React Navigation theme (no navigation dependency).
 
 ## Public Runtime Exports
@@ -244,6 +257,10 @@ Only `@chipmobilesdk/rn-theme` is public. Deep imports (`.../src/...`) are unsup
 
 ## Configuration Validation
 
+Both errors extend `SdkError` from `@chipmobilesdk/rn-core` and carry a `code`
+(`ThemeErrorCode`): `invalid_config` for `ThemeConfigError`, `contrast` for
+`ThemeContrastError`.
+
 Invalid input throws `ThemeConfigError` whose `path` names the field, e.g.
 `overrides.dark.color.error`. Checked: brand and seed colours (opaque, supported format),
 tone colours, typography numbers and font maps, named themes, override keys (must exist),
@@ -288,12 +305,6 @@ See the mapping table in `CHANGELOG.md` (`## 1.0.0`). In short: rename `typograp
 augmentation (`UnistylesThemeFromBrand`) with the one in *Setup Order*; move app tokens from
 spreads and casts into `extend`.
 
-## Release Validation
-
-```bash
-npm run validate
-```
-
 ## Semver and Migration
 
 - Patch: internal fix with no public shape or behaviour change.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-theme",
-	"version": "1.0.1",
+	"version": "1.2.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -29,9 +29,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",

package/skills/sdk-rn-theme/SKILL.md

@@ -49,7 +49,8 @@ Unistyles 3. Single source of truth for visual tokens; app tokens join through `
 
 Runtime: `createUnistylesConfig`, `buildThemes`, `applyThemeMode`, `byTone`, `layout`,
 `presets`, `auditTheme`, `contrastRatio`, `withAlpha`, `toNavigationTheme`,
-`DEFAULT_BREAKPOINTS`, `ThemeConfigError`, `ThemeContrastError`.
+`DEFAULT_BREAKPOINTS`, `ThemeConfigError`, `ThemeContrastError` (both rn-core SDK errors with a
+`ThemeErrorCode`).
 
 Theme groups: `color`, `tone`, `typography`, `font`, `fontWeight`, `spacing`, `radius`,
 `borderWidth`, `size`, `opacity`, `motion`, `shadow`, `zIndex`, `maxFontScale`,

package/src/color/roles.ts

@@ -7,6 +7,7 @@ import type {
 	StandardToneName,
 	ToneColors,
 } from '../types/colors';
+import { DEFAULT_OPACITY } from '../tokens/defaults';
 import { argbFromColor, hexFromArgb, withAlpha } from './parse';
 
 /**
@@ -27,7 +28,8 @@ const MAX_NEUTRAL_SEED_CHROMA = 16;
 const NEUTRAL_VARIANT_EXTRA_CHROMA = 4;
 
 /** Material 3 opacities applied to `onSurface` and the scrim. */
-export const DISABLED_CONTENT_OPACITY = 0.38;
+/** The same figure as `opacity.disabledContent`, from its one definition (THM-07). */
+export const DISABLED_CONTENT_OPACITY = DEFAULT_OPACITY.disabledContent;
 const SCRIM_OPACITY = 0.32;
 
 /**

package/src/index.ts

@@ -2,6 +2,7 @@
 export { buildThemes } from './theme/buildThemes';
 export type { BuildThemesOptions } from './theme/buildThemes';
 export { ThemeConfigError, ThemeContrastError } from './theme/errors';
+export type { ThemeErrorCode } from './theme/errors';
 
 // ─── Unistyles ──────────────────────────────────────────────────────────────
 export { createUnistylesConfig } from './unistyles/createUnistylesConfig';

package/src/theme/buildThemes.ts

@@ -1,4 +1,6 @@
-import { Platform as ReactNativePlatform } from 'react-native';
+import { createDiagnosticChannel } from '@chipmobilesdk/rn-core';
+
+import { currentPlatform, lazyPeer } from '@chipmobilesdk/rn-core';
 import { buildCategorical } from '../color/categorical';
 import { auditTheme } from '../color/contrast';
 import { buildColorRoles, buildPalettes, buildTones } from '../color/roles';
@@ -25,32 +27,44 @@ import type {
 	Themes,
 } from '../types/theme';
 import type { FontToken, FontWeightName } from '../types/typography';
-import { describeFailures, ThemeContrastError } from './errors';
-import { mergeOverrides, pick } from './overrides';
+import { describeFailures, ThemeConfigError, ThemeContrastError } from './errors';
+import { isPlainObject, mergeOverrides, pick } from './overrides';
 import { validateThemeConfig } from './validateThemeConfig';
 
 export interface BuildThemesOptions {
 	/** Platform whose font resolution applies. Defaults to the running platform. */
 	platform?: Platform;
+	/**
+	 * `borderWidth.hairline`. Defaults to React Native's `StyleSheet.hairlineWidth`,
+	 * or 1 where React Native is not loaded, so `buildThemes` runs on Node (THM-04).
+	 */
+	hairlineWidth?: number;
+}
+
+/** Read only when no `hairlineWidth` is given, so building themes needs no React Native. */
+const reactNative = lazyPeer('react-native', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native') as { StyleSheet?: { hairlineWidth?: number } };
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+function deviceHairlineWidth(): number {
+	const result = reactNative.get();
+	return (result.ok ? result.module.StyleSheet?.hairlineWidth : undefined) ?? 1;
 }
 
-/** Groups that come straight from tokens (presets and tones are derived after). */
-const TOKEN_KEYS = [
-	'color',
-	'typography',
-	'font',
-	'fontWeight',
-	'spacing',
-	'radius',
-	'borderWidth',
-	'size',
-	'opacity',
-	'motion',
-	'shadow',
-	'zIndex',
-	'maxFontScale',
-	'categorical',
-] as const;
+/** The standard tone names an app's own tone may not take over (THM-03). */
+const STANDARD_TONES: ReadonlySet<string> = new Set([
+	'neutral',
+	'primary',
+	'info',
+	'success',
+	'warning',
+	'error',
+]);
 
 interface ThemeSource {
 	name: string;
@@ -70,23 +84,59 @@ function cloneFonts(font: Record<FontWeightName, FontToken>): Record<FontWeightN
 	return copy;
 }
 
+/**
+ * Every top-level group an override may name, and nothing else.
+ *
+ * An override naming a group that does not exist — `radii` for `radius`,
+ * `colors` for `color` — used to be dropped without a word, so the override
+ * simply had no effect (THM-01). The list is derived from what was generated
+ * rather than written out by hand, so a new token group cannot be forgotten
+ * (THM-06).
+ */
+function assertKnownOverrideGroups(
+	overrides: unknown,
+	known: Iterable<string>,
+	path: string,
+): void {
+	if (!isPlainObject(overrides)) {
+		return;
+	}
+	const allowed = new Set(known);
+	for (const key of Object.keys(overrides)) {
+		if (overrides[key] === undefined || allowed.has(key)) {
+			continue;
+		}
+		throw new ThemeConfigError(
+			`${path}.${key}`,
+			'does not exist on the theme. Add new tokens through `extend`.',
+		);
+	}
+}
+
 function buildOne(
 	source: ThemeSource,
 	fonts: ReturnType<typeof buildFonts>,
 	overrides: unknown,
+	hairlineWidth: number,
 ): object {
 	const { name, scheme, config, palettes } = source;
 	const path = `overrides.${name}`;
-	const color = buildColorRoles(palettes, scheme);
+	const generatedColor = buildColorRoles(palettes, scheme);
+
+	// Colour is merged first, because what follows is derived from it: an
+	// override of `color.shadow` or `color.onSurface` used to leave `shadow` and
+	// `tone.neutral` built from the generated value, so a theme that pinned a
+	// colour disagreed with itself (THM-02).
+	const color = mergeOverrides(generatedColor, pick(overrides, ['color'])?.color, `${path}.color`);
 
-	const generated = {
+	const tokenGroups = {
 		color,
 		typography: buildTypography(config.typography, fonts.font, fonts.family),
 		font: cloneFonts(fonts.font),
 		fontWeight: buildFontWeight(),
 		spacing: buildSpacing(),
 		radius: buildRadius(),
-		borderWidth: buildBorderWidth(),
+		borderWidth: buildBorderWidth(hairlineWidth),
 		size: buildSize(),
 		opacity: buildOpacity(),
 		motion: buildMotion(),
@@ -94,21 +144,41 @@ function buildOne(
 		zIndex: buildZIndex(),
 		maxFontScale: config.typography?.maxFontScale ?? DEFAULT_MAX_FONT_SCALE,
 		categorical: buildCategorical(config.brandColors.primary, scheme),
-	};
-	const tokens = mergeOverrides(generated, pick(overrides, TOKEN_KEYS), path);
+	} satisfies Omit<BaseTheme<string>, 'tone' | (typeof PRESET_KEYS)[number]>;
+
+	const tokenKeys = Object.keys(tokenGroups);
+	const tokens = mergeOverrides(tokenGroups, pick(overrides, tokenKeys), path);
 	const tone = mergeOverrides(
-		buildTones<string>(palettes, color, scheme),
+		// From the merged colour, so `tone.neutral` follows an override of
+		// `color.onSurface` as the text presets already did.
+		buildTones<string>(palettes, tokens.color, scheme),
 		pick(overrides, ['tone'])?.tone,
 		`${path}.tone`,
 	);
 	const presets = mergeOverrides(buildPresets(tokens), pick(overrides, PRESET_KEYS), path);
-	const base = { ...tokens, tone, ...presets } as BaseTheme<string>;
+	const base = { ...tokens, tone, ...presets } satisfies BaseTheme<string>;
 
 	if (!config.extend) {
+		assertKnownOverrideGroups(overrides, [...tokenKeys, 'tone', ...PRESET_KEYS], path);
 		return base;
 	}
 
 	const extension = config.extend({ name, scheme, theme: base });
+	for (const key of Object.keys(extension)) {
+		if (key in base) {
+			// `extend` returning `{ spacing: … }` replaced the whole spacing scale
+			// with whatever it held, unvalidated (THM-03).
+			throw new ThemeConfigError(
+				`extend.${key}`,
+				'is already a theme group. Give the extension token a name of its own.',
+			);
+		}
+	}
+	assertKnownOverrideGroups(
+		overrides,
+		[...tokenKeys, 'tone', ...PRESET_KEYS, ...Object.keys(extension)],
+		path,
+	);
 	const extensionOverrides = pick(overrides, Object.keys(extension));
 
 	return { ...base, ...mergeOverrides(extension, extensionOverrides, path) };
@@ -129,11 +199,15 @@ function checkContrast(name: string, theme: object, strict: boolean): void {
 		throw new ThemeContrastError(name, failures);
 	}
 
+	channel.emit('contrast', 'warn', { theme: name, failures: failures.length });
 	console.warn(
 		`[rn-theme] Theme "${name}" breaks contrast guarantees after overrides:\n${describeFailures(failures)}`,
 	);
 }
 
+/** Contrast warnings also reach the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel<'contrast'>('rn-theme');
+
 /**
  * Builds every theme from brand config — pure, with no Unistyles dependency
  * (spec AC-9.4). `createUnistylesConfig` wraps this; call it directly to feed
@@ -150,18 +224,31 @@ export function buildThemes<
 	validateThemeConfig(config);
 
 	const loose = config as unknown as ThemeConfig<object, string, string>;
-	const platform = options?.platform ?? (ReactNativePlatform.OS === 'ios' ? 'ios' : 'android');
+	// rn-core's one platform source (CORE-09); off-device, fonts resolve as on Android.
+	const platform = options?.platform ?? (currentPlatform() === 'ios' ? 'ios' : 'android');
+	const hairlineWidth = options?.hairlineWidth ?? deviceHairlineWidth();
 	const fonts = buildFonts(loose.typography, platform);
 	const basePalettes = buildPalettes(loose);
 	const sources: ThemeSource[] = [
 		{ name: 'light', scheme: 'light', config: loose, palettes: basePalettes },
 		{ name: 'dark', scheme: 'dark', config: loose, palettes: basePalettes },
 		...Object.entries(loose.themes ?? {}).map(([name, named]) => {
+			const tones = { ...loose.tones, ...named.tones } as Record<string, string>;
+			for (const tone of Object.keys(tones)) {
+				if (STANDARD_TONES.has(tone)) {
+					// A custom tone named `primary` silently replaced the standard
+					// one, contrast guarantees and all (THM-03).
+					throw new ThemeConfigError(
+						`themes.${name}.tones.${tone}`,
+						'is a standard tone. Override it through `overrides` instead.',
+					);
+				}
+			}
 			const namedConfig = {
 				...loose,
 				brandColors: named.brandColors ?? loose.brandColors,
 				seeds: { ...loose.seeds, ...named.seeds },
-				tones: { ...loose.tones, ...named.tones } as Record<string, string>,
+				tones,
 			};
 
 			return {
@@ -176,7 +263,7 @@ export function buildThemes<
 
 	for (const source of sources) {
 		const overrides = (loose.overrides as Record<string, unknown> | undefined)?.[source.name];
-		const theme = buildOne(source, fonts, overrides);
+		const theme = buildOne(source, fonts, overrides, hairlineWidth);
 
 		checkContrast(source.name, theme, loose.strict === true);
 		themes[source.name] = theme;

package/src/theme/errors.ts

@@ -1,23 +1,36 @@
+import { SdkError } from '@chipmobilesdk/rn-core';
+
 import type { ContrastFailure } from '../color/contrast';
 
-/** Invalid configuration or override; `path` names the offending field. */
-export class ThemeConfigError extends Error {
+/**
+ * The package's error codes (THM-09): `invalid_config` for a config or override
+ * the package rejects, `contrast` for a theme that breaks a contrast guarantee.
+ */
+export type ThemeErrorCode = 'invalid_config' | 'contrast';
+
+/**
+ * Invalid configuration or override; `path` names the offending field. An
+ * `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-theme'`.
+ */
+export class ThemeConfigError extends SdkError<ThemeErrorCode> {
 	readonly path: string;
 
 	constructor(path: string, message: string) {
-		super(`${path}: ${message}`);
+		super('rn-theme', 'invalid_config', { message: `${path}: ${message}` });
 		this.name = 'ThemeConfigError';
 		this.path = path;
 	}
 }
 
 /** Thrown in `strict` mode when a theme breaks a contrast guarantee. */
-export class ThemeContrastError extends Error {
+export class ThemeContrastError extends SdkError<ThemeErrorCode> {
 	readonly themeName: string;
 	readonly failures: ContrastFailure[];
 
 	constructor(themeName: string, failures: ContrastFailure[]) {
-		super(`Theme "${themeName}" breaks contrast guarantees:\n${describeFailures(failures)}`);
+		super('rn-theme', 'contrast', {
+			message: `Theme "${themeName}" breaks contrast guarantees:\n${describeFailures(failures)}`,
+		});
 		this.name = 'ThemeContrastError';
 		this.themeName = themeName;
 		this.failures = failures;

package/src/theme/validateThemeConfig.ts

@@ -36,6 +36,32 @@ function assertPositiveNumber(value: unknown, path: string): void {
 	}
 }
 
+/** The tones this package builds, which an app's own tone may not take over. */
+const STANDARD_TONE_NAMES: ReadonlySet<string> = new Set([
+	'neutral',
+	'primary',
+	'info',
+	'success',
+	'warning',
+	'error',
+]);
+
+function validateCustomTones(value: unknown, path: string): void {
+	if (value == null) {
+		return;
+	}
+	assertObject(value, path);
+	for (const name of Object.keys(value)) {
+		if (STANDARD_TONE_NAMES.has(name)) {
+			throw new ThemeConfigError(
+				`${path}.${name}`,
+				'is a standard tone; customise it through `overrides.<theme>.tone` instead.',
+			);
+		}
+	}
+	validateColorRecord(value, path);
+}
+
 function validateColorRecord(value: unknown, path: string, keys?: readonly string[]): void {
 	if (value == null) {
 		return;
@@ -134,7 +160,7 @@ function validateNamedThemes(value: unknown): void {
 		}
 
 		validateColorRecord(theme.seeds, `${path}.seeds`, SEED_KEYS);
-		validateColorRecord(theme.tones, `${path}.tones`);
+		validateCustomTones(theme.tones, `${path}.tones`);
 	}
 }
 
@@ -157,7 +183,7 @@ export function validateThemeConfig(config: unknown): void {
 	assertObject(config, 'config');
 	validateBrandColors(config.brandColors, 'brandColors');
 	validateColorRecord(config.seeds, 'seeds', SEED_KEYS);
-	validateColorRecord(config.tones, 'tones');
+	validateCustomTones(config.tones, 'tones');
 	validateTypography(config.typography);
 	validateNamedThemes(config.themes);
 

package/src/tokens/defaults.ts

@@ -1,4 +1,3 @@
-import { StyleSheet } from 'react-native';
 import { withAlpha } from '../color/parse';
 import type {
 	BorderWidthTokens,
@@ -35,23 +34,30 @@ export function buildRadius(): RadiusTokens {
 	return { none: 0, xs: 2, sm: 4, md: 8, lg: 16, xl: 24, full: 9999 };
 }
 
-export function buildBorderWidth(): BorderWidthTokens {
-	return { hairline: StyleSheet.hairlineWidth, thin: 1, thick: 2 };
+/** `hairline` is the device's thinnest line, resolved by `buildThemes` (THM-04). */
+export function buildBorderWidth(hairline: number): BorderWidthTokens {
+	return { hairline, thin: 1, thick: 2 };
 }
 
 export function buildSize(): SizeTokens {
 	return { touchTarget: 44, icon: { sm: 16, md: 20, lg: 24 } };
 }
 
+/**
+ * The opacity scale, as one definition. `color.disabled` is derived from
+ * `disabledContent` rather than from a second copy of 0.38 (THM-07).
+ */
+export const DEFAULT_OPACITY: OpacityTokens = {
+	hover: 0.08,
+	focus: 0.1,
+	pressed: 0.1,
+	dragged: 0.16,
+	disabledContent: 0.38,
+	disabledContainer: 0.12,
+};
+
 export function buildOpacity(): OpacityTokens {
-	return {
-		hover: 0.08,
-		focus: 0.1,
-		pressed: 0.1,
-		dragged: 0.16,
-		disabledContent: 0.38,
-		disabledContainer: 0.12,
-	};
+	return { ...DEFAULT_OPACITY };
 }
 
 export function buildMotion(): MotionTokens {

package/src/unistyles/createUnistylesConfig.ts

@@ -1,7 +1,7 @@
 import { buildThemes, type BuildThemesOptions } from '../theme/buildThemes';
 import { ThemeConfigError } from '../theme/errors';
 import { isPlainObject } from '../theme/overrides';
-import { themeNamesOf } from '../theme/validateThemeConfig';
+import { themeNamesOf, validateThemeConfig } from '../theme/validateThemeConfig';
 import { DEFAULT_BREAKPOINTS } from '../tokens/defaults';
 import type { EmptyExtension, ThemeConfig, ThemeName, Themes } from '../types/theme';
 
@@ -159,6 +159,9 @@ export function createUnistylesConfig<
 	config: ThemeConfig<TExt, TTone, TName>,
 	options?: UnistylesConfigOptions<NoInfer<TName>, TBreakpoints>,
 ): UnistylesConfig<TExt, TTone, TName, TBreakpoints> {
+	// The config first: reading `config.themes` for the theme names threw a
+	// TypeError with no path when the config itself was not an object (THM-10).
+	validateThemeConfig(config);
 	validateOptions(options, themeNamesOf(config));
 
 	return {

package/src/unistyles/themeMode.ts

@@ -1,4 +1,6 @@
-import { UnistylesRuntime } from 'react-native-unistyles';
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import { ThemeConfigError } from '../theme/errors';
 
 export type ThemeMode = 'system' | 'light' | 'dark';
 
@@ -8,16 +10,37 @@ export interface ThemeModeRuntime {
 	setTheme(name: string): void;
 }
 
-// The package cannot see the app's augmented `UnistylesThemes`, so `setTheme`
-// is typed as `never` here; the runtime accepts any configured theme name.
-const defaultRuntime = UnistylesRuntime as unknown as ThemeModeRuntime;
+// Loaded when a mode is first applied, so importing the package (and building
+// themes) never loads Unistyles (THM-04). The package cannot see the app's
+// augmented `UnistylesThemes`, so the runtime is typed by the two calls it needs.
+const unistyles = lazyPeer('react-native-unistyles', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-unistyles') as { UnistylesRuntime: ThemeModeRuntime };
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+function defaultRuntime(): ThemeModeRuntime {
+	return unistyles.require(
+		peer =>
+			new ThemeConfigError(
+				'applyThemeMode',
+				`${peer} is not installed; pass a runtime or install it`,
+			),
+	).UnistylesRuntime;
+}
 
 /**
  * Applies a light/dark/system preference. Adaptive themes are switched off
  * before a manual theme is set; in the other order the next OS colour-scheme
  * change overrides the user's choice. Persisting the preference is the app's.
  */
-export function applyThemeMode(mode: ThemeMode, runtime: ThemeModeRuntime = defaultRuntime): void {
+export function applyThemeMode(
+	mode: ThemeMode,
+	runtime: ThemeModeRuntime = defaultRuntime(),
+): void {
 	if (mode === 'system') {
 		runtime.setAdaptiveThemes(true);
 		return;

package/src/vendor/mcu/index.ts

@@ -2,4 +2,4 @@
 // imports from here only, so the vendored surface stays explicit.
 export { Hct } from './hct/hct';
 export { TonalPalette } from './palettes/tonal_palette';
-export { argbFromRgb, lstarFromArgb } from './utils/color_utils';
+export { argbFromRgb } from './utils/color_utils';