@chipmobilesdk/rn-theme 0.2.1 → 0.2.2

package/README.md

@@ -77,7 +77,7 @@ StyleSheet.configure(
 
 Import the setup module first in the app entrypoint.
 
-## Theme Start Strategy
+## Theme Start Strategy
 
 Choose exactly one startup strategy.
 
@@ -93,9 +93,62 @@ System adaptive themes:
 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
+Using `initialTheme` and `adaptiveThemes: true` together is invalid. Persisting a user theme preference, if needed, belongs in the consuming app.
+
+## Unistyles 3 Style Authoring and TypeScript Diagnostics
+
+### Style arrays and variants solve different problems
+
+Unistyles 3 supports React Native's array syntax and recommends it when merging
+independent styles because the array preserves merge order and each style's attached
+Unistyles state:
+
+```tsx
+<View style={[styles.container, styles.emphasis]} />
+```
+
+Do not merge Unistyles entries with object spread. After a stylesheet recalculation,
+Unistyles may no longer know the intended override order.
+
+Use `styles.useVariants(...)` instead when a finite component prop or state such as
+`selected`, `disabled`, or `size` changes one or more style entries. Variants model
+semantic component states; they are not a replacement for every style array.
+
+If a valid array does not typecheck, inspect the inferred type of every entry. A member
+may be a dynamic function that was not called, or TypeScript may have widened a mixed
+stylesheet to an object/function union. Fix that inference instead of casting the array.
+
+### Dynamic functions and inference
+
+Unistyles supports static objects and dynamic functions, including both in one
+stylesheet. Call a dynamic entry before passing it to a `style` prop, and pass only
+serializable arguments:
+
+```tsx
+<View style={[styles.container, styles.sized(width)]} />
+```
+
+If TypeScript widens sibling entries to a union such as
+`UnistylesValues | ((...) => UnistylesValues)`, move the dynamic entries into a separate
+`StyleSheet.create` call. This is a TypeScript inference workaround, not an Unistyles
+runtime restriction. Prefer variants for a finite set of states and dynamic functions
+for open-ended values such as a measured width.
+
+### Localize vague TypeScript errors
+
+Keep stylesheets at module scope. When TypeScript reports a vague error at every JSX
+use instead of at the invalid style property, temporarily move the relevant
+`StyleSheet.create` declaration above the component or extract the suspect entries into
+a smaller stylesheet. This often makes inference fail at the actual initializer. It is
+a debugging technique, not a required declaration order; the real runtime ordering rule
+remains that `StyleSheet.configure` must run before importing themed components.
+
+See the official Unistyles 3 guidance for
+[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/).
+
+## Public Runtime Exports
 
 - `createUnistylesConfig(config, options?)`
 - `generateLightPalette(brandColors)`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-theme",
-	"version": "0.2.1",
+	"version": "0.2.2",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

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

@@ -1,6 +1,6 @@
 ---
 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: brand palettes, Unistyles config, color/typography tokens, dark mode, style composition, variants, and dynamic-style diagnostics. Use when setting up theming, adding a design token, wiring light/dark, or debugging Unistyles setup and type errors."
 metadata:
   package: "@chipmobilesdk/rn-theme"
   packageVersion: "0.2.0"
@@ -19,6 +19,7 @@ This is the single source of truth for color, typography, spacing and radius tok
 - 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
+- Style arrays, variants, or dynamic functions produce unexpected TypeScript errors
 
 ## Do not use this for
 
@@ -32,6 +33,22 @@ renders. Getting this wrong produces an app that renders with no styling and no
 Read the `## Setup Order` and `## Theme Start Strategy` sections of the README before
 changing entry-point wiring.
 
+## Unistyles 3 authoring guardrails
+
+- Merge independent styles with array syntax: `[styles.base, styles.extra]`. Do not
+  object-spread Unistyles entries. Variants are for finite semantic states such as
+  `selected`, `disabled`, or `size`, not a replacement for every array.
+- Call dynamic style entries before passing them to a `style` prop, and use only
+  serializable arguments. Mixing static and dynamic entries is supported; if TypeScript
+  widens sibling entries into an object/function union, split the dynamic entries into a
+  separate stylesheet instead of casting.
+- When an error is reported at many JSX usages, temporarily move the stylesheet above
+  the component or isolate suspect entries so the invalid initializer is diagnosed.
+  Treat this as a debugging technique, not a runtime ordering requirement.
+
+Read `## Unistyles 3 Style Authoring and TypeScript Diagnostics` in the README for the
+reasoning, examples, and upstream documentation links.
+
 ## Public API (v0.2.0)
 
 Runtime:
@@ -56,4 +73,5 @@ Read only the section you need from
 | Full export list | `## Public Runtime Exports`, `## Public Type Exports` |
 | Config rejected at runtime | `## Configuration Validation` |
 | Peer dependency rules | `## Compatibility`, `## Dependency Classification` |
+| Style arrays, variants, or dynamic-style type errors | `## Unistyles 3 Style Authoring and TypeScript Diagnostics` |
 | Upgrading across versions | `## Semver and Migration` |