@rootnative/core 0.0.0-alpha.9 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,119 @@
1
+ /** Options for `schemeGuardScript`. */
2
+ interface SchemeGuardScriptOptions {
3
+ /**
4
+ * The `localStorage` key that holds the mode the reader chose. A stored
5
+ * `'light'` or `'dark'` wins over the OS scheme, as it does in
6
+ * `ThemeProvider`. Pass `null` when the app does not keep the mode in
7
+ * `localStorage` under one key: the script then reads the OS scheme only.
8
+ *
9
+ * @default THEME_MODE_STORAGE_KEY ('rootnative.theme-mode'), the key that
10
+ * `ThemeProvider` writes through `storage`
11
+ */
12
+ storageKey?: string | null;
13
+ }
14
+ /** Options for `schemeGuardCss`. */
15
+ interface SchemeGuardCssOptions {
16
+ /**
17
+ * The CSS color that a dark-scheme reader sees while the page is hidden.
18
+ * Use the background color of the dark theme, for example
19
+ * `darkTheme.colors.background`.
20
+ */
21
+ background: string;
22
+ /**
23
+ * The element that holds the app. The guard hides it until the theme is
24
+ * ready.
25
+ *
26
+ * @default '#root', the element Expo hydrates into
27
+ */
28
+ rootSelector?: string;
29
+ /**
30
+ * How long to wait for the theme before the page shows anyway, in
31
+ * milliseconds. This is for a bundle that fails to load. A short value
32
+ * shows the light page to a dark-scheme reader on a slow connection; a long
33
+ * value keeps a reader with a failed bundle on an empty page.
34
+ *
35
+ * @default 8000
36
+ */
37
+ timeoutMs?: number;
38
+ }
39
+
40
+ /**
41
+ * The source of an inline script for the `<head>` of a static export. It
42
+ * finds the scheme the reader will get after hydration and writes it to
43
+ * `<html>` as `SCHEME_ATTRIBUTE`, before the body paints.
44
+ *
45
+ * ## The problem it solves
46
+ *
47
+ * The export server cannot know the color scheme of the reader, so the HTML
48
+ * holds the light theme. react-native-web writes each theme color into the
49
+ * HTML as an inline style, and shell CSS cannot change an inline style. So a
50
+ * reader with a dark scheme sees the light page until the bundle downloads
51
+ * and hydrates: about 1.3 s on a fast computer, and more than 5 s on a slow
52
+ * phone. A mode stored with `storage` loads after hydration, so a reader who
53
+ * chose dark sees the same light page.
54
+ *
55
+ * This script and `schemeGuardCss` hide the page from a dark-scheme reader
56
+ * until `ThemeProvider` shows the final theme. A light-scheme reader sees no
57
+ * change. Without JavaScript the script does not run, so nothing is hidden.
58
+ *
59
+ * ## How to use it
60
+ *
61
+ * Put both in the HTML shell — for Expo Router that is `app/+html.tsx`. The
62
+ * script must come before the body:
63
+ *
64
+ * ```tsx
65
+ * import { darkTheme } from '@rootnative/core'
66
+ * import {
67
+ * schemeGuardCss,
68
+ * schemeGuardScript,
69
+ * } from '@rootnative/core/static-export'
70
+ *
71
+ * <head>
72
+ * <script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
73
+ * <style
74
+ * dangerouslySetInnerHTML={{
75
+ * __html: schemeGuardCss({ background: darkTheme.colors.background }),
76
+ * }}
77
+ * />
78
+ * </head>
79
+ * ```
80
+ *
81
+ * The scheme comes from the same sources as `ThemeProvider` uses: a stored
82
+ * `'light'` or `'dark'` first, then the OS scheme. The script cannot see a
83
+ * mode that the app controls with `mode`. It then reads the OS scheme, and
84
+ * the page can stay hidden until hydration for a reader who will see light.
85
+ */
86
+ declare function schemeGuardScript(options?: SchemeGuardScriptOptions): string;
87
+ /**
88
+ * CSS for the HTML shell of a static export. For a reader whose scheme is
89
+ * dark, it hides the app element and paints `background` until
90
+ * `ThemeProvider` marks the theme as ready. See `schemeGuardScript` for the
91
+ * problem, and for the script that this CSS needs.
92
+ *
93
+ * The hidden page keeps its layout, so nothing moves when it shows. The cost
94
+ * is time: a dark-scheme reader sees content when hydration ends, not when the
95
+ * HTML arrives, so the Largest Contentful Paint is later for that reader.
96
+ *
97
+ * If the theme is not ready after `timeoutMs`, the page shows anyway. That is
98
+ * for a bundle that fails to load.
99
+ */
100
+ declare function schemeGuardCss(options: SchemeGuardCssOptions): string;
101
+
102
+ /**
103
+ * The two `<html>` attributes the scheme guard is built on. The shell script
104
+ * and `ThemeProvider` write them, and `schemeGuardCss` reads them, so the
105
+ * writers and the CSS share one spelling.
106
+ */
107
+ /**
108
+ * Set on `<html>` by `schemeGuardScript`, before the body paints, to the
109
+ * scheme the reader will get after hydration: `'dark'` or `'light'`.
110
+ */
111
+ declare const SCHEME_ATTRIBUTE = "data-rootnative-scheme";
112
+ /**
113
+ * Set on `<html>` by `ThemeProvider` on web, on the first render after
114
+ * hydration with the stored mode loaded. From then on the theme on screen is
115
+ * the final one, so the guard stands down.
116
+ */
117
+ declare const THEME_READY_ATTRIBUTE = "data-rootnative-theme-ready";
118
+
119
+ export { SCHEME_ATTRIBUTE, type SchemeGuardCssOptions, type SchemeGuardScriptOptions, THEME_READY_ATTRIBUTE, schemeGuardCss, schemeGuardScript };
@@ -0,0 +1,55 @@
1
+ import {
2
+ SCHEME_ATTRIBUTE,
3
+ THEME_MODE_STORAGE_KEY,
4
+ THEME_READY_ATTRIBUTE
5
+ } from "../chunk-OK7DBCK4.mjs";
6
+ import "../chunk-Y6FXYEAI.mjs";
7
+
8
+ // src/static-export/schemeGuard.ts
9
+ var KEYFRAMES = "rootnative-scheme-guard";
10
+ var DEFAULT_ROOT_SELECTOR = "#root";
11
+ var DEFAULT_TIMEOUT_MS = 8e3;
12
+ function scriptLiteral(value) {
13
+ return JSON.stringify(value).replace(/</g, "\\u003c");
14
+ }
15
+ function schemeGuardScript(options) {
16
+ const storageKey = (options == null ? void 0 : options.storageKey) === void 0 ? THEME_MODE_STORAGE_KEY : options.storageKey;
17
+ const readStored = storageKey === null ? "" : `try { stored = window.localStorage.getItem(${scriptLiteral(storageKey)}) } catch (e) {}
18
+ `;
19
+ return `(function () {
20
+ try {
21
+ var stored = null
22
+ ${readStored}var scheme = stored === 'dark' || stored === 'light'
23
+ ? stored
24
+ : window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
25
+ ? 'dark'
26
+ : 'light'
27
+ document.documentElement.setAttribute(${scriptLiteral(SCHEME_ATTRIBUTE)}, scheme)
28
+ } catch (e) {}
29
+ })()
30
+ `;
31
+ }
32
+ function schemeGuardCss(options) {
33
+ var _a, _b;
34
+ const root = (_a = options.rootSelector) != null ? _a : DEFAULT_ROOT_SELECTOR;
35
+ const timeout = (_b = options.timeoutMs) != null ? _b : DEFAULT_TIMEOUT_MS;
36
+ const guarded = `html[${SCHEME_ATTRIBUTE}='dark']:not([${THEME_READY_ATTRIBUTE}])`;
37
+ return `@keyframes ${KEYFRAMES} {
38
+ to { visibility: visible; }
39
+ }
40
+ ${guarded},
41
+ ${guarded} body {
42
+ background-color: ${options.background};
43
+ }
44
+ ${guarded} ${root} {
45
+ visibility: hidden;
46
+ animation: ${KEYFRAMES} 0s ${timeout}ms forwards;
47
+ }
48
+ `;
49
+ }
50
+ export {
51
+ SCHEME_ATTRIBUTE,
52
+ THEME_READY_ATTRIBUTE,
53
+ schemeGuardCss,
54
+ schemeGuardScript
55
+ };
@@ -1,22 +1,23 @@
1
1
  /**
2
- * Base theme interface that all design systems must implement.
3
- * Provides a generic contract for colors, typography, and shared tokens.
4
- * Extend this to create a custom design system theme.
2
+ * Base theme interface that all design systems must implement: color roles
3
+ * and typography roles, with any role names. Extend this to create a custom
4
+ * design system theme, and add token groups of your own on the theme root.
5
+ *
6
+ * It has no Material Design group. `shape`, `spacing`, `stateLayer`,
7
+ * `elevation` and `motion` belong to {@link Theme}. The components of
8
+ * `@rootnative/components` read the MD3 roles and groups, so they need a
9
+ * {@link Theme}.
5
10
  *
6
11
  * @example
7
12
  * interface MyTheme extends BaseTheme {
8
13
  * colors: { brand: string; background: string; text: string }
9
14
  * typography: { heading: TypographyToken; body: TypographyToken }
15
+ * radius: { card: number; control: number }
10
16
  * }
11
17
  */
