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