@dloizides/design-tokens 1.2.0 → 1.4.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
@@ -1,120 +1,219 @@
1
- # Changelog
2
-
3
- All notable changes to `@dloizides/design-tokens` are documented here.
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
-
53
- ## [1.1.0]
54
-
55
- ### Fixed
56
-
57
- - **WCAG AA contrast (UX-11)**: `light.textSecondary` in `EREVNA_TOKENS` and `KATALOGOS_TOKENS`
58
- was `#777777`, which measures **4.48:1 on `#ffffff` and 4.18:1 on the `#f7f7f7` card surface** —
59
- both under the AA 4.5:1 floor for normal text, and form-field labels render in this colour.
60
- Now `#717171` (**4.88:1** and **4.56:1** against those same two surfaces, verified against each
61
- preset's ACTUAL surfaces rather than assumed from another package's).
62
- `AML_TOKENS` was already compliant (`#4a5567`, worst case 6.97:1) and is unchanged.
63
-
64
- This is the same defect `@dloizides/theme-web@1.2.0` fixed in its `DEFAULT_THEME_CONFIG`, but
65
- that fix does NOT reach these presets — apps resolving colours through a preset bypass
66
- theme-web's defaults entirely. The bad value survived here independently.
67
-
68
- ### Added
69
-
70
- - **`src/contrast.ts`** — a correct WCAG 2.1 contrast implementation (sRGB gamma linearization +
71
- ITU-R BT.709 weighting; NOT a naive channel average, which mis-scores exactly the mid-greys that
72
- matter). Deliberately a COPY of theme-web's, not an import: this package ships **zero
73
- dependencies and zero peers** by design, and depending on a React theming package for pure
74
- arithmetic would invert the layering (theme-web already depends on this package).
75
- Exported (`contrastRatio`, `relativeLuminance`, `meetsContrast`, `isHexColor`, and the
76
- `AA_*_RATIO` thresholds) so consumers that let users override tokens at runtime can validate
77
- those overrides with the same maths that guards the shipped presets.
78
- - **`src/contrast.test.ts`** — pins the calculator against external reference pairs
79
- (`#767676`/white = 4.54:1, `#777777`/white = 4.48:1, black/white = 21:1, and `#808080`'s true
80
- luminance of 0.2159 vs a channel-average's 0.502) so the guard cannot silently be wrong.
81
- - **`src/presets/presets.contrast.test.ts`** — a permanent guard measuring every text-role colour
82
- in EVERY preset against every surface it renders on, in BOTH modes. Failures must be registered
83
- in `KNOWN_GAPS` with their exact measured ratio, and the registry is asserted to be exactly
84
- accurate — so a gap cannot be added silently, a stale entry fails once the colour is fixed, and
85
- a newly failing colour nobody registered fails the suite outright. Non-hex token values (AML's
86
- `rgba()` dark border, which has no fixed luminance) are excluded by an asserted explicit list
87
- rather than silently skipped.
88
-
89
- ### Notes
90
-
91
- - Only TEXT and essential-boundary roles are asserted. Decorative fills (`primary`/`secondary`/
92
- `accent`, and the `success`/`warning`/`info` semantic bases) carry no contrast requirement;
93
- asserting them would turn a compliance guard into a brand redesign.
94
- - 8 pre-existing gaps are registered, all one root cause: a single token serving both a text role
95
- and a fill/decorative role across both modes (`border`/`divider`, `semantic.error`). These need
96
- the roles split before any value can move — a design change, not a colour nudge. They mirror the
97
- gaps already registered in `@dloizides/theme-web`.
98
-
99
- ## [1.0.0]
100
-
101
- ### Added
102
-
103
- - Initial release (task #78) — the cross-stack design-token source.
104
- - **Token shape** (`DesignTokens`) whose core fields mirror `@dloizides/tenant-theme-web`'s
105
- `TenantThemeConfig` (`primary`/`secondary`/`accent`/`semantic`/`light`/`dark`/`typography`/
106
- `branding`), plus optional `radii`/`shadows`/`extensions` supersets for richer stacks.
107
- - **Three emitters from one source**: `toCssVars` (CSS custom properties for vanilla-JS),
108
- `toRnTheme` (a `TenantThemeConfig`-compatible object for RN-web), `toTailwindPreset` (a Tailwind
109
- preset for the DOM-React ThemeStudio).
110
- - **Per-app presets** seeded byte-for-byte from current values: `EREVNA_TOKENS`,
111
- `KATALOGOS_TOKENS` (from each RN app's `default` theme preset), and `AML_TOKENS` (from the AML
112
- console's `wwwroot/shared/ui.css` `:root`). Plus the `PRESETS` map.
113
- - **The cross-stack naming contract (#78b)**: `DEFAULT_CSS_VAR_NAMES` (canonical kebab names) and
114
- `AML_CSS_VAR_NAMES` (the AML console's existing `ui.css` variable names), documented in the
115
- README with the full name-mapping table and the open naming decisions.
116
- - Behaviour-preserving by design: runtime tests assert `toRnTheme(EREVNA_TOKENS)` deep-equals the
117
- app's current `DEFAULT_THEME_CONFIG` and `toCssVars(AML_TOKENS, AML_CSS_VAR_NAMES)` reproduces
118
- `ui.css`'s `:root` verbatim. Zero visual change on adoption.
119
- - Values only — no components (those live in `@dloizides/ui-layout`/`ui-forms`/`ui-feedback`/
120
- `ui-icons`/`ui-tables`). Zero runtime dependencies.
1
+ # Changelog
2
+
3
+ ## 1.4.0
4
+
5
+ **The on-brand foreground is now DERIVED, not defaulted to white.**
6
+
7
+ This package already shipped the WCAG maths (`contrast.ts`) and an optional `onBrand`
8
+ slot — and a live AA failure shipped anyway: **white on `#38bdf8` at 2.14:1** on a
9
+ production primary button. The slot was optional *with a white default*, so the safe
10
+ path required opting in and the default was the failing one. An optional safety feature
11
+ with an unsafe default is not a safety feature; it is a trap that reads as protection in
12
+ review. The same pair was then hand-patched five separate times across the codebase, one
13
+ of them inside a verification EMAIL where CSS cannot be patched after sending.
14
+
15
+ ### New
16
+
17
+ - `resolveOnBrand(background, explicit?)` — returns the higher-contrast of a light ink
18
+ (`#ffffff`) and a dark ink (`#03121f`) for the given brand colour. An explicit value is
19
+ honoured as given; a non-hex background (no fixed luminance) falls back to light ink as
20
+ a documented last resort rather than as the unexamined default for everything.
21
+ - `onBrandRatio(background, explicit?)` — the measured ratio, or `null` when unmeasurable.
22
+ Returns the NUMBER, so a consumer can assert the pair instead of assuming it.
23
+ - `canCarryAccessibleInk(background)` — false for a mid-luminance fill that fails against
24
+ BOTH inks. Distinguishes "we picked the wrong ink" from "no ink works" — different bugs
25
+ with different owners.
26
+ - `ON_BRAND_LIGHT_INK`, `ON_BRAND_DARK_INK`.
27
+
28
+ Exported from the package root so a consumer that accepts a brand colour at RUNTIME (a
29
+ per-tenant branding endpoint) derives its foreground with the same maths that guards the
30
+ shipped presets. The runtime path is how an AA failure re-enters a codebase whose static
31
+ presets all pass.
32
+
33
+ ### Changed (behaviour)
34
+
35
+ All three emitters now derive the on-brand ink instead of skipping or whitening it:
36
+
37
+ - `toUiTheme` — `palette.onBrand` was `tokens.onBrand ?? '#ffffff'`, now
38
+ `resolveOnBrand(tokens.primary, tokens.onBrand)`.
39
+ - `toCssVars` — `--on-brand` was emitted only when the preset declared `onBrand`. It is
40
+ now always emitted (when the name map asks for it): a MISSING custom property sends the
41
+ stylesheet to its own hardcoded fallback, which is how white-on-pale-brand shipped.
42
+ - `toTailwindPreset` — `colors['on-brand']` is likewise always emitted, and its type
43
+ changed from `string | undefined` to `string`.
44
+
45
+ **No shipped preset's emitted value changes.** All four presets have a `primary` that
46
+ white genuinely wins on (aml `#4f46e5` 6.29:1, erevna/katalogos `#005f73` 7.28:1,
47
+ digitalkin `#007E4A` 5.14:1 explicit), so the derivation returns exactly what they emitted
48
+ before. The change is visible only to a consumer with a PALE brand — which is the defect.
49
+
50
+ `onBrand` remains OPTIONAL. Making it required would be a compile break for every consumer
51
+ on a published, adopted interface, and it would push the decision back onto exactly the
52
+ caller who already got it wrong five times. Derivation fixes the DEFAULT, which is where
53
+ the defect actually lives.
54
+
55
+ ### Guards
56
+
57
+ - `presets.contrast.test.ts` now asserts every preset's `primary`/derived-ink pair clears
58
+ 4.5:1, MEASURES any explicit `onBrand` rather than trusting it, and records on the
59
+ record which brand fills can carry no accessible ink at all.
60
+ - `toCssVars` / `toTailwindPreset` had **zero** `onBrand` coverage — they emitted it
61
+ blind. Both now assert the derived value, including the pale-brand case.
62
+ - 144 tests (was 140 + 4 new files/cases; `onBrand.test.ts` pins every ratio as a measured
63
+ number so a change to the derivation cannot quietly re-tune what "accessible" means).
64
+
65
+ ### Known finding (not fixed here)
66
+
67
+ `accent: #008d5c` (erevna, katalogos) peaks at **4.47:1** against its best ink and can
68
+ carry NO AA foreground. Nothing in the fleet paints text on an accent fill today — it is
69
+ read as a text *colour*, never a text-bearing fill — so this is recorded and asserted as a
70
+ known state rather than silently fixed by redesigning two live portals' brand green. It
71
+ becomes a real failure the moment anything paints text on that fill.
72
+
73
+ All notable changes to `@dloizides/design-tokens` are documented here.
74
+
75
+ ## [1.3.0]
76
+
77
+ ### Added
78
+
79
+ - **`DIGITALKIN_TOKENS`** — the Digital Kin brand preset (green `#007E4A`, yellow `#FFAB00`,
80
+ Geologica as the sole text family). Registered in `PRESETS` under `digitalkin` and
81
+ re-exported from the package root.
82
+
83
+ Purely additive: the other 20 exports are byte-identical to 1.2.0, and all four emitters
84
+ produce identical output for `aml` / `erevna` / `katalogos`. `PRESETS` gains one key and
85
+ loses none. Verified by diffing this build against the published 1.2.0 tarball.
86
+
87
+ ### Notes
88
+
89
+ - The Digital Kin accent (`#FFAB00`) is a HIGHLIGHT colour: white on it measures **1.90:1**,
90
+ so it carries stars, focus rings and ornaments with dark ink on top (**9.81:1**) — never a
91
+ white-on-yellow button. Both halves are asserted by `digitalkin.test.ts`.
92
+ - DynaPuff is deliberately absent from the token set. It has **no Greek glyphs**, and browser
93
+ font fallback is per-glyph, so a mixed Greek/Latin heading would render in two typefaces at
94
+ once. It lives only inside the wordmark SVG as vector paths.
95
+ - Unlike the other three presets, `digitalkin`'s **borders meet WCAG 1.4.11** (3.34:1 light,
96
+ 3.40:1 dark) rather than inheriting the registered `*.border` gaps. Those gaps are frozen
97
+ current values of live portals; this preset ships before it has pixels to regress, so it
98
+ takes the compliant value.
99
+ - One registered gap: **`digitalkin.dark.semantic.error`** (2.28:1). `semantic.error` is a
100
+ single token rendered as text in both modes, and AA on white caps its luminance at 0.183
101
+ while AA on the raised dark surface demands ≥0.267 — mutually exclusive. Fixing it needs a
102
+ mode-aware split of `SemanticColors` affecting all four presets, not a colour nudge.
103
+
104
+ ## [1.2.0]
105
+
106
+ ### Added
107
+
108
+ `DesignTokens` was a **lossy carrier**. Two RN-web apps (ichnos, kefi) discovered this
109
+ independently and wrote the *same* private workaround: the shape had no slot for the muted
110
+ inset surface, the on-brand foreground, or the three status background tints, so each app
111
+ smuggled those five values into free slots of the broadcast theme via a hand-rolled overlay.
112
+ Two independent uses of one workaround is the trigger to extract it. These are now
113
+ first-class slots, and the overlay is a shipped emitter.
114
+
115
+ - **`ModeColors.surfaceMuted?`** — the subtle inset surface (table header rows, chips, wells).
116
+ Distinct from `surface` (cards) and `surfaceElevated` (modals): it recedes rather than lifts.
117
+ - **`DesignTokens.onBrand?`** — the foreground for content sitting ON a `primary`-filled
118
+ surface. It is a *contrast partner* of `primary`, not a mode colour, so it lives beside it.
119
+ - **`SemanticColors.successBg?` / `warningBg?` / `errorBg?` / `infoBg?`** — the soft fill a
120
+ status badge, banner or row-highlight paints behind text of the base colour. A tint is NOT
121
+ derivable from its base (it is hand-picked for contrast), so it needs its own slot; without
122
+ one a status surface could not be themed at all.
123
+ - **`toUiTheme(tokens, mode?)`** — a fourth emitter: the shared RN UI kit's `UiTheme` (what
124
+ `@dloizides/ui-feedback`'s `UiProvider` broadcasts). It is **lossless** — every token the
125
+ shape can express lands in an addressable slot (`palette.onBrand`, `palette.surfaceMuted`,
126
+ each status tint at the `100` step), so an app can round-trip its entire palette back out
127
+ of the live provider instead of keeping a parallel static copy that can never follow a
128
+ dark-mode toggle or a per-tenant brand. The theme type is declared **structurally** here,
129
+ exactly as `RnThemeConfig` declares the `TenantThemeConfig` shape, so the package keeps its
130
+ zero-dependency / zero-peer guarantee and takes no dependency on the kit it feeds.
131
+ - **`UI_TINT_STEP` / `UI_MAIN_STEP` / `UI_DEEP_STEP`** — the step names, exported so a consumer
132
+ addresses a scale by name rather than by a magic `'500'`.
133
+ - CSS-variable names (`--on-brand`, `--surface-muted`, `--success-bg`, …) and Tailwind colour
134
+ keys (`on-brand`, `surface-muted`, `success-bg`, …) for the new tokens.
135
+
136
+ ### Fixed
137
+
138
+ - **Scale collapse.** The naive `value => ({ '100': v, '500': v, '700': v })` projection that
139
+ both apps used writes ONE value into every step, silently discarding the deeper brand step
140
+ and every status tint — a theme built that way cannot reproduce the palette it came from.
141
+ `toUiTheme` emits `secondary` as its own scale and each status tint at the `100` step, so
142
+ the values survive. The package's own emitters (`toCssVars`, `toRnTheme`,
143
+ `toTailwindPreset`) were checked and carry no equivalent collapse.
144
+
145
+ ### Compatibility
146
+
147
+ Entirely additive. Every new token is optional and every new emitted key appears **only** when
148
+ a preset declares the token, so `AML_TOKENS`, `EREVNA_TOKENS` and `KATALOGOS_TOKENS` emit
149
+ byte-identical CSS, RN-theme and Tailwind output — verified by the pre-existing emitter test
150
+ suites passing unmodified.
151
+
152
+ ## [1.1.0]
153
+
154
+ ### Fixed
155
+
156
+ - **WCAG AA contrast (UX-11)**: `light.textSecondary` in `EREVNA_TOKENS` and `KATALOGOS_TOKENS`
157
+ was `#777777`, which measures **4.48:1 on `#ffffff` and 4.18:1 on the `#f7f7f7` card surface** —
158
+ both under the AA 4.5:1 floor for normal text, and form-field labels render in this colour.
159
+ Now `#717171` (**4.88:1** and **4.56:1** against those same two surfaces, verified against each
160
+ preset's ACTUAL surfaces rather than assumed from another package's).
161
+ `AML_TOKENS` was already compliant (`#4a5567`, worst case 6.97:1) and is unchanged.
162
+
163
+ This is the same defect `@dloizides/theme-web@1.2.0` fixed in its `DEFAULT_THEME_CONFIG`, but
164
+ that fix does NOT reach these presets — apps resolving colours through a preset bypass
165
+ theme-web's defaults entirely. The bad value survived here independently.
166
+
167
+ ### Added
168
+
169
+ - **`src/contrast.ts`** — a correct WCAG 2.1 contrast implementation (sRGB gamma linearization +
170
+ ITU-R BT.709 weighting; NOT a naive channel average, which mis-scores exactly the mid-greys that
171
+ matter). Deliberately a COPY of theme-web's, not an import: this package ships **zero
172
+ dependencies and zero peers** by design, and depending on a React theming package for pure
173
+ arithmetic would invert the layering (theme-web already depends on this package).
174
+ Exported (`contrastRatio`, `relativeLuminance`, `meetsContrast`, `isHexColor`, and the
175
+ `AA_*_RATIO` thresholds) so consumers that let users override tokens at runtime can validate
176
+ those overrides with the same maths that guards the shipped presets.
177
+ - **`src/contrast.test.ts`** — pins the calculator against external reference pairs
178
+ (`#767676`/white = 4.54:1, `#777777`/white = 4.48:1, black/white = 21:1, and `#808080`'s true
179
+ luminance of 0.2159 vs a channel-average's 0.502) so the guard cannot silently be wrong.
180
+ - **`src/presets/presets.contrast.test.ts`** — a permanent guard measuring every text-role colour
181
+ in EVERY preset against every surface it renders on, in BOTH modes. Failures must be registered
182
+ in `KNOWN_GAPS` with their exact measured ratio, and the registry is asserted to be exactly
183
+ accurate — so a gap cannot be added silently, a stale entry fails once the colour is fixed, and
184
+ a newly failing colour nobody registered fails the suite outright. Non-hex token values (AML's
185
+ `rgba()` dark border, which has no fixed luminance) are excluded by an asserted explicit list
186
+ rather than silently skipped.
187
+
188
+ ### Notes
189
+
190
+ - Only TEXT and essential-boundary roles are asserted. Decorative fills (`primary`/`secondary`/
191
+ `accent`, and the `success`/`warning`/`info` semantic bases) carry no contrast requirement;
192
+ asserting them would turn a compliance guard into a brand redesign.
193
+ - 8 pre-existing gaps are registered, all one root cause: a single token serving both a text role
194
+ and a fill/decorative role across both modes (`border`/`divider`, `semantic.error`). These need
195
+ the roles split before any value can move — a design change, not a colour nudge. They mirror the
196
+ gaps already registered in `@dloizides/theme-web`.
197
+
198
+ ## [1.0.0]
199
+
200
+ ### Added
201
+
202
+ - Initial release (task #78) — the cross-stack design-token source.
203
+ - **Token shape** (`DesignTokens`) whose core fields mirror `@dloizides/tenant-theme-web`'s
204
+ `TenantThemeConfig` (`primary`/`secondary`/`accent`/`semantic`/`light`/`dark`/`typography`/
205
+ `branding`), plus optional `radii`/`shadows`/`extensions` supersets for richer stacks.
206
+ - **Three emitters from one source**: `toCssVars` (CSS custom properties for vanilla-JS),
207
+ `toRnTheme` (a `TenantThemeConfig`-compatible object for RN-web), `toTailwindPreset` (a Tailwind
208
+ preset for the DOM-React ThemeStudio).
209
+ - **Per-app presets** seeded byte-for-byte from current values: `EREVNA_TOKENS`,
210
+ `KATALOGOS_TOKENS` (from each RN app's `default` theme preset), and `AML_TOKENS` (from the AML
211
+ console's `wwwroot/shared/ui.css` `:root`). Plus the `PRESETS` map.
212
+ - **The cross-stack naming contract (#78b)**: `DEFAULT_CSS_VAR_NAMES` (canonical kebab names) and
213
+ `AML_CSS_VAR_NAMES` (the AML console's existing `ui.css` variable names), documented in the
214
+ README with the full name-mapping table and the open naming decisions.
215
+ - Behaviour-preserving by design: runtime tests assert `toRnTheme(EREVNA_TOKENS)` deep-equals the
216
+ app's current `DEFAULT_THEME_CONFIG` and `toCssVars(AML_TOKENS, AML_CSS_VAR_NAMES)` reproduces
217
+ `ui.css`'s `:root` verbatim. Zero visual change on adoption.
218
+ - Values only — no components (those live in `@dloizides/ui-layout`/`ui-forms`/`ui-feedback`/
219
+ `ui-icons`/`ui-tables`). Zero runtime dependencies.
package/dist/index.d.mts CHANGED
@@ -179,8 +179,18 @@ interface DesignTokens {
179
179
  * Foreground colour for content sitting ON a `primary`-filled surface — a
180
180
  * filled button's label, a brand header's text. It is a *contrast partner* of
181
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.
182
+ * `light`/`dark`.
183
+ *
184
+ * OPTIONAL, AND SAFE TO OMIT. When absent, every emitter DERIVES it from
185
+ * `primary` via `resolveOnBrand` — picking whichever of the light/dark inks
186
+ * scores higher under the WCAG maths in `contrast.ts`. It is no longer
187
+ * defaulted to white: white on a pale brand shipped a 2.14:1 button to
188
+ * production, and "a preset with a pale primary MUST set it explicitly" was
189
+ * exactly the instruction that a preset author cannot be relied on to follow.
190
+ *
191
+ * Set it only to override the derivation with a considered brand ink. An
192
+ * explicit value is honoured as given and MEASURED by the preset contrast
193
+ * guard, so a bad one fails CI rather than shipping.
184
194
  */
185
195
  onBrand?: string;
186
196
  /** Semantic/status colours */
@@ -363,8 +373,12 @@ interface TailwindColors {
363
373
  primary: string;
364
374
  secondary: string;
365
375
  accent: string;
366
- /** Emitted only when the preset declares `onBrand`. */
367
- 'on-brand'?: string;
376
+ /**
377
+ * The primary's contrast partner. ALWAYS emitted — derived from `primary` when
378
+ * the preset declares no `onBrand`, so a consumer's `text-on-brand` utility
379
+ * cannot silently resolve to its own white fallback on a pale brand.
380
+ */
381
+ 'on-brand': string;
368
382
  success: string;
369
383
  warning: string;
370
384
  error: string;
@@ -414,31 +428,6 @@ interface TailwindPreset {
414
428
  */
415
429
  declare function toTailwindPreset(tokens: DesignTokens): TailwindPreset;
416
430
 
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
431
  /** Flat colour fields the kit reads directly. Mirrors `ui-feedback`'s `FeedbackThemeColors`. */
443
432
  interface UiThemeColors {
444
433
  background: string;
@@ -482,7 +471,10 @@ declare const UI_DEEP_STEP = "700";
482
471
  *
483
472
  * Every value is carried into an addressable slot:
484
473
  * - `palette.primary` / `secondary` / `accent` — the brand scales.
485
- * - `palette.onBrand` — {@link DesignTokens.onBrand}, the primary's contrast partner.
474
+ * - `palette.onBrand` — the primary's contrast partner. DERIVED from `primary`
475
+ * via `resolveOnBrand` when the preset declares no {@link DesignTokens.onBrand},
476
+ * so a pale brand gets dark ink instead of the white that used to be the
477
+ * silent default (and which shipped a 2.14:1 button to production).
486
478
  * - `palette.surfaceMuted` — the mode's {@link ModeColors.surfaceMuted}.
487
479
  * - `semantic.*` — each status colour at `500`, its `*Bg` tint at `100`.
488
480
  *
@@ -511,6 +503,62 @@ declare function toUiTheme(tokens: DesignTokens, mode?: UiThemeMode): UiThemeCon
511
503
  */
512
504
  declare const AML_TOKENS: DesignTokens;
513
505
 
506
+ /**
507
+ * Digital Kin (Greek digital-literacy guide site) tokens.
508
+ *
509
+ * Seeded from the Figma `Typography & Colors Style Guide` (design spec §8): green
510
+ * `#007E4A`, yellow `#FFAB00`, black, white. Unlike the aml/erevna/katalogos
511
+ * presets — which were extracted byte-for-byte from an existing running app — this
512
+ * preset is authored from the brand source, because the app does not exist yet.
513
+ * That difference is not cosmetic: those presets must preserve their app's current
514
+ * pixels, so their AA failures are frozen in `KNOWN_GAPS`. This one has no pixels
515
+ * to preserve, so it is held to the floor the guard actually asks for wherever
516
+ * that is arithmetically reachable (see `border` below).
517
+ *
518
+ * THE ACCENT IS A HIGHLIGHT, NOT A BUTTON COLOUR. `#FFAB00` is light: white text
519
+ * on it measures 1.90:1, nowhere near the 4.5:1 AA floor. It carries stars,
520
+ * focus rings, underlines and small ornaments, always with DARK ink on top
521
+ * (`light.text` on it measures 9.81:1). `digitalkin.test.ts` asserts BOTH halves
522
+ * of that, so "just make the CTA yellow" fails the build rather than shipping
523
+ * unreadable.
524
+ *
525
+ * TYPOGRAPHY (spec D21): Geologica ONLY. It covers Greek, Latin, Cyrillic and
526
+ * Vietnamese, and its `CRSV`/`SHRP` variable axes supply the display voice that
527
+ * DynaPuff would otherwise have provided. DynaPuff has NO Greek glyphs at all, and
528
+ * because browser font fallback is per-GLYPH rather than per-element, a heading
529
+ * like "Digital Kin — Ξεκινήστε εδώ" would render the Latin half in DynaPuff and
530
+ * the Greek half in an arbitrary system font, inside one element. It is therefore
531
+ * deliberately absent from this file: it exists only inside `wordmark.svg`, whose
532
+ * text is converted to vector paths and loads no font at all.
533
+ *
534
+ * Three deliberate divergences from the raw Figma palette, all for AA contrast on
535
+ * an audience of older users who are frequently outdoors:
536
+ * * `light.textSecondary` is `#5A5A5A` (6.41:1 on the `#F5F7F5` card, its worst
537
+ * surface) rather than a mid grey. A muted grey that fails AA is the single
538
+ * most common way a "designed" palette becomes unreadable, and this palette's
539
+ * secondary text carries guide intros and difficulty labels.
540
+ * * `border` is darker than a decorative hairline would be — `#7E8A80` (3.34:1
541
+ * on white) and `#6B7D71` (3.40:1 on the raised dark surface) — so it clears
542
+ * WCAG 1.4.11 as an INPUT OUTLINE. The other three presets have their light
543
+ * borders registered as known gaps because darkening a live portal's hairlines
544
+ * is a visual regression; this preset ships before any pixels exist, so it
545
+ * takes the compliant value instead of inheriting the gap. `divider`, which
546
+ * is decorative only and carries no contrast requirement, stays light.
547
+ * * Dark-mode surfaces lift the green rather than reusing `#007E4A` as a
548
+ * background, which would leave no room for readable text above it.
549
+ *
550
+ * ONE REGISTERED GAP — `dark.semantic.error`. `semantic.error` is a SINGLE token
551
+ * rendered as text in BOTH modes, so one hex must clear 4.5:1 against white AND
552
+ * against `#1E2A22`. Those requirements are mutually exclusive: AA on white caps
553
+ * its relative luminance at 0.183, AA on the raised dark surface demands at least
554
+ * 0.267. No colour satisfies both, so this is not a value that was chosen badly —
555
+ * it needs a mode-aware split of the token, which is a shape change to
556
+ * `SemanticColors` affecting all four presets. Registered in
557
+ * `presets.contrast.test.ts` with its measured ratio, exactly like the identical
558
+ * gap in erevna/katalogos/aml.
559
+ */
560
+ declare const DIGITALKIN_TOKENS: DesignTokens;
561
+
514
562
  /**
515
563
  * Erevna (surveys/forms — realm `questioner`) tokens.
516
564
  *
@@ -606,4 +654,58 @@ declare function contrastRatio(foreground: string, background: string): number;
606
654
  /** True when `foreground` on `background` meets `requiredRatio`. */
607
655
  declare function meetsContrast(foreground: string, background: string, requiredRatio: number): boolean;
608
656
 
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 };
657
+ /**
658
+ * Light ink for a dark/saturated brand fill. Also the last-resort value when the
659
+ * brand colour is not a measurable hex (see {@link resolveOnBrand}).
660
+ */
661
+ declare const ON_BRAND_LIGHT_INK = "#ffffff";
662
+ /**
663
+ * Dark ink for a pale brand fill.
664
+ *
665
+ * Not pure black: a near-black navy carries the brand's own hue, so a pale-blue
666
+ * button reads as designed rather than as a default. Measured 8.83:1 on
667
+ * `#38bdf8` and 9.98:1 on `#FFAB00`.
668
+ */
669
+ declare const ON_BRAND_DARK_INK = "#03121f";
670
+ /**
671
+ * The best available foreground for content sitting ON `background`.
672
+ *
673
+ * Resolution order:
674
+ * 1. `explicit` — an author's stated brand ink is honoured as given. It is NOT
675
+ * silently replaced, because overriding a deliberate design decision behind
676
+ * the author's back is its own class of bug; the preset contrast guard
677
+ * measures it instead, so a bad explicit value fails CI rather than shipping.
678
+ * 2. A non-hex `background` (e.g. `rgba()`) has no fixed luminance without
679
+ * knowing what it composites over, so no ratio can be computed. Returns
680
+ * {@link ON_BRAND_LIGHT_INK} as an unavoidable last resort — documented and
681
+ * pinned by a test, rather than being the unexamined default for everything.
682
+ * 3. Otherwise the higher-contrast of the two candidate inks, measured with the
683
+ * WCAG 2.1 maths in `contrast.ts`.
684
+ *
685
+ * Exported from the package root so consumers that let USERS supply a brand
686
+ * colour at runtime (per-tenant branding endpoints) can derive the matching
687
+ * foreground with the same maths that guards the shipped presets — the runtime
688
+ * path is how an AA failure re-enters a codebase whose static presets all pass.
689
+ */
690
+ declare function resolveOnBrand(background: string, explicit?: string): string;
691
+ /**
692
+ * The contrast ratio the derived foreground achieves on `background`, or `null`
693
+ * when `background` is not measurable.
694
+ *
695
+ * Exists so a consumer can ASSERT the pair rather than assume it. Some brand
696
+ * colours cannot carry an AA foreground in either direction — `#008d5c` peaks at
697
+ * 4.47:1 against its best ink — and the only honest answer there is the number,
698
+ * not a boolean that rounds a near-miss up to "compliant".
699
+ */
700
+ declare function onBrandRatio(background: string, explicit?: string): number | null;
701
+ /**
702
+ * True when `background` can carry an AA-passing foreground at all.
703
+ *
704
+ * A brand colour in the mid-luminance band fails against BOTH inks. Such a
705
+ * colour is not fixable by choosing a better foreground — it needs the fill
706
+ * itself to move — so this distinguishes "we picked the wrong ink" from "no ink
707
+ * works", which are different bugs with different owners.
708
+ */
709
+ declare function canCarryAccessibleInk(background: string): boolean;
710
+
711
+ 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, DIGITALKIN_TOKENS, type DesignTokens, EREVNA_TOKENS, type InkScale, KATALOGOS_TOKENS, type ModeColors, ON_BRAND_DARK_INK, ON_BRAND_LIGHT_INK, 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, canCarryAccessibleInk, contrastRatio, isHexColor, meetsContrast, onBrandRatio, relativeLuminance, resolveOnBrand, toCssVars, toRnTheme, toTailwindPreset, toUiTheme };