12
18
  interface BaseTheme {
13
19
  colors: Record<string, string>;
14
20
  typography: Record<string, TypographyToken>;
15
- shape: Shape;
16
- spacing: Spacing;
17
- stateLayer: StateLayer;
18
- elevation: Elevation;
19
- motion: Motion;
20
21
  [key: string]: unknown;
21
22
  }
22
23
  /**
@@ -28,6 +29,11 @@ interface BaseTheme {
28
29
  interface Theme extends BaseTheme {
29
30
  colors: Colors;
30
31
  typography: Typography;
32
+ shape: Shape;
33
+ spacing: Spacing;
34
+ stateLayer: StateLayer;
35
+ elevation: Elevation;
36
+ motion: Motion;
31
37
  topAppBar?: TopAppBarTokens;
32
38
  }
33
39
  /**
@@ -136,7 +142,7 @@ interface TypographyToken {
136
142
  lineHeight: number;
137
143
  letterSpacing: number;
138
144
  }
139
- /** Corner radius tokens from none (0) to full (9999 for pill shapes). */
145
+ /** Corner radius tokens from none (0) to full (999 for pill shapes). */
140
146
  interface Shape {
141
147
  /** Global multiplier for corner radii. `0` = sharp, `1` = default MD3, `2` = double rounding. Does not affect `cornerNone` or `cornerFull`. */
142
148
  roundness: number;
@@ -156,16 +162,44 @@ interface Spacing {
156
162
  lg: number;
157
163
  xl: number;
158
164
  }
165
+ /**
166
+ * Layout tokens of the MD3 top app bar, in dp. `AppBar` follows the Compose
167
+ * `TopAppBarLayout` geometry: each side slot and the title carry
168
+ * `horizontalPadding`. So the title starts at
169
+ * `max(titleStartInset, horizontalPadding + leading width) + horizontalPadding`
170
+ * from the start edge (16 with no leading content, 56 after a 48dp navigation
171
+ * icon), and the last action ends `horizontalPadding` (4) from the end edge.
172
+ * No pair of values puts the title and the actions on one wider gutter. Pad
173
+ * the bar with `style` for that (AppBar docs, "Align with a Page Gutter").
174
+ */
159
175
  interface TopAppBarTokens {
176
+ /** Padding at each end of the top row, and on each side of the title. Default 4. */
160
177
  horizontalPadding: number;
178
+ /**
179
+ * Smallest start position of the title's own padding, used when the
180
+ * leading slot is narrower. With `horizontalPadding`, also the start inset
181
+ * of the title row of a `medium` or `large` bar. Default 12.
182
+ */
161
183
  titleStartInset: number;
184
+ /** Height of a `small` or `center-aligned` bar, and of a collapsed `medium` or `large` bar. Default 64. */
162
185
  smallContainerHeight: number;
186
+ /** Height of a `medium` bar with no subtitle. A subtitle adds 24. Default 112. */
163
187
  mediumContainerHeight: number;
188
+ /** Height of a `large` bar with no subtitle. A subtitle adds 32. Default 152. */
164
189
  largeContainerHeight: number;
190
+ /** Height of the row that holds the navigation icon and the actions. Default 64. */
165
191
  topRowHeight: number;
192
+ /** Smallest height of the leading and trailing slots. Default 48. */
166
193
  sideSlotMinHeight: number;
194
+ /**
195
+ * Width of the frame around the navigation icon, and the smallest width of
196
+ * custom slot content, so a 40dp `IconButton` takes the 48dp footprint of
197
+ * an MD3 icon button. Default 48.
198
+ */
167
199
  iconFrameSize: number;
200
+ /** Space under the title of a `medium` bar. Default 24. */
168
201
  mediumTitleBottomPadding: number;
202
+ /** Space under the title of a `large` bar. Default 28. */
169
203
  largeTitleBottomPadding: number;
170
204
  }
171
205
  /** Opacity values for interactive state feedback (press, hover, focus, drag, disabled). */
package/llms.txt CHANGED
@@ -1,8 +1,8 @@
1
1
  # @rootnative/core — Theme System for React Native
2
2
 
3
- > Version: 0.0.0-alpha.9
4
- > Peer deps: react >=18, react-native >=0.72, @rootnative/inertia >=0.0.6 <0.1.0 (required — every animation runs on it)
5
- > Optional: @material/material-color-utilities >=0.4.0 (for createMaterialTheme)
3
+ > Version: 0.0.2
4
+ > Peer deps: react >=19.3.0 <20.0.0, react-native >=0.88.0 <0.89.0, @rootnative/inertia >=0.0.26 <0.1.0 (required — every animation runs on it)
5
+ > createMaterialTheme needs no extra install — its color engine (@material/material-color-utilities) is bundled behind the create-theme subpath
6
6
 
7
7
  ## Quick Start
8
8
 
@@ -20,9 +20,25 @@ export default function App() {
20
20
 
21
21
  ## API
22
22
 
23
+ ### When to pick which — theme paths
24
+
25
+ Ask this first. Every path below ends in the same `<ThemeProvider theme={...}>`.
26
+
27
+ | You want | Reach for |
28
+ | --- | --- |
29
+ | MD3 defaults, no setup | `<ThemeProvider>` alone (light), or `theme={{ light: lightTheme, dark: darkTheme }}` to follow the OS |
30
+ | A full MD3 palette from one brand color | `createMaterialTheme(seed)` from `@rootnative/core/create-theme` |
31
+ | MD3 with a few token overrides | Spread over `lightTheme` / `darkTheme` (see the custom-theme example under ThemeProvider) |
32
+ | MD3 with sharper or rounder corners | The `roundness` option on `createMaterialTheme`, or `applyRoundness()` on an existing theme |
33
+ | MD3 components plus your own tokens | Spread `lightTheme` in `defineTheme<AppTheme>()` and add a token group on the theme root |
34
+ | Your own role names, for your own components only (the library components need the MD3 roles) | `defineTheme<MyTheme>()` + `useTheme<MyTheme>()` |
35
+ | Light/dark switching and persistence | The `{ light, dark }` pair + `useThemeMode()`; add `storage` to persist |
36
+ | One part of the app with its own colors | A nested `ThemeProvider` with its own pair (see Nested providers) |
37
+ | No light flash for dark readers of a static web export | `schemeGuardScript` + `schemeGuardCss` from `@rootnative/core/static-export` in the HTML shell |
38
+
23
39
  ### ThemeProvider
24
40
 
25
- Wrap your app root to supply the theme to all components. Works with any design system — Material Design 3 or custom themes. Defaults to the MD3 light theme when no theme is provided.
41
+ Wrap your app root to supply the theme to all components. Takes an MD3 theme, or a theme with your own role names for your own components. The components of `@rootnative/components` read the MD3 color and typography roles, so they need a theme that keeps them. Defaults to the MD3 light theme when no theme is provided.
26
42
 
27
43
  ```tsx
28
44
  import { ThemeProvider, darkTheme } from '@rootnative/core'
@@ -33,8 +49,24 @@ import { ThemeProvider, darkTheme } from '@rootnative/core'
33
49
  // Dark theme
34
50
  <ThemeProvider theme={darkTheme}>{children}</ThemeProvider>
35
51
 
36
- // Custom theme
52
+ // Light/dark, following the OS setting
37
53
  import { lightTheme } from '@rootnative/core'
54
+
55
+ <ThemeProvider theme={{ light: lightTheme, dark: darkTheme }}>
56
+ {children}
57
+ </ThemeProvider>
58
+
59
+ // ...and remembering the user's override across launches
60
+ import AsyncStorage from '@react-native-async-storage/async-storage'
61
+
62
+ <ThemeProvider
63
+ theme={{ light: lightTheme, dark: darkTheme }}
64
+ storage={AsyncStorage}
65
+ >
66
+ {children}
67
+ </ThemeProvider>
68
+
69
+ // Custom theme
38
70
  import type { Theme } from '@rootnative/core'
39
71
 
40
72
  const custom: Theme = {
@@ -45,9 +77,82 @@ const custom: Theme = {
45
77
  ```
46
78
 
47
79
  Props:
48
- - `theme?: BaseTheme` — Theme object. Default: `lightTheme` (MD3)
80
+ - `theme?: BaseTheme | { light: BaseTheme; dark: BaseTheme }` — A single theme, or a light/dark pair. A pair enables `useThemeMode()`. Default: `lightTheme` (MD3)
81
+ - `mode?: 'system' | 'light' | 'dark'` — Controlled mode. Leave unset and use `setMode()` instead. Pair with `onModeChange`. On a static web export, `'system'` renders light on the server and while the client hydrates, then follows the OS on the render after hydration. No hydration gate is needed around it. A dark-scheme reader sees light until hydration ends; see "Static export: the dark first paint (web)". A nested provider with a pair and none of `mode`, `defaultMode` and `storage` follows the mode of its parent; see "Nested providers"
82
+ - `defaultMode?: 'system' | 'light' | 'dark'` — Initial mode when uncontrolled. Default: `'system'`. On a nested provider, setting it gives the provider a mode of its own
83
+ - `onModeChange?: (mode: ThemeMode) => void`
84
+ - `storage?: { getItem, setItem }` — Persists the mode. Any AsyncStorage-shaped object; sync or async. Nothing is persisted unless you pass this. On a nested provider, setting it gives the provider a mode of its own, and it overwrites the mode the root stored: every provider uses the key `THEME_MODE_STORAGE_KEY` (`'rootnative.theme-mode'`)
85
+ - `iconResolver?: IconResolver` — Renders string icon names. Pass `mdiResolver` from `@rootnative/components/mdi` for MaterialDesignIcons, or your own. Without it a string name renders nothing and logs one warning. A nested provider without it uses the resolver of its parent
49
86
  - `children: ReactNode`
50
87
 
88
+ ### useThemeMode()
89
+
90
+ Reads and controls light/dark mode. Requires a provider given a `{ light, dark }` pair — it throws otherwise, since a single-theme provider has no mode to control.
91
+
92
+ Returns `{ mode, scheme, setMode, isReady }`:
93
+ - `mode` — what was asked for, including `'system'`
94
+ - `scheme` — the resolved `'light' | 'dark'` actually rendering. Use this to sync anything outside the theme, such as the status bar
95
+ - `setMode(mode)` — switches mode, and persists it when `storage` is set
96
+ - `isReady` — `false` until a persisted mode has loaded. Always `true` without `storage`. Gate a splash screen on it to avoid a launch flash
97
+
98
+ ```tsx
99
+ import { useThemeMode } from '@rootnative/core'
100
+ import { StatusBar } from 'expo-status-bar'
101
+
102
+ function ThemeToggle() {
103
+ const { scheme, setMode } = useThemeMode()
104
+
105
+ return (
106
+ <>
107
+ <StatusBar style={scheme === 'dark' ? 'light' : 'dark'} />
108
+ <Button onPress={() => setMode(scheme === 'dark' ? 'light' : 'dark')}>
109
+ Toggle theme
110
+ </Button>
111
+ </>
112
+ )
113
+ }
114
+ ```
115
+
116
+ ### Nested providers
117
+
118
+ A second `ThemeProvider` inside the root one gives one part of the app its own theme, for example the colors of an image:
119
+
120
+ ```tsx
121
+ import { createMaterialTheme } from '@rootnative/core/create-theme'
122
+
123
+ const themes = useMemo(() => {
124
+ const { lightTheme: light, darkTheme: dark } = createMaterialTheme(seed)
125
+ return { light, dark }
126
+ }, [seed])
127
+
128
+ <ThemeProvider theme={themes}>{children}</ThemeProvider>
129
+ ```
130
+
131
+ What a nested provider takes from its parent:
132
+ - **Icon resolver** — with no `iconResolver`, it uses the resolver of its parent.
133
+ - **Mode** — a nested provider with a pair, below a parent with a pair, follows the mode of the parent when it gets none of `mode`, `defaultMode` and `storage`. `useThemeMode()` below it reports the mode of the parent, and `setMode()` sets the mode of the parent. Pass any of the three props to give it a mode of its own.
134
+ - **Named transitions** — its `MotionConfig` merges with the one above, so the named transitions of the app stay.
135
+
136
+ A nested provider with a single theme has no mode, so `useThemeMode()` throws below it.
137
+
138
+ **An overlay carries the nested theme.** `Dialog`, `Menu`, `Tooltip`, `BottomSheet`, `SearchView`, the modal `NavigationDrawer` and the snackbar render through a `Portal` at the `PortalHost`, which is usually above the nested provider. `Portal` reads the theme, the mode, the icon resolver and the named transitions where you write the overlay, and provides them again at the host, so the overlay surface and every component in its content take the nested theme.
139
+
140
+ ### useThemeScope() and ThemeScopeProvider
141
+
142
+ The pair that `Portal` uses, for content you render at another place yourself, for example through `createPortal` or a third-party modal. `useThemeScope()` reads the theme, the mode, the icon resolver and the motion config of the call site as one `ThemeScope` value. `<ThemeScopeProvider scope={scope}>` provides that value to its children, as if the providers of the call site stood there. A `ThemeProvider` below it inherits from it the same way it inherits from a real parent. Treat `ThemeScope` as opaque.
143
+
144
+ ```tsx
145
+ import { ThemeScopeProvider, useThemeScope } from '@rootnative/core'
146
+
147
+ function MyPortal({ children }) {
148
+ const scope = useThemeScope()
149
+ return createPortal(
150
+ <ThemeScopeProvider scope={scope}>{children}</ThemeScopeProvider>,
151
+ host,
152
+ )
153
+ }
154
+ ```
155
+
51
156
  ### useTheme()
52
157
 
53
158
  Returns the current theme from the nearest `ThemeProvider`.
@@ -68,7 +173,7 @@ const theme = useTheme<MyTheme>()
68
173
 
69
174
  ### defineTheme(theme)
70
175
 
71
- Identity function that validates a custom theme object against `BaseTheme`. Provides type-checking and autocompletion.
176
+ Identity function that validates a custom theme object against `BaseTheme`. Provides type-checking and autocompletion. The theme below has its own role names, so it is for your own components. `BaseTheme` needs only `colors` and `typography`; the other token groups of such a theme are your own. For the library components, spread `lightTheme` and add your tokens beside the MD3 roles.
72
177
 
73
178
  ```tsx
74
179
  import { defineTheme } from '@rootnative/core'
@@ -76,7 +181,7 @@ import type { BaseTheme, TypographyToken } from '@rootnative/core'
76
181
 
77
182
  interface MyColors { [key: string]: string; brand: string; background: string; text: string }
78
183
  interface MyTypography { [key: string]: TypographyToken; heading: TypographyToken; body: TypographyToken }
79
- interface MyTheme extends BaseTheme { colors: MyColors; typography: MyTypography }
184
+ interface MyTheme extends BaseTheme { colors: MyColors; typography: MyTypography; radius: { control: number; card: number } }
80
185
 
81
186
  const myTheme = defineTheme<MyTheme>({
82
187
  colors: { brand: '#FF6B00', background: '#FFFFFF', text: '#1A1A1A' },
@@ -84,11 +189,7 @@ const myTheme = defineTheme<MyTheme>({
84
189
  heading: { fontFamily: 'Inter', fontSize: 24, fontWeight: '700', lineHeight: 32, letterSpacing: 0 },
85
190
  body: { fontFamily: 'Inter', fontSize: 16, fontWeight: '400', lineHeight: 24, letterSpacing: 0.5 },
86
191
  },
87
- shape: { roundness: 1, cornerNone: 0, cornerExtraSmall: 4, cornerSmall: 8, cornerMedium: 12, cornerLarge: 16, cornerExtraLarge: 28, cornerFull: 9999 },
88
- spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 },
89
- stateLayer: { pressedOpacity: 0.1, focusedOpacity: 0.1, hoveredOpacity: 0.08, draggedOpacity: 0.16, disabledOpacity: 0.38, disabledContainerOpacity: 0.12 },
90
- elevation: { ... },
91
- motion: { ... },
192
+ radius: { control: 8, card: 16 },
92
193
  })
93
194
  ```
94
195
 
@@ -99,7 +200,27 @@ Generates a complete MD3 light and dark theme from a single seed color. Uses Goo
99
200
  Defaults are byte-identical to the upstream MD3 `material-color-utilities` library — pure spec output.
100
201
 
101
202
  **Spec-aligned options:**
102
- - `variant?: 'tonalSpot' | 'neutral' | 'vibrant' | 'expressive' | 'fidelity' | 'content' | 'monochrome' | 'rainbow' | 'fruitSalad'` — MD3 scheme variant (default `'tonalSpot'`, the Material You default on Android 12+). Each is a spec-defined recipe for deriving the palette. Use `'monochrome'` for spec-legal pure-grey themes, `'vibrant'` for high-colorfulness, etc.
203
+ - `variant?: 'tonalSpot' | 'neutral' | 'vibrant' | 'expressive' | 'fidelity' | 'content' | 'monochrome' | 'rainbow' | 'fruitSalad'` — MD3 scheme variant (default `'tonalSpot'`, the Material You default on Android 12+). Each is a spec-defined recipe for deriving the palette. Use `'monochrome'` for spec-legal pure-grey themes, `'vibrant'` for high-colorfulness, etc. **Two variants move the primary hue away from your seed — see the table below.**
204
+
205
+ **Does the variant keep the seed hue?**
206
+
207
+ Ask this first if the seed is a brand color. `expressive` and `fruitSalad` rotate the primary hue by design — this is correct MD3 behavior, not a defect, but it means the generated `primary` is not your brand color. Example results for the seed `#E07A3F` (a strong orange):
208
+
209
+ | Variant | Light `primary` | Keeps the seed hue? |
210
+ | --- | --- | --- |
211
+ | `tonalSpot` | `#8d4e2a` | Yes |
212
+ | `neutral` | — | Yes (low chroma) |
213
+ | `vibrant` | `#9d4300` | Yes |
214
+ | `expressive` | `#585799` | **No — rotates to blue-violet** |
215
+ | `fidelity` | `#9b450b` | Yes — also returns the seed as `primaryContainer` |
216
+ | `content` | `#9b450b` | Yes |
217
+ | `monochrome` | — | Yes (chroma 0) |
218
+ | `rainbow` | `#984714` | Yes |
219
+ | `fruitSalad` | `#974066` | **No — rotates to magenta** |
220
+
221
+ Use `fidelity`, `content`, or `tonalSpot` to keep the seed hue. Pick `expressive` for colorfulness only when the palette does not have to match a brand color.
222
+
223
+ **`fidelity` pins `primaryContainer` to the seed in both modes.** With `variant: 'fidelity'` the seed is returned as `primaryContainer` in the light theme **and** the dark theme (`onPrimaryContainer` stays dark in both). This is upstream MD3 fidelity behavior: the scheme holds the source color exactly. Every other container role gets darker in dark mode, so a bright container with dark text can break the surface ramp. Override `primaryContainer` / `onPrimaryContainer` for the dark theme if the ramp matters more than seed fidelity.
103
224
  - `contrastLevel?: 'standard' | 'medium' | 'high'` — MD3 contrast preset (default `'standard'`). Maps to MD3 contrast values `0 / 0.5 / 1.0`. Use `'medium'` or `'high'` for WCAG AAA / low-vision modes.
104
225
  - `fontFamily?: string` — Custom font family applied to all 30 typography styles (15 base + 15 emphasized). When omitted, platform defaults are used (Roboto on Android, System on iOS).
105
226
  - `roundness?: number` — Global corner-radius multiplier. `0` = sharp corners, `1` = default MD3 (default), `2` = double rounding. Does not affect `cornerNone` or `cornerFull`.
@@ -135,18 +256,27 @@ createMaterialTheme('#006A6A', { surfaceTone: 'neutral' })
135
256
  // Override: per-palette chroma
136
257
  createMaterialTheme('#006A6A', { seedAdjustments: { primary: 60, secondary: 32 } })
137
258
 
138
- // Use in provider
259
+ // Use in provider — pinned light
139
260
  <ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
140
261
 
141
- // Or with dark mode
142
- <ThemeProvider theme={isDark ? darkTheme : lightTheme}>{children}</ThemeProvider>
262
+ // Or hand both to the provider and let it follow the OS. Rename on
263
+ // destructure so the pair matches the prop's { light, dark } shape.
264
+ const { lightTheme: light, darkTheme: dark } = createMaterialTheme('#006A6A')
265
+
266
+ <ThemeProvider theme={{ light, dark }}>{children}</ThemeProvider>
143
267
  ```
144
268
 
145
269
  Returns: `{ lightTheme: Theme, darkTheme: Theme }`
146
270
 
147
271
  The generated themes include all 49 MD3 color roles plus shared tokens (typography, shape, spacing, stateLayer, elevation, motion, topAppBar).
148
272
 
149
- Requires `@material/material-color-utilities` as a peer dependency: `npm install @material/material-color-utilities`
273
+ No extra install is needed: `@material/material-color-utilities` is bundled inside `@rootnative/core`, behind the `create-theme` subpath. Projects that never import the subpath never load it.
274
+
275
+ The subpath also imports nothing from `react-native`, so it runs in plain Node — print a palette from a script, check a theme in CI, or feed the roles to a design-token pipeline:
276
+
277
+ ```bash
278
+ node -e "import('@rootnative/core/create-theme').then(({ createMaterialTheme }) => console.log(createMaterialTheme('#006A6A').lightTheme.colors))"
279
+ ```
150
280
 
151
281
  ### applyRoundness(roundness)
152
282
 
@@ -181,8 +311,8 @@ material.defaultTopAppBarTokens
181
311
 
182
312
  ### Theme type hierarchy
183
313
 
184
- - `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string, TypographyToken>`, plus shape, spacing, stateLayer, elevation, motion.
185
- - `Theme` — Material Design 3 theme. Extends `BaseTheme` with 49 MD3 color roles, 30 typography variants (15 base + 15 emphasized), and optional `topAppBar` tokens. `MaterialTheme` is an identical alias (same type) — use it to disambiguate in multi-design-system codebases.
314
+ - `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string, TypographyToken>`, and an index signature for token groups of your own. It has no MD3 group.
315
+ - `Theme` — Material Design 3 theme. Extends `BaseTheme` with 49 MD3 color roles, 30 typography variants (15 base + 15 emphasized), the `shape`, `spacing`, `stateLayer`, `elevation` and `motion` groups, and optional `topAppBar` tokens. `MaterialTheme` is an identical alias (same type) — use it to disambiguate in multi-design-system codebases.
186
316
 
187
317
  ### Theme structure
188
318
 
@@ -190,20 +320,23 @@ material.defaultTopAppBarTokens
190
320
  BaseTheme {
191
321
  colors: Record<string, string>
192
322
  typography: Record<string, TypographyToken>
193
- shape: Shape — roundness, cornerNone, cornerExtraSmall, cornerSmall, cornerMedium, cornerLarge, cornerExtraLarge, cornerFull
194
- spacing: Spacing — xs, sm, md, lg, xl
195
- elevation: Elevation — level0..level5 (shadow properties)
196
- stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, draggedOpacity, disabledOpacity, disabledContainerOpacity
197
- motion: Motion — duration, easing, and MD3 Expressive spring tokens (springFastSpatial, springDefaultSpatial, springSlowSpatial, springFastEffects, springDefaultEffects, springSlowEffects — each { tension, friction, mass })
323
+ [key: string]: unknown — token groups of your own
198
324
  }
199
325
 
200
326
  Theme extends BaseTheme {
201
327
  colors: Colors — 49 MD3 color roles
202
328
  typography: Typography — 30 type scale variants: 15 base (displayLarge..labelSmall) + 15 MD3 Expressive emphasized (displayLargeEmphasized..labelSmallEmphasized)
203
- topAppBar?: TopAppBarTokens
329
+ shape: Shape — roundness, cornerNone, cornerExtraSmall, cornerSmall, cornerMedium, cornerLarge, cornerExtraLarge, cornerFull
330
+ spacing: Spacing — xs, sm, md, lg, xl
331
+ elevation: Elevation — level0..level5 (shadow properties)
332
+ stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, draggedOpacity, disabledOpacity, disabledContainerOpacity
333
+ motion: Motion — duration, easing, and MD3 Expressive spring tokens (springFastSpatial, springDefaultSpatial, springSlowSpatial, springFastEffects, springDefaultEffects, springSlowEffects — each { tension, friction, mass })
334
+ topAppBar?: TopAppBarTokens — horizontalPadding, titleStartInset, smallContainerHeight, mediumContainerHeight, largeContainerHeight, topRowHeight, sideSlotMinHeight, iconFrameSize, mediumTitleBottomPadding, largeTitleBottomPadding (AppBar geometry in dp)
204
335
  }
205
336
  ```
206
337
 
338
+ `TopAppBarTokens`: `AppBar` follows the Compose `TopAppBarLayout` geometry. The title starts at `max(titleStartInset, horizontalPadding + leading width) + horizontalPadding` from the start edge (16dp with no leading content, 56dp after a 48dp navigation icon), and the last action ends `horizontalPadding` (4dp) from the end edge. No pair of token values puts both on one wider gutter: keep the tokens and pad the bar with `style` (`paddingStart: gutter - horizontalPadding - titleStartInset`, `paddingEnd: gutter - horizontalPadding`).
339
+
207
340
  Colors: primary, onPrimary, primaryContainer, onPrimaryContainer, primaryFixed, onPrimaryFixed, primaryFixedDim, onPrimaryFixedVariant, secondary (same pattern), tertiary (same pattern), error, onError, errorContainer, onErrorContainer, background, onBackground, surface, surfaceDim, surfaceBright, surfaceContainerLowest, surfaceContainerLow, surfaceContainer, surfaceContainerHigh, surfaceContainerHighest, onSurface, surfaceVariant, onSurfaceVariant, outline, outlineVariant, surfaceTint, shadow, scrim, inverseSurface, inverseOnSurface, inversePrimary
208
341
 
209
342
  Typography variants: displayLarge, displayMedium, displaySmall, headlineLarge, headlineMedium, headlineSmall, titleLarge, titleMedium, titleSmall, bodyLarge, bodyMedium, bodySmall, labelLarge, labelMedium, labelSmall — each with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing. Each also has an MD3 Expressive `<name>Emphasized` variant (same size/line height, weight one step heavier: 400→500, 500→700).
@@ -232,3 +365,60 @@ const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })
232
365
 
