@dloizides/design-tokens 1.1.0 → 1.2.0

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 CHANGED
@@ -2,6 +2,54 @@
2
2
 
3
3
  All notable changes to `@dloizides/design-tokens` are documented here.
4
4
 
5
+ ## [1.2.0]
6
+
7
+ ### Added
8
+
9
+ `DesignTokens` was a **lossy carrier**. Two RN-web apps (ichnos, kefi) discovered this
10
+ independently and wrote the *same* private workaround: the shape had no slot for the muted
11
+ inset surface, the on-brand foreground, or the three status background tints, so each app
12
+ smuggled those five values into free slots of the broadcast theme via a hand-rolled overlay.
13
+ Two independent uses of one workaround is the trigger to extract it. These are now
14
+ first-class slots, and the overlay is a shipped emitter.
15
+
16
+ - **`ModeColors.surfaceMuted?`** — the subtle inset surface (table header rows, chips, wells).
17
+ Distinct from `surface` (cards) and `surfaceElevated` (modals): it recedes rather than lifts.
18
+ - **`DesignTokens.onBrand?`** — the foreground for content sitting ON a `primary`-filled
19
+ surface. It is a *contrast partner* of `primary`, not a mode colour, so it lives beside it.
20
+ - **`SemanticColors.successBg?` / `warningBg?` / `errorBg?` / `infoBg?`** — the soft fill a
21
+ status badge, banner or row-highlight paints behind text of the base colour. A tint is NOT
22
+ derivable from its base (it is hand-picked for contrast), so it needs its own slot; without
23
+ one a status surface could not be themed at all.
24
+ - **`toUiTheme(tokens, mode?)`** — a fourth emitter: the shared RN UI kit's `UiTheme` (what
25
+ `@dloizides/ui-feedback`'s `UiProvider` broadcasts). It is **lossless** — every token the
26
+ shape can express lands in an addressable slot (`palette.onBrand`, `palette.surfaceMuted`,
27
+ each status tint at the `100` step), so an app can round-trip its entire palette back out
28
+ of the live provider instead of keeping a parallel static copy that can never follow a
29
+ dark-mode toggle or a per-tenant brand. The theme type is declared **structurally** here,
30
+ exactly as `RnThemeConfig` declares the `TenantThemeConfig` shape, so the package keeps its
31
+ zero-dependency / zero-peer guarantee and takes no dependency on the kit it feeds.
32
+ - **`UI_TINT_STEP` / `UI_MAIN_STEP` / `UI_DEEP_STEP`** — the step names, exported so a consumer
33
+ addresses a scale by name rather than by a magic `'500'`.
34
+ - CSS-variable names (`--on-brand`, `--surface-muted`, `--success-bg`, …) and Tailwind colour
35
+ keys (`on-brand`, `surface-muted`, `success-bg`, …) for the new tokens.
36
+
37
+ ### Fixed
38
+
39
+ - **Scale collapse.** The naive `value => ({ '100': v, '500': v, '700': v })` projection that
40
+ both apps used writes ONE value into every step, silently discarding the deeper brand step
41
+ and every status tint — a theme built that way cannot reproduce the palette it came from.
42
+ `toUiTheme` emits `secondary` as its own scale and each status tint at the `100` step, so
43
+ the values survive. The package's own emitters (`toCssVars`, `toRnTheme`,
44
+ `toTailwindPreset`) were checked and carry no equivalent collapse.
45
+
46
+ ### Compatibility
47
+
48
+ Entirely additive. Every new token is optional and every new emitted key appears **only** when
49
+ a preset declares the token, so `AML_TOKENS`, `EREVNA_TOKENS` and `KATALOGOS_TOKENS` emit
50
+ byte-identical CSS, RN-theme and Tailwind output — verified by the pre-existing emitter test
51
+ suites passing unmodified.
52
+
5
53
  ## [1.1.0]
6
54
 
