@cognitap/radiant 0.0.1 → 0.0.3

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.
Files changed (192) hide show
  1. package/CHANGELOG.md +323 -15
  2. package/LICENSE +1 -1
  3. package/README.md +963 -220
  4. package/RELEASE_POLICY.md +23 -95
  5. package/dist/library/Accordion.d.ts +56 -0
  6. package/dist/library/Accordion.d.ts.map +1 -0
  7. package/dist/library/Accordion.js +89 -0
  8. package/dist/library/Accordion.js.map +1 -0
  9. package/dist/library/Button.d.ts +25 -3
  10. package/dist/library/Button.d.ts.map +1 -1
  11. package/dist/library/Button.js +31 -3
  12. package/dist/library/Button.js.map +1 -1
  13. package/dist/library/Card.d.ts +31 -0
  14. package/dist/library/Card.d.ts.map +1 -0
  15. package/dist/library/Card.js +69 -0
  16. package/dist/library/Card.js.map +1 -0
  17. package/dist/library/Checkbox.d.ts +13 -0
  18. package/dist/library/Checkbox.d.ts.map +1 -0
  19. package/dist/library/Checkbox.js +77 -0
  20. package/dist/library/Checkbox.js.map +1 -0
  21. package/dist/library/Collapsible.d.ts +32 -0
  22. package/dist/library/Collapsible.d.ts.map +1 -0
  23. package/dist/library/Collapsible.js +99 -0
  24. package/dist/library/Collapsible.js.map +1 -0
  25. package/dist/library/Dialog.d.ts +50 -0
  26. package/dist/library/Dialog.d.ts.map +1 -0
  27. package/dist/library/Dialog.js +215 -0
  28. package/dist/library/Dialog.js.map +1 -0
  29. package/dist/library/Field.d.ts +68 -0
  30. package/dist/library/Field.d.ts.map +1 -0
  31. package/dist/library/Field.js +114 -0
  32. package/dist/library/Field.js.map +1 -0
  33. package/dist/library/Input.d.ts +10 -0
  34. package/dist/library/Input.d.ts.map +1 -0
  35. package/dist/library/Input.js +51 -0
  36. package/dist/library/Input.js.map +1 -0
  37. package/dist/library/Link.d.ts +27 -0
  38. package/dist/library/Link.d.ts.map +1 -0
  39. package/dist/library/Link.js +50 -0
  40. package/dist/library/Link.js.map +1 -0
  41. package/dist/library/RadioGroup.d.ts +27 -0
  42. package/dist/library/RadioGroup.d.ts.map +1 -0
  43. package/dist/library/RadioGroup.js +103 -0
  44. package/dist/library/RadioGroup.js.map +1 -0
  45. package/dist/library/ThemeScope.d.ts +10 -0
  46. package/dist/library/ThemeScope.d.ts.map +1 -0
  47. package/dist/library/ThemeScope.js +41 -0
  48. package/dist/library/ThemeScope.js.map +1 -0
  49. package/dist/library/actionStyles.d.ts +11 -0
  50. package/dist/library/actionStyles.d.ts.map +1 -0
  51. package/dist/library/actionStyles.js +75 -0
  52. package/dist/library/actionStyles.js.map +1 -0
  53. package/dist/library/cn.d.ts +1 -2
  54. package/dist/library/cn.d.ts.map +1 -1
  55. package/dist/library/cn.js +1 -8
  56. package/dist/library/cn.js.map +1 -1
  57. package/dist/library/controlStyles.d.ts +5 -0
  58. package/dist/library/controlStyles.d.ts.map +1 -0
  59. package/dist/library/controlStyles.js +15 -0
  60. package/dist/library/controlStyles.js.map +1 -0
  61. package/dist/library/index.d.ts +24 -1
  62. package/dist/library/index.d.ts.map +1 -1
  63. package/dist/library/index.js +11 -0
  64. package/dist/library/index.js.map +1 -1
  65. package/dist/library/internal/events.d.ts +8 -0
  66. package/dist/library/internal/events.d.ts.map +1 -0
  67. package/dist/library/internal/events.js +13 -0
  68. package/dist/library/internal/events.js.map +1 -0
  69. package/dist/library/internal/ids.d.ts +3 -0
  70. package/dist/library/internal/ids.d.ts.map +1 -0
  71. package/dist/library/internal/ids.js +6 -0
  72. package/dist/library/internal/ids.js.map +1 -0
  73. package/dist/library/internal/selection.d.ts +5 -0
  74. package/dist/library/internal/selection.d.ts.map +1 -0
  75. package/dist/library/internal/selection.js +18 -0
  76. package/dist/library/internal/selection.js.map +1 -0
  77. package/dist/library/presentation.d.ts +18 -0
  78. package/dist/library/presentation.d.ts.map +1 -0
  79. package/dist/library/presentation.js +2 -0
  80. package/dist/library/presentation.js.map +1 -0
  81. package/dist/library/react/useComposedRefs.d.ts +4 -0
  82. package/dist/library/react/useComposedRefs.d.ts.map +1 -0
  83. package/dist/library/react/useComposedRefs.js +28 -0
  84. package/dist/library/react/useComposedRefs.js.map +1 -0
  85. package/dist/library/react/useControllableState.d.ts +16 -0
  86. package/dist/library/react/useControllableState.d.ts.map +1 -0
  87. package/dist/library/react/useControllableState.js +29 -0
  88. package/dist/library/react/useControllableState.js.map +1 -0
  89. package/dist/library/react/useNativeOwner.d.ts +17 -0
  90. package/dist/library/react/useNativeOwner.d.ts.map +1 -0
  91. package/dist/library/react/useNativeOwner.js +17 -0
  92. package/dist/library/react/useNativeOwner.js.map +1 -0
  93. package/dist/library/reset.css +1 -0
  94. package/dist/library/styles.css +2 -1
  95. package/dist/library/themes/components.d.ts +217 -0
  96. package/dist/library/themes/components.d.ts.map +1 -0
  97. package/dist/library/themes/components.js +229 -0
  98. package/dist/library/themes/components.js.map +1 -0
  99. package/dist/library/themes/default.d.ts +2 -0
  100. package/dist/library/themes/default.d.ts.map +1 -0
  101. package/dist/library/themes/default.js +4 -0
  102. package/dist/library/themes/default.js.map +1 -0
  103. package/dist/library/themes/defineTheme.d.ts +33 -0
  104. package/dist/library/themes/defineTheme.d.ts.map +1 -0
  105. package/dist/library/themes/defineTheme.js +98 -0
  106. package/dist/library/themes/defineTheme.js.map +1 -0
  107. package/dist/library/themes/expressive.d.ts +2 -0
  108. package/dist/library/themes/expressive.d.ts.map +1 -0
  109. package/dist/library/themes/expressive.js +132 -0
  110. package/dist/library/themes/expressive.js.map +1 -0
  111. package/dist/library/themes/glass.d.ts +2 -0
  112. package/dist/library/themes/glass.d.ts.map +1 -0
  113. package/dist/library/themes/glass.js +132 -0
  114. package/dist/library/themes/glass.js.map +1 -0
  115. package/dist/library/themes/index.d.ts +14 -0
  116. package/dist/library/themes/index.d.ts.map +1 -0
  117. package/dist/library/themes/index.js +21 -0
  118. package/dist/library/themes/index.js.map +1 -0
  119. package/dist/library/themes/jelly.d.ts +2 -0
  120. package/dist/library/themes/jelly.d.ts.map +1 -0
  121. package/dist/library/themes/jelly.js +130 -0
  122. package/dist/library/themes/jelly.js.map +1 -0
  123. package/dist/library/themes/preset-values.d.ts +4 -0
  124. package/dist/library/themes/preset-values.d.ts.map +1 -0
  125. package/dist/library/themes/preset-values.js +5 -0
  126. package/dist/library/themes/preset-values.js.map +1 -0
  127. package/dist/library/themes/radiant.d.ts +2 -0
  128. package/dist/library/themes/radiant.d.ts.map +1 -0
  129. package/dist/library/themes/radiant.js +129 -0
  130. package/dist/library/themes/radiant.js.map +1 -0
  131. package/dist/library/themes/sharp-3d.d.ts +2 -0
  132. package/dist/library/themes/sharp-3d.d.ts.map +1 -0
  133. package/dist/library/themes/sharp-3d.js +142 -0
  134. package/dist/library/themes/sharp-3d.js.map +1 -0
  135. package/dist/library/themes/soft-squircle.d.ts +2 -0
  136. package/dist/library/themes/soft-squircle.d.ts.map +1 -0
  137. package/dist/library/themes/soft-squircle.js +131 -0
  138. package/dist/library/themes/soft-squircle.js.map +1 -0
  139. package/dist/library/themes/ticket.d.ts +2 -0
  140. package/dist/library/themes/ticket.d.ts.map +1 -0
  141. package/dist/library/themes/ticket.js +141 -0
  142. package/dist/library/themes/ticket.js.map +1 -0
  143. package/dist/library/themes/tokens.d.ts +100 -0
  144. package/dist/library/themes/tokens.d.ts.map +1 -0
  145. package/dist/library/themes/tokens.js +171 -0
  146. package/dist/library/themes/tokens.js.map +1 -0
  147. package/dist/library/themes/types.d.ts +2 -0
  148. package/dist/library/themes/types.d.ts.map +1 -0
  149. package/dist/library/themes/types.js +2 -0
  150. package/dist/library/themes/types.js.map +1 -0
  151. package/docs/accessibility.md +189 -0
  152. package/docs/system.md +218 -0
  153. package/docs/theming.md +392 -0
  154. package/package.json +28 -11
  155. package/src/Accordion.tsx +235 -0
  156. package/src/Button.tsx +95 -15
  157. package/src/Card.tsx +143 -0
  158. package/src/Checkbox.tsx +189 -0
  159. package/src/Collapsible.tsx +193 -0
  160. package/src/Dialog.tsx +333 -0
  161. package/src/Field.tsx +293 -0
  162. package/src/Input.tsx +82 -0
  163. package/src/Link.tsx +95 -0
  164. package/src/RadioGroup.tsx +255 -0
  165. package/src/ThemeScope.tsx +64 -0
  166. package/src/actionStyles.ts +90 -0
  167. package/src/cn.ts +1 -10
  168. package/src/controlStyles.ts +19 -0
  169. package/src/index.ts +93 -1
  170. package/src/internal/events.ts +17 -0
  171. package/src/internal/ids.ts +5 -0
  172. package/src/internal/selection.ts +20 -0
  173. package/src/presentation.ts +12 -0
  174. package/src/react/useComposedRefs.ts +32 -0
  175. package/src/react/useControllableState.ts +50 -0
  176. package/src/react/useNativeOwner.ts +33 -0
  177. package/src/styles.css +2 -14
  178. package/src/themes/baseline.css +116 -0
  179. package/src/themes/components.ts +249 -0
  180. package/src/themes/default.ts +4 -0
  181. package/src/themes/defineTheme.ts +145 -0
  182. package/src/themes/expressive.ts +132 -0
  183. package/src/themes/glass.ts +135 -0
  184. package/src/themes/index.ts +33 -0
  185. package/src/themes/jelly.ts +130 -0
  186. package/src/themes/preset-values.ts +5 -0
  187. package/src/themes/radiant.ts +129 -0
  188. package/src/themes/sharp-3d.ts +142 -0
  189. package/src/themes/soft-squircle.ts +131 -0
  190. package/src/themes/ticket.ts +141 -0
  191. package/src/themes/tokens.ts +262 -0
  192. package/src/themes/types.ts +10 -0
