@chipmobilesdk/rn-theme 0.2.1 → 1.0.0

package/CHANGELOG.md

@@ -1,24 +1,92 @@
-# 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.
+# Changelog
+
+## 1.0.0 - 2026-10-17
+
+Major release: accessible colour roles for any brand, a complete token set, type-safe
+extension, and style presets. See `specs/014-rn-theme-v1/spec.md` in the source repository.
+
+### Added
+
+- HCT tonal colour engine (vendored material-color-utilities v0.4.0, Apache-2.0): every role
+  is a fixed tone, so documented contrast pairs hold for any brand input.
+- Full Material 3 role set: `onXContainer`, `onSurfaceVariant`, surface tiers, `inverse*`,
+  `outline`, `outlineVariant`, `scrim`, semantic container roles.
+- `seeds` (neutral and semantic hues), custom `tones`, `tone.*` bundles and `byTone`.
+- `extend` for app tokens, `themes` for extra named themes, validated `overrides`, `strict`.
+- `buildThemes`, `auditTheme`, `contrastRatio`, `withAlpha`, `applyThemeMode`,
+  `toNavigationTheme`, `ThemeConfigError`, `ThemeContrastError`, `DEFAULT_BREAKPOINTS`.
+- Tokens: typography Small/Large sizes, `font`/`fontWeight` with per-platform font files,
+  spacing `none`/`xxs`/`smPlus`/`mdPlus`/`xlPlus`/`xxxl`, radius `none`/`xs`, `borderWidth`,
+  `size`, `opacity`, `motion`, `maxFontScale`, `categorical`; default breakpoints.
+- Presets: static `layout` and `presets`; theme `text`, `stack`, `inline`, `border`, `box`.
+
+### Changed
+
+- Brand colours keep hue and chroma but take fixed role tones; the supplied hex is no
+  longer used as-is. Neutral surfaces carry a faint primary tint.
+- `error`/`success`/`warning`/`info` are now readable as text (≥ 4.5:1) in both themes.
+- Shadows are `boxShadow` strings (cross-platform) instead of iOS props + `elevation`.
+- The package no longer augments `react-native-unistyles`; the app augments once from
+  `typeof config.themes`.
+- `createUnistylesConfig` returns `breakpoints` and never invokes an `initialTheme` resolver.
+
+### Removed
+
+- `generateLightPalette`, `generateDarkPalette`, `UnistylesThemeFromBrand`, `ThemeColors`,
+  `StyleTheme`, `StyleConfig`, the `tinycolor2` dependency, named and `hsl()` colour inputs.
+
+### Migration (0.2.x → 1.0.0)
+
+| 0.2.x | 1.0.0 |
+|---|---|
+| `createUnistylesConfig({ brandColors, typographyConfig })` | `createUnistylesConfig({ brandColors, typography })` |
+| `StyleConfig` / `StyleTheme` / `ThemeColors` | `ThemeConfig` / `Theme` / `ColorRoles` |
+| `UnistylesThemeFromBrand` in `declare module` | `interface UnistylesThemes extends AppThemes {}` with `type AppThemes = typeof config.themes` |
+| `generateLightPalette(brand)` / `generateDarkPalette(brand)` | `buildThemes({ brandColors }).light.color` / `.dark.color` |
+| `color.border` | `color.outline` (interactive boundaries, ≥ 3:1) or `color.outlineVariant` (dividers) |
+| `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 |
+| `shadow.md.shadowColor` … `elevation` | `shadow.md.boxShadow` |
+| App tokens spread into the theme + cast | `extend: ({ theme }) => ({ ... })` |
+| `overrides` adding unknown keys | rejected — use `extend` |
+| Colour strings like `teal`, `hsl(...)` | `#RRGGBB`, `#RRGGBBAA`, `rgb()`, `rgba()` |
+| Typography roles | unchanged sizes (medium); `<role>Small` / `<role>Large` added |
+| Spacing / radius keys | unchanged values; new keys added |
+
+## 0.2.2 - 2026-08-02
+
+### Changed
+
+- README and agent skill: Unistyles 3 style authoring and TypeScript diagnostics guidance.
+  No runtime change.
+
+## 0.2.1 - 2026-08-01
+
+### Changed
+
+- The agent skill (`skills/`) ships in the package. No runtime change.
+
+## 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.
+
+### 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/NOTICE

