@cognitap/radiant 0.0.2 → 0.0.3
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 +315 -0
- package/README.md +939 -28
- 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/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 +24 -1
- package/dist/library/index.d.ts.map +1 -1
- package/dist/library/index.js +11 -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 +14 -0
- package/dist/library/themes/index.d.ts.map +1 -0
- package/dist/library/themes/index.js +21 -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/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/docs/accessibility.md +189 -0
- package/docs/system.md +218 -0
- package/docs/theming.md +392 -0
- package/package.json +26 -9
- 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/controlStyles.ts +19 -0
- package/src/index.ts +93 -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 +33 -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/ticket.ts +141 -0
- package/src/themes/tokens.ts +262 -0
- package/src/themes/types.ts +10 -0
package/docs/system.md
ADDED
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
# Radiant system guide
|
|
2
|
+
|
|
3
|
+
Use this guide to theme, compose and customise the ten families in the current
|
|
4
|
+
source: Button, Link, Field, Input, Checkbox, RadioGroup (including Radio),
|
|
5
|
+
Dialog, Collapsible, Accordion and Card. Their public props and types are in the
|
|
6
|
+
[README](../README.md) and package declarations. Changes under
|
|
7
|
+
[Unreleased](../CHANGELOG.md#unreleased) require a release before npm consumers
|
|
8
|
+
can use them; keep JavaScript and CSS on the same version. Radiant remains
|
|
9
|
+
experimental during 0.x.
|
|
10
|
+
|
|
11
|
+
## Compose by responsibility
|
|
12
|
+
|
|
13
|
+
Use Button for actions and Link for navigation, including when a Link looks
|
|
14
|
+
like a button. Use Field for label/help/error relationships, and native controls
|
|
15
|
+
for values and selection. Card groups content; Dialog owns open state and its
|
|
16
|
+
native modal lifecycle; Collapsible owns a disclosure; Accordion composes
|
|
17
|
+
Collapsible for a selection of sections.
|
|
18
|
+
|
|
19
|
+
DialogTrigger and DialogClose compose Button in both default and replacement
|
|
20
|
+
paths. They accept Button's presentation and `render` interface. RadioGroup
|
|
21
|
+
composes Field. Action-shaped Link shares Button's presentation while retaining
|
|
22
|
+
an anchor. Reuse these families when assembling an interface so their theme,
|
|
23
|
+
keyboard behavior and relationships travel together.
|
|
24
|
+
|
|
25
|
+
Action presentation uses three independent choices:
|
|
26
|
+
|
|
27
|
+
| Prop | Values | Default |
|
|
28
|
+
| ------------- | ------------------------------------------------------------------------- | ----------------------------- |
|
|
29
|
+
| `variant` | `solid`, `soft`, `outline`, `ghost`; Link also accepts `inline`, `subtle` | Button `solid`; Link `inline` |
|
|
30
|
+
| `tone` | `accent`, `neutral`, `warning`, `danger` | `accent` |
|
|
31
|
+
| `controlSize` | `small`, `medium`, `large` | `medium` |
|
|
32
|
+
|
|
33
|
+
Input, Checkbox, Radio and RadioGroup share `controlSize`. Input's numeric native
|
|
34
|
+
`size` still measures character width. A variant selects treatment; a tone
|
|
35
|
+
selects its semantic palette.
|
|
36
|
+
|
|
37
|
+
## Set up styles and themes
|
|
38
|
+
|
|
39
|
+
Choose one CSS route: import `@cognitap/radiant/styles.css` once for compiled
|
|
40
|
+
styles, or import `@cognitap/radiant/tailwind.css` alongside your application's
|
|
41
|
+
Tailwind entry. The reset is a separate opt-in import. Compiled CSS supplies a
|
|
42
|
+
neutral light/dark baseline without a provider. Follow the
|
|
43
|
+
[setup examples](../README.md#usage) and [Tailwind route](../README.md#with-tailwind).
|
|
44
|
+
|
|
45
|
+
Author a theme with `defineTheme({ id, name, tokens, components, modes })`.
|
|
46
|
+
It validates typed partial definitions and resolves immutable light/dark maps.
|
|
47
|
+
Choose a built-in preset from the readonly `themes` registry by stable `id`, or
|
|
48
|
+
use its named export, such as `radiant`, `glass` or `defaultTheme`. Load preset
|
|
49
|
+
fonts in your application; choosing a theme never downloads a font. The
|
|
50
|
+
[theming reference](theming.md#define-and-apply-a-theme) owns the authoring
|
|
51
|
+
example, token defaults, preset IDs, font families/weights and migration steps.
|
|
52
|
+
|
|
53
|
+
| Token group | Shared responsibility |
|
|
54
|
+
| ------------ | ---------------------------------------------------------------------------------- |
|
|
55
|
+
| `color` | Surface, foreground, borders, focus, invalid/disabled colors and action tone pairs |
|
|
56
|
+
| `typography` | Body, label and heading font decisions |
|
|
57
|
+
| `control` | Small/medium/large metrics, control shape and borders |
|
|
58
|
+
| `surface` | Canvas background, panel shape, spacing, elevation and backdrop |
|
|
59
|
+
| `focus` | Outline width, offset and style |
|
|
60
|
+
| `motion` | Press/release, color and disclosure timing |
|
|
61
|
+
| `spacing` | Label, field, group, header and footer gaps |
|
|
62
|
+
| `state` | Disabled opacity |
|
|
63
|
+
|
|
64
|
+
Apply a theme with `ThemeScope`, a normal `div` whose props/ref target that
|
|
65
|
+
host. `mode` is independently `light`, `dark` or `system`; system follows the
|
|
66
|
+
browser preference through CSS. Omitted theme/mode inherit. An explicit named
|
|
67
|
+
theme starts afresh from library defaults, then common values, then its mode
|
|
68
|
+
layer. Nested `defaultTheme` resets inherited effects as well as colors.
|
|
69
|
+
|
|
70
|
+
Within a scope, precedence is **component override → shared role → neutral
|
|
71
|
+
baseline**. Promote a decision to `tokens` when it should affect several
|
|
72
|
+
families; put a deliberate exception in `components.<family>`. Button-only
|
|
73
|
+
fonts/effects stay action-local. `components.radioGroup.gap` spaces options;
|
|
74
|
+
`components.radio.labelGap` spaces an option's label. Passive surfaces use
|
|
75
|
+
surface roles, and Radio stays round by default.
|
|
76
|
+
|
|
77
|
+
Use `ThemeComponentOverrides` for reusable component configuration and
|
|
78
|
+
`ThemeStyle` for local `style` values. Public CSS variables follow their typed
|
|
79
|
+
paths: `tokens.control.radius` becomes `--rad-control-radius`, and
|
|
80
|
+
`components.input.radius` becomes `--rad-input-radius`. Local styles override
|
|
81
|
+
generated values on the same host; caller classes merge after defaults. Use the
|
|
82
|
+
Tailwind route to generate new utility classes supplied by your application.
|
|
83
|
+
|
|
84
|
+
A mode-only scope re-materialises its selected theme. Put token exceptions that
|
|
85
|
+
must survive it on a ThemeScope's inline `style` or in the theme definition;
|
|
86
|
+
intervening ordinary DOM/stylesheet overrides are not recovered automatically.
|
|
87
|
+
A new named theme clears inherited exceptions. See the precise
|
|
88
|
+
[scope and override rules](theming.md#scopes-mode-and-overrides).
|
|
89
|
+
|
|
90
|
+
## Find the actual styling and ref target
|
|
91
|
+
|
|
92
|
+
Root `className`, `style`, native attributes and `ref` reach the documented
|
|
93
|
+
host. A convenience label does not move input props to its wrapper.
|
|
94
|
+
|
|
95
|
+
| Public family / parts | Host and target |
|
|
96
|
+
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
97
|
+
| Button / Link | `button` / `a`, including through a compatible `render` adapter |
|
|
98
|
+
| Field | `div` in control layout; `fieldset` in group layout |
|
|
99
|
+
| Input / Checkbox / Radio | Native `input`; Checkbox/Radio wrapper, label and indicator use `parts` |
|
|
100
|
+
| RadioGroup | Field's `fieldset`; `parts.options` styles its internal option grid |
|
|
101
|
+
| Dialog | Logical state owner with no DOM/style/ref target |
|
|
102
|
+
| DialogTrigger / DialogClose | Button's `button` host |
|
|
103
|
+
| DialogContent / DialogTitle / DialogDescription | `dialog` / `h2` / `p` |
|
|
104
|
+
| Collapsible / CollapsibleTrigger / CollapsibleContent | `details` / `summary` / `div` |
|
|
105
|
+
| Accordion / AccordionItem / AccordionTrigger / AccordionContent | `div` / Collapsible `details` / `summary` / `div`; trigger `level` adds a heading without moving the ref |
|
|
106
|
+
| Card / CardHeader / CardContent / CardFooter | Passive `div` hosts |
|
|
107
|
+
| CardTitle / CardDescription | Heading selected by `level` / `p` |
|
|
108
|
+
|
|
109
|
+
Field exposes `parts.label`, `description`, `error` and `required`;
|
|
110
|
+
Checkbox/Radio expose `parts.wrapper`, `label` and `indicator`. RadioGroup adds
|
|
111
|
+
`parts.options` to Field's hooks. Each hook accepts only `className` and `style`.
|
|
112
|
+
Use the explicit compound parts for layout where a family provides them.
|
|
113
|
+
|
|
114
|
+
`data-slot` is a set of identity tokens. Select with membership, for example
|
|
115
|
+
`[data-slot~="dialog-trigger"]`. Composed identities retain their base:
|
|
116
|
+
`button dialog-trigger`, `button dialog-close`, `field radio-group`,
|
|
117
|
+
`collapsible accordion-item`, `collapsible-trigger accordion-trigger`, and
|
|
118
|
+
`collapsible-content accordion-content`. Caller identities are additive only
|
|
119
|
+
where the family's props support them; owned identities remain protected.
|
|
120
|
+
|
|
121
|
+
Style actual state: native `:disabled`, `:checked`, `:indeterminate` and `open`;
|
|
122
|
+
Button pending uses `aria-busy`; Field/RadioGroup expose presence-based
|
|
123
|
+
`data-invalid`, `data-disabled` and `data-required`. DialogContent and the
|
|
124
|
+
disclosure parts expose `data-state="open" | "closed"`. Actions expose
|
|
125
|
+
`data-variant`, `data-tone` and `data-control-size`; controls expose
|
|
126
|
+
`data-control-size` independently of native Input `size`. There is no universal
|
|
127
|
+
synthetic state attribute to substitute for native or ARIA state.
|
|
128
|
+
|
|
129
|
+
## State and forms
|
|
130
|
+
|
|
131
|
+
Keep one owner per state axis for a mount. Use `value`/`checked`/`open` for
|
|
132
|
+
controlled state and their `default*` counterparts for initial uncontrolled
|
|
133
|
+
state. Accordion uses `value`/`defaultValue` and a fixed single/multiple type.
|
|
134
|
+
Remount to change ownership or selection type. Controlled callbacks request a
|
|
135
|
+
change; the consumer decides whether to accept it. No-op requests and prop
|
|
136
|
+
synchronisation do not create another semantic change callback.
|
|
137
|
+
|
|
138
|
+
Text changes and blur retain native event meanings. RadioGroup owns its options'
|
|
139
|
+
name/selection; `value={null}` clears a controlled group and `""` remains a real
|
|
140
|
+
option value. Choose one state-writing callback, `onValueChange` or `onChange`.
|
|
141
|
+
Checkbox's `checked` is boolean state; its `value` is submitted data.
|
|
142
|
+
|
|
143
|
+
Field owns IDs, label/help/error relationships and inherited metadata. Give an
|
|
144
|
+
explicit control ID through Field's `controlId`. Radiant controls consume those
|
|
145
|
+
relationships; a native adapter uses `children(controlProps)` and forwards them
|
|
146
|
+
to its control. Owned error/disabled/required state cannot be erased by a child.
|
|
147
|
+
A plain Field group preserves native fieldset/first-legend behavior and does
|
|
148
|
+
not make every checkbox required. RadioGroup applies its requirement to the
|
|
149
|
+
mutually exclusive native choice.
|
|
150
|
+
|
|
151
|
+
The consumer owns validation rules/timing, touched/dirty state, error text,
|
|
152
|
+
submission and persistence. Native reset restores uncontrolled controls; a
|
|
153
|
+
controlled adapter resets its values and validation metadata together. Form
|
|
154
|
+
reset does not reset Dialog or disclosure state. Dialog retains its DOM form
|
|
155
|
+
association; compose one form without nesting forms. TanStack is an optional
|
|
156
|
+
reference adapter, outside the runtime dependency and public export surface.
|
|
157
|
+
|
|
158
|
+
For cancellable activation, guards run first, the consumer handler runs next,
|
|
159
|
+
and the library requests a change only when `defaultPrevented` is false.
|
|
160
|
+
Native change/toggle/blur are observations, not vetoable requests. Preserve one
|
|
161
|
+
handler chain and the real host ref, including callback-ref cleanup. Public
|
|
162
|
+
`useField`, `useDialog`, `useCollapsible` and `useAccordion` return null outside
|
|
163
|
+
their owner; required parts fail clearly when misplaced. The
|
|
164
|
+
[React binding reference](https://github.com/cognitap/radiant/blob/main/docs/react-bindings.md)
|
|
165
|
+
details lifecycle, reconciliation, SSR and hydration behavior.
|
|
166
|
+
|
|
167
|
+
## Preserve behavior when customising
|
|
168
|
+
|
|
169
|
+
Button, Link and Dialog actions support `render(resolvedNativeProps)`. Forward
|
|
170
|
+
all resolved props, ref and children to one compatible button or anchor;
|
|
171
|
+
presentation is already resolved. A router adapter keeps native modified-click,
|
|
172
|
+
target and download behavior. Preserve Button's resolved pending children and
|
|
173
|
+
guarded handler; passing them through another Button would wrap/style them
|
|
174
|
+
again. Field's control-prop callback adapts relationships rather than replacing
|
|
175
|
+
Field's host.
|
|
176
|
+
|
|
177
|
+
Keep native controls and labels operable, accessible names/description IDs
|
|
178
|
+
connected, and focus/invalid/disabled/pending cues visible. Closed Dialog/details
|
|
179
|
+
content stays mounted and hidden by the native/functional styles. Preserve
|
|
180
|
+
Dialog bounds, scrolling, top-layer modal focus behavior, and a direct-child
|
|
181
|
+
summary for details. Keep decorative indicators hidden from assistive technology.
|
|
182
|
+
Preserve reduced-motion alternatives and forced-colors readability when changing
|
|
183
|
+
paint, motion or hosts. A type-correct adapter alone does not prove these behaviors.
|
|
184
|
+
|
|
185
|
+
## Reuse the canonical examples
|
|
186
|
+
|
|
187
|
+
Use the global Storybook **Theme** and **Mode** controls in Canvas and Docs.
|
|
188
|
+
Ordinary stories inherit them; **System → Theming → Comparison** is the named
|
|
189
|
+
preset comparison. Follow the [Storybook inspection guide](https://github.com/cognitap/radiant/blob/main/docs/storybook.md).
|
|
190
|
+
|
|
191
|
+
| Need | Canonical live source |
|
|
192
|
+
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
193
|
+
| One labelled control and local override | [Input Default / Customisation](https://github.com/cognitap/radiant/blob/main/src/Input.stories.tsx) |
|
|
194
|
+
| Native form, optional TanStack owner, the same form in Card or Dialog | [ProfileExample](https://github.com/cognitap/radiant/blob/main/.storybook/examples/ProfileForm.tsx), exposed by [Recipes → Forms](https://github.com/cognitap/radiant/blob/main/src/Form.stories.tsx); choose its `placement` control |
|
|
195
|
+
| Assembled interface across all ten families | [WorkspaceSettings](https://github.com/cognitap/radiant/blob/main/.storybook/examples/WorkspaceSettings.tsx), exposed by [Recipes → Workspace → Settings](https://github.com/cognitap/radiant/blob/main/src/Workspace.stories.tsx) |
|
|
196
|
+
|
|
197
|
+
These are development examples using public Radiant names, not package exports.
|
|
198
|
+
Adapt the existing form's state owner and placement rather than copying a second
|
|
199
|
+
form or replacing its actions with bespoke styled hosts. Application imports
|
|
200
|
+
come from `@cognitap/radiant`; implementation deep imports are unsupported.
|
|
201
|
+
|
|
202
|
+
The installed composition checkpoint reuses these exact recipes with public
|
|
203
|
+
package imports. When copying TypeScript recipe sources into an application,
|
|
204
|
+
follow its local module-resolution rules: Cognitap's current Next/Turbopack
|
|
205
|
+
setup needs extensionless local TSX imports, whereas the NodeNext installed
|
|
206
|
+
fixture uses `.js` specifiers. This adaptation does not change Radiant's compiled
|
|
207
|
+
JavaScript imports. See the [checkpoint commands](https://github.com/cognitap/radiant/blob/main/docs/testing.md#evidence-and-readiness).
|
|
208
|
+
An older registry package cannot verify newer exported components; use a matching
|
|
209
|
+
build/archive checkpoint and keep the registry limitation explicit until release.
|
|
210
|
+
|
|
211
|
+
For a change to this contract, update its guide/reference and canonical example
|
|
212
|
+
together, then run the [verification gate](https://github.com/cognitap/radiant/blob/main/docs/testing.md).
|
|
213
|
+
Use the [browser/AT matrix](accessibility.md) for target combinations, manual
|
|
214
|
+
scenarios, exact-version evidence and unverified gaps.
|
|
215
|
+
Check relevant keyboard/form/ref behavior and actual appearance in both modes;
|
|
216
|
+
automated accessibility results do not establish complete visual or assistive
|
|
217
|
+
technology readiness. Historical design decisions and acceptance sketches remain
|
|
218
|
+
in the [harmonisation record](https://github.com/cognitap/radiant/blob/main/docs/contracts/README.md).
|
package/docs/theming.md
ADDED
|
@@ -0,0 +1,392 @@
|
|
|
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
|
+
## Scopes, mode, and overrides
|
|
74
|
+
|
|
75
|
+
`ThemeScope` renders a normal `div` and accepts its native props and ref. It
|
|
76
|
+
paints its canvas, foreground, and body typography within that subtree. It does
|
|
77
|
+
not change the document, install event listeners, load fonts, or persist a
|
|
78
|
+
preference. A native top-layer Dialog remains in its original scope.
|
|
79
|
+
|
|
80
|
+
- `theme={theme}` starts a fresh named theme from library defaults. Every shared
|
|
81
|
+
token is materialised and every omitted component override is reset to its
|
|
82
|
+
CSS fallback. An outer theme cannot leak its action font or press effect in.
|
|
83
|
+
- Omit `theme` to inherit the current theme. Omit `mode` to inherit the current
|
|
84
|
+
mode. At the application root, the stylesheet defaults to system preference.
|
|
85
|
+
- `mode="light"`, `"dark"`, or `"system"` selects appearance independently of
|
|
86
|
+
theme identity. System follows the CSS media query, so server markup and the
|
|
87
|
+
first client render agree. A mode-only scope resolves the current named theme
|
|
88
|
+
in its selected mode.
|
|
89
|
+
- An inner scope with neither `theme` nor `mode` follows ordinary CSS inheritance;
|
|
90
|
+
it does not establish a new theme. A root scope also paints the neutral canvas
|
|
91
|
+
and typography.
|
|
92
|
+
- Explicit `style` values win over generated values on the same scope host.
|
|
93
|
+
Known theme variables supplied inline to ancestor ThemeScopes are carried
|
|
94
|
+
through mode-only scopes. A new named theme clears these inherited exceptions.
|
|
95
|
+
|
|
96
|
+
Use `defaultTheme` for a complete reset, including component effects:
|
|
97
|
+
|
|
98
|
+
```tsx
|
|
99
|
+
import { Button, ThemeScope, defaultTheme, ticket } from '@cognitap/radiant'
|
|
100
|
+
|
|
101
|
+
;<ThemeScope
|
|
102
|
+
theme={ticket}
|
|
103
|
+
mode="light"
|
|
104
|
+
>
|
|
105
|
+
<Button>Ticket action</Button>
|
|
106
|
+
<ThemeScope theme={defaultTheme}>
|
|
107
|
+
<Button>Neutral action</Button>
|
|
108
|
+
</ThemeScope>
|
|
109
|
+
</ThemeScope>
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Use shared tokens for local changes that should affect multiple families:
|
|
113
|
+
|
|
114
|
+
```tsx
|
|
115
|
+
<ThemeScope
|
|
116
|
+
theme={brand}
|
|
117
|
+
style={{ '--rad-control-radius': '1.25rem', padding: '2rem' }}
|
|
118
|
+
>
|
|
119
|
+
<Input aria-label="Garden name" />
|
|
120
|
+
<Button>Save</Button>
|
|
121
|
+
</ThemeScope>
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Ordinary CSS overrides inherit within their existing scope. A mode-only scope
|
|
125
|
+
re-materialises the selected theme, so token overrides from an intervening
|
|
126
|
+
stylesheet rule or an ordinary DOM wrapper are not automatically recovered
|
|
127
|
+
there. Put exceptions that must survive a mode change on a `ThemeScope` inline
|
|
128
|
+
`style`, or include them in the theme definition. No browser computed-style
|
|
129
|
+
snapshot is taken. Ordinary body styles, such as a locally changed font size,
|
|
130
|
+
still follow the cascade and inheritance appropriate to their host.
|
|
131
|
+
|
|
132
|
+
Components resolve **local component override → shared semantic role → neutral
|
|
133
|
+
baseline**. For example, `components.button.radius` overrides Button without
|
|
134
|
+
changing Input; `tokens.control.radius` changes both. Checkbox caps its inherited
|
|
135
|
+
radius at a quarter of its indicator size so it remains a box; an explicit
|
|
136
|
+
`components.checkbox.radius` still wins. Radio stays circular by default, even
|
|
137
|
+
under squircle or scoop control themes. Shared disabled opacity is applied once
|
|
138
|
+
to the relevant visual unit.
|
|
139
|
+
|
|
140
|
+
Input, Checkbox, and Radio derive their default control outline from the shared
|
|
141
|
+
border and foreground colors. This gives interactive boundaries more contrast
|
|
142
|
+
than passive surface dividers. Their explicit `borderColor`, invalid, disabled,
|
|
143
|
+
and focus overrides keep their normal precedence. Disabled selection marks use
|
|
144
|
+
the muted foreground unless the component supplies its own `mark` color.
|
|
145
|
+
|
|
146
|
+
Component overrides use the existing family configuration keys, grouped under
|
|
147
|
+
`button`, `link`, `field`, `input`, `checkbox`, `radio`, `radioGroup`, `dialog`,
|
|
148
|
+
`collapsible`, `accordion`, and `card`. Public declaration types are the
|
|
149
|
+
closed-key reference. `radioGroup.gap` controls group layout;
|
|
150
|
+
`radio.labelGap` controls spacing within a single option. Button-only fonts,
|
|
151
|
+
uppercase text, sheen, shadows, squash, and pressed shape belong under
|
|
152
|
+
`components.button`. Passive surfaces have their own shared surface tokens.
|
|
153
|
+
|
|
154
|
+
Public variable names are derived from the typed registry:
|
|
155
|
+
|
|
156
|
+
| Authoring path | CSS variable |
|
|
157
|
+
| ------------------------------ | ----------------------------- |
|
|
158
|
+
| `tokens.color.accent` | `--rad-color-accent` |
|
|
159
|
+
| `tokens.control.medium.height` | `--rad-control-medium-height` |
|
|
160
|
+
| `tokens.typography.family` | `--rad-typography-family` |
|
|
161
|
+
| `components.button.radius` | `--rad-button-radius` |
|
|
162
|
+
| `components.radioGroup.gap` | `--rad-radio-group-gap` |
|
|
163
|
+
|
|
164
|
+
Matching caller utilities merge with component defaults on the Tailwind route;
|
|
165
|
+
application CSS follows the normal cascade. Generated theme values are inline
|
|
166
|
+
custom properties, so a normal stylesheet declaration on that same host does
|
|
167
|
+
not override them. Put a token override on a descendant or use the host's
|
|
168
|
+
`style` prop. Internal variables beginning `--_` are implementation details.
|
|
169
|
+
|
|
170
|
+
## Preserve functional styles
|
|
171
|
+
|
|
172
|
+
Appearance overrides must preserve closed Dialog/details visibility, dialog
|
|
173
|
+
geometry and scrolling, real control hit targets, and accessible names. Keep
|
|
174
|
+
focus, invalid, disabled, and pending cues visible. The library retains
|
|
175
|
+
forced-colors system colors and reduced-motion alternatives; a theme must not
|
|
176
|
+
erase them with replacement CSS. See the [system guide's functional CSS obligations](system.md#preserve-behavior-when-customising)
|
|
177
|
+
for host replacement and the behavior that overrides must preserve. Importing the optional reset is not required for
|
|
178
|
+
these behaviors.
|
|
179
|
+
|
|
180
|
+
## Presets and fonts
|
|
181
|
+
|
|
182
|
+
The readonly `themes` registry contains these presets, exported individually
|
|
183
|
+
from `@cognitap/radiant`. Each has a deliberate light and dark palette.
|
|
184
|
+
|
|
185
|
+
| Stable ID | Display name | Named export | Shared font family | Action exception |
|
|
186
|
+
| --------------- | ------------- | -------------- | ------------------ | ------------------------------------ |
|
|
187
|
+
| `radiant` | Radiant | `radiant` | Inter | Weight 550 |
|
|
188
|
+
| `default` | Default | `defaultTheme` | System sans | Library baseline |
|
|
189
|
+
| `soft-squircle` | Soft squircle | `soft` | Nunito | Weight 800 |
|
|
190
|
+
| `expressive` | Expressive | `expressive` | Poppins | Weight 600 |
|
|
191
|
+
| `glass` | Glass | `glass` | Manrope | Weight 700; backdrop filter |
|
|
192
|
+
| `sharp-3d` | Sharp 3D | `sharp` | System sans | Archivo Black, weight 400, uppercase |
|
|
193
|
+
| `jelly` | Jelly | `jelly` | Baloo 2 | Weight 700 |
|
|
194
|
+
| `ticket` | Ticket | `ticket` | Barlow Condensed | Weight 600, uppercase |
|
|
195
|
+
|
|
196
|
+
All families have `system-ui, sans-serif` fallbacks. Preset body weight is 400;
|
|
197
|
+
load the label and heading weights 600 and 700 as well as the action weight
|
|
198
|
+
listed above. Default uses baseline label/heading weights 550/600. Radiant's
|
|
199
|
+
Inter action weight 550 requires a variable font or an appropriate supplied
|
|
200
|
+
face; the browser chooses an available weight otherwise.
|
|
201
|
+
|
|
202
|
+
Fonts are application assets. Load the named families with your font loader or
|
|
203
|
+
self-hosted `@font-face` rules before showing the themed UI. Defining or choosing
|
|
204
|
+
a theme never downloads a font. Storybook's font loading belongs to Storybook,
|
|
205
|
+
not the package. `Theme` has no `fonts` field or font-loading API.
|
|
206
|
+
|
|
207
|
+
Glass uses a gradient `surface.canvas` and translucent `color.surface`.
|
|
208
|
+
`components.dialog.backdropFilter` frosts content behind the dialog panel;
|
|
209
|
+
`components.dialog.backdrop` paints the surrounding modal overlay. Button's
|
|
210
|
+
existing `backdrop` override is also a filter and remains independent. Ticket
|
|
211
|
+
uses a compact, solid checkbox outline so small indicators
|
|
212
|
+
remain legible alongside its scooped, dashed controls and surfaces.
|
|
213
|
+
Shape uses CSS `corner-shape`; browsers that do not support it
|
|
214
|
+
retain ordinary rounded corners. A palette definition does not certify contrast
|
|
215
|
+
for arbitrary content, custom backgrounds, or translucent combinations.
|
|
216
|
+
|
|
217
|
+
## Shared token reference
|
|
218
|
+
|
|
219
|
+
These 66 roles and concrete neutral defaults come from
|
|
220
|
+
[`src/themes/tokens.ts`](../src/themes/tokens.ts). CSS names are `--rad-` plus the
|
|
221
|
+
kebab-case dotted path. Values shown in both modes differ only where listed.
|
|
222
|
+
`color` values are CSS colors; `surface.canvas` and `surface.backdrop` are full
|
|
223
|
+
CSS backgrounds and may be gradients. `components.button.backdrop` and
|
|
224
|
+
`components.dialog.backdropFilter` are CSS backdrop-filter values. Lengths and
|
|
225
|
+
durations remain CSS strings; opacity is numeric.
|
|
226
|
+
|
|
227
|
+
| Path | Light default | Dark default |
|
|
228
|
+
| ------------------------------ | ------------------------------------ | ------------------------------------ |
|
|
229
|
+
| `color.surface` | `oklch(1 0 0)` | `oklch(0.21 0.006 286)` |
|
|
230
|
+
| `color.foreground` | `oklch(0.21 0.006 286)` | `oklch(0.985 0 0)` |
|
|
231
|
+
| `color.mutedForeground` | `oklch(0.45 0.01 286)` | `oklch(0.75 0.01 286)` |
|
|
232
|
+
| `color.border` | `oklch(0.885 0.005 286)` | `oklch(0.4 0.008 286)` |
|
|
233
|
+
| `color.placeholder` | `oklch(0.5 0.01 286)` | `oklch(0.7 0.01 286)` |
|
|
234
|
+
| `color.disabledBackground` | `oklch(0.96 0.005 286)` | `oklch(0.26 0.006 286)` |
|
|
235
|
+
| `color.disabledBorder` | `oklch(0.88 0.005 286)` | `oklch(0.38 0.006 286)` |
|
|
236
|
+
| `color.invalid` | `oklch(0.56 0.19 25)` | `oklch(0.75 0.16 25)` |
|
|
237
|
+
| `color.focus` | `oklch(0.55 0.13 255)` | `oklch(0.75 0.13 255)` |
|
|
238
|
+
| `color.accent` | `oklch(0.21 0.006 286)` | `oklch(0.92 0.005 286)` |
|
|
239
|
+
| `color.accentForeground` | `oklch(0.985 0 0)` | `oklch(0.21 0.006 286)` |
|
|
240
|
+
| `color.neutral` | `oklch(0.955 0.004 286)` | `oklch(0.3 0.006 286)` |
|
|
241
|
+
| `color.neutralForeground` | `oklch(0.21 0.006 286)` | `oklch(0.985 0 0)` |
|
|
242
|
+
| `color.warning` | `oklch(0.8 0.14 78)` | Same |
|
|
243
|
+
| `color.warningForeground` | `oklch(0.3 0.07 55)` | Same |
|
|
244
|
+
| `color.danger` | `oklch(0.56 0.19 25)` | `oklch(0.72 0.17 25)` |
|
|
245
|
+
| `color.dangerForeground` | `oklch(0.99 0 0)` | `oklch(0.2 0.04 25)` |
|
|
246
|
+
| `typography.family` | `system-ui, sans-serif` | Same |
|
|
247
|
+
| `typography.bodySize` | `0.875rem` | Same |
|
|
248
|
+
| `typography.smallSize` | `0.8125rem` | Same |
|
|
249
|
+
| `typography.headingSize` | `1.125rem` | Same |
|
|
250
|
+
| `typography.bodyWeight` | `400` | Same |
|
|
251
|
+
| `typography.labelWeight` | `550` | Same |
|
|
252
|
+
| `typography.headingWeight` | `600` | Same |
|
|
253
|
+
| `typography.letterSpacing` | `-0.011em` | Same |
|
|
254
|
+
| `control.small.height` | `2rem` | Same |
|
|
255
|
+
| `control.small.paddingInline` | `0.75rem` | Same |
|
|
256
|
+
| `control.small.fontSize` | `0.8125rem` | Same |
|
|
257
|
+
| `control.small.indicatorSize` | `1rem` | Same |
|
|
258
|
+
| `control.medium.height` | `2.5rem` | Same |
|
|
259
|
+
| `control.medium.paddingInline` | `1rem` | Same |
|
|
260
|
+
| `control.medium.fontSize` | `0.875rem` | Same |
|
|
261
|
+
| `control.medium.indicatorSize` | `1.125rem` | Same |
|
|
262
|
+
| `control.large.height` | `3rem` | Same |
|
|
263
|
+
| `control.large.paddingInline` | `1.375rem` | Same |
|
|
264
|
+
| `control.large.fontSize` | `0.9375rem` | Same |
|
|
265
|
+
| `control.large.indicatorSize` | `1.25rem` | Same |
|
|
266
|
+
| `control.radius` | `0.5rem` | Same |
|
|
267
|
+
| `control.cornerShape` | `round` | Same |
|
|
268
|
+
| `control.borderWidth` | `1px` | Same |
|
|
269
|
+
| `control.borderStyle` | `solid` | Same |
|
|
270
|
+
| `surface.canvas` | `oklch(1 0 0)` | `oklch(0.16 0.006 286)` |
|
|
271
|
+
| `surface.radius` | `0.75rem` | Same |
|
|
272
|
+
| `surface.cornerShape` | `round` | Same |
|
|
273
|
+
| `surface.borderWidth` | `1px` | Same |
|
|
274
|
+
| `surface.borderStyle` | `solid` | Same |
|
|
275
|
+
| `surface.padding` | `1.5rem` | Same |
|
|
276
|
+
| `surface.gap` | `1rem` | Same |
|
|
277
|
+
| `surface.shadow` | `0 1px 2px 0 rgb(0 0 0 / 0.06)` | `0 1px 2px 0 rgb(0 0 0 / 0.25)` |
|
|
278
|
+
| `surface.overlayShadow` | `0 24px 64px -16px rgb(0 0 0 / 0.3)` | `0 24px 64px -16px rgb(0 0 0 / 0.6)` |
|
|
279
|
+
| `surface.backdrop` | `rgb(0 0 0 / 0.45)` | `rgb(0 0 0 / 0.65)` |
|
|
280
|
+
| `focus.width` | `2px` | Same |
|
|
281
|
+
| `focus.offset` | `2px` | Same |
|
|
282
|
+
| `focus.style` | `solid` | Same |
|
|
283
|
+
| `motion.pressDuration` | `80ms` | Same |
|
|
284
|
+
| `motion.pressEase` | `cubic-bezier(0.3, 0, 0, 1)` | Same |
|
|
285
|
+
| `motion.releaseDuration` | `160ms` | Same |
|
|
286
|
+
| `motion.releaseEase` | `cubic-bezier(0.2, 0.8, 0.2, 1)` | Same |
|
|
287
|
+
| `motion.colorDuration` | `150ms` | Same |
|
|
288
|
+
| `motion.disclosureDuration` | `150ms` | Same |
|
|
289
|
+
| `spacing.labelGap` | `0.5rem` | Same |
|
|
290
|
+
| `spacing.fieldGap` | `0.375rem` | Same |
|
|
291
|
+
| `spacing.groupGap` | `0.75rem` | Same |
|
|
292
|
+
| `spacing.headerGap` | `0.375rem` | Same |
|
|
293
|
+
| `spacing.footerGap` | `0.5rem` | Same |
|
|
294
|
+
| `state.disabledOpacity` | `0.5` | Same |
|
|
295
|
+
|
|
296
|
+
## Migration from Button-centred themes
|
|
297
|
+
|
|
298
|
+
This is a breaking CSS-token migration. Use the JavaScript and stylesheet from
|
|
299
|
+
the same version; do not mix new theme data with an old compiled stylesheet.
|
|
300
|
+
|
|
301
|
+
1. Replace wrappers such as `<div style={theme.style}>` with
|
|
302
|
+
`<ThemeScope theme={theme}>`. `Theme.style`, `Theme.surface`, and the
|
|
303
|
+
`radiantTheme` style alias are removed. Use `radiant` with `ThemeScope`, which
|
|
304
|
+
chooses the canvas for the active mode. A hand-written `{ name, style }`
|
|
305
|
+
object is no longer a `Theme`: author it with `defineTheme`.
|
|
306
|
+
2. Move shared settings out of `buttonTheme` into `tokens`: font family into
|
|
307
|
+
`typography.family`, heights/padding/font sizes into the matching `control`
|
|
308
|
+
size group, radius/shape/borders into `control` and `surface`, focus into
|
|
309
|
+
`color.focus`/`focus`, and timing into `motion`. Input, Checkbox, Radio,
|
|
310
|
+
Dialog, Collapsible, Card, and Link no longer fall back through Button's
|
|
311
|
+
overrides. Input's native numeric `size` attribute is unchanged.
|
|
312
|
+
3. Replace the removed `buttonTheme`, `linkTheme`, `fieldTheme`, `inputTheme`,
|
|
313
|
+
`checkboxTheme`, `radioTheme`, `dialogTheme`, `collapsibleTheme`,
|
|
314
|
+
`accordionTheme`, and `cardTheme` helpers with `components.<family>` in
|
|
315
|
+
`defineTheme`. Their corresponding `*Theme` type aliases are removed; use
|
|
316
|
+
`ThemeComponentOverrides` or an indexed family type such as
|
|
317
|
+
`NonNullable<ThemeComponentOverrides['button']>` for reusable configuration.
|
|
318
|
+
For a one-off host or named part, use `style` with typed `--rad-*` variables:
|
|
319
|
+
|
|
320
|
+
```tsx
|
|
321
|
+
import { Button, type ThemeStyle } from '@cognitap/radiant'
|
|
322
|
+
|
|
323
|
+
const local: ThemeStyle = { '--rad-button-radius': '1rem' }
|
|
324
|
+
|
|
325
|
+
;<Button style={local}>Save</Button>
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
A local style is a partial override; a named `ThemeScope` deliberately resets
|
|
329
|
+
omitted settings to the shared baseline. Do not spread a resolved mode map
|
|
330
|
+
onto a wrapper as a replacement for ThemeScope's theme/mode inheritance.
|
|
331
|
+
|
|
332
|
+
4. Rename direct CSS overrides using the following map. Button's `focusColor`
|
|
333
|
+
maps to `--rad-button-focus-color`; it no longer changes shared focus.
|
|
334
|
+
Move the old `radioTheme({ gap })` group shortcut to
|
|
335
|
+
`components.radioGroup.gap`; `components.radio.labelGap` remains option-local.
|
|
336
|
+
5. Remove `glowHover`: it never had a rendering effect and is rejected by
|
|
337
|
+
`defineTheme`. The library no longer supplies `--ease-spring`, `--ease-snap`,
|
|
338
|
+
or `--ease-settle`; put the required literal `linear(...)`/`cubic-bezier(...)`
|
|
339
|
+
curve in the motion token or a deliberate component exception. Application
|
|
340
|
+
CSS variables are also supported when your application defines them.
|
|
341
|
+
|
|
342
|
+
| Old variable | Replacement |
|
|
343
|
+
| -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
|
344
|
+
| `--color-background` | `--rad-color-surface` (canvas is `--rad-surface-canvas`) |
|
|
345
|
+
| `--color-foreground`, `--color-border`, `--color-focus` | Corresponding `--rad-color-*` role |
|
|
346
|
+
| `--color-primary`, `--color-primary-foreground` | `--rad-color-accent`, `--rad-color-accent-foreground` |
|
|
347
|
+
| `--color-secondary`, `--color-secondary-foreground` | `--rad-color-neutral`, `--rad-color-neutral-foreground` |
|
|
348
|
+
| `--color-warning`, `--color-warning-foreground` | `--rad-color-warning`, `--rad-color-warning-foreground` |
|
|
349
|
+
| `--color-destructive`, `--color-destructive-foreground` | `--rad-color-danger`, `--rad-color-danger-foreground` |
|
|
350
|
+
| `--radius-control` | `--rad-control-radius` |
|
|
351
|
+
| `--button-*`, `--input-*`, `--field-*`, other family overrides | `--rad-button-*`, `--rad-input-*`, `--rad-field-*`, corresponding prefixed family |
|
|
352
|
+
| `--radio-gap` | `--rad-radio-group-gap` |
|
|
353
|
+
| `--button-focus-color` (stale consumers) | `--rad-color-focus` for shared focus; `--rad-button-focus-color` for Button alone |
|
|
354
|
+
|
|
355
|
+
The source stylesheet no longer registers `background`, `foreground`, `border`,
|
|
356
|
+
`primary`, `secondary`, `warning`, `destructive`, or `focus` color aliases, or the
|
|
357
|
+
`control` radius alias. Replace classes such as `bg-primary` with
|
|
358
|
+
`bg-(--rad-color-accent)` and `rounded-control` with
|
|
359
|
+
`rounded-(--rad-control-radius)`, or define your own application aliases.
|
|
360
|
+
|
|
361
|
+
The theme registry is readonly; choose a preset by
|
|
362
|
+
`theme.id` rather than editing the registry or relying on its display name.
|
|
363
|
+
Storybook's global Theme and Mode controls use this same preset registry.
|
|
364
|
+
Button and Link now share `variant`, `tone`, and `controlSize`; see the
|
|
365
|
+
[README action migration table](../README.md#action-api-migration-breaking).
|
|
366
|
+
Action-only geometry, elevation and motion remain deliberate Button component
|
|
367
|
+
overrides consumed by both Button and action-shaped Link. Inline/subtle Link
|
|
368
|
+
retains its own decoration and focus overrides. Soft and unfilled ink mixes the
|
|
369
|
+
selected tone toward the scope foreground; explicit Link colour overrides win.
|
|
370
|
+
|
|
371
|
+
### Cleanup inventory (DEV-132)
|
|
372
|
+
|
|
373
|
+
| Area | Disposition |
|
|
374
|
+
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
375
|
+
| Ten family helpers/types, `radiantTheme`, resolved `style`/`surface` fields | Removed directly under the experimental 0.x policy; replacements above |
|
|
376
|
+
| Old unprefixed color/radius aliases and ambient easing variables | Removed from the source and compiled styling routes |
|
|
377
|
+
| Old action variants, `size`/`radius` presentation props and `data-size` | Already retired by the action/form migrations; no compatibility path restored |
|
|
378
|
+
| Shared semantic tokens and typed `components` overrides | Retained as the canonical theme authoring contract |
|
|
379
|
+
| `ThemeStyle`, native props, named parts, state hooks and `render` | Retained for local styling and native composition |
|
|
380
|
+
| Button and action-shaped Link presentation | One private `actionStyles` implementation; action-only Button slots are intentionally shared |
|
|
381
|
+
| Dialog actions and Accordion sections | Compose Button and Collapsible respectively; no parallel action/disclosure paint |
|
|
382
|
+
|
|
383
|
+
Every component slot in the registry has a reader. Input, Field, Checkbox,
|
|
384
|
+
Radio, Dialog, Collapsible and Card resolve their own override, then a shared
|
|
385
|
+
role or neutral default. Only Button and action-shaped Link consume action
|
|
386
|
+
slots; inline/subtle Link keeps its own decoration/focus contract. Existing
|
|
387
|
+
preset values and light/dark mode maps are unchanged by this cleanup.
|
|
388
|
+
|
|
389
|
+
This removes compatibility paths without publishing a package. The next
|
|
390
|
+
release must carry these breaking migration notes under the
|
|
391
|
+
[release policy](../RELEASE_POLICY.md); earlier changelog entries describe their
|
|
392
|
+
delivery-time behavior.
|