@chipmobilesdk/rn-theme 0.2.0 → 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,9 +1,9 @@
 {
 	"name": "@chipmobilesdk/rn-theme",
-	"version": "0.2.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
+	"version": "0.2.2",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"exports": {
 		".": {
@@ -18,6 +18,7 @@
 		"src/types",
 		"src/unistyles",
 		"src/utils",
+		"skills",
 		"README.md",
 		"CHANGELOG.md"
 	],
@@ -42,8 +43,8 @@
 			"optional": false
 		}
 	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

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

@@ -0,0 +1,77 @@
+---
+name: sdk-rn-theme
+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"
+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.
+
+## 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
+- Style arrays, variants, or dynamic functions produce unexpected 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
+
+## Setup order matters
+
+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.
+
+## 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:
+
+- `generateLightPalette(brand)` / `generateDarkPalette(brand)` — derive full palettes
+- `createUnistylesConfig(...)` — build the Unistyles configuration object
+
+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.
+
+## Where the detail lives
+
+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` |
+| 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` |