@dashspec/renderer 0.0.0-stage → 0.1.1

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.
@@ -0,0 +1,244 @@
1
+ # Theming
2
+
3
+ Every built-in widget reads its colours, fonts, spacing and radii from **tokens**,
4
+ exposed as `--ds-*` CSS variables on the dashboard's root element. Change the tokens and
5
+ the whole dashboard follows, charts included. Nothing reads a UI library's theme, and
6
+ nothing outside the dashboard is touched.
7
+
8
+ ## Tokens
9
+
10
+ A `Theme` has a name, a mode, shared scale tokens, and one colour set per mode:
11
+
12
+ ```ts
13
+ interface Theme {
14
+ name: string;
15
+ mode: "light" | "dark" | "auto"; // auto follows the viewer's system setting
16
+ scale: ScaleTokens; // shared by both modes
17
+ light: ColorTokens;
18
+ dark: ColorTokens;
19
+ }
20
+ ```
21
+
22
+ | Group | Tokens |
23
+ |---|---|
24
+ | `scale.font` | `heading`, `body`, `data` (numbers, with tabular figures), and type `roles`: `display`, `title`, `heading`, `body`, `label`, `caption`, `kpi`, `data` (each `{ family, size, weight, lineHeight, letterSpacing? }`) |
25
+ | `scale.space` | `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl` (px) |
26
+ | `scale.radius` | `control`, `card`, `sheet`, `full` (px) |
27
+ | `scale.shadow` | `raised`, `overlay` |
28
+ | `scale.motion` | `fast`, `normal`, `slow` (ms), `easing`, `enter`, `exit` |
29
+ | `scale.z` | `raised`, `sticky`, `overlay`, `tooltip` |
30
+ | `scale.breakpoints` | `sm`, `md`, `lg`, `xl`, `tv` (px) |
31
+ | `scale.density` | `"compact"`, `"comfortable"` (default) or `"spacious"`. Scales every `--ds-space-*` (×0.75, ×1, ×1.25, rounded) and sets `--ds-control-height` (30, 36, 42 px) for filters, buttons and inputs; also emitted as `--ds-density`. Your own widgets can read it with `useThemeTokens` |
32
+ | `surface` | `page`, `card`, `sunken`, `overlay`, `selection`, `scrim`, `backdrop?` (page background, may be a gradient), `tableHeader?` |
33
+ | `text` | `primary`, `secondary`, `subtle`, `disabled`, `onFill` |
34
+ | `border` | `default`, `control`, `focus` |
35
+ | `action` | `primary`, `primaryHover`, `primaryActive`, `onPrimary` |
36
+ | `status` | `good`, `warn`, `bad`, `neutral`, `info`, each `{ fg, bg, border, solid }` |
37
+ | `chart` | `series` (categorical colours, in order), `sequential` (low → high, for heatmaps), `axis`, `grid`, `tooltipBg`, `tooltipText` |
38
+
39
+ The default theme (`defaultTheme`) uses mode `auto` and the font stack
40
+ `Inter, system-ui, sans-serif`. The package doesn't load fonts: load Inter yourself, or
41
+ set your own font.
42
+
43
+ ## `createTheme`
44
+
45
+ ### Short form
46
+
47
+ Most brands need only a few values. The short form applies to both modes:
48
+
49
+ ```ts
50
+ import { createTheme } from "@dashspec/renderer";
51
+
52
+ const acme = createTheme({
53
+ name: "acme",
54
+ colors: {
55
+ primary: "#4f46e5",
56
+ good: "#16a34a",
57
+ warn: "#d97706",
58
+ bad: "#dc2626",
59
+ series: ["#4f46e5", "#06b6d4", "#f59e0b", "#ef4444", "#8b5cf6"],
60
+ },
61
+ font: { family: "'Acme Sans', system-ui, sans-serif", data: "'Acme Mono', monospace" },
62
+ radius: 12, // card radius in px; controls get half
63
+ density: "compact",
64
+ });
65
+ ```
66
+
67
+ | Field | What it sets |
68
+ |---|---|
69
+ | `name` | The theme's name |
70
+ | `mode` | `"light"`, `"dark"` or `"auto"` (default: the base theme's, `auto`) |
71
+ | `extends` | Start from another `Theme` instead of `defaultTheme` |
72
+ | `colors.primary` | `action.primary` and `border.focus` |
73
+ | `colors.good` / `warn` / `bad` | That status tone's `solid` and `border` |
74
+ | `colors.series` | `chart.series` |
75
+ | `font.family` | Body font, and heading and data fonts unless given |
76
+ | `font.heading`, `font.data` | Heading and number fonts |
77
+ | `radius` | `radius.card`, and `radius.control` at half |
78
+ | `density` | `scale.density`: `"compact"`, `"comfortable"` or `"spacious"` (spacing and control height) |
79
+
80
+ ### Full overrides
81
+
82
+ `scale`, `light` and `dark` take any part of the token tree and are merged deeply over
83
+ the base theme after the short form. Arrays (like `series`) replace, they don't merge.
84
+
85
+ ```ts
86
+ const acme = createTheme({
87
+ colors: { primary: "#4f46e5" },
88
+ scale: {
89
+ font: { roles: { kpi: { family: "data", size: 34, weight: 700, lineHeight: 40 } } },
90
+ space: { md: 14 },
91
+ },
92
+ light: {
93
+ surface: { page: "#f8fafc", backdrop: "linear-gradient(180deg, #eef2ff 0%, #f8fafc 240px)" },
94
+ status: { good: { bg: "#dcfce7", fg: "#14532d" } },
95
+ },
96
+ dark: {
97
+ surface: { page: "#0b1020", card: "#121a2f" },
98
+ chart: { grid: "#1f2a44" },
99
+ },
100
+ });
101
+ ```
102
+
103
+ `createTheme` never changes its input or the base theme.
104
+
105
+ ## Use a theme
106
+
107
+ Pass it to the renderer, a provider, or a design system:
108
+
109
+ ```tsx
110
+ <DashboardRenderer document={doc} theme={acme} />
111
+
112
+ <DashSpecProvider theme={acme}>…</DashSpecProvider>
113
+
114
+ defineDesignSystem({ name: "Acme", theme: acme });
115
+ ```
116
+
117
+ Which theme applies: the renderer's `theme` prop, else the provider's, else the last
118
+ design system that has one, else the default theme.
119
+
120
+ ## Light, dark and auto
121
+
122
+ `mode` decides which colour set is used:
123
+
124
+ - `"light"` or `"dark"`: always that one.
125
+ - `"auto"`: follows the viewer's `prefers-color-scheme`, and switches live when it
126
+ changes. Server rendering and the first client render use light, then switch (see
127
+ [Server rendering](server-rendering.md#hydration)).
128
+
129
+ Follow your app's own dark mode by building the theme with the current mode:
130
+
131
+ ```tsx
132
+ const theme = useMemo(() => createTheme({ extends: acme, mode: isDark ? "dark" : "light" }), [isDark]);
133
+ <DashboardRenderer document={doc} theme={theme} />;
134
+ ```
135
+
136
+ A document can ask for a mode too: `"display": { "theme": "dark" }` applies `dark` to
137
+ whichever theme the host gave.
138
+
139
+ ## Named themes
140
+
141
+ Register several themes by name; a document picks one with `display.theme`:
142
+
143
+ ```tsx
144
+ <DashSpecProvider
145
+ theme={acme}
146
+ themes={{
147
+ "acme-dark": createTheme({ extends: acme, mode: "dark" }),
148
+ "acme-tv": createTheme({ extends: acme, mode: "dark", scale: { font: { roles: { kpi: { family: "data", size: 48, weight: 700, lineHeight: 56 } } } } }),
149
+ }}
150
+ >
151
+ ```
152
+
153
+ ```json
154
+ "display": { "title": "Wall screen", "theme": "acme-tv" }
155
+ ```
156
+
157
+ `display.theme` resolves in this order:
158
+
159
+ 1. A name in `themes`: that theme, in its own mode.
160
+ 2. `"light"`, `"dark"` or `"auto"`: the host's theme in that mode.
161
+ 3. Anything else: the host's theme, and `onError` receives
162
+ `{ code: "unknown-theme", message }`.
163
+
164
+ ## CSS variables
165
+
166
+ The renderer wraps the dashboard in a `<div class="ds-root" data-ds-theme="light|dark">`
167
+ and sets every token on it as a variable:
168
+
169
+ | Token | Variable |
170
+ |---|---|
171
+ | `surface.card` | `--ds-color-surface-card` |
172
+ | `text.secondary` | `--ds-color-text-secondary` |
173
+ | `status.good.bg` | `--ds-color-status-good-bg` |
174
+ | `chart.series[0]` | `--ds-color-chart-series-1` |
175
+ | `space.md` | `--ds-space-md` (`12px`; scaled by `density`) |
176
+ | `density` | `--ds-control-height` (`36px`), `--ds-density` |
177
+ | `radius.card` | `--ds-radius-card` |
178
+ | `font.roles.kpi.size` | `--ds-type-kpi-size` (also `-family`, `-weight`, `-line-height`, `-letter-spacing`) |
179
+ | `motion.fast` | `--ds-motion-fast` (`150ms`) |
180
+
181
+ Short aliases: `--ds-primary`, `--ds-good`, `--ds-warn`, `--ds-bad` (status `solid`),
182
+ `--ds-font`, `--ds-radius` (card radius), `--ds-series-1`, `--ds-series-2`, …
183
+
184
+ Use them in your own widgets so they follow the theme and dark mode:
185
+
186
+ ```css
187
+ .acme-battery {
188
+ background: var(--ds-color-surface-sunken);
189
+ border-radius: var(--ds-radius-control);
190
+ color: var(--ds-color-text-primary);
191
+ font: var(--ds-type-data-weight) var(--ds-type-data-size) / var(--ds-type-data-line-height) var(--ds-font-data);
192
+ }
193
+ .acme-battery-fill { background: var(--ds-good); }
194
+ ```
195
+
196
+ A node's `style.background` and `style.borderColor` accept token names too:
197
+ `"background": "status-good-bg"` becomes `var(--ds-color-status-good-bg)`.
198
+
199
+ `themeCssVars(theme, mode)` returns the variables for one mode as an object, if you need
200
+ them elsewhere.
201
+
202
+ ### `themeStylesheet`
203
+
204
+ To style other parts of your page with the same tokens, or for pages that don't use
205
+ React, `themeStylesheet` returns the variables as CSS: light on the selector, dark under
206
+ `[data-ds-theme="dark"]`.
207
+
208
+ ```ts
209
+ import { themeStylesheet } from "@dashspec/renderer";
210
+
211
+ const css = themeStylesheet(acme, ".acme-dashboard-shell");
212
+ // .acme-dashboard-shell { --ds-color-surface-page: #f8fafc; … }
213
+ // .acme-dashboard-shell[data-ds-theme="dark"] { … }
214
+ ```
215
+
216
+ Set `data-ds-theme="dark"` on the element yourself to switch it. Tokens whose name or
217
+ value could break out of a CSS rule (`;`, braces, `<`, `>`, line breaks, `\`) are left
218
+ out, so a theme built from user input can't inject CSS.
219
+
220
+ ## Charts
221
+
222
+ Charts use the same tokens: `chart.series` colours the series in order, `chart.axis`
223
+ and `chart.grid` the axes, `chart.tooltipBg` and `chart.tooltipText` the tooltip,
224
+ `chart.sequential` the matrix chart's scale, and fonts come from `scale.font`. They
225
+ re-theme when the mode changes.
226
+
227
+ For one chart, override anything ECharts supports with the widget's `options` prop; it
228
+ is merged last:
229
+
230
+ ```json
231
+ "trend": {
232
+ "kind": "LineChart",
233
+ "spec": {
234
+ "data": { "source": "daily" },
235
+ "x": "date",
236
+ "y": "orders",
237
+ "options": { "color": ["#0ea5e9"], "legend": { "show": false }, "grid": { "left": 48 } }
238
+ }
239
+ }
240
+ ```
241
+
242
+ `echartsTheme(theme, mode)` returns the ECharts theme object built from the tokens, if
243
+ you draw your own ECharts charts and want them to match. Inside a widget,
244
+ `useThemeTokens()` gives you `{ theme, mode }`.