@cognitap/radiant 0.0.2 → 0.0.4
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 +357 -0
- package/README.md +944 -29
- package/dist/library/Accordion.d.ts +56 -0
- package/dist/library/Accordion.d.ts.map +1 -0
- package/dist/library/Accordion.js +89 -0
- package/dist/library/Accordion.js.map +1 -0
- package/dist/library/Button.d.ts +25 -3
- package/dist/library/Button.d.ts.map +1 -1
- package/dist/library/Button.js +31 -3
- package/dist/library/Button.js.map +1 -1
- package/dist/library/Card.d.ts +31 -0
- package/dist/library/Card.d.ts.map +1 -0
- package/dist/library/Card.js +69 -0
- package/dist/library/Card.js.map +1 -0
- package/dist/library/Checkbox.d.ts +13 -0
- package/dist/library/Checkbox.d.ts.map +1 -0
- package/dist/library/Checkbox.js +77 -0
- package/dist/library/Checkbox.js.map +1 -0
- package/dist/library/Collapsible.d.ts +32 -0
- package/dist/library/Collapsible.d.ts.map +1 -0
- package/dist/library/Collapsible.js +99 -0
- package/dist/library/Collapsible.js.map +1 -0
- package/dist/library/Dialog.d.ts +50 -0
- package/dist/library/Dialog.d.ts.map +1 -0
- package/dist/library/Dialog.js +215 -0
- package/dist/library/Dialog.js.map +1 -0
- package/dist/library/Field.d.ts +68 -0
- package/dist/library/Field.d.ts.map +1 -0
- package/dist/library/Field.js +114 -0
- package/dist/library/Field.js.map +1 -0
- package/dist/library/Input.d.ts +10 -0
- package/dist/library/Input.d.ts.map +1 -0
- package/dist/library/Input.js +51 -0
- package/dist/library/Input.js.map +1 -0
- package/dist/library/Link.d.ts +27 -0
- package/dist/library/Link.d.ts.map +1 -0
- package/dist/library/Link.js +50 -0
- package/dist/library/Link.js.map +1 -0
- package/dist/library/RadioGroup.d.ts +27 -0
- package/dist/library/RadioGroup.d.ts.map +1 -0
- package/dist/library/RadioGroup.js +103 -0
- package/dist/library/RadioGroup.js.map +1 -0
- package/dist/library/ThemeScope.d.ts +10 -0
- package/dist/library/ThemeScope.d.ts.map +1 -0
- package/dist/library/ThemeScope.js +41 -0
- package/dist/library/ThemeScope.js.map +1 -0
- package/dist/library/actionStyles.d.ts +11 -0
- package/dist/library/actionStyles.d.ts.map +1 -0
- package/dist/library/actionStyles.js +75 -0
- package/dist/library/actionStyles.js.map +1 -0
- package/dist/library/cn.d.ts +1 -2
- package/dist/library/cn.d.ts.map +1 -1
- package/dist/library/cn.js +1 -8
- 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/controlStyles.d.ts +5 -0
- package/dist/library/controlStyles.d.ts.map +1 -0
- package/dist/library/controlStyles.js +15 -0
- package/dist/library/controlStyles.js.map +1 -0
- package/dist/library/index.d.ts +30 -1
- package/dist/library/index.d.ts.map +1 -1
- package/dist/library/index.js +14 -0
- package/dist/library/index.js.map +1 -1
- package/dist/library/internal/events.d.ts +8 -0
- package/dist/library/internal/events.d.ts.map +1 -0
- package/dist/library/internal/events.js +13 -0
- package/dist/library/internal/events.js.map +1 -0
- package/dist/library/internal/ids.d.ts +3 -0
- package/dist/library/internal/ids.d.ts.map +1 -0
- package/dist/library/internal/ids.js +6 -0
- package/dist/library/internal/ids.js.map +1 -0
- package/dist/library/internal/selection.d.ts +5 -0
- package/dist/library/internal/selection.d.ts.map +1 -0
- package/dist/library/internal/selection.js +18 -0
- package/dist/library/internal/selection.js.map +1 -0
- package/dist/library/presentation.d.ts +18 -0
- package/dist/library/presentation.d.ts.map +1 -0
- package/dist/library/presentation.js +2 -0
- package/dist/library/presentation.js.map +1 -0
- package/dist/library/react/useComposedRefs.d.ts +4 -0
- package/dist/library/react/useComposedRefs.d.ts.map +1 -0
- package/dist/library/react/useComposedRefs.js +28 -0
- package/dist/library/react/useComposedRefs.js.map +1 -0
- package/dist/library/react/useControllableState.d.ts +16 -0
- package/dist/library/react/useControllableState.d.ts.map +1 -0
- package/dist/library/react/useControllableState.js +29 -0
- package/dist/library/react/useControllableState.js.map +1 -0
- package/dist/library/react/useNativeOwner.d.ts +17 -0
- package/dist/library/react/useNativeOwner.d.ts.map +1 -0
- package/dist/library/react/useNativeOwner.js +17 -0
- package/dist/library/react/useNativeOwner.js.map +1 -0
- package/dist/library/reset.css +1 -0
- package/dist/library/styles.css +2 -1
- package/dist/library/themes/components.d.ts +217 -0
- package/dist/library/themes/components.d.ts.map +1 -0
- package/dist/library/themes/components.js +229 -0
- package/dist/library/themes/components.js.map +1 -0
- package/dist/library/themes/default.d.ts +2 -0
- package/dist/library/themes/default.d.ts.map +1 -0
- package/dist/library/themes/default.js +4 -0
- package/dist/library/themes/default.js.map +1 -0
- package/dist/library/themes/defineTheme.d.ts +33 -0
- package/dist/library/themes/defineTheme.d.ts.map +1 -0
- package/dist/library/themes/defineTheme.js +98 -0
- package/dist/library/themes/defineTheme.js.map +1 -0
- package/dist/library/themes/expressive.d.ts +2 -0
- package/dist/library/themes/expressive.d.ts.map +1 -0
- package/dist/library/themes/expressive.js +132 -0
- package/dist/library/themes/expressive.js.map +1 -0
- package/dist/library/themes/glass.d.ts +2 -0
- package/dist/library/themes/glass.d.ts.map +1 -0
- package/dist/library/themes/glass.js +132 -0
- package/dist/library/themes/glass.js.map +1 -0
- package/dist/library/themes/index.d.ts +18 -0
- package/dist/library/themes/index.d.ts.map +1 -0
- package/dist/library/themes/index.js +23 -0
- package/dist/library/themes/index.js.map +1 -0
- package/dist/library/themes/jelly.d.ts +2 -0
- package/dist/library/themes/jelly.d.ts.map +1 -0
- package/dist/library/themes/jelly.js +130 -0
- package/dist/library/themes/jelly.js.map +1 -0
- package/dist/library/themes/preset-values.d.ts +4 -0
- package/dist/library/themes/preset-values.d.ts.map +1 -0
- package/dist/library/themes/preset-values.js +5 -0
- package/dist/library/themes/preset-values.js.map +1 -0
- package/dist/library/themes/radiant.d.ts +2 -0
- package/dist/library/themes/radiant.d.ts.map +1 -0
- package/dist/library/themes/radiant.js +129 -0
- package/dist/library/themes/radiant.js.map +1 -0
- package/dist/library/themes/sharp-3d.d.ts +2 -0
- package/dist/library/themes/sharp-3d.d.ts.map +1 -0
- package/dist/library/themes/sharp-3d.js +142 -0
- package/dist/library/themes/sharp-3d.js.map +1 -0
- package/dist/library/themes/soft-squircle.d.ts +2 -0
- package/dist/library/themes/soft-squircle.d.ts.map +1 -0
- package/dist/library/themes/soft-squircle.js +131 -0
- package/dist/library/themes/soft-squircle.js.map +1 -0
- 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 +307 -0
- package/dist/library/themes/themeDocument.js.map +1 -0
- package/dist/library/themes/themeDocumentTypes.d.ts +69 -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/ticket.d.ts +2 -0
- package/dist/library/themes/ticket.d.ts.map +1 -0
- package/dist/library/themes/ticket.js +141 -0
- package/dist/library/themes/ticket.js.map +1 -0
- package/dist/library/themes/tokens.d.ts +100 -0
- package/dist/library/themes/tokens.d.ts.map +1 -0
- package/dist/library/themes/tokens.js +171 -0
- package/dist/library/themes/tokens.js.map +1 -0
- package/dist/library/themes/types.d.ts +2 -0
- package/dist/library/themes/types.d.ts.map +1 -0
- package/dist/library/themes/types.js +2 -0
- package/dist/library/themes/types.js.map +1 -0
- 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/docs/accessibility.md +189 -0
- package/docs/system.md +231 -0
- package/docs/theming.md +804 -0
- package/package.json +34 -10
- package/src/Accordion.tsx +235 -0
- package/src/Button.tsx +95 -15
- package/src/Card.tsx +143 -0
- package/src/Checkbox.tsx +189 -0
- package/src/Collapsible.tsx +193 -0
- package/src/Dialog.tsx +333 -0
- package/src/Field.tsx +293 -0
- package/src/Input.tsx +82 -0
- package/src/Link.tsx +95 -0
- package/src/RadioGroup.tsx +255 -0
- package/src/ThemeScope.tsx +64 -0
- package/src/actionStyles.ts +90 -0
- package/src/cn.ts +1 -10
- 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/controlStyles.ts +19 -0
- package/src/index.ts +130 -1
- package/src/internal/events.ts +17 -0
- package/src/internal/ids.ts +5 -0
- package/src/internal/selection.ts +20 -0
- package/src/presentation.ts +12 -0
- package/src/react/useComposedRefs.ts +32 -0
- package/src/react/useControllableState.ts +50 -0
- package/src/react/useNativeOwner.ts +33 -0
- package/src/styles.css +2 -14
- package/src/themes/baseline.css +116 -0
- package/src/themes/components.ts +249 -0
- package/src/themes/default.ts +4 -0
- package/src/themes/defineTheme.ts +145 -0
- package/src/themes/expressive.ts +132 -0
- package/src/themes/glass.ts +135 -0
- package/src/themes/index.ts +57 -0
- package/src/themes/jelly.ts +130 -0
- package/src/themes/preset-values.ts +5 -0
- package/src/themes/radiant.ts +129 -0
- package/src/themes/sharp-3d.ts +142 -0
- package/src/themes/soft-squircle.ts +131 -0
- package/src/themes/themeDocument.ts +340 -0
- package/src/themes/themeDocumentTypes.ts +76 -0
- package/src/themes/ticket.ts +141 -0
- package/src/themes/tokens.ts +262 -0
- package/src/themes/types.ts +10 -0
- package/src/themes/updateThemeAppearance.ts +172 -0
package/docs/theming.md
ADDED
|
@@ -0,0 +1,804 @@
|
|
|
1
|
+
# Theming Radiant
|
|
2
|
+
|
|
3
|
+
This is the theme authoring, token and migration reference. Start with the
|
|
4
|
+
[system guide](system.md) for shared composition, ownership and styling rules.
|
|
5
|
+
|
|
6
|
+
Radiant has one shared theme model: semantic tokens define the design system,
|
|
7
|
+
and component overrides describe deliberate exceptions. `Button` does not own
|
|
8
|
+
other components' typography, dimensions, shape, focus, or motion.
|
|
9
|
+
|
|
10
|
+
Import `@cognitap/radiant/styles.css` once. It supplies the complete neutral
|
|
11
|
+
light/dark baseline without a provider. `@cognitap/radiant/reset.css` is a
|
|
12
|
+
separate, optional global reset. Tailwind applications can instead use the
|
|
13
|
+
[source styling route](../README.md#with-tailwind); both routes consume the same
|
|
14
|
+
public theme variables.
|
|
15
|
+
|
|
16
|
+
## Define and apply a theme
|
|
17
|
+
|
|
18
|
+
```tsx
|
|
19
|
+
import '@cognitap/radiant/styles.css'
|
|
20
|
+
import { Button, Field, Input, ThemeScope, defineTheme } from '@cognitap/radiant'
|
|
21
|
+
|
|
22
|
+
const brand = defineTheme({
|
|
23
|
+
id: 'garden',
|
|
24
|
+
name: 'Garden',
|
|
25
|
+
tokens: {
|
|
26
|
+
color: { accent: '#166534', accentForeground: '#ffffff' },
|
|
27
|
+
typography: { family: 'system-ui, sans-serif' },
|
|
28
|
+
control: { radius: '0.75rem' },
|
|
29
|
+
surface: { radius: '1rem' }
|
|
30
|
+
},
|
|
31
|
+
components: {
|
|
32
|
+
button: { fontWeight: 650, pressScale: 0.97 }
|
|
33
|
+
},
|
|
34
|
+
modes: {
|
|
35
|
+
dark: {
|
|
36
|
+
tokens: { color: { accent: '#86efac', accentForeground: '#052e16' } }
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
})
|
|
40
|
+
|
|
41
|
+
function Settings() {
|
|
42
|
+
return (
|
|
43
|
+
<ThemeScope
|
|
44
|
+
theme={brand}
|
|
45
|
+
mode="system"
|
|
46
|
+
>
|
|
47
|
+
<Field label="Garden name">
|
|
48
|
+
<Input name="garden" />
|
|
49
|
+
</Field>
|
|
50
|
+
<Button>Save</Button>
|
|
51
|
+
</ThemeScope>
|
|
52
|
+
)
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`defineTheme({ id, name, tokens, components, modes })` accepts typed partial
|
|
57
|
+
values. `id` is a stable lowercase slug, such as `garden` or `garden-club`;
|
|
58
|
+
`name` is a nonempty display label. Select and persist identity by ID, never
|
|
59
|
+
by the label. The result is immutable, JSON-serializable theme data.
|
|
60
|
+
|
|
61
|
+
Unknown token groups, roles, component names, or override keys fail TypeScript
|
|
62
|
+
checks and throw at runtime. CSS lengths, colors, durations, and easings are
|
|
63
|
+
nonempty strings. Weights accept strings or numbers; numeric effects must be
|
|
64
|
+
finite, and opacity values must be between 0 and 1. CSS grammar and contrast
|
|
65
|
+
remain the author's responsibility: `var(--brand-accent)` is a valid value,
|
|
66
|
+
but Radiant cannot verify what that application variable resolves to.
|
|
67
|
+
|
|
68
|
+
For each mode the resolution order is **library mode defaults → common theme
|
|
69
|
+
values → that theme's mode values**. Missing dark values use the dark baseline
|
|
70
|
+
unless a common value already overrides them. Put a common color in `tokens`
|
|
71
|
+
only when it works in both modes, or supply its dark counterpart explicitly.
|
|
72
|
+
|
|
73
|
+
## 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
|
+
Font metadata does not set `typography.values.family` automatically.
|
|
213
|
+
|
|
214
|
+
Full and selective authoring JSON preserve those descriptors; only selecting
|
|
215
|
+
`typography` exports them. Compiled `Theme` output contains resolved CSS values
|
|
216
|
+
and no palette/source/font metadata. Both formats are data: plain objects,
|
|
217
|
+
arrays, strings, booleans, null and finite numbers, restricted further by their
|
|
218
|
+
field schema. Functions, class/binary instances, cycles, accessors and unsupported
|
|
219
|
+
keys fail before import can silently discard data.
|
|
220
|
+
|
|
221
|
+
## Generate a color wall
|
|
222
|
+
|
|
223
|
+
```ts
|
|
224
|
+
import { generateColorWall, colorCalibrationPresets } from '@cognitap/radiant/color'
|
|
225
|
+
import { updateThemeDocument } from '@cognitap/radiant'
|
|
226
|
+
|
|
227
|
+
const wall = generateColorWall({
|
|
228
|
+
brand: '#7C3AED',
|
|
229
|
+
wallPreset: 'expressive',
|
|
230
|
+
rampPreset: 'balanced'
|
|
231
|
+
})
|
|
232
|
+
// Registry entries supply stable IDs, names and descriptions for public controls.
|
|
233
|
+
console.log(colorCalibrationPresets)
|
|
234
|
+
// Optional dials are materialised, so this reproduces every output swatch.
|
|
235
|
+
const replay = generateColorWall(JSON.parse(JSON.stringify(wall.input)))
|
|
236
|
+
|
|
237
|
+
// Retain independently authored semantic values/modes; replace generated metadata
|
|
238
|
+
// so switching to unanchored fidelity also removes the previous anchor.
|
|
239
|
+
const previous = document.sections.color
|
|
240
|
+
const next = updateThemeDocument(
|
|
241
|
+
document,
|
|
242
|
+
{
|
|
243
|
+
color: { values: previous?.values, modes: previous?.modes, ...wall.color }
|
|
244
|
+
},
|
|
245
|
+
'replace'
|
|
246
|
+
)
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
The generator is available from the package root and from the React-free
|
|
250
|
+
`@cognitap/radiant/color` entry. It reads no browser globals, loads no fonts and
|
|
251
|
+
uses no randomness or AI. The result is detached, deeply frozen, JSON-safe data.
|
|
252
|
+
This is an unreleased API until the next package publication.
|
|
253
|
+
|
|
254
|
+
`wall.color` fits the existing `ThemeColorSection`: original `brand`, selected
|
|
255
|
+
`fidelity`, 18 `palettes` and an `anchor` only for anchored fidelity. Palette order
|
|
256
|
+
is Brand, Red, Orange, Amber, Yellow, Lime, Green, Emerald, Teal, Cyan, Sky, Blue,
|
|
257
|
+
Indigo, Violet, Purple, Pink, Rose, Neutral. Each has a stable lowercase ID and
|
|
258
|
+
11 swatches at 50, 100, 200, …, 900, 950. Generated values are opaque six-digit
|
|
259
|
+
sRGB hex; the exact original preserves its supplied spelling/case.
|
|
260
|
+
`wall.neutralInput` reports the low-chroma path. `wall.input` contains all
|
|
261
|
+
materialised controls and algorithm `version: 1` for replay. Persist that input
|
|
262
|
+
as a generator recipe separately; the current version-1 theme document stores
|
|
263
|
+
its color output, not a new untyped generation-settings field.
|
|
264
|
+
|
|
265
|
+
| Input | Default | Supported range / meaning |
|
|
266
|
+
| ---------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
267
|
+
| `brand` | Required | Opaque six-digit sRGB hex. Alpha, CSS functions, named colors and P3 sources are rejected explicitly. |
|
|
268
|
+
| `version` | `1` | Only the calibrated algorithm version 1 is supported. |
|
|
269
|
+
| `gamut` | `srgb` | Only sRGB output is currently supported. No automatic P3 fallback or source replacement. |
|
|
270
|
+
| `fidelity` | `anchored` | `anchored` preserves the original at its nearest-lightness numbered stop; `unanchored` keeps the regular ramp and separate original. |
|
|
271
|
+
| `wallPreset` | `balanced` | `classic`, `balanced`, `expressive`; selects the supporting wall's curves, automatic vividness, neutral tint and hue alignment. |
|
|
272
|
+
| `rampPreset` | `balanced` | Same three IDs, independently selects brand curves, automatic vividness and anchor reshaping. |
|
|
273
|
+
| `brandVividness` | Source-derived by ramp preset | 0–1 brand-ramp chroma, independent of wall vividness; never changes the exact source. |
|
|
274
|
+
| `vividness` | Source-derived by wall preset | 0–1 supporting-wall chroma; it never changes the brand ramp. |
|
|
275
|
+
| `lightness` | `hue-aware` | `hue-aware` adapts the middle toward each hue's gamut cusp; `shared` uses the common reference curve. |
|
|
276
|
+
| `distribution` | `1` | .75–1.35. Redistributes intermediate shades while retaining endpoints/middle in regular chromatic ramps. |
|
|
277
|
+
| `neutralTint` | Classic `.012`, Balanced `.008`, Expressive `.016` | 0–.035 peak chroma in the Neutral ramp; zero produces untinted grays. |
|
|
278
|
+
| `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. |
|
|
279
|
+
| `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. |
|
|
280
|
+
|
|
281
|
+
Classic retains the [accepted DEV-151 calibration](https://github.com/cognitap/radiant/blob/50044fc0d6d66c94b2e3dfb02fc17c0d2828aff6/docs/research/dev-151-calibration-proposal.md).
|
|
282
|
+
It uses the reference lightness curve .985, .965, .93, .87, .79, .70, .61, .52,
|
|
283
|
+
.43, .34, .24, hue-relative gamut fractions and a smooth chroma envelope. Anchored
|
|
284
|
+
fidelity reshapes neighboring lightness and chroma around the unchanged source.
|
|
285
|
+
Balanced and Expressive use monotone cubic lightness reshaping and local gamut-relative
|
|
286
|
+
chroma blending around the anchor; Classic retains linear lightness reshaping.
|
|
287
|
+
For automatic settings, let `m = sqrt(clamp(source C / .28, 0, 1))`. Balanced uses
|
|
288
|
+
wall strength `.45 + .4m` and brand strength `.18 + .65m`; Expressive uses
|
|
289
|
+
`.6 + .3m` and `.28 + .62m`. Classic uses source C / available C, clamped to
|
|
290
|
+
.10–.92 (.35 for low-chroma sources), for both. Hue-aware midpoints, envelope
|
|
291
|
+
limits and distribution curves follow the selected preset independently.
|
|
292
|
+
`distribution` multiplies each preset's exponent (Classic 1, Balanced .95,
|
|
293
|
+
Expressive 1.05); `shared` fixes the midpoint at .7. Explicit dials override
|
|
294
|
+
preset defaults, and every effective input is materialised for exact replay.
|
|
295
|
+
Public editors should clear wall-owned dials (vividness/tint/alignment) when
|
|
296
|
+
selecting a wall preset, and brandVividness when selecting a ramp preset; retain
|
|
297
|
+
independent controls and explicit semantic pins.
|
|
298
|
+
|
|
299
|
+
Nearest-lightness ties prefer the earlier/lighter stop. Black and white can
|
|
300
|
+
occupy the endpoint stops. Metrics and anchor selection use actual quantized
|
|
301
|
+
colors, rather than assuming requested OKLCH values survived mapping unchanged.
|
|
302
|
+
|
|
303
|
+
The mapper reduces chroma at constant lightness/hue until the result fits sRGB,
|
|
304
|
+
then emits 8-bit output. Conversion uses [Ottosson's Oklab matrices](https://bottosson.github.io/posts/oklab/)
|
|
305
|
+
and the [CSS Color 4 transfer functions](https://www.w3.org/TR/css-color-4/#color-conversion-code).
|
|
306
|
+
This deliberate mapper does not claim to duplicate a browser's gamut-mapping
|
|
307
|
+
algorithm. The per-call caches are discarded after generation; past calls cannot
|
|
308
|
+
change subsequent results or retain an unbounded history of user colors.
|
|
309
|
+
|
|
310
|
+
A color wall is palette data. It does not select semantic text/action/state
|
|
311
|
+
roles, guarantee contrast on arbitrary surfaces or certify chart distinctions.
|
|
312
|
+
Use `recommendColorPalette` below for working sets and named role-pair checks.
|
|
313
|
+
`compileThemeDocument` continues to use only
|
|
314
|
+
semantic `values`/`modes`; adding this metadata alone does not change a rendered
|
|
315
|
+
theme. In Storybook, **System → Color Wall → Reference** exposes the accepted
|
|
316
|
+
12 inputs and controls for visual inspection; the public workshop UI remains
|
|
317
|
+
separate documentation-application work.
|
|
318
|
+
|
|
319
|
+
## Recommend a working palette and semantic roles
|
|
320
|
+
|
|
321
|
+
```ts
|
|
322
|
+
import { generateColorWall, recommendColorPalette } from '@cognitap/radiant/color'
|
|
323
|
+
import { updateThemeDocument, compileThemeDocument } from '@cognitap/radiant'
|
|
324
|
+
|
|
325
|
+
const wall = generateColorWall({ brand: '#7C3AED' })
|
|
326
|
+
const palette = recommendColorPalette(wall, {
|
|
327
|
+
working: { support: 'teal' },
|
|
328
|
+
modes: { dark: { focus: '#ABCDEF' } }
|
|
329
|
+
})
|
|
330
|
+
|
|
331
|
+
// Replace the complete color section, preserving the original source and all ramps.
|
|
332
|
+
// Merge the canvas layer to retain surface radius, spacing and other authored values.
|
|
333
|
+
const colored = updateThemeDocument(document, { color: palette.color }, 'replace')
|
|
334
|
+
const themed = updateThemeDocument(colored, { surface: palette.surface })
|
|
335
|
+
const theme = compileThemeDocument(themed)
|
|
336
|
+
const failures = palette.checks.filter(check => check.pass === false)
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
`recommendColorPalette(wall, options?)` consumes a complete version-1 sRGB wall.
|
|
340
|
+
It returns deeply frozen, detached, JSON-safe recommendations. The original
|
|
341
|
+
brand, fidelity, anchor and all 18 ramps remain unchanged in `palette.color`.
|
|
342
|
+
The result has five parts:
|
|
343
|
+
|
|
344
|
+
- `working`: primary, support, neutral, success, warning and danger, each with a
|
|
345
|
+
wall `paletteId` and independently selected light/dark background/foreground pairs.
|
|
346
|
+
- `color`: the original wall metadata plus complete light/dark maps for the
|
|
347
|
+
existing shared color roles. No common-mode values are needed.
|
|
348
|
+
- `surface`: light/dark `canvas` layers, using the existing surface token group.
|
|
349
|
+
- `checks`: measured pairs with mode, role names, exact colors, unrounded ratio,
|
|
350
|
+
minimum, pass/fail and an actionable failure message.
|
|
351
|
+
- `pass`: whether every listed required pair passes. This is a scoped contrast
|
|
352
|
+
result, not a complete accessibility or arbitrary-theme certification.
|
|
353
|
+
|
|
354
|
+
Defaults use Brand as primary, Neutral for surfaces, Emerald for success, Amber
|
|
355
|
+
for warning and Red for danger. The support family is nearest to primary hue +
|
|
356
|
+
150°. Low-chroma candidates use the wall's explicit hue direction and nominal
|
|
357
|
+
family geometry rather than numerical hue noise. `working` can replace any of
|
|
358
|
+
these family IDs with another existing wall family. Duplicate families are
|
|
359
|
+
allowed deliberately; color alone does not establish status meaning or chart
|
|
360
|
+
separation. Use labels/icons as appropriate.
|
|
361
|
+
|
|
362
|
+
Light canvas/surface start at Neutral 50/100, dark at 950/900. Foreground,
|
|
363
|
+
secondary text, borders, focus, invalid state and action shades are selected
|
|
364
|
+
against the actual emitted opaque surfaces, independently for each mode. Solid
|
|
365
|
+
pairs require 4.5:1 text contrast. Among eligible primary shades, choose the
|
|
366
|
+
smallest Oklab distance to the original brand, including lightness and both
|
|
367
|
+
chromatic axes. Primary fill also requires 3:1 against both surfaces because it
|
|
368
|
+
identifies checked Checkbox/Radio state. Thus a readable exact source is retained
|
|
369
|
+
when its boundaries also pass; otherwise a nearby readable shade is selected. Exact source identity stays separate: yellow may
|
|
370
|
+
remain the exact Brand 200 while a darker related shade supplies the light action.
|
|
371
|
+
Black/white ink can be selected when it gives the strongest text contrast.
|
|
372
|
+
|
|
373
|
+
`options.version` defaults to 1. `options.modes.light`/`dark` can override any
|
|
374
|
+
existing color role and `canvas`, using opaque six-digit sRGB hex. Provided
|
|
375
|
+
surfaces drive automatic dependent choices; explicit foregrounds and other role
|
|
376
|
+
colors are retained even if they fail. Unsupported fields, palette IDs, versions,
|
|
377
|
+
non-opaque colors and incomplete walls fail with a path or available ID list.
|
|
378
|
+
Recipes remain ordinary serializable options; the existing theme document stores
|
|
379
|
+
mapped values and wall metadata, without adding an untyped recipe field.
|
|
380
|
+
|
|
381
|
+
Contrast uses the [WCAG sRGB luminance formula](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
|
|
382
|
+
on final hex values. Normal text (including secondary text, placeholder and invalid
|
|
383
|
+
text) is checked at 4.5:1 on canvas and surface; solid action/working-palette ink
|
|
384
|
+
is checked at 4.5:1 on its fill. Meaningful border, offset focus ring and primary
|
|
385
|
+
checked-state fill are checked at 3:1 on both surfaces. These are Radiant's
|
|
386
|
+
conservative role policies, not a requirement that every decorative boundary or
|
|
387
|
+
hover/rest color differ by 3:1. See [non-text contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html).
|
|
388
|
+
|
|
389
|
+
Disabled token pairs have `minimum: null` and `pass: null`, explicitly reflecting
|
|
390
|
+
the inactive-control exception. Their informational ratios exclude component
|
|
391
|
+
opacity/effects. Pending actions remain active and are not exempt. Support/success
|
|
392
|
+
are working-palette pairs; the current component tones remain accent, neutral,
|
|
393
|
+
warning and danger. No new component tones or runtime token roles are introduced.
|
|
394
|
+
|
|
395
|
+
Apply color and canvas together before relying on the report. A color-only import,
|
|
396
|
+
component/local override, gradient/translucent surface or rendered hover/pressed
|
|
397
|
+
effect can change the effective pair. Recheck those contexts in the browser; this
|
|
398
|
+
base-pair report does not silently certify them. **System → Color Palette →
|
|
399
|
+
Reference** reuses the canonical profile form and inspects invalid, disabled,
|
|
400
|
+
checked, pending and keyboard-focus states in both modes. DEV-155 owns the wider
|
|
401
|
+
theme-editor integration is described below; the public editor itself remains in radiant-docs.
|
|
402
|
+
|
|
403
|
+
## Apply palette, spacing and surfaces together
|
|
404
|
+
|
|
405
|
+
Use `updateThemeAppearance` when the workshop applies generated colors and bounded
|
|
406
|
+
geometry together. It produces an ordinary version-1 `ThemeDocument`; compile it
|
|
407
|
+
through the existing runtime and use either installed CSS route.
|
|
408
|
+
|
|
409
|
+
```ts
|
|
410
|
+
import {
|
|
411
|
+
themeDocumentFromDefinition,
|
|
412
|
+
updateThemeAppearance,
|
|
413
|
+
compileThemeDocument,
|
|
414
|
+
generateColorWall,
|
|
415
|
+
recommendColorPalette
|
|
416
|
+
} from '@cognitap/radiant'
|
|
417
|
+
|
|
418
|
+
const initial = themeDocumentFromDefinition({
|
|
419
|
+
id: 'brand-workshop',
|
|
420
|
+
name: 'Brand workshop',
|
|
421
|
+
components: { button: { radius: '12px' } } // A deliberate exception survives edits.
|
|
422
|
+
})
|
|
423
|
+
const palette = recommendColorPalette(generateColorWall({ brand: '#7C3AED' }))
|
|
424
|
+
const document = updateThemeAppearance(initial, {
|
|
425
|
+
palette,
|
|
426
|
+
geometry: {
|
|
427
|
+
values: { spacing: 1.25, density: 1.1, controlRadius: 8, surfaceRadius: 16, elevation: 2 },
|
|
428
|
+
modes: { dark: { backdropOpacity: 0.75 } }
|
|
429
|
+
}
|
|
430
|
+
})
|
|
431
|
+
const theme = compileThemeDocument(document)
|
|
432
|
+
// <ThemeScope theme={theme} mode="system">...</ThemeScope>
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
The optional `palette` is the mapped result of `recommendColorPalette`, not raw
|
|
436
|
+
wall metadata. Its complete color section replaces previous common/mode colors;
|
|
437
|
+
its light/dark canvas leaves merge into surface settings in the same immutable
|
|
438
|
+
operation. Applying a palette never erases radii, padding, elevation or component
|
|
439
|
+
exceptions. A failing deliberate palette choice is retained; inspect its contrast
|
|
440
|
+
report before applying it.
|
|
441
|
+
|
|
442
|
+
`geometry.values` controls both modes; `geometry.modes.light`/`dark` override
|
|
443
|
+
individual controls. Omitted controls retain authored settings. Each provided
|
|
444
|
+
control maps to the existing semantic token leaves in both modes, overriding
|
|
445
|
+
older common or mode values for those leaves. No recipe metadata or new runtime
|
|
446
|
+
token group is added. An empty update changes no values.
|
|
447
|
+
|
|
448
|
+
| Geometry control | Accepted values | Existing responsibilities |
|
|
449
|
+
| ------------------------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
450
|
+
| `spacing` | 0.5–2 | Multiplies all five `spacing` gaps plus `surface.padding` and `surface.gap`. |
|
|
451
|
+
| `density` | 0.75–1.5 | Multiplies small/medium/large control height, inline padding and indicator size; retains font sizes. |
|
|
452
|
+
| `controlRadius` | 0–32 px | Shared action/input radius; Checkbox caps the inherited radius; Radio remains circular. |
|
|
453
|
+
| `surfaceRadius` | 0–48 px | Card, Dialog and Collapsible shape, including Accordion items. |
|
|
454
|
+
| `controlBorderWidth`, `surfaceBorderWidth` | 0–4 px | Respective shared border widths. |
|
|
455
|
+
| `borderStyle` | `solid`, `dashed`, `dotted` | Both control and surface borders. |
|
|
456
|
+
| `elevation` | Integer 0–3 | 0 removes passive/overlay shadows; 1 uses mode defaults; 2/3 select raised/floating shadows with mode-specific opacity. |
|
|
457
|
+
| `backdropOpacity` | 0–0.9 | Black modal backdrop opacity; panel backdrop filtering stays a Dialog component exception. |
|
|
458
|
+
|
|
459
|
+
Scale controls derive absolute values from the neutral baseline, retaining rem
|
|
460
|
+
units. Reapplying `spacing: 1.25` is idempotent; it never multiplies already-edited
|
|
461
|
+
values. `density: 1` restores baseline metric leaves, while fonts and unrelated
|
|
462
|
+
settings remain authored. Action-local effects/shadows remain component decisions;
|
|
463
|
+
inline Link retains text metrics, and action-shaped Link follows control metrics.
|
|
464
|
+
Values outside the bounds, unknown keys/modes and unsupported `version` (default 1)
|
|
465
|
+
fail with a path instead of being silently clamped. These bounds support workshop
|
|
466
|
+
exploration; border removal, small targets or overrides still need contextual
|
|
467
|
+
accessibility review. Focus behavior, state ownership and forced-colors behavior
|
|
468
|
+
remain the existing families' responsibility.
|
|
469
|
+
|
|
470
|
+
Precedence stays **component exception → shared role → baseline**, followed by
|
|
471
|
+
caller utility/style overrides on the host. Nested mode scopes resolve the same
|
|
472
|
+
compiled theme and retain explicit scope style exceptions; named themes reset
|
|
473
|
+
them. **System → Theme Appearance → Workspace** reuses the canonical ten-family
|
|
474
|
+
workspace, inspects all three control sizes and demonstrates these precedence
|
|
475
|
+
rules. Installed-package checks include the generated theme through compiled CSS
|
|
476
|
+
and Tailwind, with and without a reset.
|
|
477
|
+
|
|
478
|
+
Existing theme definitions, presets, token names, generated baseline CSS and CSS
|
|
479
|
+
imports need no migration. Existing documents can be passed directly; authored
|
|
480
|
+
`ThemeDefinition` inputs use `themeDocumentFromDefinition`. Resolved presets remain
|
|
481
|
+
runtime data and cannot recover their original authoring intent. Advanced CSS
|
|
482
|
+
geometry stays available through typed `updateThemeDocument` token sections and
|
|
483
|
+
component overrides. Public editing and handoff UI follow in DEV-158/DEV-159.
|
|
484
|
+
|
|
485
|
+
## Scopes, mode, and overrides
|
|
486
|
+
|
|
487
|
+
`ThemeScope` renders a normal `div` and accepts its native props and ref. It
|
|
488
|
+
paints its canvas, foreground, and body typography within that subtree. It does
|
|
489
|
+
not change the document, install event listeners, load fonts, or persist a
|
|
490
|
+
preference. A native top-layer Dialog remains in its original scope.
|
|
491
|
+
|
|
492
|
+
- `theme={theme}` starts a fresh named theme from library defaults. Every shared
|
|
493
|
+
token is materialised and every omitted component override is reset to its
|
|
494
|
+
CSS fallback. An outer theme cannot leak its action font or press effect in.
|
|
495
|
+
- Omit `theme` to inherit the current theme. Omit `mode` to inherit the current
|
|
496
|
+
mode. At the application root, the stylesheet defaults to system preference.
|
|
497
|
+
- `mode="light"`, `"dark"`, or `"system"` selects appearance independently of
|
|
498
|
+
theme identity. System follows the CSS media query, so server markup and the
|
|
499
|
+
first client render agree. A mode-only scope resolves the current named theme
|
|
500
|
+
in its selected mode.
|
|
501
|
+
- An inner scope with neither `theme` nor `mode` follows ordinary CSS inheritance;
|
|
502
|
+
it does not establish a new theme. A root scope also paints the neutral canvas
|
|
503
|
+
and typography.
|
|
504
|
+
- Explicit `style` values win over generated values on the same scope host.
|
|
505
|
+
Known theme variables supplied inline to ancestor ThemeScopes are carried
|
|
506
|
+
through mode-only scopes. A new named theme clears these inherited exceptions.
|
|
507
|
+
|
|
508
|
+
Use `defaultTheme` for a complete reset, including component effects:
|
|
509
|
+
|
|
510
|
+
```tsx
|
|
511
|
+
import { Button, ThemeScope, defaultTheme, ticket } from '@cognitap/radiant'
|
|
512
|
+
|
|
513
|
+
;<ThemeScope
|
|
514
|
+
theme={ticket}
|
|
515
|
+
mode="light"
|
|
516
|
+
>
|
|
517
|
+
<Button>Ticket action</Button>
|
|
518
|
+
<ThemeScope theme={defaultTheme}>
|
|
519
|
+
<Button>Neutral action</Button>
|
|
520
|
+
</ThemeScope>
|
|
521
|
+
</ThemeScope>
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
Use shared tokens for local changes that should affect multiple families:
|
|
525
|
+
|
|
526
|
+
```tsx
|
|
527
|
+
<ThemeScope
|
|
528
|
+
theme={brand}
|
|
529
|
+
style={{ '--rad-control-radius': '1.25rem', padding: '2rem' }}
|
|
530
|
+
>
|
|
531
|
+
<Input aria-label="Garden name" />
|
|
532
|
+
<Button>Save</Button>
|
|
533
|
+
</ThemeScope>
|
|
534
|
+
```
|
|
535
|
+
|
|
536
|
+
Ordinary CSS overrides inherit within their existing scope. A mode-only scope
|
|
537
|
+
re-materialises the selected theme, so token overrides from an intervening
|
|
538
|
+
stylesheet rule or an ordinary DOM wrapper are not automatically recovered
|
|
539
|
+
there. Put exceptions that must survive a mode change on a `ThemeScope` inline
|
|
540
|
+
`style`, or include them in the theme definition. No browser computed-style
|
|
541
|
+
snapshot is taken. Ordinary body styles, such as a locally changed font size,
|
|
542
|
+
still follow the cascade and inheritance appropriate to their host.
|
|
543
|
+
|
|
544
|
+
Components resolve **local component override → shared semantic role → neutral
|
|
545
|
+
baseline**. For example, `components.button.radius` overrides Button without
|
|
546
|
+
changing Input; `tokens.control.radius` changes both. Checkbox caps its inherited
|
|
547
|
+
radius at a quarter of its indicator size so it remains a box; an explicit
|
|
548
|
+
`components.checkbox.radius` still wins. Radio stays circular by default, even
|
|
549
|
+
under squircle or scoop control themes. Shared disabled opacity is applied once
|
|
550
|
+
to the relevant visual unit.
|
|
551
|
+
|
|
552
|
+
Input, Checkbox, and Radio derive their default control outline from the shared
|
|
553
|
+
border and foreground colors. This gives interactive boundaries more contrast
|
|
554
|
+
than passive surface dividers. Their explicit `borderColor`, invalid, disabled,
|
|
555
|
+
and focus overrides keep their normal precedence. Disabled selection marks use
|
|
556
|
+
the muted foreground unless the component supplies its own `mark` color.
|
|
557
|
+
|
|
558
|
+
Component overrides use the existing family configuration keys, grouped under
|
|
559
|
+
`button`, `link`, `field`, `input`, `checkbox`, `radio`, `radioGroup`, `dialog`,
|
|
560
|
+
`collapsible`, `accordion`, and `card`. Public declaration types are the
|
|
561
|
+
closed-key reference. `radioGroup.gap` controls group layout;
|
|
562
|
+
`radio.labelGap` controls spacing within a single option. Button-only fonts,
|
|
563
|
+
uppercase text, sheen, shadows, squash, and pressed shape belong under
|
|
564
|
+
`components.button`. Passive surfaces have their own shared surface tokens.
|
|
565
|
+
|
|
566
|
+
Public variable names are derived from the typed registry:
|
|
567
|
+
|
|
568
|
+
| Authoring path | CSS variable |
|
|
569
|
+
| ------------------------------ | ----------------------------- |
|
|
570
|
+
| `tokens.color.accent` | `--rad-color-accent` |
|
|
571
|
+
| `tokens.control.medium.height` | `--rad-control-medium-height` |
|
|
572
|
+
| `tokens.typography.family` | `--rad-typography-family` |
|
|
573
|
+
| `components.button.radius` | `--rad-button-radius` |
|
|
574
|
+
| `components.radioGroup.gap` | `--rad-radio-group-gap` |
|
|
575
|
+
|
|
576
|
+
Matching caller utilities merge with component defaults on the Tailwind route;
|
|
577
|
+
application CSS follows the normal cascade. Generated theme values are inline
|
|
578
|
+
custom properties, so a normal stylesheet declaration on that same host does
|
|
579
|
+
not override them. Put a token override on a descendant or use the host's
|
|
580
|
+
`style` prop. Internal variables beginning `--_` are implementation details.
|
|
581
|
+
|
|
582
|
+
## Preserve functional styles
|
|
583
|
+
|
|
584
|
+
Appearance overrides must preserve closed Dialog/details visibility, dialog
|
|
585
|
+
geometry and scrolling, real control hit targets, and accessible names. Keep
|
|
586
|
+
focus, invalid, disabled, and pending cues visible. The library retains
|
|
587
|
+
forced-colors system colors and reduced-motion alternatives; a theme must not
|
|
588
|
+
erase them with replacement CSS. See the [system guide's functional CSS obligations](system.md#preserve-behavior-when-customising)
|
|
589
|
+
for host replacement and the behavior that overrides must preserve. Importing the optional reset is not required for
|
|
590
|
+
these behaviors.
|
|
591
|
+
|
|
592
|
+
## Presets and fonts
|
|
593
|
+
|
|
594
|
+
The readonly `themes` registry contains these presets, exported individually
|
|
595
|
+
from `@cognitap/radiant`. Each has a deliberate light and dark palette.
|
|
596
|
+
|
|
597
|
+
| Stable ID | Display name | Named export | Shared font family | Action exception |
|
|
598
|
+
| --------------- | ------------- | -------------- | ------------------ | ------------------------------------ |
|
|
599
|
+
| `radiant` | Radiant | `radiant` | Inter | Weight 550 |
|
|
600
|
+
| `default` | Default | `defaultTheme` | System sans | Library baseline |
|
|
601
|
+
| `soft-squircle` | Soft squircle | `soft` | Nunito | Weight 800 |
|
|
602
|
+
| `expressive` | Expressive | `expressive` | Poppins | Weight 600 |
|
|
603
|
+
| `glass` | Glass | `glass` | Manrope | Weight 700; backdrop filter |
|
|
604
|
+
| `sharp-3d` | Sharp 3D | `sharp` | System sans | Archivo Black, weight 400, uppercase |
|
|
605
|
+
| `jelly` | Jelly | `jelly` | Baloo 2 | Weight 700 |
|
|
606
|
+
| `ticket` | Ticket | `ticket` | Barlow Condensed | Weight 600, uppercase |
|
|
607
|
+
|
|
608
|
+
All families have `system-ui, sans-serif` fallbacks. Preset body weight is 400;
|
|
609
|
+
load the label and heading weights 600 and 700 as well as the action weight
|
|
610
|
+
listed above. Default uses baseline label/heading weights 550/600. Radiant's
|
|
611
|
+
Inter action weight 550 requires a variable font or an appropriate supplied
|
|
612
|
+
face; the browser chooses an available weight otherwise.
|
|
613
|
+
|
|
614
|
+
Fonts are application assets. Load the named families with your font loader or
|
|
615
|
+
self-hosted `@font-face` rules before showing the themed UI. Defining or choosing
|
|
616
|
+
a theme never downloads a font. Storybook's font loading belongs to Storybook,
|
|
617
|
+
not the package. `Theme` has no `fonts` field or font-loading API.
|
|
618
|
+
|
|
619
|
+
Glass uses a gradient `surface.canvas` and translucent `color.surface`.
|
|
620
|
+
`components.dialog.backdropFilter` frosts content behind the dialog panel;
|
|
621
|
+
`components.dialog.backdrop` paints the surrounding modal overlay. Button's
|
|
622
|
+
existing `backdrop` override is also a filter and remains independent. Ticket
|
|
623
|
+
uses a compact, solid checkbox outline so small indicators
|
|
624
|
+
remain legible alongside its scooped, dashed controls and surfaces.
|
|
625
|
+
Shape uses CSS `corner-shape`; browsers that do not support it
|
|
626
|
+
retain ordinary rounded corners. A palette definition does not certify contrast
|
|
627
|
+
for arbitrary content, custom backgrounds, or translucent combinations.
|
|
628
|
+
|
|
629
|
+
## Shared token reference
|
|
630
|
+
|
|
631
|
+
These 66 roles and concrete neutral defaults come from
|
|
632
|
+
[`src/themes/tokens.ts`](../src/themes/tokens.ts). CSS names are `--rad-` plus the
|
|
633
|
+
kebab-case dotted path. Values shown in both modes differ only where listed.
|
|
634
|
+
`color` values are CSS colors; `surface.canvas` and `surface.backdrop` are full
|
|
635
|
+
CSS backgrounds and may be gradients. `components.button.backdrop` and
|
|
636
|
+
`components.dialog.backdropFilter` are CSS backdrop-filter values. Lengths and
|
|
637
|
+
durations remain CSS strings; opacity is numeric.
|
|
638
|
+
|
|
639
|
+
| Path | Light default | Dark default |
|
|
640
|
+
| ------------------------------ | ------------------------------------ | ------------------------------------ |
|
|
641
|
+
| `color.surface` | `oklch(1 0 0)` | `oklch(0.21 0.006 286)` |
|
|
642
|
+
| `color.foreground` | `oklch(0.21 0.006 286)` | `oklch(0.985 0 0)` |
|
|
643
|
+
| `color.mutedForeground` | `oklch(0.45 0.01 286)` | `oklch(0.75 0.01 286)` |
|
|
644
|
+
| `color.border` | `oklch(0.885 0.005 286)` | `oklch(0.4 0.008 286)` |
|
|
645
|
+
| `color.placeholder` | `oklch(0.5 0.01 286)` | `oklch(0.7 0.01 286)` |
|
|
646
|
+
| `color.disabledBackground` | `oklch(0.96 0.005 286)` | `oklch(0.26 0.006 286)` |
|
|
647
|
+
| `color.disabledBorder` | `oklch(0.88 0.005 286)` | `oklch(0.38 0.006 286)` |
|
|
648
|
+
| `color.invalid` | `oklch(0.56 0.19 25)` | `oklch(0.75 0.16 25)` |
|
|
649
|
+
| `color.focus` | `oklch(0.55 0.13 255)` | `oklch(0.75 0.13 255)` |
|
|
650
|
+
| `color.accent` | `oklch(0.21 0.006 286)` | `oklch(0.92 0.005 286)` |
|
|
651
|
+
| `color.accentForeground` | `oklch(0.985 0 0)` | `oklch(0.21 0.006 286)` |
|
|
652
|
+
| `color.neutral` | `oklch(0.955 0.004 286)` | `oklch(0.3 0.006 286)` |
|
|
653
|
+
| `color.neutralForeground` | `oklch(0.21 0.006 286)` | `oklch(0.985 0 0)` |
|
|
654
|
+
| `color.warning` | `oklch(0.8 0.14 78)` | Same |
|
|
655
|
+
| `color.warningForeground` | `oklch(0.3 0.07 55)` | Same |
|
|
656
|
+
| `color.danger` | `oklch(0.56 0.19 25)` | `oklch(0.72 0.17 25)` |
|
|
657
|
+
| `color.dangerForeground` | `oklch(0.99 0 0)` | `oklch(0.2 0.04 25)` |
|
|
658
|
+
| `typography.family` | `system-ui, sans-serif` | Same |
|
|
659
|
+
| `typography.bodySize` | `0.875rem` | Same |
|
|
660
|
+
| `typography.smallSize` | `0.8125rem` | Same |
|
|
661
|
+
| `typography.headingSize` | `1.125rem` | Same |
|
|
662
|
+
| `typography.bodyWeight` | `400` | Same |
|
|
663
|
+
| `typography.labelWeight` | `550` | Same |
|
|
664
|
+
| `typography.headingWeight` | `600` | Same |
|
|
665
|
+
| `typography.letterSpacing` | `-0.011em` | Same |
|
|
666
|
+
| `control.small.height` | `2rem` | Same |
|
|
667
|
+
| `control.small.paddingInline` | `0.75rem` | Same |
|
|
668
|
+
| `control.small.fontSize` | `0.8125rem` | Same |
|
|
669
|
+
| `control.small.indicatorSize` | `1rem` | Same |
|
|
670
|
+
| `control.medium.height` | `2.5rem` | Same |
|
|
671
|
+
| `control.medium.paddingInline` | `1rem` | Same |
|
|
672
|
+
| `control.medium.fontSize` | `0.875rem` | Same |
|
|
673
|
+
| `control.medium.indicatorSize` | `1.125rem` | Same |
|
|
674
|
+
| `control.large.height` | `3rem` | Same |
|
|
675
|
+
| `control.large.paddingInline` | `1.375rem` | Same |
|
|
676
|
+
| `control.large.fontSize` | `0.9375rem` | Same |
|
|
677
|
+
| `control.large.indicatorSize` | `1.25rem` | Same |
|
|
678
|
+
| `control.radius` | `0.5rem` | Same |
|
|
679
|
+
| `control.cornerShape` | `round` | Same |
|
|
680
|
+
| `control.borderWidth` | `1px` | Same |
|
|
681
|
+
| `control.borderStyle` | `solid` | Same |
|
|
682
|
+
| `surface.canvas` | `oklch(1 0 0)` | `oklch(0.16 0.006 286)` |
|
|
683
|
+
| `surface.radius` | `0.75rem` | Same |
|
|
684
|
+
| `surface.cornerShape` | `round` | Same |
|
|
685
|
+
| `surface.borderWidth` | `1px` | Same |
|
|
686
|
+
| `surface.borderStyle` | `solid` | Same |
|
|
687
|
+
| `surface.padding` | `1.5rem` | Same |
|
|
688
|
+
| `surface.gap` | `1rem` | Same |
|
|
689
|
+
| `surface.shadow` | `0 1px 2px 0 rgb(0 0 0 / 0.06)` | `0 1px 2px 0 rgb(0 0 0 / 0.25)` |
|
|
690
|
+
| `surface.overlayShadow` | `0 24px 64px -16px rgb(0 0 0 / 0.3)` | `0 24px 64px -16px rgb(0 0 0 / 0.6)` |
|
|
691
|
+
| `surface.backdrop` | `rgb(0 0 0 / 0.45)` | `rgb(0 0 0 / 0.65)` |
|
|
692
|
+
| `focus.width` | `2px` | Same |
|
|
693
|
+
| `focus.offset` | `2px` | Same |
|
|
694
|
+
| `focus.style` | `solid` | Same |
|
|
695
|
+
| `motion.pressDuration` | `80ms` | Same |
|
|
696
|
+
| `motion.pressEase` | `cubic-bezier(0.3, 0, 0, 1)` | Same |
|
|
697
|
+
| `motion.releaseDuration` | `160ms` | Same |
|
|
698
|
+
| `motion.releaseEase` | `cubic-bezier(0.2, 0.8, 0.2, 1)` | Same |
|
|
699
|
+
| `motion.colorDuration` | `150ms` | Same |
|
|
700
|
+
| `motion.disclosureDuration` | `150ms` | Same |
|
|
701
|
+
| `spacing.labelGap` | `0.5rem` | Same |
|
|
702
|
+
| `spacing.fieldGap` | `0.375rem` | Same |
|
|
703
|
+
| `spacing.groupGap` | `0.75rem` | Same |
|
|
704
|
+
| `spacing.headerGap` | `0.375rem` | Same |
|
|
705
|
+
| `spacing.footerGap` | `0.5rem` | Same |
|
|
706
|
+
| `state.disabledOpacity` | `0.5` | Same |
|
|
707
|
+
|
|
708
|
+
## Migration from Button-centred themes
|
|
709
|
+
|
|
710
|
+
This is a breaking CSS-token migration. Use the JavaScript and stylesheet from
|
|
711
|
+
the same version; do not mix new theme data with an old compiled stylesheet.
|
|
712
|
+
|
|
713
|
+
1. Replace wrappers such as `<div style={theme.style}>` with
|
|
714
|
+
`<ThemeScope theme={theme}>`. `Theme.style`, `Theme.surface`, and the
|
|
715
|
+
`radiantTheme` style alias are removed. Use `radiant` with `ThemeScope`, which
|
|
716
|
+
chooses the canvas for the active mode. A hand-written `{ name, style }`
|
|
717
|
+
object is no longer a `Theme`: author it with `defineTheme`.
|
|
718
|
+
2. Move shared settings out of `buttonTheme` into `tokens`: font family into
|
|
719
|
+
`typography.family`, heights/padding/font sizes into the matching `control`
|
|
720
|
+
size group, radius/shape/borders into `control` and `surface`, focus into
|
|
721
|
+
`color.focus`/`focus`, and timing into `motion`. Input, Checkbox, Radio,
|
|
722
|
+
Dialog, Collapsible, Card, and Link no longer fall back through Button's
|
|
723
|
+
overrides. Input's native numeric `size` attribute is unchanged.
|
|
724
|
+
3. Replace the removed `buttonTheme`, `linkTheme`, `fieldTheme`, `inputTheme`,
|
|
725
|
+
`checkboxTheme`, `radioTheme`, `dialogTheme`, `collapsibleTheme`,
|
|
726
|
+
`accordionTheme`, and `cardTheme` helpers with `components.<family>` in
|
|
727
|
+
`defineTheme`. Their corresponding `*Theme` type aliases are removed; use
|
|
728
|
+
`ThemeComponentOverrides` or an indexed family type such as
|
|
729
|
+
`NonNullable<ThemeComponentOverrides['button']>` for reusable configuration.
|
|
730
|
+
For a one-off host or named part, use `style` with typed `--rad-*` variables:
|
|
731
|
+
|
|
732
|
+
```tsx
|
|
733
|
+
import { Button, type ThemeStyle } from '@cognitap/radiant'
|
|
734
|
+
|
|
735
|
+
const local: ThemeStyle = { '--rad-button-radius': '1rem' }
|
|
736
|
+
|
|
737
|
+
;<Button style={local}>Save</Button>
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
A local style is a partial override; a named `ThemeScope` deliberately resets
|
|
741
|
+
omitted settings to the shared baseline. Do not spread a resolved mode map
|
|
742
|
+
onto a wrapper as a replacement for ThemeScope's theme/mode inheritance.
|
|
743
|
+
|
|
744
|
+
4. Rename direct CSS overrides using the following map. Button's `focusColor`
|
|
745
|
+
maps to `--rad-button-focus-color`; it no longer changes shared focus.
|
|
746
|
+
Move the old `radioTheme({ gap })` group shortcut to
|
|
747
|
+
`components.radioGroup.gap`; `components.radio.labelGap` remains option-local.
|
|
748
|
+
5. Remove `glowHover`: it never had a rendering effect and is rejected by
|
|
749
|
+
`defineTheme`. The library no longer supplies `--ease-spring`, `--ease-snap`,
|
|
750
|
+
or `--ease-settle`; put the required literal `linear(...)`/`cubic-bezier(...)`
|
|
751
|
+
curve in the motion token or a deliberate component exception. Application
|
|
752
|
+
CSS variables are also supported when your application defines them.
|
|
753
|
+
|
|
754
|
+
| Old variable | Replacement |
|
|
755
|
+
| -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
|
756
|
+
| `--color-background` | `--rad-color-surface` (canvas is `--rad-surface-canvas`) |
|
|
757
|
+
| `--color-foreground`, `--color-border`, `--color-focus` | Corresponding `--rad-color-*` role |
|
|
758
|
+
| `--color-primary`, `--color-primary-foreground` | `--rad-color-accent`, `--rad-color-accent-foreground` |
|
|
759
|
+
| `--color-secondary`, `--color-secondary-foreground` | `--rad-color-neutral`, `--rad-color-neutral-foreground` |
|
|
760
|
+
| `--color-warning`, `--color-warning-foreground` | `--rad-color-warning`, `--rad-color-warning-foreground` |
|
|
761
|
+
| `--color-destructive`, `--color-destructive-foreground` | `--rad-color-danger`, `--rad-color-danger-foreground` |
|
|
762
|
+
| `--radius-control` | `--rad-control-radius` |
|
|
763
|
+
| `--button-*`, `--input-*`, `--field-*`, other family overrides | `--rad-button-*`, `--rad-input-*`, `--rad-field-*`, corresponding prefixed family |
|
|
764
|
+
| `--radio-gap` | `--rad-radio-group-gap` |
|
|
765
|
+
| `--button-focus-color` (stale consumers) | `--rad-color-focus` for shared focus; `--rad-button-focus-color` for Button alone |
|
|
766
|
+
|
|
767
|
+
The source stylesheet no longer registers `background`, `foreground`, `border`,
|
|
768
|
+
`primary`, `secondary`, `warning`, `destructive`, or `focus` color aliases, or the
|
|
769
|
+
`control` radius alias. Replace classes such as `bg-primary` with
|
|
770
|
+
`bg-(--rad-color-accent)` and `rounded-control` with
|
|
771
|
+
`rounded-(--rad-control-radius)`, or define your own application aliases.
|
|
772
|
+
|
|
773
|
+
The theme registry is readonly; choose a preset by
|
|
774
|
+
`theme.id` rather than editing the registry or relying on its display name.
|
|
775
|
+
Storybook's global Theme and Mode controls use this same preset registry.
|
|
776
|
+
Button and Link now share `variant`, `tone`, and `controlSize`; see the
|
|
777
|
+
[README action migration table](../README.md#action-api-migration-breaking).
|
|
778
|
+
Action-only geometry, elevation and motion remain deliberate Button component
|
|
779
|
+
overrides consumed by both Button and action-shaped Link. Inline/subtle Link
|
|
780
|
+
retains its own decoration and focus overrides. Soft and unfilled ink mixes the
|
|
781
|
+
selected tone toward the scope foreground; explicit Link colour overrides win.
|
|
782
|
+
|
|
783
|
+
### Cleanup inventory (DEV-132)
|
|
784
|
+
|
|
785
|
+
| Area | Disposition |
|
|
786
|
+
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
787
|
+
| Ten family helpers/types, `radiantTheme`, resolved `style`/`surface` fields | Removed directly under the experimental 0.x policy; replacements above |
|
|
788
|
+
| Old unprefixed color/radius aliases and ambient easing variables | Removed from the source and compiled styling routes |
|
|
789
|
+
| Old action variants, `size`/`radius` presentation props and `data-size` | Already retired by the action/form migrations; no compatibility path restored |
|
|
790
|
+
| Shared semantic tokens and typed `components` overrides | Retained as the canonical theme authoring contract |
|
|
791
|
+
| `ThemeStyle`, native props, named parts, state hooks and `render` | Retained for local styling and native composition |
|
|
792
|
+
| Button and action-shaped Link presentation | One private `actionStyles` implementation; action-only Button slots are intentionally shared |
|
|
793
|
+
| Dialog actions and Accordion sections | Compose Button and Collapsible respectively; no parallel action/disclosure paint |
|
|
794
|
+
|
|
795
|
+
Every component slot in the registry has a reader. Input, Field, Checkbox,
|
|
796
|
+
Radio, Dialog, Collapsible and Card resolve their own override, then a shared
|
|
797
|
+
role or neutral default. Only Button and action-shaped Link consume action
|
|
798
|
+
slots; inline/subtle Link keeps its own decoration/focus contract. Existing
|
|
799
|
+
preset values and light/dark mode maps are unchanged by this cleanup.
|
|
800
|
+
|
|
801
|
+
This removes compatibility paths without publishing a package. The next
|
|
802
|
+
release must carry these breaking migration notes under the
|
|
803
|
+
[release policy](../RELEASE_POLICY.md); earlier changelog entries describe their
|
|
804
|
+
delivery-time behavior.
|