@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.
- package/CHANGELOG.md +69 -0
- package/README.md +28 -15
- package/dist/library/Card.d.ts.map +1 -1
- package/dist/library/Card.js +8 -6
- package/dist/library/Card.js.map +1 -1
- package/dist/library/Checkbox.js +2 -2
- package/dist/library/Checkbox.js.map +1 -1
- package/dist/library/Collapsible.d.ts.map +1 -1
- package/dist/library/Collapsible.js +5 -4
- package/dist/library/Collapsible.js.map +1 -1
- package/dist/library/Dialog.d.ts.map +1 -1
- package/dist/library/Dialog.js +8 -6
- package/dist/library/Dialog.js.map +1 -1
- package/dist/library/Field.js +4 -4
- package/dist/library/Field.js.map +1 -1
- package/dist/library/Input.d.ts.map +1 -1
- package/dist/library/Input.js +4 -3
- package/dist/library/Input.js.map +1 -1
- package/dist/library/Link.d.ts.map +1 -1
- package/dist/library/Link.js +0 -1
- package/dist/library/Link.js.map +1 -1
- package/dist/library/RadioGroup.js +2 -2
- package/dist/library/RadioGroup.js.map +1 -1
- package/dist/library/ThemeScope.js +1 -1
- package/dist/library/ThemeScope.js.map +1 -1
- package/dist/library/actionStyles.js +2 -2
- package/dist/library/actionStyles.js.map +1 -1
- package/dist/library/cn.d.ts +2 -1
- package/dist/library/cn.d.ts.map +1 -1
- package/dist/library/cn.js +22 -1
- package/dist/library/cn.js.map +1 -1
- package/dist/library/color/colorFamilies.d.ts +3 -0
- package/dist/library/color/colorFamilies.d.ts.map +1 -0
- package/dist/library/color/colorFamilies.js +20 -0
- package/dist/library/color/colorFamilies.js.map +1 -0
- package/dist/library/color/generateColorWall.d.ts +54 -0
- package/dist/library/color/generateColorWall.d.ts.map +1 -0
- package/dist/library/color/generateColorWall.js +231 -0
- package/dist/library/color/generateColorWall.js.map +1 -0
- package/dist/library/color/index.d.ts +5 -0
- package/dist/library/color/index.d.ts.map +1 -0
- package/dist/library/color/index.js +3 -0
- package/dist/library/color/index.js.map +1 -0
- package/dist/library/color/oklch.d.ts +17 -0
- package/dist/library/color/oklch.d.ts.map +1 -0
- package/dist/library/color/oklch.js +79 -0
- package/dist/library/color/oklch.js.map +1 -0
- package/dist/library/color/recommendColorPalette.d.ts +65 -0
- package/dist/library/color/recommendColorPalette.d.ts.map +1 -0
- package/dist/library/color/recommendColorPalette.js +263 -0
- package/dist/library/color/recommendColorPalette.js.map +1 -0
- package/dist/library/index.d.ts +10 -2
- package/dist/library/index.d.ts.map +1 -1
- package/dist/library/index.js +5 -1
- package/dist/library/index.js.map +1 -1
- package/dist/library/styles.css +1 -1
- package/dist/library/themes/defineTheme.d.ts.map +1 -1
- package/dist/library/themes/defineTheme.js +5 -1
- package/dist/library/themes/defineTheme.js.map +1 -1
- package/dist/library/themes/index.d.ts +4 -0
- package/dist/library/themes/index.d.ts.map +1 -1
- package/dist/library/themes/index.js +2 -0
- package/dist/library/themes/index.js.map +1 -1
- package/dist/library/themes/themeDocument.d.ts +16 -0
- package/dist/library/themes/themeDocument.d.ts.map +1 -0
- package/dist/library/themes/themeDocument.js +332 -0
- package/dist/library/themes/themeDocument.js.map +1 -0
- package/dist/library/themes/themeDocumentTypes.d.ts +80 -0
- package/dist/library/themes/themeDocumentTypes.d.ts.map +1 -0
- package/dist/library/themes/themeDocumentTypes.js +2 -0
- package/dist/library/themes/themeDocumentTypes.js.map +1 -0
- package/dist/library/themes/tokens.d.ts +7 -0
- package/dist/library/themes/tokens.d.ts.map +1 -1
- package/dist/library/themes/tokens.js +99 -0
- package/dist/library/themes/tokens.js.map +1 -1
- package/dist/library/themes/updateThemeAppearance.d.ts +29 -0
- package/dist/library/themes/updateThemeAppearance.d.ts.map +1 -0
- package/dist/library/themes/updateThemeAppearance.js +138 -0
- package/dist/library/themes/updateThemeAppearance.js.map +1 -0
- package/dist/library/typography/index.d.ts +72 -0
- package/dist/library/typography/index.d.ts.map +1 -0
- package/dist/library/typography/index.js +160 -0
- package/dist/library/typography/index.js.map +1 -0
- package/dist/library/typography/types.d.ts +78 -0
- package/dist/library/typography/types.d.ts.map +1 -0
- package/dist/library/typography/types.js +2 -0
- package/dist/library/typography/types.js.map +1 -0
- package/docs/system.md +20 -0
- package/docs/theming.md +616 -0
- package/package.json +17 -5
- package/src/Card.tsx +8 -6
- package/src/Checkbox.tsx +2 -2
- package/src/Collapsible.tsx +5 -4
- package/src/Dialog.tsx +8 -6
- package/src/Field.tsx +4 -4
- package/src/Input.tsx +4 -3
- package/src/Link.tsx +0 -1
- package/src/RadioGroup.tsx +2 -2
- package/src/ThemeScope.tsx +1 -1
- package/src/actionStyles.ts +2 -2
- package/src/cn.ts +25 -1
- package/src/color/colorFamilies.ts +19 -0
- package/src/color/generateColorWall.ts +358 -0
- package/src/color/index.ts +11 -0
- package/src/color/oklch.ts +95 -0
- package/src/color/recommendColorPalette.ts +375 -0
- package/src/index.ts +40 -0
- package/src/styles.css +1 -0
- package/src/themes/baseline.css +131 -0
- package/src/themes/defineTheme.ts +5 -1
- package/src/themes/index.ts +25 -0
- package/src/themes/themeDocument.ts +370 -0
- package/src/themes/themeDocumentTypes.ts +88 -0
- package/src/themes/tokens.ts +137 -0
- package/src/themes/updateThemeAppearance.ts +172 -0
- package/src/typography/index.ts +199 -0
- package/src/typography/types.ts +92 -0
- 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
|