@@ -0,0 +1,392 @@
1
+ # Theming Radiant
2
+
3
+ This is the theme authoring, token and migration reference. Start with the
4
+ [system guide](system.md) for shared composition, ownership and styling rules.
5
+
6
+ Radiant has one shared theme model: semantic tokens define the design system,
7
+ and component overrides describe deliberate exceptions. `Button` does not own
8
+ other components' typography, dimensions, shape, focus, or motion.
9
+
10
+ Import `@cognitap/radiant/styles.css` once. It supplies the complete neutral
11
+ light/dark baseline without a provider. `@cognitap/radiant/reset.css` is a
12
+ separate, optional global reset. Tailwind applications can instead use the
13
+ [source styling route](../README.md#with-tailwind); both routes consume the same
14
+ public theme variables.
15
+
16
+ ## Define and apply a theme
17
+
18
+ ```tsx
19
+ import '@cognitap/radiant/styles.css'
20
+ import { Button, Field, Input, ThemeScope, defineTheme } from '@cognitap/radiant'
21
+
22
+ const brand = defineTheme({
23
+ id: 'garden',
24
+ name: 'Garden',
25
+ tokens: {
26
+ color: { accent: '#166534', accentForeground: '#ffffff' },
27
+ typography: { family: 'system-ui, sans-serif' },
28
+ control: { radius: '0.75rem' },
29
+ surface: { radius: '1rem' }
30
+ },
31
+ components: {
32
+ button: { fontWeight: 650, pressScale: 0.97 }
33
+ },
34
+ modes: {
35
+ dark: {
36
+ tokens: { color: { accent: '#86efac', accentForeground: '#052e16' } }
37
+ }
38
+ }
39
+ })
40
+
41
+ function Settings() {
42
+ return (
43
+ <ThemeScope
44
+ theme={brand}
45
+ mode="system"
46
+ >
47
+ <Field label="Garden name">
48
+ <Input name="garden" />
49
+ </Field>
50
+ <Button>Save</Button>
51
+ </ThemeScope>
52
+ )
53
+ }
54
+ ```
55
+
56
+ `defineTheme({ id, name, tokens, components, modes })` accepts typed partial
57
+ values. `id` is a stable lowercase slug, such as `garden` or `garden-club`;
58
+ `name` is a nonempty display label. Select and persist identity by ID, never
59
+ by the label. The result is immutable, JSON-serializable theme data.
60
+
61
+ Unknown token groups, roles, component names, or override keys fail TypeScript
62
+ checks and throw at runtime. CSS lengths, colors, durations, and easings are
63
+ nonempty strings. Weights accept strings or numbers; numeric effects must be
64
+ finite, and opacity values must be between 0 and 1. CSS grammar and contrast
65
+ remain the author's responsibility: `var(--brand-accent)` is a valid value,
66
+ but Radiant cannot verify what that application variable resolves to.
67
+
68
+ For each mode the resolution order is **library mode defaults → common theme
69
+ values → that theme's mode values**. Missing dark values use the dark baseline
70
+ unless a common value already overrides them. Put a common color in `tokens`
71
+ only when it works in both modes, or supply its dark counterpart explicitly.
72
+
73
+ ## Scopes, mode, and overrides
74
+
75
+ `ThemeScope` renders a normal `div` and accepts its native props and ref. It
76
+ paints its canvas, foreground, and body typography within that subtree. It does
77
+ not change the document, install event listeners, load fonts, or persist a
78
+ preference. A native top-layer Dialog remains in its original scope.
79
+
80
+ - `theme={theme}` starts a fresh named theme from library defaults. Every shared
81
+ token is materialised and every omitted component override is reset to its
82
+ CSS fallback. An outer theme cannot leak its action font or press effect in.
83
+ - Omit `theme` to inherit the current theme. Omit `mode` to inherit the current
84
+ mode. At the application root, the stylesheet defaults to system preference.
85
+ - `mode="light"`, `"dark"`, or `"system"` selects appearance independently of
86
+ theme identity. System follows the CSS media query, so server markup and the
87
+ first client render agree. A mode-only scope resolves the current named theme
88
+ in its selected mode.
89
+ - An inner scope with neither `theme` nor `mode` follows ordinary CSS inheritance;
90
+ it does not establish a new theme. A root scope also paints the neutral canvas
91
+ and typography.
92
+ - Explicit `style` values win over generated values on the same scope host.
93
+ Known theme variables supplied inline to ancestor ThemeScopes are carried
94
+ through mode-only scopes. A new named theme clears these inherited exceptions.
95
+
96
+ Use `defaultTheme` for a complete reset, including component effects:
97
+
98
+ ```tsx
99
+ import { Button, ThemeScope, defaultTheme, ticket } from '@cognitap/radiant'
100
+
101
+ ;<ThemeScope
102
+ theme={ticket}
103
+ mode="light"
104
+ >
105
+ <Button>Ticket action</Button>
106
+ <ThemeScope theme={defaultTheme}>
107
+ <Button>Neutral action</Button>
108
+ </ThemeScope>
109
+ </ThemeScope>
110
+ ```
111
+
112
+ Use shared tokens for local changes that should affect multiple families:
113
+
114
+ ```tsx
115
+ <ThemeScope
116
+ theme={brand}
117
+ style={{ '--rad-control-radius': '1.25rem', padding: '2rem' }}
118
+ >
119
+ <Input aria-label="Garden name" />
120
+ <Button>Save</Button>
121
+ </ThemeScope>
122
+ ```
123
+
124
+ Ordinary CSS overrides inherit within their existing scope. A mode-only scope
125
+ re-materialises the selected theme, so token overrides from an intervening
126
+ stylesheet rule or an ordinary DOM wrapper are not automatically recovered
127
+ there. Put exceptions that must survive a mode change on a `ThemeScope` inline
128
+ `style`, or include them in the theme definition. No browser computed-style
129
+ snapshot is taken. Ordinary body styles, such as a locally changed font size,
130
+ still follow the cascade and inheritance appropriate to their host.
131
+
132
+ Components resolve **local component override → shared semantic role → neutral
133
+ baseline**. For example, `components.button.radius` overrides Button without
134
+ changing Input; `tokens.control.radius` changes both. Checkbox caps its inherited
135
+ radius at a quarter of its indicator size so it remains a box; an explicit
136
+ `components.checkbox.radius` still wins. Radio stays circular by default, even
137
+ under squircle or scoop control themes. Shared disabled opacity is applied once
138
+ to the relevant visual unit.
139
+
140
+ Input, Checkbox, and Radio derive their default control outline from the shared
141
+ border and foreground colors. This gives interactive boundaries more contrast
142
+ than passive surface dividers. Their explicit `borderColor`, invalid, disabled,
143
+ and focus overrides keep their normal precedence. Disabled selection marks use
144
+ the muted foreground unless the component supplies its own `mark` color.
145
+
146
+ Component overrides use the existing family configuration keys, grouped under
147
+ `button`, `link`, `field`, `input`, `checkbox`, `radio`, `radioGroup`, `dialog`,
148
+ `collapsible`, `accordion`, and `card`. Public declaration types are the
149
+ closed-key reference. `radioGroup.gap` controls group layout;
150
+ `radio.labelGap` controls spacing within a single option. Button-only fonts,
151
+ uppercase text, sheen, shadows, squash, and pressed shape belong under
152
+ `components.button`. Passive surfaces have their own shared surface tokens.
153
+
154
+ Public variable names are derived from the typed registry:
155
+
156
+ | Authoring path | CSS variable |
157
+ | ------------------------------ | ----------------------------- |
158
+ | `tokens.color.accent` | `--rad-color-accent` |
159
+ | `tokens.control.medium.height` | `--rad-control-medium-height` |
160
+ | `tokens.typography.family` | `--rad-typography-family` |
161
+ | `components.button.radius` | `--rad-button-radius` |
162
+ | `components.radioGroup.gap` | `--rad-radio-group-gap` |
163
+
164
+ Matching caller utilities merge with component defaults on the Tailwind route;
165
+ application CSS follows the normal cascade. Generated theme values are inline
166
+ custom properties, so a normal stylesheet declaration on that same host does
167
+ not override them. Put a token override on a descendant or use the host's
168
+ `style` prop. Internal variables beginning `--_` are implementation details.
169
+
170
+ ## Preserve functional styles
171
+
172
+ Appearance overrides must preserve closed Dialog/details visibility, dialog
173
+ geometry and scrolling, real control hit targets, and accessible names. Keep
174
+ focus, invalid, disabled, and pending cues visible. The library retains
175
+ forced-colors system colors and reduced-motion alternatives; a theme must not
176
+ erase them with replacement CSS. See the [system guide's functional CSS obligations](system.md#preserve-behavior-when-customising)
177
+ for host replacement and the behavior that overrides must preserve. Importing the optional reset is not required for
178
+ these behaviors.
179
+
180
+ ## Presets and fonts
181
+
182
+ The readonly `themes` registry contains these presets, exported individually
183
+ from `@cognitap/radiant`. Each has a deliberate light and dark palette.
184
+
185
+ | Stable ID | Display name | Named export | Shared font family | Action exception |
186
+ | --------------- | ------------- | -------------- | ------------------ | ------------------------------------ |
187
+ | `radiant` | Radiant | `radiant` | Inter | Weight 550 |
188
+ | `default` | Default | `defaultTheme` | System sans | Library baseline |
189
+ | `soft-squircle` | Soft squircle | `soft` | Nunito | Weight 800 |
190
+ | `expressive` | Expressive | `expressive` | Poppins | Weight 600 |
191
+ | `glass` | Glass | `glass` | Manrope | Weight 700; backdrop filter |
192
+ | `sharp-3d` | Sharp 3D | `sharp` | System sans | Archivo Black, weight 400, uppercase |
193
+ | `jelly` | Jelly | `jelly` | Baloo 2 | Weight 700 |
194
+ | `ticket` | Ticket | `ticket` | Barlow Condensed | Weight 600, uppercase |
195
+
196
+ All families have `system-ui, sans-serif` fallbacks. Preset body weight is 400;
197
+ load the label and heading weights 600 and 700 as well as the action weight
198
+ listed above. Default uses baseline label/heading weights 550/600. Radiant's
199
+ Inter action weight 550 requires a variable font or an appropriate supplied
200
+ face; the browser chooses an available weight otherwise.
201
+
202
+ Fonts are application assets. Load the named families with your font loader or
203
+ self-hosted `@font-face` rules before showing the themed UI. Defining or choosing
204
+ a theme never downloads a font. Storybook's font loading belongs to Storybook,
205
+ not the package. `Theme` has no `fonts` field or font-loading API.
206
+
207
+ Glass uses a gradient `surface.canvas` and translucent `color.surface`.
208
+ `components.dialog.backdropFilter` frosts content behind the dialog panel;
209
+ `components.dialog.backdrop` paints the surrounding modal overlay. Button's
210
+ existing `backdrop` override is also a filter and remains independent. Ticket
211
+ uses a compact, solid checkbox outline so small indicators
212
+ remain legible alongside its scooped, dashed controls and surfaces.
213
+ Shape uses CSS `corner-shape`; browsers that do not support it
214
+ retain ordinary rounded corners. A palette definition does not certify contrast
215
+ for arbitrary content, custom backgrounds, or translucent combinations.
216
+
217
+ ## Shared token reference
218
+
219
+ These 66 roles and concrete neutral defaults come from
220
+ [`src/themes/tokens.ts`](../src/themes/tokens.ts). CSS names are `--rad-` plus the
221
+ kebab-case dotted path. Values shown in both modes differ only where listed.
222
+ `color` values are CSS colors; `surface.canvas` and `surface.backdrop` are full
223
+ CSS backgrounds and may be gradients. `components.button.backdrop` and
224
+ `components.dialog.backdropFilter` are CSS backdrop-filter values. Lengths and
225
+ durations remain CSS strings; opacity is numeric.
226
+
227
+ | Path | Light default | Dark default |
228
+ | ------------------------------ | ------------------------------------ | ------------------------------------ |
229
+ | `color.surface` | `oklch(1 0 0)` | `oklch(0.21 0.006 286)` |
230
+ | `color.foreground` | `oklch(0.21 0.006 286)` | `oklch(0.985 0 0)` |
231
+ | `color.mutedForeground` | `oklch(0.45 0.01 286)` | `oklch(0.75 0.01 286)` |
232
+ | `color.border` | `oklch(0.885 0.005 286)` | `oklch(0.4 0.008 286)` |
233
+ | `color.placeholder` | `oklch(0.5 0.01 286)` | `oklch(0.7 0.01 286)` |
234
+ | `color.disabledBackground` | `oklch(0.96 0.005 286)` | `oklch(0.26 0.006 286)` |
235
+ | `color.disabledBorder` | `oklch(0.88 0.005 286)` | `oklch(0.38 0.006 286)` |
236
+ | `color.invalid` | `oklch(0.56 0.19 25)` | `oklch(0.75 0.16 25)` |
237
+ | `color.focus` | `oklch(0.55 0.13 255)` | `oklch(0.75 0.13 255)` |
238
+ | `color.accent` | `oklch(0.21 0.006 286)` | `oklch(0.92 0.005 286)` |
239
+ | `color.accentForeground` | `oklch(0.985 0 0)` | `oklch(0.21 0.006 286)` |
240
+ | `color.neutral` | `oklch(0.955 0.004 286)` | `oklch(0.3 0.006 286)` |
241
+ | `color.neutralForeground` | `oklch(0.21 0.006 286)` | `oklch(0.985 0 0)` |
242
+ | `color.warning` | `oklch(0.8 0.14 78)` | Same |
243
+ | `color.warningForeground` | `oklch(0.3 0.07 55)` | Same |
244
+ | `color.danger` | `oklch(0.56 0.19 25)` | `oklch(0.72 0.17 25)` |
245
+ | `color.dangerForeground` | `oklch(0.99 0 0)` | `oklch(0.2 0.04 25)` |
246
+ | `typography.family` | `system-ui, sans-serif` | Same |
247
+ | `typography.bodySize` | `0.875rem` | Same |
248
+ | `typography.smallSize` | `0.8125rem` | Same |
249
+ | `typography.headingSize` | `1.125rem` | Same |
250
+ | `typography.bodyWeight` | `400` | Same |
251
+ | `typography.labelWeight` | `550` | Same |
252
+ | `typography.headingWeight` | `600` | Same |
253
+ | `typography.letterSpacing` | `-0.011em` | Same |
254
+ | `control.small.height` | `2rem` | Same |
255
+ | `control.small.paddingInline` | `0.75rem` | Same |
256
+ | `control.small.fontSize` | `0.8125rem` | Same |
257
+ | `control.small.indicatorSize` | `1rem` | Same |
258
+ | `control.medium.height` | `2.5rem` | Same |
259
+ | `control.medium.paddingInline` | `1rem` | Same |
260
+ | `control.medium.fontSize` | `0.875rem` | Same |
261
+ | `control.medium.indicatorSize` | `1.125rem` | Same |
262
+ | `control.large.height` | `3rem` | Same |
263
+ | `control.large.paddingInline` | `1.375rem` | Same |
264
+ | `control.large.fontSize` | `0.9375rem` | Same |
265
+ | `control.large.indicatorSize` | `1.25rem` | Same |
266
+ | `control.radius` | `0.5rem` | Same |
267
+ | `control.cornerShape` | `round` | Same |
268
+ | `control.borderWidth` | `1px` | Same |
269
+ | `control.borderStyle` | `solid` | Same |
270
+ | `surface.canvas` | `oklch(1 0 0)` | `oklch(0.16 0.006 286)` |
271
+ | `surface.radius` | `0.75rem` | Same |
272
+ | `surface.cornerShape` | `round` | Same |
273
+ | `surface.borderWidth` | `1px` | Same |
274
+ | `surface.borderStyle` | `solid` | Same |
275
+ | `surface.padding` | `1.5rem` | Same |
276
+ | `surface.gap` | `1rem` | Same |
277
+ | `surface.shadow` | `0 1px 2px 0 rgb(0 0 0 / 0.06)` | `0 1px 2px 0 rgb(0 0 0 / 0.25)` |
278
+ | `surface.overlayShadow` | `0 24px 64px -16px rgb(0 0 0 / 0.3)` | `0 24px 64px -16px rgb(0 0 0 / 0.6)` |
279
+ | `surface.backdrop` | `rgb(0 0 0 / 0.45)` | `rgb(0 0 0 / 0.65)` |
280
+ | `focus.width` | `2px` | Same |
281
+ | `focus.offset` | `2px` | Same |
282
+ | `focus.style` | `solid` | Same |
283
+ | `motion.pressDuration` | `80ms` | Same |
284
+ | `motion.pressEase` | `cubic-bezier(0.3, 0, 0, 1)` | Same |
285
+ | `motion.releaseDuration` | `160ms` | Same |
286
+ | `motion.releaseEase` | `cubic-bezier(0.2, 0.8, 0.2, 1)` | Same |
287
+ | `motion.colorDuration` | `150ms` | Same |
288
+ | `motion.disclosureDuration` | `150ms` | Same |
289
+ | `spacing.labelGap` | `0.5rem` | Same |
290
+ | `spacing.fieldGap` | `0.375rem` | Same |
291
+ | `spacing.groupGap` | `0.75rem` | Same |
292
+ | `spacing.headerGap` | `0.375rem` | Same |
293
+ | `spacing.footerGap` | `0.5rem` | Same |
294
+ | `state.disabledOpacity` | `0.5` | Same |
295
+
296
+ ## Migration from Button-centred themes
297
+
298
+ This is a breaking CSS-token migration. Use the JavaScript and stylesheet from
299
+ the same version; do not mix new theme data with an old compiled stylesheet.
300
+
301
+ 1. Replace wrappers such as `<div style={theme.style}>` with
302
+ `<ThemeScope theme={theme}>`. `Theme.style`, `Theme.surface`, and the
303
+ `radiantTheme` style alias are removed. Use `radiant` with `ThemeScope`, which
304
+ chooses the canvas for the active mode. A hand-written `{ name, style }`
305
+ object is no longer a `Theme`: author it with `defineTheme`.
306
+ 2. Move shared settings out of `buttonTheme` into `tokens`: font family into
307
+ `typography.family`, heights/padding/font sizes into the matching `control`
308
+ size group, radius/shape/borders into `control` and `surface`, focus into
309
+ `color.focus`/`focus`, and timing into `motion`. Input, Checkbox, Radio,
310
+ Dialog, Collapsible, Card, and Link no longer fall back through Button's
311
+ overrides. Input's native numeric `size` attribute is unchanged.
312
+ 3. Replace the removed `buttonTheme`, `linkTheme`, `fieldTheme`, `inputTheme`,
313
+ `checkboxTheme`, `radioTheme`, `dialogTheme`, `collapsibleTheme`,
314
+ `accordionTheme`, and `cardTheme` helpers with `components.<family>` in
315
+ `defineTheme`. Their corresponding `*Theme` type aliases are removed; use
316
+ `ThemeComponentOverrides` or an indexed family type such as
317
+ `NonNullable<ThemeComponentOverrides['button']>` for reusable configuration.
318
+ For a one-off host or named part, use `style` with typed `--rad-*` variables:
319
+
320
+ ```tsx
321
+ import { Button, type ThemeStyle } from '@cognitap/radiant'
322
+
323
+ const local: ThemeStyle = { '--rad-button-radius': '1rem' }
324
+
325
+ ;<Button style={local}>Save</Button>
326
+ ```
327
+
328
+ A local style is a partial override; a named `ThemeScope` deliberately resets
329
+ omitted settings to the shared baseline. Do not spread a resolved mode map
330
+ onto a wrapper as a replacement for ThemeScope's theme/mode inheritance.
331
+
332
+ 4. Rename direct CSS overrides using the following map. Button's `focusColor`
333
+ maps to `--rad-button-focus-color`; it no longer changes shared focus.
334
+ Move the old `radioTheme({ gap })` group shortcut to
335
+ `components.radioGroup.gap`; `components.radio.labelGap` remains option-local.
336
+ 5. Remove `glowHover`: it never had a rendering effect and is rejected by
337
+ `defineTheme`. The library no longer supplies `--ease-spring`, `--ease-snap`,
338
+ or `--ease-settle`; put the required literal `linear(...)`/`cubic-bezier(...)`
339
+ curve in the motion token or a deliberate component exception. Application
340
+ CSS variables are also supported when your application defines them.
341
+
342
+ | Old variable | Replacement |
343
+ | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
344
+ | `--color-background` | `--rad-color-surface` (canvas is `--rad-surface-canvas`) |
345
+ | `--color-foreground`, `--color-border`, `--color-focus` | Corresponding `--rad-color-*` role |
346
+ | `--color-primary`, `--color-primary-foreground` | `--rad-color-accent`, `--rad-color-accent-foreground` |
347
+ | `--color-secondary`, `--color-secondary-foreground` | `--rad-color-neutral`, `--rad-color-neutral-foreground` |
348
+ | `--color-warning`, `--color-warning-foreground` | `--rad-color-warning`, `--rad-color-warning-foreground` |
349
+ | `--color-destructive`, `--color-destructive-foreground` | `--rad-color-danger`, `--rad-color-danger-foreground` |
350
+ | `--radius-control` | `--rad-control-radius` |
351
+ | `--button-*`, `--input-*`, `--field-*`, other family overrides | `--rad-button-*`, `--rad-input-*`, `--rad-field-*`, corresponding prefixed family |
352
+ | `--radio-gap` | `--rad-radio-group-gap` |
353
+ | `--button-focus-color` (stale consumers) | `--rad-color-focus` for shared focus; `--rad-button-focus-color` for Button alone |
354
+
355
+ The source stylesheet no longer registers `background`, `foreground`, `border`,
356
+ `primary`, `secondary`, `warning`, `destructive`, or `focus` color aliases, or the
357
+ `control` radius alias. Replace classes such as `bg-primary` with
358
+ `bg-(--rad-color-accent)` and `rounded-control` with
359
+ `rounded-(--rad-control-radius)`, or define your own application aliases.
360
+
361
+ The theme registry is readonly; choose a preset by
362
+ `theme.id` rather than editing the registry or relying on its display name.
363
+ Storybook's global Theme and Mode controls use this same preset registry.
364
+ Button and Link now share `variant`, `tone`, and `controlSize`; see the
365
+ [README action migration table](../README.md#action-api-migration-breaking).
366
+ Action-only geometry, elevation and motion remain deliberate Button component
367
+ overrides consumed by both Button and action-shaped Link. Inline/subtle Link
368
+ retains its own decoration and focus overrides. Soft and unfilled ink mixes the
369
+ selected tone toward the scope foreground; explicit Link colour overrides win.
370
+
371
+ ### Cleanup inventory (DEV-132)
372
+
373
+ | Area | Disposition |
374
+ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
375
+ | Ten family helpers/types, `radiantTheme`, resolved `style`/`surface` fields | Removed directly under the experimental 0.x policy; replacements above |
376
+ | Old unprefixed color/radius aliases and ambient easing variables | Removed from the source and compiled styling routes |
377
+ | Old action variants, `size`/`radius` presentation props and `data-size` | Already retired by the action/form migrations; no compatibility path restored |
378
+ | Shared semantic tokens and typed `components` overrides | Retained as the canonical theme authoring contract |
379
+ | `ThemeStyle`, native props, named parts, state hooks and `render` | Retained for local styling and native composition |
380
+ | Button and action-shaped Link presentation | One private `actionStyles` implementation; action-only Button slots are intentionally shared |
381
+ | Dialog actions and Accordion sections | Compose Button and Collapsible respectively; no parallel action/disclosure paint |
382
+
383
+ Every component slot in the registry has a reader. Input, Field, Checkbox,
384
+ Radio, Dialog, Collapsible and Card resolve their own override, then a shared
385
+ role or neutral default. Only Button and action-shaped Link consume action
386
+ slots; inline/subtle Link keeps its own decoration/focus contract. Existing
387
+ preset values and light/dark mode maps are unchanged by this cleanup.
388
+
389
+ This removes compatibility paths without publishing a package. The next
390
+ release must carry these breaking migration notes under the
391
+ [release policy](../RELEASE_POLICY.md); earlier changelog entries describe their
392
+ delivery-time behavior.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cognitap/radiant",
3
- "version": "0.0.1",
3
+ "version": "0.0.3",
4
4
  "description": "React interaction components and presentation primitives",
5
5
  "homepage": "https://github.com/cognitap/radiant#readme",
6
6
  "bugs": {
@@ -15,10 +15,14 @@
15
15
  "LICENSE",
16
16
  "CHANGELOG.md",
17
17
  "RELEASE_POLICY.md",
18
+ "docs/system.md",
19
+ "docs/accessibility.md",
20
+ "docs/theming.md",
18
21
  "dist/library",
19
22
  "src/**/*.ts",
20
23
  "src/**/*.tsx",
21
24
  "src/styles.css",
25
+ "src/themes/baseline.css",
22
26
  "!src/**/*.stories.*",
23
27
  "!src/**/*.test.*"
24
28
  ],
@@ -41,28 +45,35 @@
41
45
  "tag": "latest"
42
46
  },
43
47
  "dependencies": {
48
+ "class-variance-authority": "0.7.1",
44
49
  "cn": "0.4.0"
45
50
  },
46
51
  "devDependencies": {
47
52
  "@storybook/addon-a11y": "10.6.1",
48
53
  "@storybook/addon-docs": "10.6.1",
54
+ "@storybook/addon-vitest": "10.6.1",
49
55
  "@storybook/react-vite": "10.6.1",
50
56
  "@tailwindcss/cli": "4.3.3",
51
57
  "@tailwindcss/vite": "4.3.3",
58
+ "@tanstack/react-form": "1.33.5",
52
59
  "@types/node": "26.6.5",
53
60
  "@types/react": "19.3.0",
54
61
  "@types/react-dom": "19.3.0",
62
+ "@vitest/browser-playwright": "5.0.5",
55
63
  "husky": "9.1.7",
64
+ "jsdom": "30.1.3",
56
65
  "lint-staged": "17.6.0",
57
66
  "oxfmt": "0.72.0",
58
67
  "oxlint": "1.87.0",
68
+ "playwright": "1.64.1",
59
69
  "react": "19.3.0",
60
70
  "react-dom": "19.3.0",
61
71
  "rimraf": "6.1.3",
62
72
  "storybook": "10.6.1",
63
73
  "tailwindcss": "4.3.3",
64
74
  "typescript": "6.0.3",
65
- "vite": "8.3.4"
75
+ "vite": "8.3.4",
76
+ "vitest": "5.0.5"
66
77
  },
67
78
  "peerDependencies": {
68
79
  "react": "^19.3.0",
@@ -81,21 +92,27 @@
81
92
  }
82
93
  },
83
94
  "scripts": {
84
- "storybook": "storybook dev --host 127.0.0.1 --port 6006 --no-open --disable-telemetry",
95
+ "storybook": "pnpm theme:generate && storybook dev --host 127.0.0.1 --port 6006 --no-open --disable-telemetry",
85
96
  "build": "rimraf dist/library && pnpm build:js && pnpm build:css",
86
97
  "build:js": "tsc -p tsconfig.build.json",
87
- "build:css": "tailwindcss -i styles/library.css -o dist/library/styles.css --minify && tailwindcss -i styles/reset.css -o dist/library/reset.css --minify",
98
+ "build:css": "pnpm theme:generate && tailwindcss -i styles/library.css -o dist/library/styles.css --minify && tailwindcss -i styles/reset.css -o dist/library/reset.css --minify && node scripts/preserve-css-layer-order.mjs",
88
99
  "watch": "pnpm run --parallel '/^watch:/'",
89
100
  "watch:js": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
90
- "watch:styles": "tailwindcss -i styles/library.css -o dist/library/styles.css --watch=always",
91
- "build:storybook": "storybook build --output-dir dist/storybook --disable-telemetry",
101
+ "watch:styles": "pnpm theme:generate && tailwindcss -i styles/library.css -o dist/library/styles.css --watch=always",
102
+ "build:storybook": "pnpm theme:generate && storybook build --output-dir dist/storybook --disable-telemetry",
92
103
  "test": "pnpm build && node --test tests/*.test.mjs && node scripts/verify-package.mjs",
93
104
  "test:package": "pnpm build && node scripts/verify-package.mjs",
94
- "typecheck": "tsc --noEmit",
105
+ "typecheck": "tsc --noEmit && pnpm typecheck:contracts",
106
+ "typecheck:contracts": "tsc -p docs/contracts/tsconfig.json",
95
107
  "lint": "oxlint --deny-warnings",
96
- "fmt": "oxfmt",
97
- "fmt:check": "oxfmt --check",
98
- "check": "pnpm fmt:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build:storybook",
99
- "release:prepare": "node scripts/prepare-release.mjs"
108
+ "format": "oxfmt",
109
+ "format:check": "oxfmt --check",
110
+ "check": "pnpm theme:check && pnpm format:check && pnpm lint && pnpm typecheck && pnpm test --styles --compositions && pnpm build:storybook && pnpm test:browser",
111
+ "test:compositions": "pnpm build && node scripts/verify-package.mjs --compositions",
112
+ "release:prepare": "node scripts/prepare-release.mjs",
113
+ "theme:generate": "node scripts/generate-theme-css.mjs",
114
+ "theme:check": "node scripts/generate-theme-css.mjs --check",
115
+ "watch:theme": "node scripts/generate-theme-css.mjs --watch",
116
+ "test:browser": "pnpm theme:generate && node scripts/record-browser-environment.mjs && vitest run"
100
117
  }
101
118
  }