@cognitap/radiant 0.0.6 → 0.0.8

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 (196) hide show
  1. package/CHANGELOG.md +82 -395
  2. package/README.md +41 -1014
  3. package/RELEASE_POLICY.md +3 -3
  4. package/dist/library/Accordion.d.ts +3 -0
  5. package/dist/library/Accordion.d.ts.map +1 -1
  6. package/dist/library/Accordion.js +1 -1
  7. package/dist/library/Accordion.js.map +1 -1
  8. package/dist/library/Button.d.ts +5 -0
  9. package/dist/library/Button.d.ts.map +1 -1
  10. package/dist/library/Button.js +8 -7
  11. package/dist/library/Button.js.map +1 -1
  12. package/dist/library/Card.d.ts +2 -0
  13. package/dist/library/Card.d.ts.map +1 -1
  14. package/dist/library/Card.js +1 -1
  15. package/dist/library/Card.js.map +1 -1
  16. package/dist/library/Checkbox.d.ts +5 -0
  17. package/dist/library/Checkbox.d.ts.map +1 -1
  18. package/dist/library/Checkbox.js +3 -2
  19. package/dist/library/Checkbox.js.map +1 -1
  20. package/dist/library/Collapsible.d.ts +4 -0
  21. package/dist/library/Collapsible.d.ts.map +1 -1
  22. package/dist/library/Collapsible.js +22 -4
  23. package/dist/library/Collapsible.js.map +1 -1
  24. package/dist/library/Dialog.d.ts +3 -0
  25. package/dist/library/Dialog.d.ts.map +1 -1
  26. package/dist/library/Dialog.js.map +1 -1
  27. package/dist/library/Field.d.ts +8 -0
  28. package/dist/library/Field.d.ts.map +1 -1
  29. package/dist/library/Field.js +2 -0
  30. package/dist/library/Field.js.map +1 -1
  31. package/dist/library/Input.d.ts +3 -0
  32. package/dist/library/Input.d.ts.map +1 -1
  33. package/dist/library/Input.js +1 -0
  34. package/dist/library/Input.js.map +1 -1
  35. package/dist/library/Link.d.ts +5 -0
  36. package/dist/library/Link.d.ts.map +1 -1
  37. package/dist/library/Link.js.map +1 -1
  38. package/dist/library/RadioGroup.d.ts +8 -0
  39. package/dist/library/RadioGroup.d.ts.map +1 -1
  40. package/dist/library/RadioGroup.js +4 -2
  41. package/dist/library/RadioGroup.js.map +1 -1
  42. package/dist/library/Select.d.ts +87 -0
  43. package/dist/library/Select.d.ts.map +1 -0
  44. package/dist/library/Select.js +454 -0
  45. package/dist/library/Select.js.map +1 -0
  46. package/dist/library/cn.d.ts.map +1 -1
  47. package/dist/library/cn.js +20 -3
  48. package/dist/library/cn.js.map +1 -1
  49. package/dist/library/examples/expressive.d.ts +4 -0
  50. package/dist/library/examples/expressive.d.ts.map +1 -0
  51. package/dist/library/{themes → examples}/expressive.js +4 -3
  52. package/dist/library/examples/expressive.js.map +1 -0
  53. package/dist/library/examples/glass.d.ts +4 -0
  54. package/dist/library/examples/glass.d.ts.map +1 -0
  55. package/dist/library/{themes → examples}/glass.js +9 -3
  56. package/dist/library/examples/glass.js.map +1 -0
  57. package/dist/library/examples/index.d.ts +13 -0
  58. package/dist/library/examples/index.d.ts.map +1 -0
  59. package/dist/library/examples/index.js +32 -0
  60. package/dist/library/examples/index.js.map +1 -0
  61. package/dist/library/examples/jelly.d.ts +4 -0
  62. package/dist/library/examples/jelly.d.ts.map +1 -0
  63. package/dist/library/{themes → examples}/jelly.js +4 -3
  64. package/dist/library/examples/jelly.js.map +1 -0
  65. package/dist/library/examples/preset-values.d.ts.map +1 -0
  66. package/dist/library/examples/preset-values.js.map +1 -0
  67. package/dist/library/examples/radiant.d.ts +4 -0
  68. package/dist/library/examples/radiant.d.ts.map +1 -0
  69. package/dist/library/{themes → examples}/radiant.js +4 -3
  70. package/dist/library/examples/radiant.js.map +1 -0
  71. package/dist/library/examples/sharp-3d.d.ts +4 -0
  72. package/dist/library/examples/sharp-3d.d.ts.map +1 -0
  73. package/dist/library/{themes → examples}/sharp-3d.js +4 -3
  74. package/dist/library/examples/sharp-3d.js.map +1 -0
  75. package/dist/library/examples/soft-squircle.d.ts +4 -0
  76. package/dist/library/examples/soft-squircle.d.ts.map +1 -0
  77. package/dist/library/{themes → examples}/soft-squircle.js +4 -3
  78. package/dist/library/examples/soft-squircle.js.map +1 -0
  79. package/dist/library/examples/ticket.d.ts +4 -0
  80. package/dist/library/examples/ticket.d.ts.map +1 -0
  81. package/dist/library/{themes → examples}/ticket.js +4 -3
  82. package/dist/library/examples/ticket.js.map +1 -0
  83. package/dist/library/index.d.ts +3 -1
  84. package/dist/library/index.d.ts.map +1 -1
  85. package/dist/library/index.js +2 -1
  86. package/dist/library/index.js.map +1 -1
  87. package/dist/library/internal/select.d.ts +37 -0
  88. package/dist/library/internal/select.d.ts.map +1 -0
  89. package/dist/library/internal/select.js +42 -0
  90. package/dist/library/internal/select.js.map +1 -0
  91. package/dist/library/motion/MotionLink.d.ts +1 -0
  92. package/dist/library/motion/MotionLink.d.ts.map +1 -1
  93. package/dist/library/motion/MotionLink.js +9 -10
  94. package/dist/library/motion/MotionLink.js.map +1 -1
  95. package/dist/library/motion/host.d.ts +7 -3
  96. package/dist/library/motion/host.d.ts.map +1 -1
  97. package/dist/library/motion/host.js +13 -5
  98. package/dist/library/motion/host.js.map +1 -1
  99. package/dist/library/motion/popup.d.ts +5 -0
  100. package/dist/library/motion/popup.d.ts.map +1 -0
  101. package/dist/library/motion/popup.js +60 -0
  102. package/dist/library/motion/popup.js.map +1 -0
  103. package/dist/library/motion/press.d.ts.map +1 -1
  104. package/dist/library/motion/press.js +41 -14
  105. package/dist/library/motion/press.js.map +1 -1
  106. package/dist/library/motion/pressPolicy.d.ts.map +1 -1
  107. package/dist/library/motion/pressPolicy.js +2 -2
  108. package/dist/library/motion/pressPolicy.js.map +1 -1
  109. package/dist/library/motion/react.d.ts.map +1 -1
  110. package/dist/library/motion/react.js +3 -1
  111. package/dist/library/motion/react.js.map +1 -1
  112. package/dist/library/motion/transitions.d.ts.map +1 -1
  113. package/dist/library/motion/transitions.js +48 -15
  114. package/dist/library/motion/transitions.js.map +1 -1
  115. package/dist/library/react/useControllableState.d.ts +1 -0
  116. package/dist/library/react/useControllableState.d.ts.map +1 -1
  117. package/dist/library/react/useControllableState.js +8 -1
  118. package/dist/library/react/useControllableState.js.map +1 -1
  119. package/dist/library/selectStyles.d.ts +4 -0
  120. package/dist/library/selectStyles.d.ts.map +1 -0
  121. package/dist/library/selectStyles.js +32 -0
  122. package/dist/library/selectStyles.js.map +1 -0
  123. package/dist/library/styles.css +1 -1
  124. package/dist/library/themes/components.d.ts +24 -0
  125. package/dist/library/themes/components.d.ts.map +1 -1
  126. package/dist/library/themes/components.js +24 -0
  127. package/dist/library/themes/components.js.map +1 -1
  128. package/dist/library/themes/index.d.ts +1 -11
  129. package/dist/library/themes/index.d.ts.map +1 -1
  130. package/dist/library/themes/index.js +1 -19
  131. package/dist/library/themes/index.js.map +1 -1
  132. package/docs/accessibility.md +76 -142
  133. package/docs/architecture.md +208 -0
  134. package/docs/motion.md +115 -396
  135. package/docs/theming.md +275 -882
  136. package/package.json +9 -5
  137. package/src/Accordion.tsx +4 -1
  138. package/src/Button.tsx +13 -7
  139. package/src/Card.tsx +3 -1
  140. package/src/Checkbox.tsx +7 -2
  141. package/src/Collapsible.tsx +28 -4
  142. package/src/Dialog.tsx +3 -0
  143. package/src/Field.tsx +8 -0
  144. package/src/Input.tsx +3 -0
  145. package/src/Link.tsx +5 -0
  146. package/src/RadioGroup.tsx +10 -2
  147. package/src/Select.tsx +781 -0
  148. package/src/cn.ts +20 -3
  149. package/src/{themes → examples}/expressive.ts +5 -3
  150. package/src/{themes → examples}/glass.ts +10 -3
  151. package/src/examples/index.ts +35 -0
  152. package/src/{themes → examples}/jelly.ts +5 -3
  153. package/src/{themes → examples}/radiant.ts +5 -3
  154. package/src/{themes → examples}/sharp-3d.ts +5 -3
  155. package/src/{themes → examples}/soft-squircle.ts +5 -3
  156. package/src/{themes → examples}/ticket.ts +5 -3
  157. package/src/index.ts +28 -13
  158. package/src/internal/select.ts +80 -0
  159. package/src/motion/MotionLink.tsx +16 -11
  160. package/src/motion/host.ts +16 -7
  161. package/src/motion/popup.ts +55 -0
  162. package/src/motion/press.ts +32 -12
  163. package/src/motion/pressPolicy.ts +4 -2
  164. package/src/motion/react.ts +3 -1
  165. package/src/motion/transitions.ts +45 -14
  166. package/src/react/useControllableState.ts +7 -1
  167. package/src/selectStyles.ts +34 -0
  168. package/src/themes/components.ts +24 -0
  169. package/src/themes/index.ts +1 -22
  170. package/dist/library/themes/expressive.d.ts +0 -2
  171. package/dist/library/themes/expressive.d.ts.map +0 -1
  172. package/dist/library/themes/expressive.js.map +0 -1
  173. package/dist/library/themes/glass.d.ts +0 -2
  174. package/dist/library/themes/glass.d.ts.map +0 -1
  175. package/dist/library/themes/glass.js.map +0 -1
  176. package/dist/library/themes/jelly.d.ts +0 -2
  177. package/dist/library/themes/jelly.d.ts.map +0 -1
  178. package/dist/library/themes/jelly.js.map +0 -1
  179. package/dist/library/themes/preset-values.d.ts.map +0 -1
  180. package/dist/library/themes/preset-values.js.map +0 -1
  181. package/dist/library/themes/radiant.d.ts +0 -2
  182. package/dist/library/themes/radiant.d.ts.map +0 -1
  183. package/dist/library/themes/radiant.js.map +0 -1
  184. package/dist/library/themes/sharp-3d.d.ts +0 -2
  185. package/dist/library/themes/sharp-3d.d.ts.map +0 -1
  186. package/dist/library/themes/sharp-3d.js.map +0 -1
  187. package/dist/library/themes/soft-squircle.d.ts +0 -2
  188. package/dist/library/themes/soft-squircle.d.ts.map +0 -1
  189. package/dist/library/themes/soft-squircle.js.map +0 -1
  190. package/dist/library/themes/ticket.d.ts +0 -2
  191. package/dist/library/themes/ticket.d.ts.map +0 -1
  192. package/dist/library/themes/ticket.js.map +0 -1
  193. package/docs/system.md +0 -264
  194. /package/dist/library/{themes → examples}/preset-values.d.ts +0 -0
  195. /package/dist/library/{themes → examples}/preset-values.js +0 -0
  196. /package/src/{themes → examples}/preset-values.ts +0 -0
