@dloizides/design-tokens 1.3.0 → 1.5.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,149 +1,243 @@
1
- # Changelog
2
-
3
- All notable changes to `@dloizides/design-tokens` are documented here.
4
-
5
- ## [1.3.0]
6
-
7
- ### Added
8
-
9
- - **`DIGITALKIN_TOKENS`** — the Digital Kin brand preset (green `#007E4A`, yellow `#FFAB00`,
10
- Geologica as the sole text family). Registered in `PRESETS` under `digitalkin` and
11
- re-exported from the package root.
12
-
13
- Purely additive: the other 20 exports are byte-identical to 1.2.0, and all four emitters
14
- produce identical output for `aml` / `erevna` / `katalogos`. `PRESETS` gains one key and
15
- loses none. Verified by diffing this build against the published 1.2.0 tarball.
16
-
17
- ### Notes
18
-
19
- - The Digital Kin accent (`#FFAB00`) is a HIGHLIGHT colour: white on it measures **1.90:1**,
20
- so it carries stars, focus rings and ornaments with dark ink on top (**9.81:1**) — never a
21
- white-on-yellow button. Both halves are asserted by `digitalkin.test.ts`.
22
- - DynaPuff is deliberately absent from the token set. It has **no Greek glyphs**, and browser
23
- font fallback is per-glyph, so a mixed Greek/Latin heading would render in two typefaces at
24
- once. It lives only inside the wordmark SVG as vector paths.
25
- - Unlike the other three presets, `digitalkin`'s **borders meet WCAG 1.4.11** (3.34:1 light,
26
- 3.40:1 dark) rather than inheriting the registered `*.border` gaps. Those gaps are frozen
27
- current values of live portals; this preset ships before it has pixels to regress, so it
28
- takes the compliant value.
29
- - One registered gap: **`digitalkin.dark.semantic.error`** (2.28:1). `semantic.error` is a
30
- single token rendered as text in both modes, and AA on white caps its luminance at 0.183
31
- while AA on the raised dark surface demands ≥0.267 — mutually exclusive. Fixing it needs a
32
- mode-aware split of `SemanticColors` affecting all four presets, not a colour nudge.
33
-
34
- ## [1.2.0]
35
-
36
- ### Added
37
-
38
- `DesignTokens` was a **lossy carrier**. Two RN-web apps (ichnos, kefi) discovered this
39
- independently and wrote the *same* private workaround: the shape had no slot for the muted
40
- inset surface, the on-brand foreground, or the three status background tints, so each app
41
- smuggled those five values into free slots of the broadcast theme via a hand-rolled overlay.
42
- Two independent uses of one workaround is the trigger to extract it. These are now
43
- first-class slots, and the overlay is a shipped emitter.
44
-
45
- - **`ModeColors.surfaceMuted?`** — the subtle inset surface (table header rows, chips, wells).
46
- Distinct from `surface` (cards) and `surfaceElevated` (modals): it recedes rather than lifts.
47
- - **`DesignTokens.onBrand?`** — the foreground for content sitting ON a `primary`-filled
48
- surface. It is a *contrast partner* of `primary`, not a mode colour, so it lives beside it.
49
- - **`SemanticColors.successBg?` / `warningBg?` / `errorBg?` / `infoBg?`** — the soft fill a
50
- status badge, banner or row-highlight paints behind text of the base colour. A tint is NOT
51
- derivable from its base (it is hand-picked for contrast), so it needs its own slot; without
52
- one a status surface could not be themed at all.
53
- - **`toUiTheme(tokens, mode?)`** — a fourth emitter: the shared RN UI kit's `UiTheme` (what
54
- `@dloizides/ui-feedback`'s `UiProvider` broadcasts). It is **lossless** — every token the
55
- shape can express lands in an addressable slot (`palette.onBrand`, `palette.surfaceMuted`,
56
- each status tint at the `100` step), so an app can round-trip its entire palette back out
57
- of the live provider instead of keeping a parallel static copy that can never follow a
58
- dark-mode toggle or a per-tenant brand. The theme type is declared **structurally** here,
59
- exactly as `RnThemeConfig` declares the `TenantThemeConfig` shape, so the package keeps its
60
- zero-dependency / zero-peer guarantee and takes no dependency on the kit it feeds.
61
- - **`UI_TINT_STEP` / `UI_MAIN_STEP` / `UI_DEEP_STEP`** — the step names, exported so a consumer
62
- addresses a scale by name rather than by a magic `'500'`.
63
- - CSS-variable names (`--on-brand`, `--surface-muted`, `--success-bg`, …) and Tailwind colour
64
- keys (`on-brand`, `surface-muted`, `success-bg`, …) for the new tokens.
65
-
66
- ### Fixed
67
-
68
- - **Scale collapse.** The naive `value => ({ '100': v, '500': v, '700': v })` projection that
69
- both apps used writes ONE value into every step, silently discarding the deeper brand step
70
- and every status tint — a theme built that way cannot reproduce the palette it came from.
71
- `toUiTheme` emits `secondary` as its own scale and each status tint at the `100` step, so
72
- the values survive. The package's own emitters (`toCssVars`, `toRnTheme`,
73
- `toTailwindPreset`) were checked and carry no equivalent collapse.
74
-
75
- ### Compatibility
76
-
77
- Entirely additive. Every new token is optional and every new emitted key appears **only** when
78
- a preset declares the token, so `AML_TOKENS`, `EREVNA_TOKENS` and `KATALOGOS_TOKENS` emit
79
- byte-identical CSS, RN-theme and Tailwind output — verified by the pre-existing emitter test
80
- suites passing unmodified.
81
-
82
- ## [1.1.0]
83
-
84
- ### Fixed
85
-
86
- - **WCAG AA contrast (UX-11)**: `light.textSecondary` in `EREVNA_TOKENS` and `KATALOGOS_TOKENS`
87
- was `#777777`, which measures **4.48:1 on `#ffffff` and 4.18:1 on the `#f7f7f7` card surface** —
88
- both under the AA 4.5:1 floor for normal text, and form-field labels render in this colour.
89
- Now `#717171` (**4.88:1** and **4.56:1** against those same two surfaces, verified against each
90
- preset's ACTUAL surfaces rather than assumed from another package's).
91
- `AML_TOKENS` was already compliant (`#4a5567`, worst case 6.97:1) and is unchanged.
92
-
93
- This is the same defect `@dloizides/theme-web@1.2.0` fixed in its `DEFAULT_THEME_CONFIG`, but
94
- that fix does NOT reach these presets — apps resolving colours through a preset bypass
95
- theme-web's defaults entirely. The bad value survived here independently.
96
-
97
- ### Added
98
-
99
- - **`src/contrast.ts`** — a correct WCAG 2.1 contrast implementation (sRGB gamma linearization +
100
- ITU-R BT.709 weighting; NOT a naive channel average, which mis-scores exactly the mid-greys that
101
- matter). Deliberately a COPY of theme-web's, not an import: this package ships **zero
102
- dependencies and zero peers** by design, and depending on a React theming package for pure
103
- arithmetic would invert the layering (theme-web already depends on this package).
104
- Exported (`contrastRatio`, `relativeLuminance`, `meetsContrast`, `isHexColor`, and the
105
- `AA_*_RATIO` thresholds) so consumers that let users override tokens at runtime can validate
106
- those overrides with the same maths that guards the shipped presets.
107
- - **`src/contrast.test.ts`** — pins the calculator against external reference pairs
108
- (`#767676`/white = 4.54:1, `#777777`/white = 4.48:1, black/white = 21:1, and `#808080`'s true
109
- luminance of 0.2159 vs a channel-average's 0.502) so the guard cannot silently be wrong.
110
- - **`src/presets/presets.contrast.test.ts`** — a permanent guard measuring every text-role colour
111
- in EVERY preset against every surface it renders on, in BOTH modes. Failures must be registered
112
- in `KNOWN_GAPS` with their exact measured ratio, and the registry is asserted to be exactly
113
- accurate — so a gap cannot be added silently, a stale entry fails once the colour is fixed, and
114
- a newly failing colour nobody registered fails the suite outright. Non-hex token values (AML's
115
- `rgba()` dark border, which has no fixed luminance) are excluded by an asserted explicit list
116
- rather than silently skipped.
117
-
118
- ### Notes
119
-
120
- - Only TEXT and essential-boundary roles are asserted. Decorative fills (`primary`/`secondary`/
121
- `accent`, and the `success`/`warning`/`info` semantic bases) carry no contrast requirement;
122
- asserting them would turn a compliance guard into a brand redesign.
123
- - 8 pre-existing gaps are registered, all one root cause: a single token serving both a text role
124
- and a fill/decorative role across both modes (`border`/`divider`, `semantic.error`). These need
125
- the roles split before any value can move — a design change, not a colour nudge. They mirror the
126
- gaps already registered in `@dloizides/theme-web`.
127
-
128
- ## [1.0.0]
129
-
130
- ### Added
131
-
132
- - Initial release (task #78) — the cross-stack design-token source.
133
- - **Token shape** (`DesignTokens`) whose core fields mirror `@dloizides/tenant-theme-web`'s
134
- `TenantThemeConfig` (`primary`/`secondary`/`accent`/`semantic`/`light`/`dark`/`typography`/
135
- `branding`), plus optional `radii`/`shadows`/`extensions` supersets for richer stacks.
136
- - **Three emitters from one source**: `toCssVars` (CSS custom properties for vanilla-JS),
137
- `toRnTheme` (a `TenantThemeConfig`-compatible object for RN-web), `toTailwindPreset` (a Tailwind
138
- preset for the DOM-React ThemeStudio).
139
- - **Per-app presets** seeded byte-for-byte from current values: `EREVNA_TOKENS`,
140
- `KATALOGOS_TOKENS` (from each RN app's `default` theme preset), and `AML_TOKENS` (from the AML
141
- console's `wwwroot/shared/ui.css` `:root`). Plus the `PRESETS` map.
142
- - **The cross-stack naming contract (#78b)**: `DEFAULT_CSS_VAR_NAMES` (canonical kebab names) and
143
- `AML_CSS_VAR_NAMES` (the AML console's existing `ui.css` variable names), documented in the
144
- README with the full name-mapping table and the open naming decisions.
145
- - Behaviour-preserving by design: runtime tests assert `toRnTheme(EREVNA_TOKENS)` deep-equals the
146
- app's current `DEFAULT_THEME_CONFIG` and `toCssVars(AML_TOKENS, AML_CSS_VAR_NAMES)` reproduces
147
- `ui.css`'s `:root` verbatim. Zero visual change on adoption.
148
- - Values only — no components (those live in `@dloizides/ui-layout`/`ui-forms`/`ui-feedback`/
149
- `ui-icons`/`ui-tables`). Zero runtime dependencies.
1
+ # Changelog
2
+
3
+ ## 1.5.0
4
+
5
+ **FINREG per-module brand colours (task R-01) — additive, non-breaking.**
6
+
7
+ FINREG's interim EDA logo binds a colour to each of its three product modules, so colour is module
8
+ identity, not one app's brand primary. Adds `FINREG_MODULE_COLORS` beside the per-app presets. No
9
+ existing token, preset, emitter or type is touched, so every current consumer is byte-identical.
10
+
11
+ ### New
12
+
13
+ - `FINREG_MODULE_COLORS` — the three decided EDA module colours, each with an AA-safe on-white
14
+ companion:
15
+ - Payments (cyan): `base #4FD8F0` (1.69:1 on white, fill only) / `onWhite #0C7D91` (4.82:1).
16
+ - Accounting (magenta): `base #E85FBF` (3.08:1) / `onWhite #D11E9B` (4.81:1).
17
+ - CRM (violet): `base #7B8FF7` (2.95:1) / `onWhite #4763F4` (4.82:1).
18
+ - `FinregModuleColor`, `FinregModuleColors` types.
19
+
20
+ The `base` hexes are transcribed verbatim from the logo decision — this package did not choose
21
+ them. The `onWhite` companions were DERIVED with the `contrast.ts` WCAG maths (lightest shade of
22
+ the same hue that clears the 4.5:1 AA text floor on white, carried a little past the floor), and
23
+ both halves are pinned by `finregModules.test.ts` so a drift below AA fails the build. This is the
24
+ SOURCE of the hexes; a later rebrand wave adopts the token into the apps, which read it rather than
25
+ re-declaring the literal (`no-raw-color-literal`).
26
+
27
+ ## 1.4.0
28
+
29
+ **The on-brand foreground is now DERIVED, not defaulted to white.**
30
+
31
+ This package already shipped the WCAG maths (`contrast.ts`) and an optional `onBrand`
32
+ slot — and a live AA failure shipped anyway: **white on `#38bdf8` at 2.14:1** on a
33
+ production primary button. The slot was optional *with a white default*, so the safe
34
+ path required opting in and the default was the failing one. An optional safety feature
35
+ with an unsafe default is not a safety feature; it is a trap that reads as protection in
36
+ review. The same pair was then hand-patched five separate times across the codebase, one
37
+ of them inside a verification EMAIL where CSS cannot be patched after sending.
38
+
39
+ ### New
40
+
41
+ - `resolveOnBrand(background, explicit?)` — returns the higher-contrast of a light ink
42
+ (`#ffffff`) and a dark ink (`#03121f`) for the given brand colour. An explicit value is
43
+ honoured as given; a non-hex background (no fixed luminance) falls back to light ink as
44
+ a documented last resort rather than as the unexamined default for everything.
45
+ - `onBrandRatio(background, explicit?)` — the measured ratio, or `null` when unmeasurable.
46
+ Returns the NUMBER, so a consumer can assert the pair instead of assuming it.
47
+ - `canCarryAccessibleInk(background)` — false for a mid-luminance fill that fails against
48
+ BOTH inks. Distinguishes "we picked the wrong ink" from "no ink works" — different bugs
49
+ with different owners.
50
+ - `ON_BRAND_LIGHT_INK`, `ON_BRAND_DARK_INK`.
51
+
52
+ Exported from the package root so a consumer that accepts a brand colour at RUNTIME (a
53
+ per-tenant branding endpoint) derives its foreground with the same maths that guards the
54
+ shipped presets. The runtime path is how an AA failure re-enters a codebase whose static
55
+ presets all pass.
56
+
57
+ ### Changed (behaviour)
58
+
59
+ All three emitters now derive the on-brand ink instead of skipping or whitening it:
60
+
61
+ - `toUiTheme` — `palette.onBrand` was `tokens.onBrand ?? '#ffffff'`, now
62
+ `resolveOnBrand(tokens.primary, tokens.onBrand)`.
63
+ - `toCssVars` — `--on-brand` was emitted only when the preset declared `onBrand`. It is
64
+ now always emitted (when the name map asks for it): a MISSING custom property sends the
65
+ stylesheet to its own hardcoded fallback, which is how white-on-pale-brand shipped.
66
+ - `toTailwindPreset` — `colors['on-brand']` is likewise always emitted, and its type
67
+ changed from `string | undefined` to `string`.
68
+
69
+ **No shipped preset's emitted value changes.** All four presets have a `primary` that
70
+ white genuinely wins on (aml `#4f46e5` 6.29:1, erevna/katalogos `#005f73` 7.28:1,
71
+ digitalkin `#007E4A` 5.14:1 explicit), so the derivation returns exactly what they emitted
72
+ before. The change is visible only to a consumer with a PALE brand — which is the defect.
73
+
74
+ `onBrand` remains OPTIONAL. Making it required would be a compile break for every consumer
75
+ on a published, adopted interface, and it would push the decision back onto exactly the
76
+ caller who already got it wrong five times. Derivation fixes the DEFAULT, which is where
77
+ the defect actually lives.
78
+
79
+ ### Guards
80
+
81
+ - `presets.contrast.test.ts` now asserts every preset's `primary`/derived-ink pair clears
82
+ 4.5:1, MEASURES any explicit `onBrand` rather than trusting it, and records on the
83
+ record which brand fills can carry no accessible ink at all.
84
+ - `toCssVars` / `toTailwindPreset` had **zero** `onBrand` coverage — they emitted it
85
+ blind. Both now assert the derived value, including the pale-brand case.
86
+ - 144 tests (was 140 + 4 new files/cases; `onBrand.test.ts` pins every ratio as a measured
87
+ number so a change to the derivation cannot quietly re-tune what "accessible" means).
88
+
89
+ ### Known finding (not fixed here)
90
+
91
+ `accent: #008d5c` (erevna, katalogos) peaks at **4.47:1** against its best ink and can
92
+ carry NO AA foreground. Nothing in the fleet paints text on an accent fill today — it is
93
+ read as a text *colour*, never a text-bearing fill — so this is recorded and asserted as a
94
+ known state rather than silently fixed by redesigning two live portals' brand green. It
95
+ becomes a real failure the moment anything paints text on that fill.
96
+
97
+ All notable changes to `@dloizides/design-tokens` are documented here.
98
+
99
+ ## [1.3.0]
100
+
101
+ ### Added
102
+
103
+ - **`DIGITALKIN_TOKENS`** — the Digital Kin brand preset (green `#007E4A`, yellow `#FFAB00`,
104
+ Geologica as the sole text family). Registered in `PRESETS` under `digitalkin` and
105
+ re-exported from the package root.
106
+
107
+ Purely additive: the other 20 exports are byte-identical to 1.2.0, and all four emitters
108
+ produce identical output for `aml` / `erevna` / `katalogos`. `PRESETS` gains one key and
109
+ loses none. Verified by diffing this build against the published 1.2.0 tarball.
110
+
111
+ ### Notes
112
+
113
+ - The Digital Kin accent (`#FFAB00`) is a HIGHLIGHT colour: white on it measures **1.90:1**,
114
+ so it carries stars, focus rings and ornaments with dark ink on top (**9.81:1**) — never a
115
+ white-on-yellow button. Both halves are asserted by `digitalkin.test.ts`.
116
+ - DynaPuff is deliberately absent from the token set. It has **no Greek glyphs**, and browser
117
+ font fallback is per-glyph, so a mixed Greek/Latin heading would render in two typefaces at
118
+ once. It lives only inside the wordmark SVG as vector paths.
119
+ - Unlike the other three presets, `digitalkin`'s **borders meet WCAG 1.4.11** (3.34:1 light,
120
+ 3.40:1 dark) rather than inheriting the registered `*.border` gaps. Those gaps are frozen
121
+ current values of live portals; this preset ships before it has pixels to regress, so it
122
+ takes the compliant value.
123
+ - One registered gap: **`digitalkin.dark.semantic.error`** (2.28:1). `semantic.error` is a
124
+ single token rendered as text in both modes, and AA on white caps its luminance at 0.183
125
+ while AA on the raised dark surface demands ≥0.267 — mutually exclusive. Fixing it needs a
126
+ mode-aware split of `SemanticColors` affecting all four presets, not a colour nudge.
127
+
128
+ ## [1.2.0]
129
+
130
+ ### Added
131
+
132
+ `DesignTokens` was a **lossy carrier**. Two RN-web apps (ichnos, kefi) discovered this
133
+ independently and wrote the *same* private workaround: the shape had no slot for the muted
134
+ inset surface, the on-brand foreground, or the three status background tints, so each app
135
+ smuggled those five values into free slots of the broadcast theme via a hand-rolled overlay.
136
+ Two independent uses of one workaround is the trigger to extract it. These are now
137
+ first-class slots, and the overlay is a shipped emitter.
138
+
139
+ - **`ModeColors.surfaceMuted?`** — the subtle inset surface (table header rows, chips, wells).
140
+ Distinct from `surface` (cards) and `surfaceElevated` (modals): it recedes rather than lifts.
141
+ - **`DesignTokens.onBrand?`** — the foreground for content sitting ON a `primary`-filled
142
+ surface. It is a *contrast partner* of `primary`, not a mode colour, so it lives beside it.
143
+ - **`SemanticColors.successBg?` / `warningBg?` / `errorBg?` / `infoBg?`** — the soft fill a
144
+ status badge, banner or row-highlight paints behind text of the base colour. A tint is NOT
145
+ derivable from its base (it is hand-picked for contrast), so it needs its own slot; without
146
+ one a status surface could not be themed at all.
147
+ - **`toUiTheme(tokens, mode?)`** — a fourth emitter: the shared RN UI kit's `UiTheme` (what
148
+ `@dloizides/ui-feedback`'s `UiProvider` broadcasts). It is **lossless** — every token the
149
+ shape can express lands in an addressable slot (`palette.onBrand`, `palette.surfaceMuted`,
150
+ each status tint at the `100` step), so an app can round-trip its entire palette back out
151
+ of the live provider instead of keeping a parallel static copy that can never follow a
152
+ dark-mode toggle or a per-tenant brand. The theme type is declared **structurally** here,
153
+ exactly as `RnThemeConfig` declares the `TenantThemeConfig` shape, so the package keeps its
154
+ zero-dependency / zero-peer guarantee and takes no dependency on the kit it feeds.
155
+ - **`UI_TINT_STEP` / `UI_MAIN_STEP` / `UI_DEEP_STEP`** — the step names, exported so a consumer
156
+ addresses a scale by name rather than by a magic `'500'`.
157
+ - CSS-variable names (`--on-brand`, `--surface-muted`, `--success-bg`, …) and Tailwind colour
158
+ keys (`on-brand`, `surface-muted`, `success-bg`, …) for the new tokens.
159
+
160
+ ### Fixed
161
+
162
+ - **Scale collapse.** The naive `value => ({ '100': v, '500': v, '700': v })` projection that
163
+ both apps used writes ONE value into every step, silently discarding the deeper brand step
164
+ and every status tint — a theme built that way cannot reproduce the palette it came from.
165
+ `toUiTheme` emits `secondary` as its own scale and each status tint at the `100` step, so
166
+ the values survive. The package's own emitters (`toCssVars`, `toRnTheme`,
167
+ `toTailwindPreset`) were checked and carry no equivalent collapse.
168
+
169
+ ### Compatibility
170
+
171
+ Entirely additive. Every new token is optional and every new emitted key appears **only** when
172
+ a preset declares the token, so `AML_TOKENS`, `EREVNA_TOKENS` and `KATALOGOS_TOKENS` emit
173
+ byte-identical CSS, RN-theme and Tailwind output — verified by the pre-existing emitter test
174
+ suites passing unmodified.
175
+
176
+ ## [1.1.0]
177
+
178
+ ### Fixed
179
+
180
+ - **WCAG AA contrast (UX-11)**: `light.textSecondary` in `EREVNA_TOKENS` and `KATALOGOS_TOKENS`
181
+ was `#777777`, which measures **4.48:1 on `#ffffff` and 4.18:1 on the `#f7f7f7` card surface** —
182
+ both under the AA 4.5:1 floor for normal text, and form-field labels render in this colour.
183
+ Now `#717171` (**4.88:1** and **4.56:1** against those same two surfaces, verified against each
184
+ preset's ACTUAL surfaces rather than assumed from another package's).
185
+ `AML_TOKENS` was already compliant (`#4a5567`, worst case 6.97:1) and is unchanged.
186
+
187
+ This is the same defect `@dloizides/theme-web@1.2.0` fixed in its `DEFAULT_THEME_CONFIG`, but
188
+ that fix does NOT reach these presets — apps resolving colours through a preset bypass
189
+ theme-web's defaults entirely. The bad value survived here independently.
190
+
191
+ ### Added
192
+
193
+ - **`src/contrast.ts`** — a correct WCAG 2.1 contrast implementation (sRGB gamma linearization +
194
+ ITU-R BT.709 weighting; NOT a naive channel average, which mis-scores exactly the mid-greys that
195
+ matter). Deliberately a COPY of theme-web's, not an import: this package ships **zero
196
+ dependencies and zero peers** by design, and depending on a React theming package for pure
197
+ arithmetic would invert the layering (theme-web already depends on this package).
198
+ Exported (`contrastRatio`, `relativeLuminance`, `meetsContrast`, `isHexColor`, and the
199
+ `AA_*_RATIO` thresholds) so consumers that let users override tokens at runtime can validate
200
+ those overrides with the same maths that guards the shipped presets.
201
+ - **`src/contrast.test.ts`** — pins the calculator against external reference pairs
202
+ (`#767676`/white = 4.54:1, `#777777`/white = 4.48:1, black/white = 21:1, and `#808080`'s true
203
+ luminance of 0.2159 vs a channel-average's 0.502) so the guard cannot silently be wrong.
204
+ - **`src/presets/presets.contrast.test.ts`** — a permanent guard measuring every text-role colour
205
+ in EVERY preset against every surface it renders on, in BOTH modes. Failures must be registered
206
+ in `KNOWN_GAPS` with their exact measured ratio, and the registry is asserted to be exactly
207
+ accurate — so a gap cannot be added silently, a stale entry fails once the colour is fixed, and
208
+ a newly failing colour nobody registered fails the suite outright. Non-hex token values (AML's
209
+ `rgba()` dark border, which has no fixed luminance) are excluded by an asserted explicit list
210
+ rather than silently skipped.
211
+
212
+ ### Notes
213
+
214
+ - Only TEXT and essential-boundary roles are asserted. Decorative fills (`primary`/`secondary`/
215
+ `accent`, and the `success`/`warning`/`info` semantic bases) carry no contrast requirement;
216
+ asserting them would turn a compliance guard into a brand redesign.
217
+ - 8 pre-existing gaps are registered, all one root cause: a single token serving both a text role
218
+ and a fill/decorative role across both modes (`border`/`divider`, `semantic.error`). These need
219
+ the roles split before any value can move — a design change, not a colour nudge. They mirror the
220
+ gaps already registered in `@dloizides/theme-web`.
221
+
222
+ ## [1.0.0]
223
+
224
+ ### Added
225
+
226
+ - Initial release (task #78) — the cross-stack design-token source.
227
+ - **Token shape** (`DesignTokens`) whose core fields mirror `@dloizides/tenant-theme-web`'s
228
+ `TenantThemeConfig` (`primary`/`secondary`/`accent`/`semantic`/`light`/`dark`/`typography`/
229
+ `branding`), plus optional `radii`/`shadows`/`extensions` supersets for richer stacks.
230
+ - **Three emitters from one source**: `toCssVars` (CSS custom properties for vanilla-JS),
231
+ `toRnTheme` (a `TenantThemeConfig`-compatible object for RN-web), `toTailwindPreset` (a Tailwind
232
+ preset for the DOM-React ThemeStudio).
233
+ - **Per-app presets** seeded byte-for-byte from current values: `EREVNA_TOKENS`,
234
+ `KATALOGOS_TOKENS` (from each RN app's `default` theme preset), and `AML_TOKENS` (from the AML
235
+ console's `wwwroot/shared/ui.css` `:root`). Plus the `PRESETS` map.
236
+ - **The cross-stack naming contract (#78b)**: `DEFAULT_CSS_VAR_NAMES` (canonical kebab names) and
237
+ `AML_CSS_VAR_NAMES` (the AML console's existing `ui.css` variable names), documented in the
238
+ README with the full name-mapping table and the open naming decisions.
239
+ - Behaviour-preserving by design: runtime tests assert `toRnTheme(EREVNA_TOKENS)` deep-equals the
240
+ app's current `DEFAULT_THEME_CONFIG` and `toCssVars(AML_TOKENS, AML_CSS_VAR_NAMES)` reproduces
241
+ `ui.css`'s `:root` verbatim. Zero visual change on adoption.
242
+ - Values only — no components (those live in `@dloizides/ui-layout`/`ui-forms`/`ui-feedback`/
243
+ `ui-icons`/`ui-tables`). Zero runtime dependencies.
package/README.md CHANGED
@@ -81,6 +81,27 @@ centralized tokens for those today, so they are omitted (nothing to emit → zer
81
81
  preset carries the richer superset (dark app-shell, ink scale, verdict palette, radii, shadows,
82
82
  fonts) in its `extensions` group.
83
83
 
84
+ ## FINREG module colours (`FINREG_MODULE_COLORS`, 1.5.0)
85
+
86
+ FINREG is a multi-module product (Payments / Accounting / CRM). Its interim **EDA** logo binds a
87
+ colour to each module — the three orbits *are* the three modules — so colour reads as module
88
+ identity rather than as one app's brand `primary`. Those tokens therefore sit **beside** the
89
+ per-app presets, not inside one:
90
+
91
+ | Module | `base` (fill) | on white | `onWhite` (AA text/icon) | on white |
92
+ |--------|---------------|----------|--------------------------|----------|
93
+ | Payments (cyan) | `#4FD8F0` | 1.69:1 ✗ | `#0C7D91` | 4.82:1 ✓ |
94
+ | Accounting (magenta) | `#E85FBF` | 3.08:1 ✗ | `#D11E9B` | 4.81:1 ✓ |
95
+ | CRM (violet) | `#7B8FF7` | 2.95:1 ✗ | `#4763F4` | 4.82:1 ✓ |
96
+
97
+ The `base` hexes are a **decided** design input (the logo), transcribed verbatim. They are light
98
+ fills — none clears the WCAG AA 4.5:1 text floor on white — so anything painting a module colour
99
+ as **text or an icon on white** uses `onWhite`, the darkened same-hue companion. The `onWhite`
100
+ values were derived (lightest shade of the hue that still clears AA, carried a little past the
101
+ floor) and both halves are pinned by `finregModules.test.ts` with their measured ratios, so a
102
+ drift below AA fails the build. This is the SOURCE of these hexes — consumers read the token, they
103
+ do not re-declare the literal (`no-raw-color-literal`).
104
+
84
105
  ## The token shape (aligned to `TenantThemeConfig`)
85
106
 
86
107
  The **core** fields intentionally mirror `@dloizides/tenant-theme-web`'s `TenantThemeConfig`