7
55
  ### Fixed
package/README.md CHANGED
@@ -12,20 +12,21 @@ values**, emitted in **three forms from one source**.
12
12
  Values only — **no components**. (Shared React components live in `@dloizides/ui-layout`,
13
13
  `ui-forms`, `ui-feedback`, `ui-icons`, `ui-tables`.)
14
14
 
15
- ## The three output forms
15
+ ## The four output forms
16
16
 
17
- One `DesignTokens` object per app feeds three pure emitters:
17
+ One `DesignTokens` object per app feeds four pure emitters:
18
18
 
19
19
  | Form | Emitter | Consumer stack | Output |
20
20
  |------|---------|----------------|--------|
21
21
  | **(a) CSS custom properties** | `toCssVars(tokens, names, opts?)` | Stack-A vanilla-JS (AML console) | a `:root { --…: …; }` string (+ optional dark-mode block) |
22
22
  | **(b) RN-web theme object** | `toRnTheme(tokens)` | RN-web (erevna, katalogos) | a `TenantThemeConfig`-compatible object |
23
23
  | **(c) Tailwind preset** | `toTailwindPreset(tokens)` | DOM-React (SyncfusionThemeStudio) | `{ theme: { extend: { colors, borderRadius, boxShadow, fontFamily } } }` |
24
+ | **(d) Shared UI kit theme** | `toUiTheme(tokens, mode?)` | RN-web on the `@dloizides/ui-*` kit (ichnos, kefi) | a `UiTheme` for `ui-feedback`'s `UiProvider` |
24
25
 
25
26
  ```ts
26
27
  import {
27
28
  AML_TOKENS, EREVNA_TOKENS, KATALOGOS_TOKENS, PRESETS,
28
- toCssVars, toRnTheme, toTailwindPreset,
29
+ toCssVars, toRnTheme, toTailwindPreset, toUiTheme,
29
30
  AML_CSS_VAR_NAMES, DEFAULT_CSS_VAR_NAMES,
30
31
  } from '@dloizides/design-tokens';
31
32
 
@@ -37,8 +38,34 @@ const rnDefault = toRnTheme(EREVNA_TOKENS);
37
38
 
38
39
  // (c) DOM-React ThemeStudio — spread into tailwind.config.presets
39
40
  const tw = toTailwindPreset(KATALOGOS_TOKENS);
41
+
42
+ // (d) Shared UI kit — hand straight to <UiProvider theme={…}>
43
+ const uiTheme = toUiTheme(MY_TOKENS);
40
44
  ```
41
45
 
46
+ ### `toUiTheme` is a LOSSLESS carrier
47
+
48
+ `toUiTheme` exists because the naive projection an app writes by hand —
49
+ `value => ({ '100': v, '500': v, '700': v })` — collapses a scale to one value, silently
50
+ discarding the deeper brand step and every status background tint. A provider fed that way
51
+ cannot reproduce the palette it was built from, which is what stops a shared component
52
+ (`StatCard`, `ThemedTextInput`, `Field`) from rendering on-brand in a consuming app.
53
+
54
+ Every token lands in an addressable slot, so an app can project its whole palette back out of
55
+ the live provider rather than keeping a static parallel copy:
56
+
57
+ | Token | Slot |
58
+ |-------|------|
59
+ | `primary` / `secondary` / `accent` | `palette.primary` / `.secondary` / `.accent` at `UI_MAIN_STEP` |
60
+ | `onBrand` | `palette.onBrand` |
61
+ | `light.surfaceMuted` (or `dark.*`, per `mode`) | `palette.surfaceMuted` |
62
+ | `semantic.success` … | `semantic.success` at `UI_MAIN_STEP` |
63
+ | `semantic.successBg` … | `semantic.success` at `UI_TINT_STEP` |
64
+
65
+ The `UiTheme` shape is declared **structurally** in this package (as `RnThemeConfig` declares
66
+ `TenantThemeConfig`), so the zero-dependency / zero-peer guarantee holds: the token source
67
+ never depends on the kit it feeds.
68
+
42
69
  ## The per-app presets