package/docs/theming.md CHANGED
@@ -1,25 +1,20 @@
1
- # Theming Radiant
1
+ # Theming
2
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.
3
+ Radiant has one theme model. Shared tokens define the design system, and
4
+ component overrides are deliberate exceptions. For how this fits the rest of the
5
+ library, see [architecture](architecture.md).
5
6
 
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.
7
+ Import `@cognitap/radiant/styles.css` once. It gives every component a neutral
8
+ light and dark baseline without a provider. Tailwind applications can use the
9
+ [source route](../README.md#with-tailwind) instead; both read the same theme
10
+ variables.
9
11
 
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
12
+ ## Make a theme
17
13
 
18
14
  ```tsx
19
- import '@cognitap/radiant/styles.css'
20
- import { Button, Field, Input, ThemeScope, defineTheme } from '@cognitap/radiant'
15
+ import { defineTheme } from '@cognitap/radiant'
21
16
 
22
- const brand = defineTheme({
17
+ const garden = defineTheme({
23
18
  id: 'garden',
24
19
  name: 'Garden',
25
20
  tokens: {
@@ -32,813 +27,306 @@ const brand = defineTheme({
32
27
  button: { fontWeight: 650, pressScale: 0.97 }
33
28
  },
34
29
  modes: {
35
- dark: {
36
- tokens: { color: { accent: '#86efac', accentForeground: '#052e16' } }
37
- }
30
+ dark: { tokens: { color: { accent: '#86efac', accentForeground: '#052e16' } } }
38
31
  }
39
32
  })
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
33
  ```
55
34
 
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.
35
+ `id` is a stable lowercase slug; store and select themes by it. `name` is the
36
+ display label. Every field is a typed partial override of the library defaults,
37
+ and the result is immutable, JSON-serializable data.
67
38
 
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.
39
+ Unknown groups, roles, components or keys fail the type check and throw at
40
+ runtime. Values are CSS strings, weights may be numbers, and opacities are
41
+ numbers from 0 to 1. Radiant does not check CSS grammar or contrast:
42
+ `var(--brand)` is accepted as is.
72
43
 
73
- ## Portable workshop documents
44
+ Each mode resolves as **library mode defaults → common values → that mode's
45
+ values**. Put a color in common `tokens` only if it works in both modes;
46
+ otherwise give its dark value too.
74
47
 
75
- `ThemeDocument` is the versioned authoring format for the public theme workshop.
76
- It keeps authored values and editor metadata; `Theme` remains the resolved data
77
- accepted by `ThemeScope`. Radiant owns validation, section updates and compilation.
78
- The documentation application owns selection, undo history, persistence and UI.
79
- These APIs are unreleased until the next package publication.
48
+ ## Apply it
80
49
 
81
50
  ```tsx
82
- import {
83
- ThemeScope,
84
- themeDocumentFromDefinition,
85
- updateThemeDocument,
86
- compileThemeDocument,
87
- exportThemeSections,
88
- parseThemeDocument
89
- } from '@cognitap/radiant'
90
-
91
- const initial = themeDocumentFromDefinition({
92
- id: 'garden',
93
- name: 'Garden',
94
- tokens: {
95
- typography: { family: 'system-ui, sans-serif' },
96
- surface: { radius: '1rem' }
97
- },
98
- components: { button: { radius: '2rem' } }
99
- })
51
+ import { Button, ThemeScope, defaultTheme } from '@cognitap/radiant'
100
52
 
101
- const document = updateThemeDocument(initial, {
102
- color: {
103
- brand: { value: '#166534', gamut: 'srgb' },
104
- palettes: [
105
- {
106
- id: 'brand',
107
- name: 'Brand',
108
- swatches: [{ stop: 500, value: '#166534' }]
109
- }
110
- ],
111
- anchor: { paletteId: 'brand', stop: 500 },
112
- values: { accent: '#166534', accentForeground: '#ffffff' },
113
- modes: { dark: { accent: '#86efac', accentForeground: '#052e16' } }
114
- }
115
- })
116
-
117
- const theme = compileThemeDocument(document)
118
- const scope = (
119
- <ThemeScope
120
- theme={theme}
121
- mode="system"
122
- >
123
- Garden
53
+ ;<ThemeScope
54
+ theme={garden}
55
+ mode="system"
56
+ >
57
+ <Button>Save</Button>
58
+ <ThemeScope theme={defaultTheme}>
59
+ <Button>Neutral action</Button>
124
60
  </ThemeScope>
125
- )
126
-
127
- // Full authoring configuration, including font descriptors and component exceptions.
128
- const fullJSON = JSON.stringify(document)
129
- // Resolved application output, accepted directly by ThemeScope after JSON round trip.
130
- const runtimeJSON = JSON.stringify(theme)
131
- // Only these sections; deliberately excludes identity and component exceptions.
132
- const colorJSON = JSON.stringify(exportThemeSections(document, ['color']))
133
-
134
- const imported = parseThemeDocument(JSON.parse(colorJSON))
135
- const next =
136
- imported.kind === 'radiant-theme'
137
- ? imported // Explicit full replacement of the editor's document.
138
- : updateThemeDocument(initial, imported.sections, 'replace')
61
+ </ThemeScope>
139
62
  ```
140
63
 
141
- `defineThemeDocument` accepts a typed document literal. `parseThemeDocument`
142
- accepts unknown data, such as `JSON.parse` output, and returns either a full
143
- `{ kind: 'radiant-theme', version: 1, id, name, sections }` document or a selective
144
- `{ kind: 'radiant-theme-sections', version: 1, sections }` export. Both are
145
- validated, detached and deeply frozen. Unsupported versions fail with a migration
146
- message; unknown fields and invalid values identify their path. No automatic
147
- version migration or silent dropping of future fields occurs. Parse text with
148
- `JSON.parse` first so malformed JSON errors remain distinct from schema errors.
149
-
150
- The section names follow the existing token groups: `color`, `typography`,
151
- `control`, `surface`, `focus`, `motion`, `spacing`, `state`, plus `components`.
152
- Each has optional `values` and `modes.light`/`modes.dark`. Values are exactly the
153
- corresponding partial token group or component override map, retaining its
154
- existing types and validation. Typography and motion will extend these sections
155
- when their richer authoring models are defined; arbitrary runtime or engine
156
- objects are not configuration fields. Editor layout can combine sections: the
157
- spacing/surfaces editor can update `control`, `surface`, `spacing`, `focus` and
158
- `state` together as needed.
159
-
160
- Compilation uses the same **mode defaults → common values → mode values**
161
- resolution as `defineTheme`, including all component resets. Metadata does not
162
- change rendered values: a palette or brand input alone never overwrites semantic
163
- roles. The color engine and semantic mapping stages will populate those values.
164
- The original `defineTheme` API, presets, CSS routes and scope behavior are unchanged.
165
- `themeDocumentFromDefinition` imports an authored `ThemeDefinition`, retaining
166
- only explicit overrides rather than baking in library defaults. It does not
167
- reverse-engineer a resolved `Theme` or recover authoring metadata from a preset.
168
-
169
- ### Section editing and import semantics
170
-
171
- | Operation | Result |
172
- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
173
- | `updateThemeDocument(doc, sections)` | Merge supplied leaves recursively; preserve omitted leaves and sections. Arrays replace as a whole. |
174
- | `updateThemeDocument(doc, sections, 'replace')` | Replace each supplied section, including all its mode layers and metadata. Omitted sections remain intact. |
175
- | `updateThemeDocument(doc, { color: {} }, 'replace')` | Reset that section to library fallback values by removing its authored values and metadata. |
176
- | `updateThemeDocument(doc, { color: {} })` | Empty merge is a no-op. |
177
- | Parse a full document and use it as editor state | Replace identity and every section; no implicit merge. |
178
- | Parse a selective export, then pass its `sections` to an update | Apply an explicit merge or replacement while retaining the destination identity. |
179
-
180
- Updates preserve deliberate component exceptions unless `components` is explicitly
181
- included. A typography change therefore retains a Button-only font; a color
182
- change retains an Input-only focus color. Select `components` separately to copy
183
- those exceptions. Resetting `color` does not reset an exception in `components`.
184
- To delete individual leaves, replace their section with the desired retained
185
- values. `null` is invalid, and optional object properties set to `undefined` are
186
- omitted, not deletion markers. Array holes and undefined array elements are invalid.
187
-
188
- ### Color identity and font boundaries
189
-
190
- `color.brand` retains the original `value`, declared `gamut` (`srgb` or
191
- `display-p3`) and optional explicitly labeled `srgbFallback`. Adding a brand
192
- materialises `fidelity: 'anchored'` unless `unanchored` was explicitly selected.
193
- `palettes` holds named ramps with unique stops from 50, 100, 200, …, 900, 950.
194
- Partial ramps can be saved while authoring. An optional `anchor` references a
195
- palette/stop whose value must exactly equal `brand.value`; a stale anchor fails
196
- validation with a regeneration/replacement instruction. An unanchored ramp omits
197
- `anchor`. A fallback cannot stand in for the unchanged original.
198
-
199
- This schema preserves the exact-anchoring decision; it does not generate ramps,
200
- parse color syntax, check gamut claims, measure contrast or prove balanced swatches.
201
- Use the color generator and semantic mapper below for those separate responsibilities. A P3 source
202
- and labeled fallback can be retained as data without claiming P3 generation support.
203
- Changing source/fidelity alongside an existing anchor requires a coherent replacement
204
- or regenerated palette; the compiler never silently adjusts the source.
205
-
206
- `typography.fonts` contains portable descriptors: unique `id`, `family`, `source`
207
- (`system`, `catalog` or `local`), optional numeric `weights` (1–1000) and `styles`
208
- (`normal`/`italic`). These describe requirements; the consuming application loads
209
- fonts and determines availability. Local font bytes, file paths/handles, URLs,
210
- DOM objects and runtime functions have no fields in the schema. A local family
211
- name can travel with the configuration, but the local font itself does not.
212
- Optional `axes` records available OpenType ranges as `{ tag, min, default, max }`.
213
- Axis tags are unique four-character ASCII identifiers; at most 32 finite, ordered
214
- ranges are accepted per font. These are capabilities for setup and inspection,
215
- not selected variations. Trial-only axis adjustments remain in the typeface lab.
216
- Full/selective documents retain these descriptors; compiling them does not change
217
- paint or load font files. Compressed custom files without inspected axes remain
218
- unverified rather than receiving invented capabilities.
219
-
220
- Font metadata does not set `typography.values.family` automatically.
221
-
222
- Full and selective authoring JSON preserve those descriptors; only selecting
223
- `typography` exports them. Compiled `Theme` output contains resolved CSS values
224
- and no palette/source/font metadata. Both formats are data: plain objects,
225
- arrays, strings, booleans, null and finite numbers, restricted further by their
226
- field schema. Functions, class/binary instances, cycles, accessors and unsupported
227
- keys fail before import can silently discard data.
228
-
229
- ## Responsive typography
230
-
231
- Typesetting is opt-in and uses the existing theme compiler. The accepted
232
- [role model](research/dev-162-typography-model.md) separates Body/Headings/UI/Code
233
- font assignments, 16 text styles and independent prose/UI rhythms.
64
+ `ThemeScope` is a plain `div` that takes native props and a ref. It paints its
65
+ canvas, foreground and body text for its subtree only. It never touches the
66
+ document, loads fonts or stores a preference.
67
+
68
+ - **`theme`** starts fresh from the library defaults. Nothing from an outer
69
+ theme leaks in, so `defaultTheme` fully resets a subtree, including button
70
+ effects.
71
+ - **`mode`** is `light`, `dark` or `system`, independent of the theme. `system`
72
+ uses a CSS media query, so server and client markup match.
73
+ - **Omit either** to inherit it. At the root the stylesheet defaults to
74
+ `system`.
75
+ - **Inline `style`** on a scope wins over its generated values. Theme variables
76
+ set inline on a scope survive nested mode-only scopes. A new named theme
77
+ clears them.
78
+
79
+ A mode-only scope recomputes the current theme, so it does not keep token
80
+ overrides from a stylesheet rule or plain wrapper above it. Put overrides that
81
+ must survive a mode switch in the theme or in a scope's inline `style`.
82
+
83
+ A native Dialog stays in the scope where it renders.
84
+
85
+ ## Override one component
86
+
87
+ Values resolve as **component override → shared token → baseline**. For
88
+ example, `components.button.radius` changes Button only, while
89
+ `tokens.control.radius` changes Button, Input and the other controls. A
90
+ component never falls back to another component's override.
91
+
92
+ Component keys are grouped by family under `components`: `button`, `link`,
93
+ `field`, `input`, `checkbox`, `radio`, `radioGroup`, `dialog`, `collapsible`,
94
+ `accordion` and `card`. Every key is listed in
95
+ [`src/themes/components.ts`](../src/themes/components.ts). Button-only fonts,
96
+ uppercase, shadows, squash and pressed shape belong under `components.button`.
97
+ `radioGroup.gap` spaces the options, and `radio.labelGap` spaces one option's
98
+ label.
99
+
100
+ Every token and key has a CSS variable named after its path:
101
+
102
+ | Path | CSS variable |
103
+ | ------------------------------ | ----------------------------- |
104
+ | `tokens.color.accent` | `--rad-color-accent` |
105
+ | `tokens.control.medium.height` | `--rad-control-medium-height` |
106
+ | `components.button.radius` | `--rad-button-radius` |
107
+ | `components.radioGroup.gap` | `--rad-radio-group-gap` |
234
108
 
235
- ```tsx
236
- import { ThemeScope, compileThemeDocument, defineThemeDocument,
237
- generateTypography, updateThemeDocument } from '@cognitap/radiant'
109
+ For a one-off change, set the variable in `style`. `ThemeStyle` types it:
238
110
 
239
- const document = defineThemeDocument({
240
- kind: 'radiant-theme', version: 1, id: 'publication', name: 'Publication',
241
- sections: { typography: { typesetting: {
242
- preset: 'source-serif',
243
- prose: { paragraphSpacing: 1.4 },
244
- styles: { 'prose-title': { weight: 650 } },
245
- } } },
246
- })
247
- const theme = compileThemeDocument(document)
111
+ ```tsx
112
+ import { Button, type ThemeStyle } from '@cognitap/radiant'
248
113
 
249
- // Inside your application, with either documented CSS route:
250
- <ThemeScope theme={theme}>
251
- <article data-rad-prose="" data-rad-type-container="">
252
- <h1>A shared language for careful work</h1>
253
- <p data-rad-text="prose-lead">A lead can use its own reusable style.</p>
254
- <p>Body copy with <em>emphasis</em> and <code>inline.code</code>.</p>
255
- <h2>A new section</h2>
256
- <p>Paragraph and heading spacing follow the prose rhythm.</p>
257
- </article>
258
- </ThemeScope>
114
+ const local: ThemeStyle = { '--rad-button-radius': '1rem' }
259
115
 
260
- const next = updateThemeDocument(document, {
261
- typography: { typesetting: { ui: { size: 18 } } },
262
- })
263
- const result = generateTypography(next.sections.typography!.typesetting)
116
+ <Button style={local}>Save</Button>
264
117
  ```
265
118
 
266
- `generateTypography`, `typographyPresets`, `typographyRoles` and their types also
267
- export from the pure `@cognitap/radiant/typography` entry. It imports no React,
268
- reads no browser globals and loads no fonts. For plain definitions, pass
269
- `result.tokens` as `tokens.typography` to `defineTheme`. `prose`, `ui`, and
270
- `styles` expose calculated settings. Immutable `result.input` is JSON-replayable
271
- and preserves manual/automatic ownership instead of pinning calculated metrics.
272
-
273
- ### Authoring and precedence
274
-
275
- `typography.typesetting` generates common defaults. Explicit `typography.values`
276
- leaves override them, followed by `typography.modes.light/dark` leaves. Existing
277
- component exceptions retain their precedence. Typography-only section exports
278
- carry recipes, explicit values and font descriptors through the existing
279
- merge/replace import rules; no second compiler or loading path is introduced.
280
-
281
- `preset` is `inter` (default), `source-serif`, or `plex`. Each `fonts.body`,
282
- `headings`, `ui` and `code` accepts a CSS `family` list and optional `profile`:
283
- `inter`, `source-serif-4`, `plex-sans`, `plex-mono`, or `manual`. A new family
284
- without a profile selects manual defaults. A profile is an explicit claim about
285
- the supplied font, not detection of an installed file. Consumers own that setup.
286
-
287
- | Manual setting | Bounds | Default |
288
- | -------------------------- | ----------------------- | ------------------------------------- |
289
- | `prose.size` | 12–40 reference px | Inter/Plex: 20, Serif: 21, manual: 20 |
290
- | `prose.lineHeight` | 1–3 | Inter/Plex: 1.6, Serif/manual: 1.65 |
291
- | `prose.paragraphSpacing` | 0–4em | 1.25em |
292
- | `prose.measure` | 20–120ch | Inter/manual: 64, Serif/Plex: 62 |
293
- | `prose.headingScale` | 1.1–1.5 | 1.25 |
294
- | `ui.size`, `ui.lineHeight` | 12–32 reference px, 1–3 | 16px / 1.5 |
295
-
296
- Each `styles[role]` accepts `assignment`, `narrow`, `wide`, `weight`, `lineHeight`,
297
- `tracking` and `measure`. Endpoint sizes are reference pixels at a 16px root,
298
- emitted as rem. Narrow is 8–256px; wide 8–512px and at least narrow. Weight is
299
- 1–1000, leading .8–3, tracking -.2–.5em and measure 0–120ch; zero measure means
300
- layout-owned. These are predictable bounds, not a guarantee every combination
301
- will look good.
302
-
303
- `recommendations.body/ui` flags known contextual starting points. Other fonts
304
- remain manually tunable. `warnings` identifies style weights outside a claimed
305
- profile's range, retaining the authored value rather than silently clamping it.
306
- Inspect warnings before accepting a theme. There is no universal readability
307
- score or implicit normalization.
308
-
309
- Context updates preserve explicit `styles` overrides. To reset a style or return
310
- a metric to automatic behavior, omit that key from the next recipe and **replace**
311
- the typography section, retaining other metadata/explicit values. Merge semantics
312
- cannot delete a stored leaf by omission. To select a fresh starting point,
313
- replace its recipe; merging only a preset ID intentionally retains old overrides.
314
- When merging a saved font assignment, change its family and profile together
315
- (use `manual` for an unfamiliar font), or replace the recipe. Merging only a
316
- family retains a previously stored profile.
317
-
318
- ### Semantic HTML and local width
319
-
320
- - `data-rad-text="prose-title"` selects presentation on any semantic element; it
321
- does not set heading levels or ARIA roles. `typographyRoles` lists all 16 values:
322
- prose title/heading/subheading/body/lead/small/quote; UI title/body/label/
323
- supporting/caption/metric/eyebrow; display; code.
324
- - `data-rad-prose` opts a container into Body typography, maximum measure and
325
- flow. Its **direct** headings, paragraphs/lists, captions, quotes and `pre`
326
- blocks receive their corresponding styles. Nested section wrappers can opt
327
- into prose explicitly.
328
- - Explicit `data-rad-text` wins over automatic element mapping. A direct block
329
- with `data-rad-not-prose` or a Radiant `data-slot` host skips mapping/flow;
330
- ordinary inherited font properties still inherit. Opt-out is not a reset.
331
- - `data-rad-type-container` establishes the named `radiant-type` inline-size
332
- container. Put it on the content column, including nested columns. Heading/
333
- display sizing interpolates over 24–56rem of local width. Body/UI sizes stay
334
- fixed rem values. Without an opt-in ancestor, roles use their compact endpoint.
335
-
336
- Hooks are low-specificity rules in the components layer. Utilities, ordinary
337
- application CSS and inline styles override them. Token shorthand utilities are
338
- registered by property in the existing class merger, for example
339
- `text-(--rad-typography-roles-prose-title-size)` and
340
- `font-(--rad-typography-roles-prose-title-family)`. An application Tailwind build
341
- must generate new utilities; importing precompiled library CSS does not do that.
342
-
343
- Measure is a maximum, not minimum width or exact character count. Prose wraps
344
- long words; preformatted code scrolls within its box. Give scrollable code
345
- keyboard access and an appropriate name where needed. UI styles leave measure
346
- to the layout. Inline code uses .9em and inherited weight/leading, not block-code
347
- line boxes. Actual italic/weight assets are required; text-style hosts disable
348
- synthetic font styles.
349
-
350
- Direct token authoring uses `roles[role].size` for the compact endpoint and
351
- `fluidSize` for the responsive expression. Set both to fix a style at all widths,
352
- or set equal `narrow`/`wide` inputs. Other role leaves are `family`, `weight`,
353
- `lineHeight`, `letterSpacing` and `measure`; prose flow leaves are
354
- `flow.paragraph`, `headingBefore` and `headingAfter`.
355
-
356
- ### Fonts, migration and verification
357
-
358
- Load chosen families/styles/weights with your application's font loader or
359
- self-hosted `@font-face`. Presets contain family/fallback lists, not font URLs,
360
- bytes or loaders. `typography.fonts` remains portable metadata; it does not load
361
- fonts or automatically select assignments. The role baseline follows the legacy
362
- shared family, with system monospace for code. Generated presets explicitly
363
- select their named families.
364
-
365
- ### Component roles and earlier themes
366
-
367
- Production families now consume the same UI roles as the workshop specimens:
368
-
369
- | Text host | Shared role | Deliberate size owner |
370
- | -------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------- |
371
- | ThemeScope, Card, DialogContent, Field, Collapsible and disclosure content | `ui-body` | Role; `collapsible.contentSize` remains an exception |
372
- | CardTitle, DialogTitle | `ui-title` | Role; component title size/weight overrides win |
373
- | Field label/legend, CollapsibleTrigger, AccordionTrigger | `ui-label` | Role; Field label overrides win |
374
- | Button, action-shaped Link | `ui-label` | Existing `controlSize` and Button font-size slots |
375
- | Input | `ui-body` | Existing `controlSize` and Input font-size slot |
376
- | Checkbox/Radio label | `ui-label` | Existing `controlSize` and label-size slots |
377
- | Field help/error, CardDescription, DialogDescription | `ui-supporting` | Role; existing component size slots win |
378
- | Inline/subtle Link | Inherits surrounding text | Parent text, including prose and code assignments |
379
-
380
- Roles supply family, weight, line height and tracking. Component UI text uses
381
- `size` (the compact endpoint), without prose measure limits or prose margins.
382
- Control sizes deliberately keep their 13/14/15px font metrics and 32/40/48px
383
- height/min-height defaults. Changing UI rhythm/style size therefore changes
384
- ordinary interface copy and labels, while size-constrained controls retain their
385
- metrics. To change those metrics, author `control.small/medium/large.fontSize`
386
- (and height/padding as needed), or a supported component font-size exception.
387
- Button and action-shaped Link share the Button-only typography exceptions.
388
- Accordion and Dialog actions reuse disclosure/Button styling respectively.
389
-
390
- The baseline `ui-body`, `ui-label`, `ui-title` and `ui-supporting` roles alias
391
- legacy family, size, weight and tracking leaves. Earlier themes and every built-in
392
- preset therefore retain their authored families/sizes/weights and deliberate
393
- Button exceptions. Baseline UI leading is now explicit: Body/Supporting 1.5,
394
- Label 1.4 and Title 1.3. Checkbox/Radio labels and disclosure triggers now use the
395
- shared label weight rather than inheriting body weight. These wrapping/rhythm
396
- changes require matching package JavaScript/CSS and layout review.
397
-
398
- To migrate a theme, replace `family/bodySize/bodyWeight` with `roles['ui-body']`,
399
- `smallSize` with `roles['ui-supporting'].size`, `headingSize/headingWeight` with
400
- `roles['ui-title']`, and `labelWeight` with `roles['ui-label'].weight`. The earlier
401
- shared family/tracking fields affect all four baseline roles; specify those
402
- leaves on each role to retain that breadth. Prefer a `typesetting` recipe when
403
- you want independently assigned Body/Headings/UI/Code families and repeatable
404
- rhythms. A recipe materializes these roles and then explicit `values`/mode role
405
- leaves override it; legacy leaves no longer control recipe-owned roles. There
406
- is no implicit recipe adoption or destructive migration of stored documents.
407
- Local component variables, caller utilities and ordinary CSS retain precedence.
408
- When migrating a legacy CSS variable applied directly to a text host, set the
409
- corresponding role variable on that host; inherited role aliases may already
410
- have resolved on the enclosing theme scope.
411
-
412
- New `roles` and `flow` are ordinary shared token leaves with partial/mode
413
- overrides. Older 0.0.4 parsers reject the new authoring keys; consume matching
414
- package JavaScript/CSS and defer the public docs pin to chapter promotion.
415
-
416
- Canonical examples: **System → Typography → Roles / Prose / Components / Serif Interface / Mono Interface**. The installed
417
- artifact gate verifies all 16 roles at 320/390/640/800px, both modes, nested
418
- containers and named/mode-only scopes, caller overrides, flow, inline code and
419
- root-enlargement/text-spacing probes through compiled CSS and Tailwind, each
420
- with/without reset. These fixtures use system fallbacks; actual-font quality
421
- remains bounded by DEV-162's recorded study. Browser zoom, manual AT, more scripts/
422
- browsers, production component adoption and final public review remain chapter
423
- acceptance work.
424
-
425
- ## Generate a color wall
119
+ Use `ThemeComponentOverrides` to type reusable override objects. Theme values
120
+ are inline custom properties, so a stylesheet rule on the same element cannot
121
+ override them; use `style`, or set the variable on a descendant. Caller classes
122
+ merge after the defaults. Variables starting with `--_` are internal.
426
123
 
427
- ```ts
428
- import { generateColorWall, colorCalibrationPresets } from '@cognitap/radiant/color'
429
- import { updateThemeDocument } from '@cognitap/radiant'
124
+ Some defaults to know:
430
125
 
431
- const wall = generateColorWall({
432
- brand: '#7C3AED',
433
- wallPreset: 'expressive',
434
- rampPreset: 'balanced'
435
- })
436
- // Registry entries supply stable IDs, names and descriptions for public controls.
437
- console.log(colorCalibrationPresets)
438
- // Optional dials are materialised, so this reproduces every output swatch.
439
- const replay = generateColorWall(JSON.parse(JSON.stringify(wall.input)))
440
-
441
- // Retain independently authored semantic values/modes; replace generated metadata
442
- // so switching to unanchored fidelity also removes the previous anchor.
443
- const previous = document.sections.color
444
- const next = updateThemeDocument(
445
- document,
446
- {
447
- color: { values: previous?.values, modes: previous?.modes, ...wall.color }
448
- },
449
- 'replace'
450
- )
451
- ```
126
+ - Checkbox caps an inherited radius at a quarter of its size, so it stays a
127
+ box. An explicit `components.checkbox.radius` still wins.
128
+ - Radio stays circular under any control shape.
129
+ - Input, Checkbox and Radio outlines mix border and foreground colors, so
130
+ controls have more contrast than passive dividers.
131
+ - Disabled opacity applies once, not again on a disabled child.
452
132
 
453
- The generator is available from the package root and from the React-free
454
- `@cognitap/radiant/color` entry. It reads no browser globals, loads no fonts and
455
- uses no randomness or AI. The result is detached, deeply frozen, JSON-safe data.
456
- This is an unreleased API until the next package publication.
457
-
458
- `wall.color` fits the existing `ThemeColorSection`: original `brand`, selected
459
- `fidelity`, 18 `palettes` and an `anchor` only for anchored fidelity. Palette order
460
- is Brand, Red, Orange, Amber, Yellow, Lime, Green, Emerald, Teal, Cyan, Sky, Blue,
461
- Indigo, Violet, Purple, Pink, Rose, Neutral. Each has a stable lowercase ID and
462
- 11 swatches at 50, 100, 200, …, 900, 950. Generated values are opaque six-digit
463
- sRGB hex; the exact original preserves its supplied spelling/case.
464
- `wall.neutralInput` reports the low-chroma path. `wall.input` contains all
465
- materialised controls and algorithm `version: 1` for replay. Persist that input
466
- as a generator recipe separately; the current version-1 theme document stores
467
- its color output, not a new untyped generation-settings field.
468
-
469
- | Input | Default | Supported range / meaning |
470
- | ---------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
471
- | `brand` | Required | Opaque six-digit sRGB hex. Alpha, CSS functions, named colors and P3 sources are rejected explicitly. |
472
- | `version` | `1` | Only the calibrated algorithm version 1 is supported. |
473
- | `gamut` | `srgb` | Only sRGB output is currently supported. No automatic P3 fallback or source replacement. |
474
- | `fidelity` | `anchored` | `anchored` preserves the original at its nearest-lightness numbered stop; `unanchored` keeps the regular ramp and separate original. |
475
- | `wallPreset` | `balanced` | `classic`, `balanced`, `expressive`; selects the supporting wall's curves, automatic vividness, neutral tint and hue alignment. |
476
- | `rampPreset` | `balanced` | Same three IDs, independently selects brand curves, automatic vividness and anchor reshaping. |
477
- | `brandVividness` | Source-derived by ramp preset | 0–1 brand-ramp chroma, independent of wall vividness; never changes the exact source. |
478
- | `vividness` | Source-derived by wall preset | 0–1 supporting-wall chroma; it never changes the brand ramp. |
479
- | `lightness` | `hue-aware` | `hue-aware` adapts the middle toward each hue's gamut cusp; `shared` uses the common reference curve. |
480
- | `distribution` | `1` | .75–1.35. Redistributes intermediate shades while retaining endpoints/middle in regular chromatic ramps. |
481
- | `neutralTint` | Classic `.012`, Balanced `.008`, Expressive `.016` | 0–.035 peak chroma in the Neutral ramp; zero produces untinted grays. |
482
- | `hueAlignment` | Classic `.6`, Balanced `.25`, Expressive `.5` | 0–1. Rotate the wall so its nearest named family moves toward the brand hue; family order/spacing stays intact. |
483
- | `neutralHue` | `255` | Any finite degrees, wrapped into [0, 360). Explicit direction when source C < .02; the near-neutral Brand ramp remains neutral apart from its exact source neighborhood. |
484
-
485
- Classic retains the [accepted DEV-151 calibration](https://github.com/cognitap/radiant/blob/50044fc0d6d66c94b2e3dfb02fc17c0d2828aff6/docs/research/dev-151-calibration-proposal.md).
486
- It uses the reference lightness curve .985, .965, .93, .87, .79, .70, .61, .52,
487
- .43, .34, .24, hue-relative gamut fractions and a smooth chroma envelope. Anchored
488
- fidelity reshapes neighboring lightness and chroma around the unchanged source.
489
- Balanced and Expressive use monotone cubic lightness reshaping and local gamut-relative
490
- chroma blending around the anchor; Classic retains linear lightness reshaping.
491
- For automatic settings, let `m = sqrt(clamp(source C / .28, 0, 1))`. Balanced uses
492
- wall strength `.45 + .4m` and brand strength `.18 + .65m`; Expressive uses
493
- `.6 + .3m` and `.28 + .62m`. Classic uses source C / available C, clamped to
494
- .10–.92 (.35 for low-chroma sources), for both. Hue-aware midpoints, envelope
495
- limits and distribution curves follow the selected preset independently.
496
- `distribution` multiplies each preset's exponent (Classic 1, Balanced .95,
497
- Expressive 1.05); `shared` fixes the midpoint at .7. Explicit dials override
498
- preset defaults, and every effective input is materialised for exact replay.
499
- Public editors should clear wall-owned dials (vividness/tint/alignment) when
500
- selecting a wall preset, and brandVividness when selecting a ramp preset; retain
501
- independent controls and explicit semantic pins.
502
-
503
- Nearest-lightness ties prefer the earlier/lighter stop. Black and white can
504
- occupy the endpoint stops. Metrics and anchor selection use actual quantized
505
- colors, rather than assuming requested OKLCH values survived mapping unchanged.
506
-
507
- The mapper reduces chroma at constant lightness/hue until the result fits sRGB,
508
- then emits 8-bit output. Conversion uses [Ottosson's Oklab matrices](https://bottosson.github.io/posts/oklab/)
509
- and the [CSS Color 4 transfer functions](https://www.w3.org/TR/css-color-4/#color-conversion-code).
510
- This deliberate mapper does not claim to duplicate a browser's gamut-mapping
511
- algorithm. The per-call caches are discarded after generation; past calls cannot
512
- change subsequent results or retain an unbounded history of user colors.
513
-
514
- A color wall is palette data. It does not select semantic text/action/state
515
- roles, guarantee contrast on arbitrary surfaces or certify chart distinctions.
516
- Use `recommendColorPalette` below for working sets and named role-pair checks.
517
- `compileThemeDocument` continues to use only
518
- semantic `values`/`modes`; adding this metadata alone does not change a rendered
519
- theme. In Storybook, **System → Color Wall → Reference** exposes the accepted
520
- 12 inputs and controls for visual inspection; the public workshop UI remains
521
- separate documentation-application work.
522
-
523
- ## Recommend a working palette and semantic roles
133
+ Restyling must keep components usable. See
134
+ [what customization must keep](architecture.md#what-customization-must-keep).
524
135
 
525
- ```ts
526
- import { generateColorWall, recommendColorPalette } from '@cognitap/radiant/color'
527
- import { updateThemeDocument, compileThemeDocument } from '@cognitap/radiant'
136
+ ## Example themes and fonts
528
137
 
529
- const wall = generateColorWall({ brand: '#7C3AED' })
530
- const palette = recommendColorPalette(wall, {
531
- working: { support: 'teal' },
532
- modes: { dark: { focus: '#ABCDEF' } }
533
- })
138
+ The core entry ships one theme, `defaultTheme`. The other presets are examples
139
+ to copy or start from, published separately at `@cognitap/radiant/examples`.
140
+ Its readonly `themes` registry lists them, each is a named export, and
141
+ `themeDefinitions` holds the definition behind each theme in the same order.
142
+ Pass a definition to `themeDocumentFromDefinition` to edit it as a document;
143
+ the theme workshop starts from these.
534
144
 
535
- // Replace the complete color section, preserving the original source and all ramps.
536
- // Merge the canvas layer to retain surface radius, spacing and other authored values.
537
- const colored = updateThemeDocument(document, { color: palette.color }, 'replace')
538
- const themed = updateThemeDocument(colored, { surface: palette.surface })
539
- const theme = compileThemeDocument(themed)
540
- const failures = palette.checks.filter(check => check.pass === false)
145
+ ```tsx
146
+ import { jelly } from '@cognitap/radiant/examples'
541
147
  ```
542
148
 
543
- `recommendColorPalette(wall, options?)` consumes a complete version-1 sRGB wall.
544
- It returns deeply frozen, detached, JSON-safe recommendations. The original
545
- brand, fidelity, anchor and all 18 ramps remain unchanged in `palette.color`.
546
- The result has five parts:
547
-
548
- - `working`: primary, support, neutral, success, warning and danger, each with a
549
- wall `paletteId` and independently selected light/dark background/foreground pairs.
550
- - `color`: the original wall metadata plus complete light/dark maps for the
551
- existing shared color roles. No common-mode values are needed.
552
- - `surface`: light/dark `canvas` layers, using the existing surface token group.
553
- - `checks`: measured pairs with mode, role names, exact colors, unrounded ratio,
554
- minimum, pass/fail and an actionable failure message.
555
- - `pass`: whether every listed required pair passes. This is a scoped contrast
556
- result, not a complete accessibility or arbitrary-theme certification.
557
-
558
- Defaults use Brand as primary, Neutral for surfaces, Emerald for success, Amber
559
- for warning and Red for danger. The support family is nearest to primary hue +
560
- 150°. Low-chroma candidates use the wall's explicit hue direction and nominal
561
- family geometry rather than numerical hue noise. `working` can replace any of
562
- these family IDs with another existing wall family. Duplicate families are
563
- allowed deliberately; color alone does not establish status meaning or chart
564
- separation. Use labels/icons as appropriate.
565
-
566
- Light canvas/surface start at Neutral 50/100, dark at 950/900. Foreground,
567
- secondary text, borders, focus, invalid state and action shades are selected
568
- against the actual emitted opaque surfaces, independently for each mode. Solid
569
- pairs require 4.5:1 text contrast. Among eligible primary shades, choose the
570
- smallest Oklab distance to the original brand, including lightness and both
571
- chromatic axes. Primary fill also requires 3:1 against both surfaces because it
572
- identifies checked Checkbox/Radio state. Thus a readable exact source is retained
573
- when its boundaries also pass; otherwise a nearby readable shade is selected. Exact source identity stays separate: yellow may
574
- remain the exact Brand 200 while a darker related shade supplies the light action.
575
- Black/white ink can be selected when it gives the strongest text contrast.
576
-
577
- `options.version` defaults to 1. `options.modes.light`/`dark` can override any
578
- existing color role and `canvas`, using opaque six-digit sRGB hex. Provided
579
- surfaces drive automatic dependent choices; explicit foregrounds and other role
580
- colors are retained even if they fail. Unsupported fields, palette IDs, versions,
581
- non-opaque colors and incomplete walls fail with a path or available ID list.
582
- Recipes remain ordinary serializable options; the existing theme document stores
583
- mapped values and wall metadata, without adding an untyped recipe field.
584
-
585
- Contrast uses the [WCAG sRGB luminance formula](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
586
- on final hex values. Normal text (including secondary text, placeholder and invalid
587
- text) is checked at 4.5:1 on canvas and surface; solid action/working-palette ink
588
- is checked at 4.5:1 on its fill. Meaningful border, offset focus ring and primary
589
- checked-state fill are checked at 3:1 on both surfaces. These are Radiant's
590
- conservative role policies, not a requirement that every decorative boundary or
591
- hover/rest color differ by 3:1. See [non-text contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html).
592
-
593
- Disabled token pairs have `minimum: null` and `pass: null`, explicitly reflecting
594
- the inactive-control exception. Their informational ratios exclude component
595
- opacity/effects. Pending actions remain active and are not exempt. Support/success
596
- are working-palette pairs; the current component tones remain accent, neutral,
597
- warning and danger. No new component tones or runtime token roles are introduced.
598
-
599
- Apply color and canvas together before relying on the report. A color-only import,
600
- component/local override, gradient/translucent surface or rendered hover/pressed
601
- effect can change the effective pair. Recheck those contexts in the browser; this
602
- base-pair report does not silently certify them. **System → Color Palette →
603
- Reference** reuses the canonical profile form and inspects invalid, disabled,
604
- checked, pending and keyboard-focus states in both modes. DEV-155 owns the wider
605
- theme-editor integration is described below; the public editor itself remains in radiant-docs.
606
-
607
- ## Apply palette, spacing and surfaces together
608
-
609
- Use `updateThemeAppearance` when the workshop applies generated colors and bounded
610
- geometry together. It produces an ordinary version-1 `ThemeDocument`; compile it
611
- through the existing runtime and use either installed CSS route.
149
+ | ID | Name | Export | Font | Button exception |
150
+ | --------------- | ------------- | --------------------- | ---------------- | ------------------------------------ |
151
+ | `radiant` | Radiant | `radiant` | Inter | Weight 550 |
152
+ | `default` | Default | `defaultTheme` (core) | System sans | None |
153
+ | `soft-squircle` | Soft squircle | `soft` | Nunito | Weight 800 |
154
+ | `expressive` | Expressive | `expressive` | Poppins | Weight 600 |
155
+ | `glass` | Glass | `glass` | Manrope | Weight 700; backdrop filter |
156
+ | `sharp-3d` | Sharp 3D | `sharp` | System sans | Archivo Black, weight 400, uppercase |
157
+ | `jelly` | Jelly | `jelly` | Baloo 2 | Weight 700 |
158
+ | `ticket` | Ticket | `ticket` | Barlow Condensed | Weight 600, uppercase |
612
159
 
613
- ```ts
614
- import {
615
- themeDocumentFromDefinition,
616
- updateThemeAppearance,
617
- compileThemeDocument,
618
- generateColorWall,
619
- recommendColorPalette
620
- } from '@cognitap/radiant'
621
-
622
- const initial = themeDocumentFromDefinition({
623
- id: 'brand-workshop',
624
- name: 'Brand workshop',
625
- components: { button: { radius: '12px' } } // A deliberate exception survives edits.
626
- })
627
- const palette = recommendColorPalette(generateColorWall({ brand: '#7C3AED' }))
628
- const document = updateThemeAppearance(initial, {
629
- palette,
630
- geometry: {
631
- values: { spacing: 1.25, density: 1.1, controlRadius: 8, surfaceRadius: 16, elevation: 2 },
632
- modes: { dark: { backdropOpacity: 0.75 } }
633
- }
634
- })
635
- const theme = compileThemeDocument(document)
636
- // <ThemeScope theme={theme} mode="system">...</ThemeScope>
637
- ```
160
+ Choosing a theme never downloads a font. Load the families yourself with weights
161
+ 400, 600 and 700 plus the Button weight above. Every family falls back to
162
+ `system-ui, sans-serif`.
638
163
 
639
- The optional `palette` is the mapped result of `recommendColorPalette`, not raw
640
- wall metadata. Its complete color section replaces previous common/mode colors;
641
- its light/dark canvas leaves merge into surface settings in the same immutable
642
- operation. Applying a palette never erases radii, padding, elevation or component
643
- exceptions. A failing deliberate palette choice is retained; inspect its contrast
644
- report before applying it.
645
-
646
- `geometry.values` controls both modes; `geometry.modes.light`/`dark` override
647
- individual controls. Omitted controls retain authored settings. Each provided
648
- control maps to the existing semantic token leaves in both modes, overriding
649
- older common or mode values for those leaves. No recipe metadata or new runtime
650
- token group is added. An empty update changes no values.
651
-
652
- | Geometry control | Accepted values | Existing responsibilities |
653
- | ------------------------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
654
- | `spacing` | 0.5–2 | Multiplies all five `spacing` gaps plus `surface.padding` and `surface.gap`. |
655
- | `density` | 0.75–1.5 | Multiplies small/medium/large control height, inline padding and indicator size; retains font sizes. |
656
- | `controlRadius` | 0–32 px | Shared action/input radius; Checkbox caps the inherited radius; Radio remains circular. |
657
- | `surfaceRadius` | 0–48 px | Card, Dialog and Collapsible shape, including Accordion items. |
658
- | `controlBorderWidth`, `surfaceBorderWidth` | 0–4 px | Respective shared border widths. |
659
- | `borderStyle` | `solid`, `dashed`, `dotted` | Both control and surface borders. |
660
- | `elevation` | Integer 0–3 | 0 removes passive/overlay shadows; 1 uses mode defaults; 2/3 select raised/floating shadows with mode-specific opacity. |
661
- | `backdropOpacity` | 0–0.9 | Black modal backdrop opacity; panel backdrop filtering stays a Dialog component exception. |
662
-
663
- Scale controls derive absolute values from the neutral baseline, retaining rem
664
- units. Reapplying `spacing: 1.25` is idempotent; it never multiplies already-edited
665
- values. `density: 1` restores baseline metric leaves, while fonts and unrelated
666
- settings remain authored. Action-local effects/shadows remain component decisions;
667
- inline Link retains text metrics, and action-shaped Link follows control metrics.
668
- Values outside the bounds, unknown keys/modes and unsupported `version` (default 1)
669
- fail with a path instead of being silently clamped. These bounds support workshop
670
- exploration; border removal, small targets or overrides still need contextual
671
- accessibility review. Focus behavior, state ownership and forced-colors behavior
672
- remain the existing families' responsibility.
673
-
674
- Precedence stays **component exception → shared role → baseline**, followed by
675
- caller utility/style overrides on the host. Nested mode scopes resolve the same
676
- compiled theme and retain explicit scope style exceptions; named themes reset
677
- them. **System → Theme Appearance → Workspace** reuses the canonical ten-family
678
- workspace, inspects all three control sizes and demonstrates these precedence
679
- rules. Installed-package checks include the generated theme through compiled CSS
680
- and Tailwind, with and without a reset.
681
-
682
- Existing theme definitions, presets, token names, generated baseline CSS and CSS
683
- imports need no migration. Existing documents can be passed directly; authored
684
- `ThemeDefinition` inputs use `themeDocumentFromDefinition`. Resolved presets remain
685
- runtime data and cannot recover their original authoring intent. Advanced CSS
686
- geometry stays available through typed `updateThemeDocument` token sections and
687
- component overrides. Public editing and handoff UI follow in DEV-158/DEV-159.
688
-
689
- ## Scopes, mode, and overrides
690
-
691
- `ThemeScope` renders a normal `div` and accepts its native props and ref. It
692
- paints its canvas, foreground, and body typography within that subtree. It does
693
- not change the document, install event listeners, load fonts, or persist a
694
- preference. A native top-layer Dialog remains in its original scope.
695
-
696
- - `theme={theme}` starts a fresh named theme from library defaults. Every shared
697
- token is materialised and every omitted component override is reset to its
698
- CSS fallback. An outer theme cannot leak its action font or press effect in.
699
- - Omit `theme` to inherit the current theme. Omit `mode` to inherit the current
700
- mode. At the application root, the stylesheet defaults to system preference.
701
- - `mode="light"`, `"dark"`, or `"system"` selects appearance independently of
702
- theme identity. System follows the CSS media query, so server markup and the
703
- first client render agree. A mode-only scope resolves the current named theme
704
- in its selected mode.
705
- - An inner scope with neither `theme` nor `mode` follows ordinary CSS inheritance;
706
- it does not establish a new theme. A root scope also paints the neutral canvas
707
- and typography.
708
- - Explicit `style` values win over generated values on the same scope host.
709
- Known theme variables supplied inline to ancestor ThemeScopes are carried
710
- through mode-only scopes. A new named theme clears these inherited exceptions.
711
-
712
- Use `defaultTheme` for a complete reset, including component effects:
164
+ Glass uses a gradient canvas and translucent surfaces.
165
+ `components.dialog.backdropFilter` blurs what is behind a dialog panel, and
166
+ `components.dialog.backdrop` paints the overlay. Shapes use CSS `corner-shape`;
167
+ browsers without it show ordinary rounded corners.
168
+
169
+ ## Typography
170
+
171
+ Typesetting is an opt-in recipe compiled into the theme. It assigns Body,
172
+ Headings, UI and Code fonts, 16 text styles, and separate prose and UI rhythms.
713
173
 
714
174
  ```tsx
715
- import { Button, ThemeScope, defaultTheme, ticket } from '@cognitap/radiant'
175
+ import { ThemeScope, compileThemeDocument, defineThemeDocument } from '@cognitap/radiant'
716
176
 
717
- ;<ThemeScope
718
- theme={ticket}
719
- mode="light"
720
- >
721
- <Button>Ticket action</Button>
722
- <ThemeScope theme={defaultTheme}>
723
- <Button>Neutral action</Button>
724
- </ThemeScope>
177
+ const theme = compileThemeDocument(defineThemeDocument({
178
+ kind: 'radiant-theme', version: 1, id: 'publication', name: 'Publication',
179
+ sections: { typography: { typesetting: {
180
+ preset: 'source-serif',
181
+ prose: { paragraphSpacing: 1.4 },
182
+ styles: { 'prose-title': { weight: 650 } }
183
+ } } }
184
+ }))
185
+
186
+ <ThemeScope theme={theme}>
187
+ <article data-rad-prose="" data-rad-type-container="">
188
+ <h1>Title</h1>
189
+ <p data-rad-text="prose-lead">Lead paragraph.</p>
190
+ </article>
725
191
  </ThemeScope>
726
192
  ```
727
193
 
728
- Use shared tokens for local changes that should affect multiple families:
194
+ `preset` is `inter` (default), `source-serif` or `plex`. Each of `fonts.body`,
195
+ `headings`, `ui` and `code` takes a CSS `family` and an optional `profile`
196
+ (`inter`, `source-serif-4`, `plex-sans`, `plex-mono` or `manual`). A profile is
197
+ your claim about the font; Radiant does not detect it.
198
+
199
+ | Setting | Range | Default |
200
+ | -------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------- |
201
+ | `prose.size` | 12–40px | Inter/Plex 20, Serif 21, manual 20 |
202
+ | `prose.lineHeight` | 1–3 | Inter/Plex 1.6, Serif/manual 1.65 |
203
+ | `prose.paragraphSpacing` | 0–4em | 1.25em |
204
+ | `prose.measure` | 20–120ch | Inter/manual 64, Serif/Plex 62 |
205
+ | `prose.headingScale` | 1.1–1.5 | 1.25 |
206
+ | `ui.size`, `ui.lineHeight` | 12–32px, 1–3 | 16px / 1.5 |
207
+ | `styles[role]` | `narrow` 8–256px, `wide` 8–512px, weight 1–1000, leading 0.8–3, tracking −0.2–0.5em, measure 0–120ch | From the preset |
208
+
209
+ Explicit `typography.values` override the recipe, and mode values override
210
+ both. Out-of-profile weights produce `warnings` rather than being clamped.
211
+ To reset a style, omit it and **replace** the typography section; a merge cannot
212
+ delete a key. `generateTypography` and the presets are also exported from the
213
+ React-free `@cognitap/radiant/typography` entry.
214
+
215
+ HTML hooks:
216
+
217
+ - `data-rad-text="<role>"` applies one of the 16 styles listed in
218
+ `typographyRoles`. It does not change heading levels or ARIA.
219
+ - `data-rad-prose` styles the container's **direct** headings, paragraphs,
220
+ lists, quotes and code blocks. `data-rad-not-prose` on a child opts it out.
221
+ - `data-rad-type-container` makes heading sizes scale with the column's width,
222
+ between 24rem and 56rem. Body and UI sizes stay fixed.
223
+
224
+ The hooks have low specificity, so utilities, your CSS and inline styles win.
225
+ Load real italic and bold faces; synthetic styles are turned off.
226
+
227
+ Components use the UI roles:
228
+
229
+ | Text | Role |
230
+ | ------------------------------------------------------------------- | ------------------------- |
231
+ | ThemeScope, Card, DialogContent, Field, disclosure body | `ui-body` |
232
+ | CardTitle, DialogTitle | `ui-title` |
233
+ | Field label, disclosure triggers, Button, Checkbox and Radio labels | `ui-label` |
234
+ | Input | `ui-body` |
235
+ | Field help and error, CardDescription, DialogDescription | `ui-supporting` |
236
+ | Inline Link | Inherits surrounding text |
237
+
238
+ Controls keep their own font size from `control.<size>.fontSize`, so changing
239
+ the UI role size does not resize buttons or inputs.
240
+
241
+ ## Colors
242
+
243
+ `generateColorWall` builds 18 palettes of 11 shades (50–950) from one brand
244
+ color. `recommendColorPalette` picks a working set from that wall, maps it to
245
+ light and dark color roles, and reports contrast checks. Both are pure,
246
+ deterministic and exported from the React-free `@cognitap/radiant/color` entry.
729
247
 
730
- ```tsx
731
- <ThemeScope
732
- theme={brand}
733
- style={{ '--rad-control-radius': '1.25rem', padding: '2rem' }}
734
- >
735
- <Input aria-label="Garden name" />
736
- <Button>Save</Button>
737
- </ThemeScope>
738
- ```
248
+ ```ts
249
+ import { generateColorWall, recommendColorPalette } from '@cognitap/radiant/color'
250
+ import { updateThemeAppearance, compileThemeDocument } from '@cognitap/radiant'
739
251
 
740
- Ordinary CSS overrides inherit within their existing scope. A mode-only scope
741
- re-materialises the selected theme, so token overrides from an intervening
742
- stylesheet rule or an ordinary DOM wrapper are not automatically recovered
743
- there. Put exceptions that must survive a mode change on a `ThemeScope` inline
744
- `style`, or include them in the theme definition. No browser computed-style
745
- snapshot is taken. Ordinary body styles, such as a locally changed font size,
746
- still follow the cascade and inheritance appropriate to their host.
747
-
748
- Components resolve **local component override → shared semantic role → neutral
749
- baseline**. For example, `components.button.radius` overrides Button without
750
- changing Input; `tokens.control.radius` changes both. Checkbox caps its inherited
751
- radius at a quarter of its indicator size so it remains a box; an explicit
752
- `components.checkbox.radius` still wins. Radio stays circular by default, even
753
- under squircle or scoop control themes. Shared disabled opacity is applied once
754
- to the relevant visual unit.
755
-
756
- Input, Checkbox, and Radio derive their default control outline from the shared
757
- border and foreground colors. This gives interactive boundaries more contrast
758
- than passive surface dividers. Their explicit `borderColor`, invalid, disabled,
759
- and focus overrides keep their normal precedence. Disabled selection marks use
760
- the muted foreground unless the component supplies its own `mark` color.
761
-
762
- Component overrides use the existing family configuration keys, grouped under
763
- `button`, `link`, `field`, `input`, `checkbox`, `radio`, `radioGroup`, `dialog`,
764
- `collapsible`, `accordion`, and `card`. Public declaration types are the
765
- closed-key reference. `radioGroup.gap` controls group layout;
766
- `radio.labelGap` controls spacing within a single option. Button-only fonts,
767
- uppercase text, sheen, shadows, squash, and pressed shape belong under
768
- `components.button`. Passive surfaces have their own shared surface tokens.
769
-
770
- Public variable names are derived from the typed registry:
771
-
772
- | Authoring path | CSS variable |
773
- | ------------------------------ | ----------------------------- |
774
- | `tokens.color.accent` | `--rad-color-accent` |
775
- | `tokens.control.medium.height` | `--rad-control-medium-height` |
776
- | `tokens.typography.family` | `--rad-typography-family` |
777
- | `components.button.radius` | `--rad-button-radius` |
778
- | `components.radioGroup.gap` | `--rad-radio-group-gap` |
252
+ const wall = generateColorWall({ brand: '#7C3AED', wallPreset: 'expressive' })
253
+ const palette = recommendColorPalette(wall, { working: { support: 'teal' } })
254
+ const failures = palette.checks.filter(check => check.pass === false)
255
+
256
+ const theme = compileThemeDocument(
257
+ updateThemeAppearance(document, {
258
+ palette,
259
+ geometry: { values: { spacing: 1.25, controlRadius: 8 } }
260
+ })
261
+ )
262
+ ```
779
263
 
780
- Matching caller utilities merge with component defaults on the Tailwind route;
781
- application CSS follows the normal cascade. Generated theme values are inline
782
- custom properties, so a normal stylesheet declaration on that same host does
783
- not override them. Put a token override on a descendant or use the host's
784
- `style` prop. Internal variables beginning `--_` are implementation details.
785
-
786
- ## Preserve functional styles
787
-
788
- Appearance overrides must preserve closed Dialog/details visibility, dialog
789
- geometry and scrolling, real control hit targets, and accessible names. Keep
790
- focus, invalid, disabled, and pending cues visible. The library retains
791
- forced-colors system colors and reduced-motion alternatives; a theme must not
792
- erase them with replacement CSS. See the [system guide's functional CSS obligations](system.md#preserve-behavior-when-customising)
793
- for host replacement and the behavior that overrides must preserve. Importing the optional reset is not required for
794
- these behaviors.
795
-
796
- ## Presets and fonts
797
-
798
- The readonly `themes` registry contains these presets, exported individually
799
- from `@cognitap/radiant`. Each has a deliberate light and dark palette.
800
-
801
- | Stable ID | Display name | Named export | Shared font family | Action exception |
802
- | --------------- | ------------- | -------------- | ------------------ | ------------------------------------ |
803
- | `radiant` | Radiant | `radiant` | Inter | Weight 550 |
804
- | `default` | Default | `defaultTheme` | System sans | Library baseline |
805
- | `soft-squircle` | Soft squircle | `soft` | Nunito | Weight 800 |
806
- | `expressive` | Expressive | `expressive` | Poppins | Weight 600 |
807
- | `glass` | Glass | `glass` | Manrope | Weight 700; backdrop filter |
808
- | `sharp-3d` | Sharp 3D | `sharp` | System sans | Archivo Black, weight 400, uppercase |
809
- | `jelly` | Jelly | `jelly` | Baloo 2 | Weight 700 |
810
- | `ticket` | Ticket | `ticket` | Barlow Condensed | Weight 600, uppercase |
811
-
812
- All families have `system-ui, sans-serif` fallbacks. Preset body weight is 400;
813
- load the label and heading weights 600 and 700 as well as the action weight
814
- listed above. Default uses baseline label/heading weights 550/600. Radiant's
815
- Inter action weight 550 requires a variable font or an appropriate supplied
816
- face; the browser chooses an available weight otherwise.
817
-
818
- Fonts are application assets. Load the named families with your font loader or
819
- self-hosted `@font-face` rules before showing the themed UI. Defining or choosing
820
- a theme never downloads a font. Storybook's font loading belongs to Storybook,
821
- not the package. `Theme` has no `fonts` field or font-loading API.
822
-
823
- Glass uses a gradient `surface.canvas` and translucent `color.surface`.
824
- `components.dialog.backdropFilter` frosts content behind the dialog panel;
825
- `components.dialog.backdrop` paints the surrounding modal overlay. Button's
826
- existing `backdrop` override is also a filter and remains independent. Ticket
827
- uses a compact, solid checkbox outline so small indicators
828
- remain legible alongside its scooped, dashed controls and surfaces.
829
- Shape uses CSS `corner-shape`; browsers that do not support it
830
- retain ordinary rounded corners. A palette definition does not certify contrast
831
- for arbitrary content, custom backgrounds, or translucent combinations.
832
-
833
- ## Shared token reference
834
-
835
- These 66 roles and concrete neutral defaults come from
836
- [`src/themes/tokens.ts`](../src/themes/tokens.ts). CSS names are `--rad-` plus the
837
- kebab-case dotted path. Values shown in both modes differ only where listed.
838
- `color` values are CSS colors; `surface.canvas` and `surface.backdrop` are full
839
- CSS backgrounds and may be gradients. `components.button.backdrop` and
840
- `components.dialog.backdropFilter` are CSS backdrop-filter values. Lengths and
841
- durations remain CSS strings; opacity is numeric.
264
+ | Wall input | Default | Range |
265
+ | ---------------- | ----------- | --------------------------------------------------- |
266
+ | `brand` | Required | Six-digit sRGB hex |
267
+ | `fidelity` | `anchored` | `anchored` keeps the exact brand color as one shade |
268
+ | `wallPreset` | `balanced` | `classic`, `balanced`, `expressive` |
269
+ | `rampPreset` | `balanced` | Same values, for the brand palette only |
270
+ | `vividness` | From preset | 0–1, other palettes |
271
+ | `brandVividness` | From preset | 0–1, brand palette |
272
+ | `lightness` | `hue-aware` | `hue-aware` or `shared` |
273
+ | `distribution` | `1` | 0.75–1.35 |
274
+ | `neutralTint` | From preset | 0–0.035 |
275
+ | `hueAlignment` | From preset | 0–1 |
276
+ | `neutralHue` | `255` | Degrees, used when the brand is nearly gray |
277
+
278
+ `wall.input` holds every effective setting, so passing it back reproduces the
279
+ same wall.
280
+
281
+ By default the working set is Brand (primary), the family nearest the brand
282
+ hue plus 150° (support), Neutral, Emerald (success), Amber (warning) and Red
283
+ (danger). Text must reach 4.5:1 against its background. Borders, focus rings and
284
+ the checked fill must reach 3:1. Disabled pairs are reported but not
285
+ required to pass. The checks cover these base pairs only. Recheck gradients,
286
+ translucency and overrides in the browser.
287
+
288
+ `updateThemeAppearance` applies a palette and geometry together without
289
+ touching component overrides:
290
+
291
+ | Geometry | Range | Changes |
292
+ | ------------------------------------------ | --------------------------- | ------------------------------------------ |
293
+ | `spacing` | 0.5–2 | All spacing gaps, surface padding and gap |
294
+ | `density` | 0.75–1.5 | Control height, padding and indicator size |
295
+ | `controlRadius` | 0–32px | Control radius |
296
+ | `surfaceRadius` | 0–48px | Card, Dialog and Collapsible radius |
297
+ | `controlBorderWidth`, `surfaceBorderWidth` | 0–4px | Border widths |
298
+ | `borderStyle` | `solid`, `dashed`, `dotted` | Control and surface borders |
299
+ | `elevation` | 0–3 | Surface and overlay shadows |
300
+ | `backdropOpacity` | 0–0.9 | Modal overlay |
301
+
302
+ Scales apply to the baseline, so applying `spacing: 1.25` twice gives the same
303
+ result. Values out of range throw instead of being clamped.
304
+
305
+ ## Theme documents
306
+
307
+ `ThemeDocument` is the editable, versioned form of a theme, used by the docs
308
+ site's theme workshop. It keeps the authored values plus metadata such as
309
+ palettes and font descriptors. `compileThemeDocument` turns it into a `Theme`
310
+ for `ThemeScope`.
311
+
312
+ | Function | Does |
313
+ | ----------------------------------------------- | --------------------------------------------------------------- |
314
+ | `themeDocumentFromDefinition(definition)` | Wraps a `defineTheme` input, keeping only explicit values |
315
+ | `updateThemeDocument(doc, sections)` | Deep-merges the given sections; arrays are replaced whole |
316
+ | `updateThemeDocument(doc, sections, 'replace')` | Replaces each given section; `{ color: {} }` resets color |
317
+ | `exportThemeSections(doc, ['color'])` | Exports chosen sections without the theme's identity |
318
+ | `parseThemeDocument(json)` | Validates a full document or a section export from `JSON.parse` |
319
+
320
+ Sections match the token groups plus `components`. Updating a section never
321
+ touches `components`, so per-component exceptions survive. Font descriptors
322
+ record requirements only; your application loads the fonts. Parsing rejects
323
+ unknown fields and unsupported versions with the failing path.
324
+
325
+ ## Token reference
326
+
327
+ CSS names are `--rad-` plus the kebab-case path. The values come from
328
+ [`src/themes/tokens.ts`](../src/themes/tokens.ts). `surface.canvas` and
329
+ `surface.backdrop` accept any CSS background, including gradients.
842
330
 
843
331
  | Path | Light default | Dark default |
844
332
  | ------------------------------ | ------------------------------------ | ------------------------------------ |
@@ -909,100 +397,5 @@ durations remain CSS strings; opacity is numeric.
909
397
  | `spacing.footerGap` | `0.5rem` | Same |
910
398
  | `state.disabledOpacity` | `0.5` | Same |
911
399
 
912
- ## Migration from Button-centred themes
913
-
914
- This is a breaking CSS-token migration. Use the JavaScript and stylesheet from
915
- the same version; do not mix new theme data with an old compiled stylesheet.
916
-
917
- 1. Replace wrappers such as `<div style={theme.style}>` with
918
- `<ThemeScope theme={theme}>`. `Theme.style`, `Theme.surface`, and the
919
- `radiantTheme` style alias are removed. Use `radiant` with `ThemeScope`, which
920
- chooses the canvas for the active mode. A hand-written `{ name, style }`
921
- object is no longer a `Theme`: author it with `defineTheme`.
922
- 2. Move shared settings out of `buttonTheme` into `tokens`: font family into
923
- `typography.family`, heights/padding/font sizes into the matching `control`
924
- size group, radius/shape/borders into `control` and `surface`, focus into
925
- `color.focus`/`focus`, and timing into `motion`. Input, Checkbox, Radio,
926
- Dialog, Collapsible, Card, and Link no longer fall back through Button's
927
- overrides. Input's native numeric `size` attribute is unchanged.
928
- 3. Replace the removed `buttonTheme`, `linkTheme`, `fieldTheme`, `inputTheme`,
929
- `checkboxTheme`, `radioTheme`, `dialogTheme`, `collapsibleTheme`,
930
- `accordionTheme`, and `cardTheme` helpers with `components.<family>` in
931
- `defineTheme`. Their corresponding `*Theme` type aliases are removed; use
932
- `ThemeComponentOverrides` or an indexed family type such as
933
- `NonNullable<ThemeComponentOverrides['button']>` for reusable configuration.
934
- For a one-off host or named part, use `style` with typed `--rad-*` variables:
935
-
936
- ```tsx
937
- import { Button, type ThemeStyle } from '@cognitap/radiant'
938
-
939
- const local: ThemeStyle = { '--rad-button-radius': '1rem' }
940
-
941
- ;<Button style={local}>Save</Button>
942
- ```
943
-
944
- A local style is a partial override; a named `ThemeScope` deliberately resets
945
- omitted settings to the shared baseline. Do not spread a resolved mode map
946
- onto a wrapper as a replacement for ThemeScope's theme/mode inheritance.
947
-
948
- 4. Rename direct CSS overrides using the following map. Button's `focusColor`
949
- maps to `--rad-button-focus-color`; it no longer changes shared focus.
950
- Move the old `radioTheme({ gap })` group shortcut to
951
- `components.radioGroup.gap`; `components.radio.labelGap` remains option-local.
952
- 5. Remove `glowHover`: it never had a rendering effect and is rejected by
953
- `defineTheme`. The library no longer supplies `--ease-spring`, `--ease-snap`,
954
- or `--ease-settle`; put the required literal `linear(...)`/`cubic-bezier(...)`
955
- curve in the motion token or a deliberate component exception. Application
956
- CSS variables are also supported when your application defines them.
957
-
958
- | Old variable | Replacement |
959
- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
960
- | `--color-background` | `--rad-color-surface` (canvas is `--rad-surface-canvas`) |
961
- | `--color-foreground`, `--color-border`, `--color-focus` | Corresponding `--rad-color-*` role |
962
- | `--color-primary`, `--color-primary-foreground` | `--rad-color-accent`, `--rad-color-accent-foreground` |
963
- | `--color-secondary`, `--color-secondary-foreground` | `--rad-color-neutral`, `--rad-color-neutral-foreground` |
964
- | `--color-warning`, `--color-warning-foreground` | `--rad-color-warning`, `--rad-color-warning-foreground` |
965
- | `--color-destructive`, `--color-destructive-foreground` | `--rad-color-danger`, `--rad-color-danger-foreground` |
966
- | `--radius-control` | `--rad-control-radius` |
967
- | `--button-*`, `--input-*`, `--field-*`, other family overrides | `--rad-button-*`, `--rad-input-*`, `--rad-field-*`, corresponding prefixed family |
968
- | `--radio-gap` | `--rad-radio-group-gap` |
969
- | `--button-focus-color` (stale consumers) | `--rad-color-focus` for shared focus; `--rad-button-focus-color` for Button alone |
970
-
971
- The source stylesheet no longer registers `background`, `foreground`, `border`,
972
- `primary`, `secondary`, `warning`, `destructive`, or `focus` color aliases, or the
973
- `control` radius alias. Replace classes such as `bg-primary` with
974
- `bg-(--rad-color-accent)` and `rounded-control` with
975
- `rounded-(--rad-control-radius)`, or define your own application aliases.
976
-
977
- The theme registry is readonly; choose a preset by
978
- `theme.id` rather than editing the registry or relying on its display name.
979
- Storybook's global Theme and Mode controls use this same preset registry.
980
- Button and Link now share `variant`, `tone`, and `controlSize`; see the
981
- [README action migration table](../README.md#action-api-migration-breaking).
982
- Action-only geometry, elevation and motion remain deliberate Button component
983
- overrides consumed by both Button and action-shaped Link. Inline/subtle Link
984
- retains its own decoration and focus overrides. Soft and unfilled ink mixes the
985
- selected tone toward the scope foreground; explicit Link colour overrides win.
986
-
987
- ### Cleanup inventory (DEV-132)
988
-
989
- | Area | Disposition |
990
- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
991
- | Ten family helpers/types, `radiantTheme`, resolved `style`/`surface` fields | Removed directly under the experimental 0.x policy; replacements above |
992
- | Old unprefixed color/radius aliases and ambient easing variables | Removed from the source and compiled styling routes |
993
- | Old action variants, `size`/`radius` presentation props and `data-size` | Already retired by the action/form migrations; no compatibility path restored |
994
- | Shared semantic tokens and typed `components` overrides | Retained as the canonical theme authoring contract |
995
- | `ThemeStyle`, native props, named parts, state hooks and `render` | Retained for local styling and native composition |
996
- | Button and action-shaped Link presentation | One private `actionStyles` implementation; action-only Button slots are intentionally shared |
997
- | Dialog actions and Accordion sections | Compose Button and Collapsible respectively; no parallel action/disclosure paint |
998
-
999
- Every component slot in the registry has a reader. Input, Field, Checkbox,
1000
- Radio, Dialog, Collapsible and Card resolve their own override, then a shared
1001
- role or neutral default. Only Button and action-shaped Link consume action
1002
- slots; inline/subtle Link keeps its own decoration/focus contract. Existing
1003
- preset values and light/dark mode maps are unchanged by this cleanup.
1004
-
1005
- This removes compatibility paths without publishing a package. The next
1006
- release must carry these breaking migration notes under the
1007
- [release policy](../RELEASE_POLICY.md); earlier changelog entries describe their
1008
- delivery-time behavior.
400
+ Typography recipes add `typography.roles` and `typography.flow` leaves, which
401
+ can also be authored directly.