@cognitap/radiant 0.0.3 → 0.0.5

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 (118) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +28 -15
  3. package/dist/library/Card.d.ts.map +1 -1
  4. package/dist/library/Card.js +8 -6
  5. package/dist/library/Card.js.map +1 -1
  6. package/dist/library/Checkbox.js +2 -2
  7. package/dist/library/Checkbox.js.map +1 -1
  8. package/dist/library/Collapsible.d.ts.map +1 -1
  9. package/dist/library/Collapsible.js +5 -4
  10. package/dist/library/Collapsible.js.map +1 -1
  11. package/dist/library/Dialog.d.ts.map +1 -1
  12. package/dist/library/Dialog.js +8 -6
  13. package/dist/library/Dialog.js.map +1 -1
  14. package/dist/library/Field.js +4 -4
  15. package/dist/library/Field.js.map +1 -1
  16. package/dist/library/Input.d.ts.map +1 -1
  17. package/dist/library/Input.js +4 -3
  18. package/dist/library/Input.js.map +1 -1
  19. package/dist/library/Link.d.ts.map +1 -1
  20. package/dist/library/Link.js +0 -1
  21. package/dist/library/Link.js.map +1 -1
  22. package/dist/library/RadioGroup.js +2 -2
  23. package/dist/library/RadioGroup.js.map +1 -1
  24. package/dist/library/ThemeScope.js +1 -1
  25. package/dist/library/ThemeScope.js.map +1 -1
  26. package/dist/library/actionStyles.js +2 -2
  27. package/dist/library/actionStyles.js.map +1 -1
  28. package/dist/library/cn.d.ts +2 -1
  29. package/dist/library/cn.d.ts.map +1 -1
  30. package/dist/library/cn.js +22 -1
  31. package/dist/library/cn.js.map +1 -1
  32. package/dist/library/color/colorFamilies.d.ts +3 -0
  33. package/dist/library/color/colorFamilies.d.ts.map +1 -0
  34. package/dist/library/color/colorFamilies.js +20 -0
  35. package/dist/library/color/colorFamilies.js.map +1 -0
  36. package/dist/library/color/generateColorWall.d.ts +54 -0
  37. package/dist/library/color/generateColorWall.d.ts.map +1 -0
  38. package/dist/library/color/generateColorWall.js +231 -0
  39. package/dist/library/color/generateColorWall.js.map +1 -0
  40. package/dist/library/color/index.d.ts +5 -0
  41. package/dist/library/color/index.d.ts.map +1 -0
  42. package/dist/library/color/index.js +3 -0
  43. package/dist/library/color/index.js.map +1 -0
  44. package/dist/library/color/oklch.d.ts +17 -0
  45. package/dist/library/color/oklch.d.ts.map +1 -0
  46. package/dist/library/color/oklch.js +79 -0
  47. package/dist/library/color/oklch.js.map +1 -0
  48. package/dist/library/color/recommendColorPalette.d.ts +65 -0
  49. package/dist/library/color/recommendColorPalette.d.ts.map +1 -0
  50. package/dist/library/color/recommendColorPalette.js +263 -0
  51. package/dist/library/color/recommendColorPalette.js.map +1 -0
  52. package/dist/library/index.d.ts +10 -2
  53. package/dist/library/index.d.ts.map +1 -1
  54. package/dist/library/index.js +5 -1
  55. package/dist/library/index.js.map +1 -1
  56. package/dist/library/styles.css +1 -1
  57. package/dist/library/themes/defineTheme.d.ts.map +1 -1
  58. package/dist/library/themes/defineTheme.js +5 -1
  59. package/dist/library/themes/defineTheme.js.map +1 -1
  60. package/dist/library/themes/index.d.ts +4 -0
  61. package/dist/library/themes/index.d.ts.map +1 -1
  62. package/dist/library/themes/index.js +2 -0
  63. package/dist/library/themes/index.js.map +1 -1
  64. package/dist/library/themes/themeDocument.d.ts +16 -0
  65. package/dist/library/themes/themeDocument.d.ts.map +1 -0
  66. package/dist/library/themes/themeDocument.js +332 -0
  67. package/dist/library/themes/themeDocument.js.map +1 -0
  68. package/dist/library/themes/themeDocumentTypes.d.ts +80 -0
  69. package/dist/library/themes/themeDocumentTypes.d.ts.map +1 -0
  70. package/dist/library/themes/themeDocumentTypes.js +2 -0
  71. package/dist/library/themes/themeDocumentTypes.js.map +1 -0
  72. package/dist/library/themes/tokens.d.ts +7 -0
  73. package/dist/library/themes/tokens.d.ts.map +1 -1
  74. package/dist/library/themes/tokens.js +99 -0
  75. package/dist/library/themes/tokens.js.map +1 -1
  76. package/dist/library/themes/updateThemeAppearance.d.ts +29 -0
  77. package/dist/library/themes/updateThemeAppearance.d.ts.map +1 -0
  78. package/dist/library/themes/updateThemeAppearance.js +138 -0
  79. package/dist/library/themes/updateThemeAppearance.js.map +1 -0
  80. package/dist/library/typography/index.d.ts +72 -0
  81. package/dist/library/typography/index.d.ts.map +1 -0
  82. package/dist/library/typography/index.js +160 -0
  83. package/dist/library/typography/index.js.map +1 -0
  84. package/dist/library/typography/types.d.ts +78 -0
  85. package/dist/library/typography/types.d.ts.map +1 -0
  86. package/dist/library/typography/types.js +2 -0
  87. package/dist/library/typography/types.js.map +1 -0
  88. package/docs/system.md +20 -0
  89. package/docs/theming.md +616 -0
  90. package/package.json +17 -5
  91. package/src/Card.tsx +8 -6
  92. package/src/Checkbox.tsx +2 -2
  93. package/src/Collapsible.tsx +5 -4
  94. package/src/Dialog.tsx +8 -6
  95. package/src/Field.tsx +4 -4
  96. package/src/Input.tsx +4 -3
  97. package/src/Link.tsx +0 -1
  98. package/src/RadioGroup.tsx +2 -2
  99. package/src/ThemeScope.tsx +1 -1
  100. package/src/actionStyles.ts +2 -2
  101. package/src/cn.ts +25 -1
  102. package/src/color/colorFamilies.ts +19 -0
  103. package/src/color/generateColorWall.ts +358 -0
  104. package/src/color/index.ts +11 -0
  105. package/src/color/oklch.ts +95 -0
  106. package/src/color/recommendColorPalette.ts +375 -0
  107. package/src/index.ts +40 -0
  108. package/src/styles.css +1 -0
  109. package/src/themes/baseline.css +131 -0
  110. package/src/themes/defineTheme.ts +5 -1
  111. package/src/themes/index.ts +25 -0
  112. package/src/themes/themeDocument.ts +370 -0
  113. package/src/themes/themeDocumentTypes.ts +88 -0
  114. package/src/themes/tokens.ts +137 -0
  115. package/src/themes/updateThemeAppearance.ts +172 -0
  116. package/src/typography/index.ts +199 -0
  117. package/src/typography/types.ts +92 -0
  118. package/src/typography.css +336 -0