@@ -0,0 +1,9 @@
+@chipmobilesdk/rn-theme
+Copyright ChipMobileSdk.
+
+This package includes software from material-color-utilities
+(https://github.com/material-foundation/material-color-utilities), v0.4.0,
+commit dd62982dfdefdfc9232ce8d76e122fb1c6d188ae, Copyright 2021-2023 Google LLC,
+licensed under the Apache License, Version 2.0. The vendored files live in
+src/vendor/mcu/ together with a copy of that license (src/vendor/mcu/LICENSE);
+each file states the modification made to it.

package/README.md

@@ -1,159 +1,302 @@
-# @chipmobilesdk/rn-theme
-
-Reusable React Native theme generation and token contracts for ChipMobileSdk-family mobile apps.
+# @chipmobilesdk/rn-theme
+
+Accessible theme generation, design tokens and style presets for ChipMobileSdk-family React
+Native apps, configured for `react-native-unistyles` 3.
 
 > **License:** `UNLICENSED`. Published publicly for use by the owner's
-> applications; no open-source license is granted.
+> applications; no open-source license is granted. Includes Apache-2.0 code from
+> material-color-utilities — see `NOTICE`.
 
-- **Version**: `0.2.0`
+- **Version**: `1.0.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.
+
+## Install
+
+```bash
+npm install @chipmobilesdk/rn-theme react-native-unistyles
+```
+
+The host app owns `react`, `react-native` and `react-native-unistyles`. The package has no
+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).
+
+## Setup Order
+
+App-owned brand values (`src/theme/brand.ts`):
+
+```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' };
+```
+
+Configure Unistyles before any themed component renders, and teach Unistyles the theme
+shape **once**, from the config itself:
+
+```ts
+import { StyleSheet } from 'react-native-unistyles';
+import { createUnistylesConfig } from '@chipmobilesdk/rn-theme';
+import { BRAND_COLORS, BRAND_TYPOGRAPHY } from './brand';
+
+const unistylesConfig = createUnistylesConfig(
+  { brandColors: BRAND_COLORS, typography: BRAND_TYPOGRAPHY },
+  { initialTheme: 'light' },
+);
+
+type AppThemes = typeof unistylesConfig.themes;
+type AppBreakpoints = typeof unistylesConfig.breakpoints;
+
+declare module 'react-native-unistyles' {
+  export interface UnistylesThemes extends AppThemes {}
+  export interface UnistylesBreakpoints extends AppBreakpoints {}
+}
+
+StyleSheet.configure(unistylesConfig);
+```
+
+Import that module first in the app entrypoint. Pass the config **inline** (or with
+`satisfies ThemeConfig`): annotating a variable as `ThemeConfig` erases the extension, tone
+and theme-name types the config would otherwise carry.
+
+The package does not augment `react-native-unistyles` itself — your augmentation is the
+only one, so an extended theme shape never conflicts.
+
+## Theme Start Strategy
+
+Choose one: `{ initialTheme: 'light' | 'dark' | <named theme> }` or
+`{ adaptiveThemes: true }`. Both together are rejected. A resolver function for
+`initialTheme` is passed to Unistyles untouched — the package never calls it.
+
+To apply a stored preference at runtime:
+
+```ts
+import { applyThemeMode } from '@chipmobilesdk/rn-theme';
+
+applyThemeMode('system'); // follow the OS
+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.
+
+## Colour System
+
+Every role is a fixed tone of an HCT tonal palette built from a brand or seed colour, so
+contrast depends only on tone and holds for **any** brand:
+
+| Guarantee | Pairs |
+|---|---|
+| ≥ 4.5:1 (text) | `error`/`success`/`warning`/`info` and `onSurfaceVariant` on `background` and `surface`; every `onX` on `X`; `onXContainer` on `XContainer`; `onSurface` on each surface tier; tone `fg`, `onContainer`, `onFill`; every text preset except `text.disabled` |
+| ≥ 3:1 (non-text) | `outline` on `background`/`surface`; tone `border` on `background`; each `categorical` colour on `surface` |
+
+- Brand colours keep their hue and chroma but always take the role tone (light 40 / dark 80;
+  containers 90 / 30). The supplied hex is not used as-is — override a role if a screen
+  needs the exact brand hex, and the contrast check below still applies.
+- Neutrals carry a faint tint of the primary hue unless `seeds.neutral` is given. Semantic
+  hues come from `seeds.error|success|warning|info` (defaults: the 0.2.x light values).
+- `disabled` is a **state** colour, exempt from contrast (WCAG 1.4.3). Muted readable text
+  is `onSurfaceVariant` or the `text.*Muted` presets.
+- `outline` bounds interactive components; `outlineVariant` is for dividers.
+- `auditTheme(theme)` lists every guaranteed pair below target. After overrides,
+  `buildThemes` warns in development; `strict: true` throws `ThemeContrastError` instead.
+
+Accepted colours: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`, `rgb()`, `rgba()`. Brand and seed
+colours must be opaque. `withAlpha(color, opacity)` applies an opacity token.
+
+## Tokens
+
+| Group | Contents |
+|---|---|
+| `color` | Material 3 roles (above) plus `scrim`, `shadow`, `disabled` |
+| `tone` | `neutral`, `primary`, `info`, `success`, `warning`, `error` and custom tones — each `{ fg, container, onContainer, border, fill, onFill }` |
+| `typography` | `display`, `headline`, `title`, `body`, `label`, `caption` (medium) plus `<role>Small` / `<role>Large` |
+| `font`, `fontWeight` | `regular`, `medium`, `semibold`, `bold`, `heavy` — `font.X` is `{ fontFamily, fontWeight }` resolved for the platform |
+| `spacing` | `none` 0, `xxs` 2, `xs` 4, `sm` 8, `smPlus` 12, `md` 16, `mdPlus` 20, `lg` 24, `xl` 32, `xlPlus` 40, `xxl` 48, `xxxl` 64 |
+| `radius` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `full` |
+| `borderWidth` | `hairline`, `thin` 1, `thick` 2 |
+| `size` | `touchTarget` 44, `icon.sm/md/lg` 16/20/24 |
+| `opacity` | `hover`, `focus`, `pressed`, `dragged`, `disabledContent`, `disabledContainer` |
+| `motion` | `duration.short/medium/long`, `easing.standard/emphasized/decelerate/accelerate` (`[x1, y1, x2, y2]`) |
+| `shadow` | `sm`, `md`, `lg` — `{ boxShadow }` |
+| `zIndex`, `maxFontScale`, `categorical` | layers; OS text-scale ceiling (default 2); chart series colours |
+
+Breakpoints default to `{ compact: 0, medium: 600, expanded: 840 }`; replace them with the
+`breakpoints` option.
+
+### Custom fonts
+
+Android cannot pick a weight inside a family, so give each weight its file there:
+
+```ts
+typography: {
+  fonts: {
+    family: 'Inter',
+    android: { regular: 'Inter-Regular', medium: 'Inter-Medium', semibold: 'Inter-SemiBold', bold: 'Inter-Bold' },
+  },
+}
+```
+
+Use `...theme.font.bold` (not a literal `fontWeight`) to change weight in a style. A missing
+Android weight falls back to the nearest one with a development warning. On iOS a partial
+map only renames the weights it lists.
+
+### Font scale
+
+`fontScale` is a design-time multiplier and does not track the OS text size. Cap the OS
+multiplier on your shared `Text` with `maxFontSizeMultiplier={theme.maxFontScale}`.
+
+## Style Presets
+
+Presets are plain style data, so stylesheets keep only what is specific to them.
+
+- **Static** (`layout`, `presets`) — no theme dependency, so Unistyles never recalculates them:
+  `layout.row`, `column`, `rowCenter`, `rowBetween`, `center`, `fill`, `wrap`, `absoluteFill`,
+  `selfStart`, `selfCenter`, `selfEnd`; `presets.glyphAlign` (Android icon-glyph centring),
+  `presets.tabularNums`.
+- **Theme** — read tokens and follow overrides: `theme.text.*` (typography + AA colour),
+  `theme.stack.<spacing>` / `theme.inline.<spacing>`, `theme.border.hairline|top|bottom|all`,
+  `theme.box.outlined|card|sheet|touchTarget`.
+
+```ts
+const styles = StyleSheet.create(theme => ({
+  row: { ...layout.rowCenter, ...theme.border.bottom, gap: theme.spacing.smPlus },
+  hint: theme.text.labelMuted,
+  container: {
+    ...theme.box.outlined,
+    variants: { tone: byTone(theme, t => ({ borderColor: t.border, backgroundColor: t.container })) },
+  },
+  // One variant style for every text; combine it by array.
+  toneText: { variants: { tone: byTone(theme, t => ({ color: t.onContainer })) } },
+  title: theme.typography.body,
+}));
+
+// <Text style={[styles.title, styles.toneText]} />
+```
+
+### Rules the Unistyles Babel plugin imposes
+
+The plugin decides **statically** which styles update on theme or variant changes. Verified
+against Unistyles 3.2.5 and 3.3.0:
+
+1. Read the theme through the stylesheet's own parameter. `const theme = cast(raw)` inside
+   the factory hides **every** dependency — those styles stop updating on theme change. Add
+   app tokens with `extend` instead of casting.
+2. Keep a literal `variants` key in the style and call `byTone(theme, …)` inline under it. A
+   variants object built elsewhere, or spread in, loses the theme or variant dependency.
+
+## Extending the Theme
+
+Add app tokens with `extend`; they are typed everywhere without casts, overridable, and
+validated (a value that is a colour must stay a colour):
+
+```ts
+createUnistylesConfig({
+  brandColors: BRAND_COLORS,
+  tones: { accent: '#BD260F' },           // full tone bundle, offered by byTone
+  extend: ({ theme, scheme }) => ({
+    appColor: { textMuted: theme.color.onSurfaceVariant, skeleton: theme.color.surfaceContainerHigh },
+  }),
+  themes: { brandB: { scheme: 'light', brandColors: BRAND_B } },   // extra named theme
+  overrides: {
+    light: { radius: { sm: 0, md: 0, lg: 0, xl: 0 }, appColor: { textMuted: '#706966' } },
+  },
+});
+```
+
+Extensions may not reuse a base group name. Override keys must already exist — new tokens
+belong in `extend`.
+
+## Integrations
+
+- `buildThemes(config)` — the same themes without Unistyles, e.g. for tests or other libraries.
+- `toNavigationTheme(theme, scheme)` — a React Navigation theme (no navigation dependency).
+
+## Public Runtime Exports
+
+`buildThemes`, `createUnistylesConfig`, `applyThemeMode`, `auditTheme`, `contrastRatio`,
+`withAlpha`, `byTone`, `layout`, `presets`, `toNavigationTheme`, `DEFAULT_BREAKPOINTS`,
+`ThemeConfigError`, `ThemeContrastError`.
+
+## Public Type Exports
+
+Config: `ThemeConfig`, `BrandColors`, `SeedColors`, `TypographyConfig`, `FontConfig`,
+`NamedThemeConfig`, `ExtendContext`, `UnistylesConfigOptions`, `BuildThemesOptions`.
+Output: `Theme`, `BaseTheme`, `Themes`, `ThemeName`, `UnistylesConfig`, `ColorRoles`,
+`ToneColors`, `Typography`, `TypographyToken`, `FontToken`, token and preset types
+(`SpacingTokens`, `TextPresets`, `BoxPresets`, …), `ContrastFailure`, `NavigationTheme`,
+`ThemeMode`, `ThemeModeRuntime`, `DeepPartial`.
+
+## Private Modules
+
+Only `@chipmobilesdk/rn-theme` is public. Deep imports (`.../src/...`) are unsupported.
+
+## Configuration Validation
+
+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),
+override colours and numbers, Unistyles options and breakpoints.
+
+## Dependency Classification
+
+- `dependencies`: none. HCT colour maths is vendored under `src/vendor/mcu` (Apache-2.0).
+- `peerDependencies`: `react`, `react-native`, `react-native-unistyles`.
+
+## Unistyles 3 Style Authoring and TypeScript Diagnostics
+
+### Style arrays and variants solve different problems
+
+Merge independent styles with array syntax (`[styles.container, styles.emphasis]`) — the
+array keeps merge order and each style's Unistyles state. Never object-spread Unistyles
+entries. Use `styles.useVariants(...)` for finite component states such as `selected` or
+`tone`.
+
+### Dynamic functions and inference
+
+Call a dynamic entry before passing it to `style`, with serializable arguments. If
+TypeScript widens sibling entries to `UnistylesValues | ((...) => UnistylesValues)`, move the
+dynamic entries into a separate `StyleSheet.create`. Every token and preset the package
+exports is typed as React Native `TextStyle`/`ViewStyle` members, so spreading them never
+degrades sibling inference.
+
+### Localize vague TypeScript errors
+
+When an error is reported at every JSX use, move the stylesheet above the component or split
+the suspect entries out to find the failing initializer.
+
+See the Unistyles 3 guides on [merging styles](https://www.unistyl.es/v3/guides/merging-styles/),
+[variants](https://www.unistyl.es/v3/references/variants/) and
+[dynamic functions](https://www.unistyl.es/v3/references/dynamic-functions/).
+
+## Migrating from 0.2.x
+
+See the mapping table in `CHANGELOG.md` (`## 1.0.0`). In short: rename `typographyConfig` to
+`typography`; replace `color.border` with `outline` (interactive) or `outlineVariant`
+(dividers); use `onSurfaceVariant` for muted text instead of `disabled`; replace the package
+augmentation (`UnistylesThemeFromBrand`) with the one in *Setup Order*; move app tokens from
+spreads and casts into `extend`.
+
+## Release Validation
+
+```bash
+npm run validate:theme
+```
+
+## Semver and Migration
+
+- Patch: internal fix with no public shape or behaviour change.
+- Minor: backward-compatible additions.
+- Major: removed export, renamed token, changed token shape or default values, or changed
+  consumer setup — with a migration table in the changelog.