233
366
  Type: `useBreakpointValue<T>(values: Partial<Record<Breakpoint, T>> & Record<'compact', T>): T`
234
367
 
368
+ ### useWindowDimensions()
369
+
370
+ Returns the window size, the same as `useWindowDimensions` from `react-native`, but hydration-safe. Use it instead of the `react-native` hook when a layout needs a number rather than a size class: a hero height, a carousel slot, a column count.
371
+
372
+ ```tsx
373
+ import { useWindowDimensions } from '@rootnative/core'
374
+
375
+ const { width } = useWindowDimensions()
376
+ const heroHeight = width * 0.56
377
+ ```
378
+
379
+ Type: `useWindowDimensions(): ScaledSize`
380
+
381
+ ### Breakpoints and static export (web)
382
+
383
+ The three hooks are hydration-safe, so **no `useHydrated` gate is needed at the call site**. The `useWindowDimensions` hook from `react-native` is **not**: on a static export it keeps the layout of a 0 wide window until the reader resizes the window.
384
+
385
+ A static export (`web.output: 'static'`) renders on a server with no DOM, where react-native-web's `Dimensions` is fixed at `width: 0` — so every breakpoint resolves to `compact` and that is what ships in the HTML. React 19 does **not** repair a `className`/`style` mismatch during hydration: it adopts the server DOM, keeps it, and fires no recoverable error, so a tablet would silently keep the phone layout.
386
+
387
+ `useWindowDimensions` therefore reports the server's 0 by 0 window for as long as the client is hydrating, matching that markup, and switches to the measured window on the re-render React schedules once hydration finishes. `useBreakpoint` reads it, so it reports `compact` for the same span, and a breakpoint and a raw width cannot disagree. On native and on a single-page web build there is no hydration, so the measured value is returned from the first render at no cost.
388
+
389
+ The practical consequence: a breakpoint-dependent layout **starts compact and widens a frame later** on a static export. That is unavoidable — the server cannot know the viewport — so design the compact variant to be the honest first paint. `Grid` inherits all of this, which matters because it resolves a `columns` map internally and leaves a consumer nowhere to put a gate of their own.
390
+
391
+ `ThemeProvider` reads the same hydration flag for `mode="system"`. The export server has no `matchMedia`, so react-native-web reports `'light'` there and the HTML ships the light theme. The provider keeps light while the client hydrates, then switches to the OS scheme on the same re-render as the window size. A reader with a dark system setting sees the light theme until hydration ends, which takes seconds on a phone; the next section hides it. The `useColorScheme` hook from `react-native` is **not** hydration-safe: a theme chosen from it stays light in a dark browser.
392
+
393
+ ### Static export: the dark first paint (web)
394
+
395
+ react-native-web writes each theme color into the HTML as an inline style, and CSS in the HTML shell cannot change an inline style. So on a static export a reader with a dark system setting sees the light page until the script downloads and hydrates: measured at 1.3 s on a fast computer and 5.5 s with a 4× CPU throttle and a 6.4 Mbit/s network, for 2.6 MB of script. A mode that `storage` restores loads after hydration too.
396
+
397
+ `@rootnative/core/static-export` hides that light page. Put its script and its CSS in the HTML shell (`app/+html.tsx` with Expo Router). The script must come before the body:
398
+
399
+ ```tsx
400
+ import { darkTheme } from '@rootnative/core'
401
+ import {
402
+ schemeGuardCss,
403
+ schemeGuardScript,
404
+ } from '@rootnative/core/static-export'
405
+
406
+ const SCHEME_GUARD_CSS = schemeGuardCss({
407
+ background: darkTheme.colors.background,
408
+ })
409
+
410
+ // inside <head>
411
+ <script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
412
+ <style dangerouslySetInnerHTML={{ __html: SCHEME_GUARD_CSS }} />
413
+ ```
414
+
415
+ 1. The script reads the stored mode (`localStorage`, key `THEME_MODE_STORAGE_KEY`), then the OS scheme, and writes the scheme to `<html>` as `data-rootnative-scheme` (`SCHEME_ATTRIBUTE`) before the body paints.
416
+ 2. For the dark scheme, the CSS hides `#root` and paints `background` under it.
417
+ 3. On the first render after hydration, with the stored mode loaded, `ThemeProvider` writes `data-rootnative-theme-ready` (`THEME_READY_ATTRIBUTE`) on `<html>`, and the page shows in the dark theme.
418
+
419
+ A light-scheme reader sees no change. Without JavaScript nothing is hidden. The cost: a dark-scheme reader sees content when hydration ends, so the Largest Contentful Paint is later for that reader. If the theme is not ready after 8 s, the page shows anyway (a failed script).
420
+
421
+ Options:
422
+ - `schemeGuardScript({ storageKey? })` — `storageKey?: string | null`, default `THEME_MODE_STORAGE_KEY`. `null` reads the OS scheme only. The script cannot see a mode that the app controls with `mode`; pass the key the app writes, or `null`
423
+ - `schemeGuardCss({ background, rootSelector?, timeoutMs? })` — `background`: the color under the hidden page, use the dark theme background. `rootSelector`: default `'#root'`, the element Expo hydrates into. `timeoutMs`: default `8000`
424
+