@dloizides/design-tokens 1.0.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,413 @@
1
+ /**
2
+ * Token shape for `@dloizides/design-tokens`.
3
+ *
4
+ * This package is a framework-agnostic design-token **source**. It owns the
5
+ * token *shape* and ships one typed token set per app (see `presets/`), each
6
+ * seeded byte-for-byte from that app's CURRENT values so adoption is a
7
+ * behaviour-preserving extraction — nothing changes visually.
8
+ *
9
+ * The CORE fields (`primary`/`secondary`/`accent`/`semantic`/`light`/`dark`/
10
+ * `typography`/`branding`) intentionally mirror `@dloizides/tenant-theme-web`'s
11
+ * `TenantThemeConfig` so per-tenant theme overrides layer cleanly on top of a
12
+ * preset. The `radii`/`shadows`/`extensions` groups are OPTIONAL supersets used
13
+ * by richer stacks (currently the vanilla-JS AML console); RN-web apps that have
14
+ * no centralized radius/shadow/shell tokens simply omit them.
15
+ *
16
+ * Values only. No components.
17
+ */
18
+ /**
19
+ * Mode-specific colour tokens shared by both light and dark configurations.
20
+ * Field names match `TenantThemeConfig`'s `ThemeModeColors` exactly. All values
21
+ * are CSS colour strings (hex, rgb, rgba).
22
+ */
23
+ interface ModeColors {
24
+ /** Page/body background */
25
+ background: string;
26
+ /** Cards, panels */
27
+ surface: string;
28
+ /** Modals, dropdowns, raised surfaces */
29
+ surfaceElevated: string;
30
+ /** Primary text */
31
+ text: string;
32
+ /** Secondary/muted text */
33
+ textSecondary: string;
34
+ /** Default borders */
35
+ border: string;
36
+ /** Divider lines */
37
+ divider: string;
38
+ }
39
+ /** Semantic/status colours. Field names match `TenantThemeConfig`'s `SemanticColorOverrides`. */
40
+ interface SemanticColors {
41
+ success: string;
42
+ warning: string;
43
+ error: string;
44
+ info: string;
45
+ }
46
+ /** Typography tokens. `fontFamily` mirrors `TenantThemeConfig`; `monoFamily` is an optional superset. */
47
+ interface Typography {
48
+ /** UI font-family stack */
49
+ fontFamily: string;
50
+ /** Optional monospace font-family stack (ids, scores, dates) */
51
+ monoFamily?: string;
52
+ /** Heading size multiplier (default 1) */
53
+ headingScale: number;
54
+ }
55
+ /** Corner-radius scale. Values are CSS length strings (e.g. '12px'). */
56
+ interface Radii {
57
+ xs: string;
58
+ sm: string;
59
+ /** The default radius (AML's `--r`). */
60
+ md: string;
61
+ lg: string;
62
+ pill: string;
63
+ }
64
+ /** Elevation scale. Values are full CSS `box-shadow` strings. */
65
+ interface Shadows {
66
+ sm: string;
67
+ md: string;
68
+ pop: string;
69
+ }
70
+ /** Branding asset references (ContentService GUIDs). Matches `TenantThemeConfig`'s `BrandingConfig`. */
71
+ interface Branding {
72
+ logoContentId: string | null;
73
+ faviconContentId: string | null;
74
+ presetId: string | null;
75
+ }
76
+ /**
77
+ * A dark app-shell layered over a light workspace. This is a Stack-A (AML
78
+ * console) concept, not part of the `TenantThemeConfig` contract.
79
+ */
80
+ interface ShellColors {
81
+ /** Shell base (`--shell`) */
82
+ background: string;
83
+ /** Shell raised (`--shell-2`) */
84
+ backgroundAlt: string;
85
+ /** Shell hairline (`--shell-line`) */
86
+ line: string;
87
+ /** On-shell text (`--on-shell`) */
88
+ on: string;
89
+ /** On-shell dim text (`--on-shell-dim`) */
90
+ onDim: string;
91
+ }
92
+ /** Extra brand tones beyond the base `primary`. Stack-A extension. */
93
+ interface BrandExtras {
94
+ /** Pressed/active brand (`--brand-press`) */
95
+ press: string;
96
+ /** Soft brand tint (`--brand-soft`) */
97
+ soft: string;
98
+ /** Focus-ring brand tint (`--brand-ring`) */
99
+ ring: string;
100
+ }
101
+ /** Ink (dark-on-light text) scale. Stack-A extension. */
102
+ interface InkScale {
103
+ /** Primary ink (`--ink`) */
104
+ base: string;
105
+ /** Soft ink (`--ink-soft`) */
106
+ soft: string;
107
+ /** Faint ink (`--ink-faint`) */
108
+ faint: string;
109
+ /** Ink overlay tint (`--ink-2`) */
110
+ overlay: string;
111
+ }
112
+ /** Extra light-workspace surfaces/lines. Stack-A extension. */
113
+ interface WorkspaceExtras {
114
+ /** Alt surface (`--surface-2`) */
115
+ surfaceAlt: string;
116
+ /** Strong line (`--line-strong`) */
117
+ lineStrong: string;
118
+ }
119
+ /**
120
+ * Sanctions-verdict palette (clear / review / block), each with a base, a soft
121
+ * background tint, and an ink tone. Stack-A (AML) extension.
122
+ */
123
+ interface VerdictColors {
124
+ ok: string;
125
+ okSoft: string;
126
+ okInk: string;
127
+ warn: string;
128
+ warnSoft: string;
129
+ warnInk: string;
130
+ bad: string;
131
+ badSoft: string;
132
+ /** Secondary block-soft tint (`--bad-soft2`) */
133
+ badSoft2: string;
134
+ badInk: string;
135
+ }
136
+ /** Optional stack-specific token groups not covered by the `TenantThemeConfig` core. */
137
+ interface TokenExtensions {
138
+ shell?: ShellColors;
139
+ brand?: BrandExtras;
140
+ ink?: InkScale;
141
+ workspace?: WorkspaceExtras;
142
+ verdict?: VerdictColors;
143
+ }
144
+ /**
145
+ * One app's complete token set. The single source the three emitters read.
146
+ * Core fields align with `TenantThemeConfig`; optional groups are supersets.
147
+ */
148
+ interface DesignTokens {
149
+ /** Brand primary colour */
150
+ primary: string;
151
+ /** Brand secondary colour */
152
+ secondary: string;
153
+ /** Accent/highlight colour */
154
+ accent: string;
155
+ /** Semantic/status colours */
156
+ semantic: SemanticColors;
157
+ /** Light-mode colours */
158
+ light: ModeColors;
159
+ /** Dark-mode colours */
160
+ dark: ModeColors;
161
+ /** Optional typography tokens */
162
+ typography?: Typography;
163
+ /** Optional corner-radius scale */
164
+ radii?: Radii;
165
+ /** Optional elevation scale */
166
+ shadows?: Shadows;
167
+ /** Branding asset references */
168
+ branding: Branding;
169
+ /** Optional stack-specific token supersets */
170
+ extensions?: TokenExtensions;
171
+ }
172
+
173
+ /**
174
+ * CSS custom-property NAME MAPS — the cross-stack naming contract.
175
+ *
176
+ * `toCssVars(tokens, names)` reads a {@link DesignTokens} and a {@link CssVarNames}
177
+ * map that says which CSS variable each token field is emitted as. A field whose
178
+ * name is `undefined` in the map is skipped, which lets a stack emit only the
179
+ * variables it actually consumes.
180
+ *
181
+ * Two maps ship:
182
+ * - {@link DEFAULT_CSS_VAR_NAMES} — canonical kebab names (`--primary`, `--bg`, …).
183
+ * The dark-mode fields have names, so a dark-mode block is emitted.
184
+ * - {@link AML_CSS_VAR_NAMES} — the vanilla-JS AML console's existing variable
185
+ * names (`--brand`, `--shell`, `--ok`, `--r`, …), so `wwwroot/shared/ui.css`
186
+ * keeps working byte-for-byte. Core fields that AML expresses via an extension
187
+ * variable are mapped to `undefined` (skipped) to avoid emitting duplicates,
188
+ * and the dark-mode fields are `undefined` (AML has no light/dark toggle — its
189
+ * dark app-shell is captured in the `shell*` extension inside `:root`).
190
+ */
191
+ /** Maps each {@link DesignTokens} field to the CSS variable it is emitted as (or `undefined` to skip). */
192
+ interface CssVarNames {
193
+ primary?: string;
194
+ secondary?: string;
195
+ accent?: string;
196
+ success?: string;
197
+ warning?: string;
198
+ error?: string;
199
+ info?: string;
200
+ lightBackground?: string;
201
+ lightSurface?: string;
202
+ lightSurfaceElevated?: string;
203
+ lightText?: string;
204
+ lightTextSecondary?: string;
205
+ lightBorder?: string;
206
+ lightDivider?: string;
207
+ darkBackground?: string;
208
+ darkSurface?: string;
209
+ darkSurfaceElevated?: string;
210
+ darkText?: string;
211
+ darkTextSecondary?: string;
212
+ darkBorder?: string;
213
+ darkDivider?: string;
214
+ radiusXs?: string;
215
+ radiusSm?: string;
216
+ radiusMd?: string;
217
+ radiusLg?: string;
218
+ radiusPill?: string;
219
+ shadowSm?: string;
220
+ shadowMd?: string;
221
+ shadowPop?: string;
222
+ fontFamily?: string;
223
+ monoFamily?: string;
224
+ shellBackground?: string;
225
+ shellBackgroundAlt?: string;
226
+ shellLine?: string;
227
+ shellOn?: string;
228
+ shellOnDim?: string;
229
+ brandPress?: string;
230
+ brandSoft?: string;
231
+ brandRing?: string;
232
+ inkBase?: string;
233
+ inkSoft?: string;
234
+ inkFaint?: string;
235
+ inkOverlay?: string;
236
+ surfaceAlt?: string;
237
+ lineStrong?: string;
238
+ ok?: string;
239
+ okSoft?: string;
240
+ okInk?: string;
241
+ warn?: string;
242
+ warnSoft?: string;
243
+ warnInk?: string;
244
+ bad?: string;
245
+ badSoft?: string;
246
+ badSoft2?: string;
247
+ badInk?: string;
248
+ }
249
+ /**
250
+ * Canonical kebab-case variable names. A stack with no existing CSS-variable
251
+ * convention (or a fresh consumer) should adopt these. Extension fields are
252
+ * omitted because the RN/DOM presets carry no extensions.
253
+ */
254
+ declare const DEFAULT_CSS_VAR_NAMES: CssVarNames;
255
+ /**
256
+ * The AML console's existing `wwwroot/shared/ui.css` variable names. Emitting the
257
+ * `aml` preset with this map reproduces AML's current `:root` byte-for-byte, so
258
+ * ui.css keeps working with zero visual change.
259
+ *
260
+ * Core fields that AML already expresses through an extension variable are mapped
261
+ * to `undefined` to avoid duplicate declarations:
262
+ * - `secondary`/`accent` — AML has a single brand; ui.css never reads them.
263
+ * - `success`/`warning`/`error`/`info` — emitted via the verdict extension
264
+ * (`--ok`/`--warn`/`--bad`); `info` has no AML variable.
265
+ * - `light.surfaceElevated` → via `workspace.surfaceAlt` (`--surface-2`).
266
+ * - `light.text` → via `ink.base` (`--ink`); `light.textSecondary` → `ink.soft`.
267
+ * - `light.divider` — AML reuses `--line`, so no separate variable.
268
+ * - all `dark*` — AML has no dark-mode toggle (its shell lives in the extension).
269
+ */
270
+ declare const AML_CSS_VAR_NAMES: CssVarNames;
271
+
272
+ /** Options for {@link toCssVars}. */
273
+ interface ToCssVarsOptions {
274
+ /**
275
+ * Selector for the dark-mode block. Only used when the name map defines any
276
+ * `dark*` variables. Defaults to `:root[data-theme="dark"]`.
277
+ */
278
+ darkSelector?: string;
279
+ }
280
+ /**
281
+ * Emit a {@link DesignTokens} as CSS custom properties. Base tokens (brand,
282
+ * semantic, light-mode, radii, shadows, fonts and any extensions) go in a
283
+ * `:root {}` block; dark-mode tokens go in a separate selector block, emitted
284
+ * only when the name map defines at least one `dark*` variable.
285
+ */
286
+ declare function toCssVars(tokens: DesignTokens, names: CssVarNames, options?: ToCssVarsOptions): string;
287
+
288
+ /**
289
+ * The RN-web theme-config shape. Structurally compatible with
290
+ * `@dloizides/tenant-theme-web`'s `TenantThemeConfig` (and each RN app's local
291
+ * `TenantThemeConfig`), so a preset can be dropped in as the `defaultThemeConfig`
292
+ * fallback without any mapping. Semantic and typography are optional (an RN app
293
+ * may leave them unset, exactly as the current `default` preset does).
294
+ */
295
+ interface RnThemeConfig {
296
+ primary: string;
297
+ secondary: string;
298
+ accent: string;
299
+ semantic?: {
300
+ success?: string;
301
+ warning?: string;
302
+ error?: string;
303
+ info?: string;
304
+ };
305
+ light: ModeColors;
306
+ dark: ModeColors;
307
+ typography?: {
308
+ fontFamily?: string;
309
+ headingScale?: number;
310
+ };
311
+ branding: Branding;
312
+ }
313
+ /**
314
+ * Emit a {@link DesignTokens} as an RN-web `TenantThemeConfig`-compatible object.
315
+ * Only the core fields are projected; the `radii`/`shadows`/`extensions`
316
+ * supersets are intentionally dropped (RN-web has no centralized token for them).
317
+ * `typography` is included only when the preset defines it, so a preset with no
318
+ * typography yields a config with no `typography` key — byte-identical to the RN
319
+ * apps' current `DEFAULT_THEME_CONFIG`.
320
+ */
321
+ declare function toRnTheme(tokens: DesignTokens): RnThemeConfig;
322
+
323
+ /** Nested colour scale emitted under `theme.extend.colors`. */
324
+ interface TailwindColors {
325
+ primary: string;
326
+ secondary: string;
327
+ accent: string;
328
+ success: string;
329
+ warning: string;
330
+ error: string;
331
+ info: string;
332
+ background: string;
333
+ surface: string;
334
+ 'surface-elevated': string;
335
+ text: string;
336
+ 'text-secondary': string;
337
+ border: string;
338
+ divider: string;
339
+ dark: {
340
+ background: string;
341
+ surface: string;
342
+ 'surface-elevated': string;
343
+ text: string;
344
+ 'text-secondary': string;
345
+ border: string;
346
+ divider: string;
347
+ };
348
+ }
349
+ /** A Tailwind preset object: `{ theme: { extend: { … } } }`. Spread into a `tailwind.config`'s `presets`. */
350
+ interface TailwindPreset {
351
+ theme: {
352
+ extend: {
353
+ colors: TailwindColors;
354
+ borderRadius?: Record<string, string>;
355
+ boxShadow?: Record<string, string>;
356
+ fontFamily?: Record<string, string[]>;
357
+ };
358
+ };
359
+ }
360
+ /**
361
+ * Emit a {@link DesignTokens} as a Tailwind preset for the DOM-React ThemeStudio.
362
+ * Colours are always present; `borderRadius`/`boxShadow`/`fontFamily` are emitted
363
+ * only when the preset defines the corresponding token group.
364
+ */
365
+ declare function toTailwindPreset(tokens: DesignTokens): TailwindPreset;
366
+
367
+ /**
368
+ * PROOViD AML console (Stack A — vanilla JS) tokens.
369
+ *
370
+ * Seeded byte-for-byte from `PROOViD/AMLService/AMLService/wwwroot/shared/ui.css`
371
+ * `:root`. Emitting via `toCssVars(AML_TOKENS, AML_CSS_VAR_NAMES)` reproduces that
372
+ * `:root` block exactly, so ui.css keeps working with zero visual change.
373
+ *
374
+ * Name-mapping notes (AML has no `TenantThemeConfig`-style secondary/accent or
375
+ * light/dark toggle):
376
+ * - `primary` = `--brand`. `secondary`/`accent` mirror it (ui.css reads neither);
377
+ * they exist only so the core shape is complete.
378
+ * - `semantic` mirrors the verdict palette (`--ok`/`--warn`/`--bad`); `info` has
379
+ * no AML variable, so it mirrors `--brand`.
380
+ * - `light` = the light workspace (`--bg`/`--surface`/…); `dark` = the dark app
381
+ * SHELL (`--shell`/`--shell-2`/…) so the shape is complete. The AML name map
382
+ * omits all `dark*` names, so no dark-mode block is emitted; the shell is
383
+ * emitted from the `extensions.shell` group inside `:root`, matching ui.css.
384
+ */
385
+ declare const AML_TOKENS: DesignTokens;
386
+
387
+ /**
388
+ * Erevna (surveys/forms — realm `questioner`) tokens.
389
+ *
390
+ * Seeded byte-for-byte from `erevna-web/src/theme/presets/default.ts`
391
+ * (`DEFAULT_THEME_CONFIG`) and `erevna-web/src/theme/utils/palette.ts`
392
+ * (`basePalette`). Adopting this preset via `toRnTheme(EREVNA_TOKENS)` yields the
393
+ * app's current `DEFAULT_THEME_CONFIG` unchanged. No `typography`/`radii`/
394
+ * `shadows` — the RN theme has no centralized tokens for those today, so they are
395
+ * omitted (nothing to emit → zero visual change).
396
+ */
397
+ declare const EREVNA_TOKENS: DesignTokens;
398
+
399
+ /**
400
+ * Katalogos (online menus — realm `onlinemenu`) tokens.
401
+ *
402
+ * Seeded byte-for-byte from `katalogos-web/src/theme/presets/default.ts`
403
+ * (`DEFAULT_THEME_CONFIG`), which is currently identical to Erevna's default.
404
+ * Kept as a separate preset so the two apps can diverge later without touching
405
+ * the other. Adopting via `toRnTheme(KATALOGOS_TOKENS)` yields the app's current
406
+ * `DEFAULT_THEME_CONFIG` unchanged.
407
+ */
408
+ declare const KATALOGOS_TOKENS: DesignTokens;
409
+
410
+ /** Every shipped app preset keyed by app slug. */
411
+ declare const PRESETS: Readonly<Record<string, DesignTokens>>;
412
+
413
+ export { AML_CSS_VAR_NAMES, AML_TOKENS, type BrandExtras, type Branding, type CssVarNames, DEFAULT_CSS_VAR_NAMES, type DesignTokens, EREVNA_TOKENS, type InkScale, KATALOGOS_TOKENS, type ModeColors, PRESETS, type Radii, type RnThemeConfig, type SemanticColors, type Shadows, type ShellColors, type TailwindColors, type TailwindPreset, type ToCssVarsOptions, type TokenExtensions, type Typography, type VerdictColors, type WorkspaceExtras, toCssVars, toRnTheme, toTailwindPreset };