43
70
 
44
71
  Each preset is seeded from that app's current source of truth:
@@ -63,6 +90,18 @@ the same field names. Fields the core cannot express (a dark app-shell, an ink s
63
90
  verdict triads) live in an optional `extensions` group and are documented as **Stack-A supersets**,
64
91
  not part of the `TenantThemeConfig` contract.
65
92
 
93
+ Three additions (1.2.0) are core rather than extensions, because they are needed by any app with
94
+ a status badge or a filled brand button — not by one stack:
95
+
96
+ | Field | Why it needs its own slot |
97
+ |-------|---------------------------|
98
+ | `light.surfaceMuted` / `dark.surfaceMuted` | The inset surface (table header rows, chips, wells) *recedes*; `surface` and `surfaceElevated` both lift. Neither substitutes. |
99
+ | `onBrand` | The foreground on a `primary` fill. A contrast partner of `primary`, so it sits beside it, not in a mode block. Defaults to white; a **pale** primary must set it. |
100
+ | `semantic.successBg` / `warningBg` / `errorBg` / `infoBg` | A status tint is hand-picked for contrast, not derivable from its base — so it cannot be computed and must be carried. |
101
+
102
+ All optional, and every emitter emits them **only** when a preset declares them, so presets that
103
+ predate 1.2.0 produce byte-identical output.
104
+
66
105
  ## The cross-stack naming contract (#78b)
67
106
 
68
107
  Different stacks use different CSS-variable names for the same token. `toCssVars` takes a
package/dist/index.d.mts CHANGED
@@ -35,13 +35,36 @@ interface ModeColors {
35
35
  border: string;
36
36
  /** Divider lines */
37
37
  divider: string;
38
+ /**
39
+ * Subtle inset surface — table header rows, chips, wells. Distinct from both
40
+ * `surface` (cards) and `surfaceElevated` (modals): it recedes rather than
41
+ * lifts. Optional; consumers fall back to `surface` when a preset omits it.
42
+ */
43
+ surfaceMuted?: string;
38
44
  }
39
- /** Semantic/status colours. Field names match `TenantThemeConfig`'s `SemanticColorOverrides`. */
45
+ /**
46
+ * Semantic/status colours. The four base fields match `TenantThemeConfig`'s
47
+ * `SemanticColorOverrides` exactly.
48
+ *
49
+ * Each base colour may also carry a `*Bg` **background tint** — the soft fill a
50
+ * status badge, banner or row-highlight paints behind text of the base colour.
51
+ * A tint is NOT derivable from its base (it is hand-picked for contrast), so it
52
+ * needs its own slot; without one a status surface cannot be themed at all.
53
+ * Optional, so existing presets are unchanged.
54
+ */
40
55
  interface SemanticColors {
41
56
  success: string;
42
57
  warning: string;
43
58
  error: string;
44
59
  info: string;
60
+ /** Soft background tint behind `success` content. */
61
+ successBg?: string;
62
+ /** Soft background tint behind `warning` content. */
63
+ warningBg?: string;
64
+ /** Soft background tint behind `error` content. */
65
+ errorBg?: string;
66
+ /** Soft background tint behind `info` content. */
67
+ infoBg?: string;
45
68
  }
46
69
  /** Typography tokens. `fontFamily` mirrors `TenantThemeConfig`; `monoFamily` is an optional superset. */
