@chipmobilesdk/rn-theme 0.2.1 → 1.0.0

package/package.json

@@ -1,50 +1,49 @@
-{
-	"name": "@chipmobilesdk/rn-theme",
-	"version": "0.2.1",
-	"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",
-		"skills",
-		"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/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-theme",
+	"version": "1.0.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/color",
+		"src/integration",
+		"src/presets",
+		"src/theme",
+		"src/tokens",
+		"src/types",
+		"src/unistyles",
+		"src/vendor",
+		"skills",
+		"README.md",
+		"CHANGELOG.md",
+		"NOTICE"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"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/skills/sdk-rn-theme/SKILL.md

@@ -1,59 +1,74 @@
 ---
 name: sdk-rn-theme
-description: "Theming for @chipmobilesdk/rn-theme: brand palettes, Unistyles config, color/typography tokens, dark mode. Use when setting up theming, adding a design token, wiring light/dark, or debugging theme setup order."
+description: "Theming for @chipmobilesdk/rn-theme: accessible brand palettes, Unistyles config, colour/typography/spacing tokens, tones and byTone variants, layout and text presets, app token extension, dark mode and theme mode. Use when setting up theming, writing or shortening a stylesheet, adding a design token, wiring light/dark, or debugging Unistyles setup, stale styles or type errors."
 metadata:
   package: "@chipmobilesdk/rn-theme"
-  packageVersion: "0.2.0"
+  packageVersion: "1.0.0"
 user-invocable: true
 disable-model-invocation: false
 ---
 
 # @chipmobilesdk/rn-theme
 
-Generates light and dark palettes from brand colors and produces a Unistyles config.
-This is the single source of truth for color, typography, spacing and radius tokens.
+Builds light/dark (and named) themes from three brand colours with guaranteed WCAG contrast,
+a full token set, and style presets, and produces the `StyleSheet.configure` object for
+Unistyles 3. Single source of truth for visual tokens; app tokens join through `extend`.
 
 ## Use this when
 
-- Bootstrapping theming in a new app
-- Adding or renaming a design token
-- Wiring light/dark mode or a theme start strategy
-- A screen renders unstyled, or `useStyles` returns an unexpected theme
+- Bootstrapping theming, or adding an app-specific token, tone or theme
+- Writing a stylesheet — check presets before hand-writing flex, text, border or box styles
+- Wiring light/dark, a user theme preference, or a React Navigation theme
+- A style does not update on theme/variant change, or a screen renders unstyled
+- Style arrays, variants or dynamic functions produce TypeScript errors
 
 ## Do not use this for
 
-- Chart-specific theming — that is `sdk-rn-chart` (`ChartThemeProvider`)
-- Per-component one-off styles that do not belong in the token set
+- Chart rendering — that is `sdk-rn-chart` (feed it `theme.categorical`)
+- UI components — this package ships none
 
-## Setup order matters
+## Rules that prevent real bugs
 
-Unistyles must be configured **before** the first component that consumes a style
-renders. Getting this wrong produces an app that renders with no styling and no error.
-Read the `## Setup Order` and `## Theme Start Strategy` sections of the README before
-changing entry-point wiring.
+- **Never cast or alias the theme inside `StyleSheet.create`** (`const theme = appTheme(raw)`):
+  the Unistyles Babel plugin then records no dependencies and the styles stop updating on
+  theme change. Declare app tokens with `extend` so `theme` is already typed.
+- **Variants**: keep a literal `variants` key and call `byTone(theme, …)` inline under it.
+  Use one tone-colour style combined by array (`[styles.title, styles.toneText]`) instead of
+  repeating variants per text style.
+- **Muted text is `onSurfaceVariant`** (or `text.*Muted`), never `disabled` — `disabled` is
+  a contrast-exempt state colour. Dividers use `outlineVariant`; interactive boundaries
+  `outline`. There is no `color.border`.
+- **Weights**: spread `theme.font.bold` etc.; a literal `fontWeight` breaks custom fonts on
+  Android.
+- Pass the config inline (or `satisfies ThemeConfig`); a `ThemeConfig` annotation erases
+  extension and theme-name types.
+- Configure Unistyles **before** the first themed component renders; the app (not the
+  package) augments `UnistylesThemes` / `UnistylesBreakpoints` from `typeof config`.
+- Merge Unistyles styles with arrays, never object spread of Unistyles entries.
 
-## Public API (v0.2.0)
+## Public API (v1.0.0)
 
-Runtime:
+Runtime: `createUnistylesConfig`, `buildThemes`, `applyThemeMode`, `byTone`, `layout`,
+`presets`, `auditTheme`, `contrastRatio`, `withAlpha`, `toNavigationTheme`,
+`DEFAULT_BREAKPOINTS`, `ThemeConfigError`, `ThemeContrastError`.
 
-- `generateLightPalette(brand)` / `generateDarkPalette(brand)` — derive full palettes
-- `createUnistylesConfig(...)` — build the Unistyles configuration object
+Theme groups: `color`, `tone`, `typography`, `font`, `fontWeight`, `spacing`, `radius`,
+`borderWidth`, `size`, `opacity`, `motion`, `shadow`, `zIndex`, `maxFontScale`,
+`categorical`, presets `text`, `stack`, `inline`, `border`, `box`, plus `extend` groups.
 
-Types: `BrandColors`, `ThemeColors`, `TypographyConfig`, `TypographyToken`, `Typography`,
-`StyleConfig`, `StyleTheme`, `DeepPartial`, `UnistylesThemeFromBrand`
-
-Anything not exported from `src/index.ts` is private and may change without a major bump —
-see `## Private Modules` and `## Semver and Migration` in the README.
+Anything not exported from the package root is private.
 
 ## Where the detail lives
 
-Read only the section you need from
-`node_modules/@chipmobilesdk/rn-theme/README.md`:
+Read only the section you need from `node_modules/@chipmobilesdk/rn-theme/README.md`:
 
 | Need | Section |
 |---|---|
-| Entry-point wiring | `## Setup Order`, `## Theme Start Strategy` |
-| Full export list | `## Public Runtime Exports`, `## Public Type Exports` |
+| Entry-point wiring, augmentation | `## Setup Order`, `## Theme Start Strategy` |
+| Which colour role to use; contrast guarantees | `## Colour System` |
+| Token names and values; custom fonts; font scale | `## Tokens` |
+| Shortening a stylesheet; plugin rules | `## Style Presets` |
+| App tokens, custom tones, named themes | `## Extending the Theme` |
 | Config rejected at runtime | `## Configuration Validation` |
-| Peer dependency rules | `## Compatibility`, `## Dependency Classification` |
-| Upgrading across versions | `## Semver and Migration` |
+| Style arrays, variants, dynamic-style type errors | `## Unistyles 3 Style Authoring and TypeScript Diagnostics` |
+| Upgrading from 0.2.x | `## Migrating from 0.2.x`, then `CHANGELOG.md` `## 1.0.0` |

package/src/color/categorical.ts

@@ -0,0 +1,33 @@
+import { Hct } from '../vendor/mcu';
+import type { ColorScheme } from '../types/colors';
+import { argbFromColor, hexFromArgb } from './parse';
+
+const SERIES_COUNT = 8;
+const SERIES_CHROMA = 48;
+/** 3 × 45°: consecutive series land far apart on the hue wheel. */
+const HUE_STEP = 135;
+
+/**
+ * Alternating tones. Every tone clears 3:1 against `surface` (98 / 6), and the
+ * 15-unit L* step keeps neighbours apart even when colour vision cannot
+ * separate their hues.
+ */
+const SERIES_TONES: Record<ColorScheme, [number, number]> = {
+	light: [40, 55],
+	dark: [80, 60],
+};
+
+/**
+ * Categorical series colours for charts, starting at the primary hue
+ * (spec US-11). Status colours stay free for status.
+ */
+export function buildCategorical(primary: string, scheme: ColorScheme): string[] {
+	const startHue = Hct.fromInt(argbFromColor(primary)).hue;
+	const tones = SERIES_TONES[scheme];
+
+	return Array.from({ length: SERIES_COUNT }, (_, index) =>
+		hexFromArgb(
+			Hct.from((startHue + index * HUE_STEP) % 360, SERIES_CHROMA, tones[index % 2]).toInt(),
+		),
+	);
+}

package/src/color/contrast.ts

@@ -0,0 +1,230 @@
+import { parseColor, type Rgba } from './parse';
+
+/** WCAG 2.x minimum ratio for text (1.4.3). */
+export const TEXT_CONTRAST = 4.5;
+/** WCAG 2.x minimum ratio for non-text boundaries (1.4.11). */
+export const NON_TEXT_CONTRAST = 3;
+
+const WHITE: Rgba = { r: 255, g: 255, b: 255, a: 1 };
+const LUMINANCE_OFFSET = 0.05;
+
+export interface ContrastFailure {
+	/** Theme path of the foreground value, e.g. `color.onPrimary`. */
+	foreground: string;
+	/** Theme path of the background value, e.g. `color.primary`. */
+	background: string;
+	ratio: number;
+	target: number;
+}
+
+interface ContrastPair {
+	foreground: string;
+	background: string;
+	target: number;
+}
+
+const ACCENT_ROLES = [
+	'primary',
+	'secondary',
+	'tertiary',
+	'error',
+	'success',
+	'warning',
+	'info',
+] as const;
+const SEMANTIC_ROLES = ['error', 'success', 'warning', 'info'] as const;
+const BASE_BACKGROUNDS = ['color.background', 'color.surface'] as const;
+const SURFACE_TIERS = [
+	'surfaceContainerLowest',
+	'surfaceContainerLow',
+	'surfaceContainer',
+	'surfaceContainerHigh',
+	'surfaceContainerHighest',
+] as const;
+
+function capitalize(value: string): string {
+	return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+function onBase(foreground: string, target = TEXT_CONTRAST): ContrastPair[] {
+	return BASE_BACKGROUNDS.map(background => ({ foreground, background, target }));
+}
+
+/**
+ * Every pair the package guarantees, expressed as theme paths. Paths missing
+ * from a theme (e.g. presets an older theme does not have) are skipped.
+ */
+function guaranteedPairs(theme: object): ContrastPair[] {
+	const pairs: ContrastPair[] = [];
+
+	for (const role of SEMANTIC_ROLES) {
+		pairs.push(...onBase(`color.${role}`));
+	}
+
+	for (const role of ACCENT_ROLES) {
+		const on = `on${capitalize(role)}`;
+		pairs.push(
+			{ foreground: `color.${on}`, background: `color.${role}`, target: TEXT_CONTRAST },
+			{
+				foreground: `color.${on}Container`,
+				background: `color.${role}Container`,
+				target: TEXT_CONTRAST,
+			},
+		);
+	}
+
+	pairs.push(
+		{ foreground: 'color.onBackground', background: 'color.background', target: TEXT_CONTRAST },
+		{ foreground: 'color.onSurface', background: 'color.surface', target: TEXT_CONTRAST },
+		{
+			foreground: 'color.onSurfaceVariant',
+			background: 'color.surfaceVariant',
+			target: TEXT_CONTRAST,
+		},
+		...onBase('color.onSurfaceVariant'),
+		{
+			foreground: 'color.inverseOnSurface',
+			background: 'color.inverseSurface',
+			target: TEXT_CONTRAST,
+		},
+		{
+			foreground: 'color.inversePrimary',
+			background: 'color.inverseSurface',
+			target: TEXT_CONTRAST,
+		},
+		...SURFACE_TIERS.map(tier => ({
+			foreground: 'color.onSurface',
+			background: `color.${tier}`,
+			target: TEXT_CONTRAST,
+		})),
+		...onBase('color.outline', NON_TEXT_CONTRAST),
+	);
+
+	const tones = readPath(theme, 'tone');
+
+	if (isRecord(tones)) {
+		for (const name of Object.keys(tones)) {
+			const tone = `tone.${name}`;
+			pairs.push(
+				...onBase(`${tone}.fg`),
+				{ foreground: `${tone}.onContainer`, background: `${tone}.container`, target: TEXT_CONTRAST },
+				{ foreground: `${tone}.onFill`, background: `${tone}.fill`, target: TEXT_CONTRAST },
+				{ foreground: `${tone}.border`, background: 'color.background', target: NON_TEXT_CONTRAST },
+			);
+		}
+	}
+
+	const text = readPath(theme, 'text');
+
+	if (isRecord(text)) {
+		for (const name of Object.keys(text)) {
+			// `text.disabled` deliberately uses the contrast-exempt disabled colour.
+			if (name !== 'disabled') {
+				pairs.push(...onBase(`text.${name}.color`));
+			}
+		}
+	}
+
+	const categorical = readPath(theme, 'categorical');
+
+	if (Array.isArray(categorical)) {
+		categorical.forEach((_, index) => {
+			pairs.push({
+				foreground: `categorical.${index}`,
+				background: 'color.surface',
+				target: NON_TEXT_CONTRAST,
+			});
+		});
+	}
+
+	return pairs;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readPath(source: unknown, path: string): unknown {
+	return path.split('.').reduce<unknown>((node, key) => {
+		if (Array.isArray(node)) {
+			return node[Number(key)];
+		}
+
+		return isRecord(node) ? node[key] : undefined;
+	}, source);
+}
+
+function channelLuminance(channel: number): number {
+	const value = channel / 255;
+
+	return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+
+function relativeLuminance({ r, g, b }: Rgba): number {
+	return (
+		0.2126 * channelLuminance(r) +
+		0.7152 * channelLuminance(g) +
+		0.0722 * channelLuminance(b)
+	);
+}
+
+function composite(top: Rgba, bottom: Rgba): Rgba {
+	const mix = (upper: number, lower: number) => upper * top.a + lower * (1 - top.a);
+
+	return { r: mix(top.r, bottom.r), g: mix(top.g, bottom.g), b: mix(top.b, bottom.b), a: 1 };
+}
+
+/**
+ * WCAG contrast ratio of two colour strings. Translucent colours are
+ * composited first: the background over `base` (default white), then the
+ * foreground over the result.
+ */
+export function contrastRatio(foreground: string, background: string, base?: string): number {
+	const fg = parseColor(foreground);
+	const bg = parseColor(background);
+	const baseColor = (base != null ? parseColor(base) : null) ?? WHITE;
+
+	if (!fg || !bg) {
+		throw new Error(`contrastRatio: unsupported colour "${!fg ? foreground : background}".`);
+	}
+
+	const opaqueBackground = composite(bg, composite(baseColor, WHITE));
+	const opaqueForeground = composite(fg, opaqueBackground);
+	const lighter = Math.max(relativeLuminance(opaqueForeground), relativeLuminance(opaqueBackground));
+	const darker = Math.min(relativeLuminance(opaqueForeground), relativeLuminance(opaqueBackground));
+
+	return (lighter + LUMINANCE_OFFSET) / (darker + LUMINANCE_OFFSET);
+}
+
+/**
+ * Checks every contrast pair the package guarantees against the given theme
+ * and returns the ones below target. An empty list means the theme passes.
+ * `color.disabled` is never audited: inactive components are exempt from
+ * WCAG 1.4.3.
+ */
+export function auditTheme(theme: object): ContrastFailure[] {
+	const base = readPath(theme, 'color.background');
+	const failures: ContrastFailure[] = [];
+
+	for (const pair of guaranteedPairs(theme)) {
+		const foreground = readPath(theme, pair.foreground);
+		const background = readPath(theme, pair.background);
+
+		if (typeof foreground !== 'string' || typeof background !== 'string') {
+			continue;
+		}
+
+		const ratio = contrastRatio(
+			foreground,
+			background,
+			typeof base === 'string' ? base : undefined,
+		);
+
+		if (ratio < pair.target) {
+			// Floored so a reported ratio never reads as passing (4.499 → 4.49).
+			failures.push({ ...pair, ratio: Math.floor(ratio * 100) / 100 });
+		}
+	}
+
+	return failures;
+}

package/src/color/parse.ts

@@ -0,0 +1,120 @@
+import { argbFromRgb } from '../vendor/mcu';
+
+/** A colour channel set: red/green/blue 0–255, alpha 0–1. */
+export interface Rgba {
+	r: number;
+	g: number;
+	b: number;
+	a: number;
+}
+
+const HEX_PATTERN = /^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB_PATTERN =
+	/^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*(\d*\.?\d+)\s*)?\)$/i;
+const CHANNEL_MAX = 255;
+
+/**
+ * Parses the colour formats the package accepts: `#RGB`, `#RGBA`, `#RRGGBB`,
+ * `#RRGGBBAA`, `rgb(r, g, b)` and `rgba(r, g, b, a)`. Returns `null` for
+ * anything else, including named colours and `hsl()`.
+ */
+export function parseColor(value: unknown): Rgba | null {
+	if (typeof value !== 'string') {
+		return null;
+	}
+
+	const color = value.trim();
+	const hex = HEX_PATTERN.exec(color);
+
+	if (hex) {
+		return parseHex(hex[1]);
+	}
+
+	const rgb = RGB_PATTERN.exec(color);
+
+	if (!rgb) {
+		return null;
+	}
+
+	const [r, g, b] = [rgb[1], rgb[2], rgb[3]].map(Number);
+	const a = rgb[4] == null ? 1 : Number(rgb[4]);
+
+	if ([r, g, b].some(channel => channel > CHANNEL_MAX) || a > 1) {
+		return null;
+	}
+
+	return { r, g, b, a };
+}
+
+function parseHex(digits: string): Rgba {
+	const full =
+		digits.length <= 4
+			? digits
+				.split('')
+				.map(digit => digit + digit)
+				.join('')
+			: digits;
+	const channel = (index: number) =>
+		parseInt(full.slice(index * 2, index * 2 + 2), 16);
+
+	return {
+		r: channel(0),
+		g: channel(1),
+		b: channel(2),
+		a: full.length === 8 ? channel(3) / CHANNEL_MAX : 1,
+	};
+}
+
+export function isValidColor(value: unknown): value is string {
+	return parseColor(value) !== null;
+}
+
+export function isOpaqueColor(value: unknown): value is string {
+	return parseColor(value)?.a === 1;
+}
+
+/** ARGB integer of an opaque colour string; throws for anything else. */
+export function argbFromColor(value: string): number {
+	const rgba = parseColor(value);
+
+	if (!rgba || rgba.a !== 1) {
+		throw new Error(`Expected an opaque colour, received "${value}".`);
+	}
+
+	return argbFromRgb(rgba.r, rgba.g, rgba.b);
+}
+
+function toHexPair(channel: number): string {
+	return Math.round(channel).toString(16).padStart(2, '0').toUpperCase();
+}
+
+export function hexFromArgb(argb: number): string {
+	// eslint-disable-next-line no-bitwise -- unpacking the ARGB integer's channels
+	const [r, g, b] = [(argb >> 16) & 0xff, (argb >> 8) & 0xff, argb & 0xff];
+
+	return `#${toHexPair(r)}${toHexPair(g)}${toHexPair(b)}`;
+}
+
+export function formatColor({ r, g, b, a }: Rgba): string {
+	const rgb = `#${toHexPair(r)}${toHexPair(g)}${toHexPair(b)}`;
+
+	return a >= 1 ? rgb : `${rgb}${toHexPair(a * CHANNEL_MAX)}`;
+}
+
+/**
+ * Applies an opacity to a colour, multiplying any alpha it already has.
+ * Returns `#RRGGBBAA` (or `#RRGGBB` when the result is opaque).
+ */
+export function withAlpha(color: string, alpha: number): string {
+	const rgba = parseColor(color);
+
+	if (!rgba) {
+		throw new Error(`withAlpha: "${color}" is not a supported colour.`);
+	}
+
+	if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) {
+		throw new Error(`withAlpha: alpha must be between 0 and 1, received ${alpha}.`);
+	}
+
+	return formatColor({ ...rgba, a: rgba.a * alpha });
+}