package/docs/theming.md CHANGED
@@ -70,6 +70,622 @@ values → that theme's mode values**. Missing dark values use the dark baseline
70
70
  unless a common value already overrides them. Put a common color in `tokens`
71
71
  only when it works in both modes, or supply its dark counterpart explicitly.
72
72
 
73
+ ## Portable workshop documents
74
+
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.
80
+
81
+ ```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
+ })
100
+
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
124
+ </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')
139
+ ```
140
+
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.
234
+
235
+ ```tsx
236
+ import { ThemeScope, compileThemeDocument, defineThemeDocument,
237
+ generateTypography, updateThemeDocument } from '@cognitap/radiant'
238
+
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)
248
+
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>
259
+
260
+ const next = updateThemeDocument(document, {
261
+ typography: { typesetting: { ui: { size: 18 } } },
262
+ })
263
+ const result = generateTypography(next.sections.typography!.typesetting)
264
+ ```
265
+
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
426
+
427
+ ```ts
428
+ import { generateColorWall, colorCalibrationPresets } from '@cognitap/radiant/color'
429
+ import { updateThemeDocument } from '@cognitap/radiant'
430
+
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
+ ```
452
+
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
524
+
525
+ ```ts
526
+ import { generateColorWall, recommendColorPalette } from '@cognitap/radiant/color'
527
+ import { updateThemeDocument, compileThemeDocument } from '@cognitap/radiant'
528
+
529
+ const wall = generateColorWall({ brand: '#7C3AED' })
530
+ const palette = recommendColorPalette(wall, {
531
+ working: { support: 'teal' },
532
+ modes: { dark: { focus: '#ABCDEF' } }
533
+ })
534
+
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)
541
+ ```
542
+
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.
612
+
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
+ ```
638
+
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
+
73
689
  ## Scopes, mode, and overrides
74
690
 
75
691
  `ThemeScope` renders a normal `div` and accepts its native props and ref. It