47
70
  interface Typography {
@@ -152,6 +175,14 @@ interface DesignTokens {
152
175
  secondary: string;
153
176
  /** Accent/highlight colour */
154
177
  accent: string;
178
+ /**
179
+ * Foreground colour for content sitting ON a `primary`-filled surface — a
180
+ * filled button's label, a brand header's text. It is a *contrast partner* of
181
+ * `primary`, not a mode colour, so it lives beside it rather than in
182
+ * `light`/`dark`. Optional; consumers fall back to white, the safe default for
183
+ * a saturated brand. A preset with a pale `primary` MUST set it explicitly.
184
+ */
185
+ onBrand?: string;
155
186
  /** Semantic/status colours */
156
187
  semantic: SemanticColors;
157
188
  /** Light-mode colours */
@@ -193,13 +224,19 @@ interface CssVarNames {
193
224
  primary?: string;
194
225
  secondary?: string;
195
226
  accent?: string;
227
+ onBrand?: string;
196
228
  success?: string;
197
229
  warning?: string;
198
230
  error?: string;
199
231
  info?: string;
232
+ successBg?: string;
233
+ warningBg?: string;
234
+ errorBg?: string;
235
+ infoBg?: string;
200
236
  lightBackground?: string;
201
237
  lightSurface?: string;
202
238
  lightSurfaceElevated?: string;
239
+ lightSurfaceMuted?: string;
203
240
  lightText?: string;
204
241
  lightTextSecondary?: string;
205
242
  lightBorder?: string;
@@ -207,6 +244,7 @@ interface CssVarNames {
207
244
  darkBackground?: string;
208
245
  darkSurface?: string;
209
246
  darkSurfaceElevated?: string;
247
+ darkSurfaceMuted?: string;
210
248
  darkText?: string;
211
249
  darkTextSecondary?: string;
212
250
  darkBorder?: string;
@@ -325,13 +363,22 @@ interface TailwindColors {
325
363
  primary: string;
326
364
  secondary: string;
327
365
  accent: string;
366
+ /** Emitted only when the preset declares `onBrand`. */
367
+ 'on-brand'?: string;
328
368
  success: string;
329
369
  warning: string;
330
370
  error: string;
331
371
  info: string;
372
+ /** Status background tints. Emitted only when the preset declares them. */
373
+ 'success-bg'?: string;
374
+ 'warning-bg'?: string;
375
+ 'error-bg'?: string;
376
+ 'info-bg'?: string;
332
377
  background: string;
333
378
  surface: string;
334
379
  'surface-elevated': string;
380
+ /** Emitted only when the preset declares `light.surfaceMuted`. */
381
+ 'surface-muted'?: string;
335
382
  text: string;
336
383
  'text-secondary': string;
337
384
  border: string;
@@ -340,6 +387,8 @@ interface TailwindColors {
340
387
  background: string;
341
388
  surface: string;
342
389
  'surface-elevated': string;
390
+ /** Emitted only when the preset declares `dark.surfaceMuted`. */
391
+ 'surface-muted'?: string;
343
392
  text: string;
344
393
  'text-secondary': string;
345
394
  border: string;
@@ -359,11 +408,89 @@ interface TailwindPreset {
359
408
  }
360
409
  /**
361
410
  * 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.
411
+ * The core colours are always present; the optional colour slots,
412
+ * `borderRadius`/`boxShadow`/`fontFamily` are emitted only when the preset
413
+ * defines the corresponding token.
364
414
  */
365
415
  declare function toTailwindPreset(tokens: DesignTokens): TailwindPreset;
366
416
 
417
+ /**
418
+ * Emit a {@link DesignTokens} as the shared RN UI kit's theme object — the value
419
+ * `@dloizides/ui-feedback`'s `UiProvider` broadcasts and every kit component
420
+ * (NavShell, DataTable, Filters, Pager, StatusBadge, ThemedTextInput, StatCard)
421
+ * reads via `useUi()`.
422
+ *
423
+ * WHY THIS LIVES HERE
424
+ * -------------------
425
+ * Two apps (ichnos, kefi) independently wrote the same adapter, and both hit the
426
+ * same wall: a naive projection assigns ONE value to every step of a scale, which
427
+ * silently discards the deeper brand step and the status background tints. Each
428
+ * then bolted a private overlay onto the result to smuggle the lost values into
429
+ * free slots. That overlay is this function, done twice — so it belongs in the
430
+ * token package, where the token shape that lost the values is defined.
431
+ *
432
+ * The emitted theme is a LOSSLESS carrier: every token the shape can express has
433
+ * an addressable slot, so an app can round-trip its whole palette back out
434
+ * (see the `*Colors` accessors in each app) instead of keeping a parallel static
435
+ * copy that cannot follow a dark-mode toggle or a per-tenant brand.
436
+ *
437
+ * The type is declared structurally here rather than imported, exactly as
438
+ * {@link RnThemeConfig} declares the `TenantThemeConfig` shape: this package
439
+ * stays framework-agnostic and takes no dependency on the kit it feeds.
440
+ */
441
+
442
+ /** Flat colour fields the kit reads directly. Mirrors `ui-feedback`'s `FeedbackThemeColors`. */
443
+ interface UiThemeColors {
444
+ background: string;
445
+ surface: string;
446
+ surfaceElevated: string;
447
+ text: string;
448
+ textSecondary: string;
449
+ border: string;
450
+ }
451
+ /** A colour scale. The `500` step is guaranteed; other steps are addressable. */
452
+ interface UiColorScale {
453
+ '500': string;
454
+ [step: string]: string;
455
+ }
456
+ /** Brand scales. `primary` is guaranteed; other names are addressable. */
457
+ interface UiThemePalette {
458
+ primary: UiColorScale;
459
+ [name: string]: UiColorScale;
460
+ }
461
+ /** Status scales. `error` is guaranteed; other names are addressable. */
462
+ interface UiThemeSemantic {
463
+ error: UiColorScale;
464
+ [name: string]: UiColorScale;
465
+ }
466
+ /** The kit theme. Structurally identical to `@dloizides/ui-feedback`'s `UiTheme`. */
467
+ interface UiThemeConfig {
468
+ colors: UiThemeColors;
469
+ palette: UiThemePalette;
470
+ semantic: UiThemeSemantic;
471
+ }
472
+ /** Which mode block ({@link DesignTokens.light} / {@link DesignTokens.dark}) to project. */
473
+ type UiThemeMode = 'light' | 'dark';
474
+ /** The soft/tint step of a scale — status background tints, muted brand fills. */
475
+ declare const UI_TINT_STEP = "100";
476
+ /** The step every shipped kit component reads. */
477
+ declare const UI_MAIN_STEP = "500";
478
+ /** The deep/pressed step of a scale. */
479
+ declare const UI_DEEP_STEP = "700";
480
+ /**
481
+ * Project a token set onto the shared kit's theme shape.
482
+ *
483
+ * Every value is carried into an addressable slot:
484
+ * - `palette.primary` / `secondary` / `accent` — the brand scales.
485
+ * - `palette.onBrand` — {@link DesignTokens.onBrand}, the primary's contrast partner.
486
+ * - `palette.surfaceMuted` — the mode's {@link ModeColors.surfaceMuted}.
487
+ * - `semantic.*` — each status colour at `500`, its `*Bg` tint at `100`.
488
+ *
489
+ * @param tokens the app's token set
490
+ * @param mode which mode block to project (default `'light'`)
491
+ */
492
+ declare function toUiTheme(tokens: DesignTokens, mode?: UiThemeMode): UiThemeConfig;
493
+
367
494
  /**
368
495
  * PROOViD AML console (Stack A — vanilla JS) tokens.
369
496
  *
@@ -479,4 +606,4 @@ declare function contrastRatio(foreground: string, background: string): number;
479
606
  /** True when `foreground` on `background` meets `requiredRatio`. */
480
607
  declare function meetsContrast(foreground: string, background: string, requiredRatio: number): boolean;
481
608
 
482
- export { AA_LARGE_TEXT_RATIO, AA_NON_TEXT_RATIO, AA_NORMAL_TEXT_RATIO, 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, contrastRatio, isHexColor, meetsContrast, relativeLuminance, toCssVars, toRnTheme, toTailwindPreset };
609
+ export { AA_LARGE_TEXT_RATIO, AA_NON_TEXT_RATIO, AA_NORMAL_TEXT_RATIO, 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, UI_DEEP_STEP, UI_MAIN_STEP, UI_TINT_STEP, type UiColorScale, type UiThemeColors, type UiThemeConfig, type UiThemeMode, type UiThemePalette, type UiThemeSemantic, type VerdictColors, type WorkspaceExtras, contrastRatio, isHexColor, meetsContrast, relativeLuminance, toCssVars, toRnTheme, toTailwindPreset, toUiTheme };
package/dist/index.d.ts CHANGED
@@ -35,13 +35,36 @@ interface ModeColors {
35
35
  border: string;
36
36
  /** Divider lines */
37
37
  divider: string;
38
+ /**
39
+ * Subtle inset surface — table header rows, chips, wells. Distinct from both
40
+ * `surface` (cards) and `surfaceElevated` (modals): it recedes rather than
41
+ * lifts. Optional; consumers fall back to `surface` when a preset omits it.
42
+ */
43
+ surfaceMuted?: string;
38
44
  }
39
- /** Semantic/status colours. Field names match `TenantThemeConfig`'s `SemanticColorOverrides`. */
45
+ /**
46
+ * Semantic/status colours. The four base fields match `TenantThemeConfig`'s
47
+ * `SemanticColorOverrides` exactly.
48
+ *
49
+ * Each base colour may also carry a `*Bg` **background tint** — the soft fill a
50
+ * status badge, banner or row-highlight paints behind text of the base colour.
51
+ * A tint is NOT derivable from its base (it is hand-picked for contrast), so it
52
+ * needs its own slot; without one a status surface cannot be themed at all.
53
+ * Optional, so existing presets are unchanged.
54
+ */
40
55
  interface SemanticColors {
41
56
  success: string;
42
57
  warning: string;
43
58
  error: string;
44
59
  info: string;
60
+ /** Soft background tint behind `success` content. */
61
+ successBg?: string;
62
+ /** Soft background tint behind `warning` content. */
63
+ warningBg?: string;
64
+ /** Soft background tint behind `error` content. */
65
+ errorBg?: string;
66
+ /** Soft background tint behind `info` content. */
67
+ infoBg?: string;
45
68
  }
46
69
  /** Typography tokens. `fontFamily` mirrors `TenantThemeConfig`; `monoFamily` is an optional superset. */
47
70
  interface Typography {
@@ -152,6 +175,14 @@ interface DesignTokens {
152
175
  secondary: string;
153
176
  /** Accent/highlight colour */
154
177
  accent: string;
178
+ /**
179
+ * Foreground colour for content sitting ON a `primary`-filled surface — a
180
+ * filled button's label, a brand header's text. It is a *contrast partner* of
181
+ * `primary`, not a mode colour, so it lives beside it rather than in
182
+ * `light`/`dark`. Optional; consumers fall back to white, the safe default for
183
+ * a saturated brand. A preset with a pale `primary` MUST set it explicitly.
184
+ */
185
+ onBrand?: string;
155
186
  /** Semantic/status colours */
156
187
  semantic: SemanticColors;
157
188
  /** Light-mode colours */
@@ -193,13 +224,19 @@ interface CssVarNames {
193
224
  primary?: string;
194
225
  secondary?: string;
195
226
  accent?: string;
227
+ onBrand?: string;
196
228
  success?: string;
197
229
  warning?: string;
198
230
  error?: string;
199
231
  info?: string;
232
+ successBg?: string;
233
+ warningBg?: string;
234
+ errorBg?: string;
235
+ infoBg?: string;
200
236
  lightBackground?: string;
201
237
  lightSurface?: string;
202
238
  lightSurfaceElevated?: string;
239
+ lightSurfaceMuted?: string;
203
240
  lightText?: string;
204
241
  lightTextSecondary?: string;
205
242
  lightBorder?: string;
@@ -207,6 +244,7 @@ interface CssVarNames {
207
244
  darkBackground?: string;
208
245
  darkSurface?: string;
209
246
  darkSurfaceElevated?: string;
247
+ darkSurfaceMuted?: string;
210
248
  darkText?: string;
211
249
  darkTextSecondary?: string;
212
250
  darkBorder?: string;
@@ -325,13 +363,22 @@ interface TailwindColors {
325
363
  primary: string;
326
364
  secondary: string;
327
365
  accent: string;
366
+ /** Emitted only when the preset declares `onBrand`. */
367
+ 'on-brand'?: string;
328
368
  success: string;
329
369
  warning: string;
330
370
  error: string;
331
371
  info: string;
372
+ /** Status background tints. Emitted only when the preset declares them. */
373
+ 'success-bg'?: string;
374
+ 'warning-bg'?: string;
375
+ 'error-bg'?: string;
376
+ 'info-bg'?: string;
332
377
  background: string;
333
378
  surface: string;
334
379
  'surface-elevated': string;
380
+ /** Emitted only when the preset declares `light.surfaceMuted`. */
381
+ 'surface-muted'?: string;
335
382
  text: string;
336
383
  'text-secondary': string;
337
384
  border: string;
@@ -340,6 +387,8 @@ interface TailwindColors {
340
387
  background: string;
341
388
  surface: string;
342
389
  'surface-elevated': string;
390
+ /** Emitted only when the preset declares `dark.surfaceMuted`. */
391
+ 'surface-muted'?: string;
343
392
  text: string;
344
393
  'text-secondary': string;
345
394
  border: string;
@@ -359,11 +408,89 @@ interface TailwindPreset {
359
408
  }
360
409
  /**
361
410
  * 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.
411
+ * The core colours are always present; the optional colour slots,
412
+ * `borderRadius`/`boxShadow`/`fontFamily` are emitted only when the preset
413
+ * defines the corresponding token.
364
414
  */
365
415
  declare function toTailwindPreset(tokens: DesignTokens): TailwindPreset;
366
416
 
417
+ /**
418
+ * Emit a {@link DesignTokens} as the shared RN UI kit's theme object — the value
419
+ * `@dloizides/ui-feedback`'s `UiProvider` broadcasts and every kit component
420
+ * (NavShell, DataTable, Filters, Pager, StatusBadge, ThemedTextInput, StatCard)
421
+ * reads via `useUi()`.
422
+ *
423
+ * WHY THIS LIVES HERE
424
+ * -------------------
425
+ * Two apps (ichnos, kefi) independently wrote the same adapter, and both hit the
426
+ * same wall: a naive projection assigns ONE value to every step of a scale, which
427
+ * silently discards the deeper brand step and the status background tints. Each
428
+ * then bolted a private overlay onto the result to smuggle the lost values into
429
+ * free slots. That overlay is this function, done twice — so it belongs in the
430
+ * token package, where the token shape that lost the values is defined.
431
+ *
432
+ * The emitted theme is a LOSSLESS carrier: every token the shape can express has
433
+ * an addressable slot, so an app can round-trip its whole palette back out
434
+ * (see the `*Colors` accessors in each app) instead of keeping a parallel static
435
+ * copy that cannot follow a dark-mode toggle or a per-tenant brand.
436
+ *
437
+ * The type is declared structurally here rather than imported, exactly as
438
+ * {@link RnThemeConfig} declares the `TenantThemeConfig` shape: this package
439
+ * stays framework-agnostic and takes no dependency on the kit it feeds.
440
+ */
441
+
442
+ /** Flat colour fields the kit reads directly. Mirrors `ui-feedback`'s `FeedbackThemeColors`. */
443
+ interface UiThemeColors {
444
+ background: string;
445
+ surface: string;
446
+ surfaceElevated: string;
447
+ text: string;
448
+ textSecondary: string;
449
+ border: string;
450
+ }
451
+ /** A colour scale. The `500` step is guaranteed; other steps are addressable. */
452
+ interface UiColorScale {
453
+ '500': string;
454
+ [step: string]: string;
455
+ }
456
+ /** Brand scales. `primary` is guaranteed; other names are addressable. */
457
+ interface UiThemePalette {
458
+ primary: UiColorScale;
459
+ [name: string]: UiColorScale;
460
+ }
461
+ /** Status scales. `error` is guaranteed; other names are addressable. */
462
+ interface UiThemeSemantic {
463
+ error: UiColorScale;
464
+ [name: string]: UiColorScale;
465
+ }
466
+ /** The kit theme. Structurally identical to `@dloizides/ui-feedback`'s `UiTheme`. */
467
+ interface UiThemeConfig {
468
+ colors: UiThemeColors;
469
+ palette: UiThemePalette;
470
+ semantic: UiThemeSemantic;
471
+ }
472
+ /** Which mode block ({@link DesignTokens.light} / {@link DesignTokens.dark}) to project. */
473
+ type UiThemeMode = 'light' | 'dark';
474
+ /** The soft/tint step of a scale — status background tints, muted brand fills. */
475
+ declare const UI_TINT_STEP = "100";
476
+ /** The step every shipped kit component reads. */
477
+ declare const UI_MAIN_STEP = "500";
478
+ /** The deep/pressed step of a scale. */
479
+ declare const UI_DEEP_STEP = "700";
480
+ /**
481
+ * Project a token set onto the shared kit's theme shape.
482
+ *
483
+ * Every value is carried into an addressable slot:
484
+ * - `palette.primary` / `secondary` / `accent` — the brand scales.
485
+ * - `palette.onBrand` — {@link DesignTokens.onBrand}, the primary's contrast partner.
486
+ * - `palette.surfaceMuted` — the mode's {@link ModeColors.surfaceMuted}.
487
+ * - `semantic.*` — each status colour at `500`, its `*Bg` tint at `100`.
488
+ *
489
+ * @param tokens the app's token set
490
+ * @param mode which mode block to project (default `'light'`)
491
+ */
492
+ declare function toUiTheme(tokens: DesignTokens, mode?: UiThemeMode): UiThemeConfig;
493
+
367
494
  /**
368
495
  * PROOViD AML console (Stack A — vanilla JS) tokens.
369
496
  *
@@ -479,4 +606,4 @@ declare function contrastRatio(foreground: string, background: string): number;
479
606
  /** True when `foreground` on `background` meets `requiredRatio`. */
480
607
  declare function meetsContrast(foreground: string, background: string, requiredRatio: number): boolean;
481
608
 
482
- export { AA_LARGE_TEXT_RATIO, AA_NON_TEXT_RATIO, AA_NORMAL_TEXT_RATIO, 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, contrastRatio, isHexColor, meetsContrast, relativeLuminance, toCssVars, toRnTheme, toTailwindPreset };
609
+ export { AA_LARGE_TEXT_RATIO, AA_NON_TEXT_RATIO, AA_NORMAL_TEXT_RATIO, 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, UI_DEEP_STEP, UI_MAIN_STEP, UI_TINT_STEP, type UiColorScale, type UiThemeColors, type UiThemeConfig, type UiThemeMode, type UiThemePalette, type UiThemeSemantic, type VerdictColors, type WorkspaceExtras, contrastRatio, isHexColor, meetsContrast, relativeLuminance, toCssVars, toRnTheme, toTailwindPreset, toUiTheme };