@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 +243 -149
- package/README.md +21 -0
- package/dist/index.d.mts +142 -31
- package/dist/index.d.ts +142 -31
- package/dist/index.js +121 -67
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +116 -68
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
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`.
|
|
183
|
-
*
|
|
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 */
|
|
@@ -200,6 +210,44 @@ interface DesignTokens {
|
|
|
200
210
|
/** Optional stack-specific token supersets */
|
|
201
211
|
extensions?: TokenExtensions;
|
|
202
212
|
}
|
|
213
|
+
/**
|
|
214
|
+
* One FINREG module's brand colour, in the two forms the brand actually renders.
|
|
215
|
+
*
|
|
216
|
+
* FINREG is a multi-module product (Payments / Accounting / CRM) whose EDA logo
|
|
217
|
+
* binds a colour to each module — the three orbits ARE the three modules. So the
|
|
218
|
+
* colour is not a single app `primary`; it is a per-module identity token that a
|
|
219
|
+
* chip, a nav entry, a badge or a logo orbit paints regardless of which app theme
|
|
220
|
+
* is active. That is why it lives beside the `DesignTokens` presets rather than
|
|
221
|
+
* inside one.
|
|
222
|
+
*
|
|
223
|
+
* The `base` fills are LIGHT by design (a cyan/magenta/violet that reads on the
|
|
224
|
+
* dark logo and on coloured chips). None of them clears the WCAG AA 4.5:1 text
|
|
225
|
+
* floor on white on its own — Payments cyan measures 1.69:1 — so any component
|
|
226
|
+
* that paints a module colour as TEXT or an ICON on a white surface MUST use
|
|
227
|
+
* `onWhite`, the darkened companion. Shipping the light fill as on-white text is
|
|
228
|
+
* exactly the class of AA failure the `onBrand` derivation elsewhere in this
|
|
229
|
+
* package exists to stop; here it is prevented by giving the accessible value its
|
|
230
|
+
* own named slot instead of leaving it to be re-derived (or forgotten) per app.
|
|
231
|
+
*/
|
|
232
|
+
interface FinregModuleColor {
|
|
233
|
+
/** Saturated brand fill (the EDA logo-orbit colour). Not AA as text on white. */
|
|
234
|
+
base: string;
|
|
235
|
+
/** Darkened companion of the same hue that clears WCAG AA (>=4.5:1) as text/icon on white. */
|
|
236
|
+
onWhite: string;
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* The three FINREG product modules, each colour-bound per the EDA logo (task R-01).
|
|
240
|
+
* The base hexes are DECIDED — do not re-tune them; `finregModules.test.ts` pins
|
|
241
|
+
* each base and each on-white ratio so a drift fails the build.
|
|
242
|
+
*/
|
|
243
|
+
interface FinregModuleColors {
|
|
244
|
+
/** Payments — cyan. */
|
|
245
|
+
payments: FinregModuleColor;
|
|
246
|
+
/** Accounting — magenta. */
|
|
247
|
+
accounting: FinregModuleColor;
|
|
248
|
+
/** CRM — violet. */
|
|
249
|
+
crm: FinregModuleColor;
|
|
250
|
+
}
|
|
203
251
|
|
|
204
252
|
/**
|
|
205
253
|
* CSS custom-property NAME MAPS — the cross-stack naming contract.
|
|
@@ -363,8 +411,12 @@ interface TailwindColors {
|
|
|
363
411
|
primary: string;
|
|
364
412
|
secondary: string;
|
|
365
413
|
accent: string;
|
|
366
|
-
/**
|
|
367
|
-
|
|
414
|
+
/**
|
|
415
|
+
* The primary's contrast partner. ALWAYS emitted — derived from `primary` when
|
|
416
|
+
* the preset declares no `onBrand`, so a consumer's `text-on-brand` utility
|
|
417
|
+
* cannot silently resolve to its own white fallback on a pale brand.
|
|
418
|
+
*/
|
|
419
|
+
'on-brand': string;
|
|
368
420
|
success: string;
|
|
369
421
|
warning: string;
|
|
370
422
|
error: string;
|
|
@@ -414,31 +466,6 @@ interface TailwindPreset {
|
|
|
414
466
|
*/
|
|
415
467
|
declare function toTailwindPreset(tokens: DesignTokens): TailwindPreset;
|
|
416
468
|
|
|
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
469
|
/** Flat colour fields the kit reads directly. Mirrors `ui-feedback`'s `FeedbackThemeColors`. */
|
|
443
470
|
interface UiThemeColors {
|
|
444
471
|
background: string;
|
|
@@ -482,7 +509,10 @@ declare const UI_DEEP_STEP = "700";
|
|
|
482
509
|
*
|
|
483
510
|
* Every value is carried into an addressable slot:
|
|
484
511
|
* - `palette.primary` / `secondary` / `accent` — the brand scales.
|
|
485
|
-
* - `palette.onBrand` —
|
|
512
|
+
* - `palette.onBrand` — the primary's contrast partner. DERIVED from `primary`
|
|
513
|
+
* via `resolveOnBrand` when the preset declares no {@link DesignTokens.onBrand},
|
|
514
|
+
* so a pale brand gets dark ink instead of the white that used to be the
|
|
515
|
+
* silent default (and which shipped a 2.14:1 button to production).
|
|
486
516
|
* - `palette.surfaceMuted` — the mode's {@link ModeColors.surfaceMuted}.
|
|
487
517
|
* - `semantic.*` — each status colour at `500`, its `*Bg` tint at `100`.
|
|
488
518
|
*
|
|
@@ -607,6 +637,33 @@ declare const KATALOGOS_TOKENS: DesignTokens;
|
|
|
607
637
|
/** Every shipped app preset keyed by app slug. */
|
|
608
638
|
declare const PRESETS: Readonly<Record<string, DesignTokens>>;
|
|
609
639
|
|
|
640
|
+
/**
|
|
641
|
+
* FINREG module colour tokens (task R-01).
|
|
642
|
+
*
|
|
643
|
+
* FINREG's interim "EDA" logo binds a colour to each of the three product
|
|
644
|
+
* modules — Payments, Accounting, CRM — so colour reads as module identity, not
|
|
645
|
+
* as one app's brand primary. Those three base hexes are a DECIDED design input
|
|
646
|
+
* (`#4FD8F0` / `#E85FBF` / `#7B8FF7`), not something this package chose, so they
|
|
647
|
+
* are transcribed here verbatim and pinned by `finregModules.test.ts`.
|
|
648
|
+
*
|
|
649
|
+
* Each module also carries an `onWhite` companion. The base fills are light — a
|
|
650
|
+
* cyan orbit at 1.69:1 on white cannot be read as text — so a badge, a table
|
|
651
|
+
* cell, a nav label or any icon that paints a module colour on a white surface
|
|
652
|
+
* needs a darkened variant that clears the WCAG AA 4.5:1 floor. The `onWhite`
|
|
653
|
+
* hexes were DERIVED, not eyeballed: each is the lightest shade of the same hue
|
|
654
|
+
* (HSL lightness reduced, hue+saturation held) that still measures at least
|
|
655
|
+
* 4.5:1 on `#FFFFFF` under the WCAG 2.1 maths in `contrast.ts`, then carried a
|
|
656
|
+
* little past the floor so sub-pixel rendering and rounding cannot drop it under.
|
|
657
|
+
* The exact measured ratios are asserted in the test, so a future edit that
|
|
658
|
+
* lightens one below AA fails the build rather than shipping an unreadable label.
|
|
659
|
+
*
|
|
660
|
+
* This is the SOURCE of these hexes. Consuming apps (a later rebrand wave) read
|
|
661
|
+
* `FINREG_MODULE_COLORS`; they must not re-declare the literals, which is the
|
|
662
|
+
* whole point of the `no-raw-color-literal` rule the consumers are bound by.
|
|
663
|
+
*/
|
|
664
|
+
|
|
665
|
+
declare const FINREG_MODULE_COLORS: FinregModuleColors;
|
|
666
|
+
|
|
610
667
|
/**
|
|
611
668
|
* WCAG 2.1 contrast-ratio maths.
|
|
612
669
|
*
|
|
@@ -662,4 +719,58 @@ declare function contrastRatio(foreground: string, background: string): number;
|
|
|
662
719
|
/** True when `foreground` on `background` meets `requiredRatio`. */
|
|
663
720
|
declare function meetsContrast(foreground: string, background: string, requiredRatio: number): boolean;
|
|
664
721
|
|
|
665
|
-
|
|
722
|
+
/**
|
|
723
|
+
* Light ink for a dark/saturated brand fill. Also the last-resort value when the
|
|
724
|
+
* brand colour is not a measurable hex (see {@link resolveOnBrand}).
|
|
725
|
+
*/
|
|
726
|
+
declare const ON_BRAND_LIGHT_INK = "#ffffff";
|
|
727
|
+
/**
|
|
728
|
+
* Dark ink for a pale brand fill.
|
|
729
|
+
*
|
|
730
|
+
* Not pure black: a near-black navy carries the brand's own hue, so a pale-blue
|
|
731
|
+
* button reads as designed rather than as a default. Measured 8.83:1 on
|
|
732
|
+
* `#38bdf8` and 9.98:1 on `#FFAB00`.
|
|
733
|
+
*/
|
|
734
|
+
declare const ON_BRAND_DARK_INK = "#03121f";
|
|
735
|
+
/**
|
|
736
|
+
* The best available foreground for content sitting ON `background`.
|
|
737
|
+
*
|
|
738
|
+
* Resolution order:
|
|
739
|
+
* 1. `explicit` — an author's stated brand ink is honoured as given. It is NOT
|
|
740
|
+
* silently replaced, because overriding a deliberate design decision behind
|
|
741
|
+
* the author's back is its own class of bug; the preset contrast guard
|
|
742
|
+
* measures it instead, so a bad explicit value fails CI rather than shipping.
|
|
743
|
+
* 2. A non-hex `background` (e.g. `rgba()`) has no fixed luminance without
|
|
744
|
+
* knowing what it composites over, so no ratio can be computed. Returns
|
|
745
|
+
* {@link ON_BRAND_LIGHT_INK} as an unavoidable last resort — documented and
|
|
746
|
+
* pinned by a test, rather than being the unexamined default for everything.
|
|
747
|
+
* 3. Otherwise the higher-contrast of the two candidate inks, measured with the
|
|
748
|
+
* WCAG 2.1 maths in `contrast.ts`.
|
|
749
|
+
*
|
|
750
|
+
* Exported from the package root so consumers that let USERS supply a brand
|
|
751
|
+
* colour at runtime (per-tenant branding endpoints) can derive the matching
|
|
752
|
+
* foreground with the same maths that guards the shipped presets — the runtime
|
|
753
|
+
* path is how an AA failure re-enters a codebase whose static presets all pass.
|
|
754
|
+
*/
|
|
755
|
+
declare function resolveOnBrand(background: string, explicit?: string): string;
|
|
756
|
+
/**
|
|
757
|
+
* The contrast ratio the derived foreground achieves on `background`, or `null`
|
|
758
|
+
* when `background` is not measurable.
|
|
759
|
+
*
|
|
760
|
+
* Exists so a consumer can ASSERT the pair rather than assume it. Some brand
|
|
761
|
+
* colours cannot carry an AA foreground in either direction — `#008d5c` peaks at
|
|
762
|
+
* 4.47:1 against its best ink — and the only honest answer there is the number,
|
|
763
|
+
* not a boolean that rounds a near-miss up to "compliant".
|
|
764
|
+
*/
|
|
765
|
+
declare function onBrandRatio(background: string, explicit?: string): number | null;
|
|
766
|
+
/**
|
|
767
|
+
* True when `background` can carry an AA-passing foreground at all.
|
|
768
|
+
*
|
|
769
|
+
* A brand colour in the mid-luminance band fails against BOTH inks. Such a
|
|
770
|
+
* colour is not fixable by choosing a better foreground — it needs the fill
|
|
771
|
+
* itself to move — so this distinguishes "we picked the wrong ink" from "no ink
|
|
772
|
+
* works", which are different bugs with different owners.
|
|
773
|
+
*/
|
|
774
|
+
declare function canCarryAccessibleInk(background: string): boolean;
|
|
775
|
+
|
|
776
|
+
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, FINREG_MODULE_COLORS, type FinregModuleColor, type FinregModuleColors, 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 };
|
package/dist/index.d.ts
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`.
|
|
183
|
-
*
|
|
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 */
|
|
@@ -200,6 +210,44 @@ interface DesignTokens {
|
|
|
200
210
|
/** Optional stack-specific token supersets */
|
|
201
211
|
extensions?: TokenExtensions;
|
|
202
212
|
}
|
|
213
|
+
/**
|
|
214
|
+
* One FINREG module's brand colour, in the two forms the brand actually renders.
|
|
215
|
+
*
|
|
216
|
+
* FINREG is a multi-module product (Payments / Accounting / CRM) whose EDA logo
|
|
217
|
+
* binds a colour to each module — the three orbits ARE the three modules. So the
|
|
218
|
+
* colour is not a single app `primary`; it is a per-module identity token that a
|
|
219
|
+
* chip, a nav entry, a badge or a logo orbit paints regardless of which app theme
|
|
220
|
+
* is active. That is why it lives beside the `DesignTokens` presets rather than
|
|
221
|
+
* inside one.
|
|
222
|
+
*
|
|
223
|
+
* The `base` fills are LIGHT by design (a cyan/magenta/violet that reads on the
|
|
224
|
+
* dark logo and on coloured chips). None of them clears the WCAG AA 4.5:1 text
|
|
225
|
+
* floor on white on its own — Payments cyan measures 1.69:1 — so any component
|
|
226
|
+
* that paints a module colour as TEXT or an ICON on a white surface MUST use
|
|
227
|
+
* `onWhite`, the darkened companion. Shipping the light fill as on-white text is
|
|
228
|
+
* exactly the class of AA failure the `onBrand` derivation elsewhere in this
|
|
229
|
+
* package exists to stop; here it is prevented by giving the accessible value its
|
|
230
|
+
* own named slot instead of leaving it to be re-derived (or forgotten) per app.
|
|
231
|
+
*/
|
|
232
|
+
interface FinregModuleColor {
|
|
233
|
+
/** Saturated brand fill (the EDA logo-orbit colour). Not AA as text on white. */
|
|
234
|
+
base: string;
|
|
235
|
+
/** Darkened companion of the same hue that clears WCAG AA (>=4.5:1) as text/icon on white. */
|
|
236
|
+
onWhite: string;
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* The three FINREG product modules, each colour-bound per the EDA logo (task R-01).
|
|
240
|
+
* The base hexes are DECIDED — do not re-tune them; `finregModules.test.ts` pins
|
|
241
|
+
* each base and each on-white ratio so a drift fails the build.
|
|
242
|
+
*/
|
|
243
|
+
interface FinregModuleColors {
|
|
244
|
+
/** Payments — cyan. */
|
|
245
|
+
payments: FinregModuleColor;
|
|
246
|
+
/** Accounting — magenta. */
|
|
247
|
+
accounting: FinregModuleColor;
|
|
248
|
+
/** CRM — violet. */
|
|
249
|
+
crm: FinregModuleColor;
|
|
250
|
+
}
|
|
203
251
|
|
|
204
252
|
/**
|
|
205
253
|
* CSS custom-property NAME MAPS — the cross-stack naming contract.
|
|
@@ -363,8 +411,12 @@ interface TailwindColors {
|
|
|
363
411
|
primary: string;
|
|
364
412
|
secondary: string;
|
|
365
413
|
accent: string;
|
|
366
|
-
/**
|
|
367
|
-
|
|
414
|
+
/**
|
|
415
|
+
* The primary's contrast partner. ALWAYS emitted — derived from `primary` when
|
|
416
|
+
* the preset declares no `onBrand`, so a consumer's `text-on-brand` utility
|
|
417
|
+
* cannot silently resolve to its own white fallback on a pale brand.
|
|
418
|
+
*/
|
|
419
|
+
'on-brand': string;
|
|
368
420
|
success: string;
|
|
369
421
|
warning: string;
|
|
370
422
|
error: string;
|
|
@@ -414,31 +466,6 @@ interface TailwindPreset {
|
|
|
414
466
|
*/
|
|
415
467
|
declare function toTailwindPreset(tokens: DesignTokens): TailwindPreset;
|
|
416
468
|
|
|
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
469
|
/** Flat colour fields the kit reads directly. Mirrors `ui-feedback`'s `FeedbackThemeColors`. */
|
|
443
470
|
interface UiThemeColors {
|
|
444
471
|
background: string;
|
|
@@ -482,7 +509,10 @@ declare const UI_DEEP_STEP = "700";
|
|
|
482
509
|
*
|
|
483
510
|
* Every value is carried into an addressable slot:
|
|
484
511
|
* - `palette.primary` / `secondary` / `accent` — the brand scales.
|
|
485
|
-
* - `palette.onBrand` —
|
|
512
|
+
* - `palette.onBrand` — the primary's contrast partner. DERIVED from `primary`
|
|
513
|
+
* via `resolveOnBrand` when the preset declares no {@link DesignTokens.onBrand},
|
|
514
|
+
* so a pale brand gets dark ink instead of the white that used to be the
|
|
515
|
+
* silent default (and which shipped a 2.14:1 button to production).
|
|
486
516
|
* - `palette.surfaceMuted` — the mode's {@link ModeColors.surfaceMuted}.
|
|
487
517
|
* - `semantic.*` — each status colour at `500`, its `*Bg` tint at `100`.
|
|
488
518
|
*
|
|
@@ -607,6 +637,33 @@ declare const KATALOGOS_TOKENS: DesignTokens;
|
|
|
607
637
|
/** Every shipped app preset keyed by app slug. */
|
|
608
638
|
declare const PRESETS: Readonly<Record<string, DesignTokens>>;
|
|
609
639
|
|
|
640
|
+
/**
|
|
641
|
+
* FINREG module colour tokens (task R-01).
|
|
642
|
+
*
|
|
643
|
+
* FINREG's interim "EDA" logo binds a colour to each of the three product
|
|
644
|
+
* modules — Payments, Accounting, CRM — so colour reads as module identity, not
|
|
645
|
+
* as one app's brand primary. Those three base hexes are a DECIDED design input
|
|
646
|
+
* (`#4FD8F0` / `#E85FBF` / `#7B8FF7`), not something this package chose, so they
|
|
647
|
+
* are transcribed here verbatim and pinned by `finregModules.test.ts`.
|
|
648
|
+
*
|
|
649
|
+
* Each module also carries an `onWhite` companion. The base fills are light — a
|
|
650
|
+
* cyan orbit at 1.69:1 on white cannot be read as text — so a badge, a table
|
|
651
|
+
* cell, a nav label or any icon that paints a module colour on a white surface
|
|
652
|
+
* needs a darkened variant that clears the WCAG AA 4.5:1 floor. The `onWhite`
|
|
653
|
+
* hexes were DERIVED, not eyeballed: each is the lightest shade of the same hue
|
|
654
|
+
* (HSL lightness reduced, hue+saturation held) that still measures at least
|
|
655
|
+
* 4.5:1 on `#FFFFFF` under the WCAG 2.1 maths in `contrast.ts`, then carried a
|
|
656
|
+
* little past the floor so sub-pixel rendering and rounding cannot drop it under.
|
|
657
|
+
* The exact measured ratios are asserted in the test, so a future edit that
|
|
658
|
+
* lightens one below AA fails the build rather than shipping an unreadable label.
|
|
659
|
+
*
|
|
660
|
+
* This is the SOURCE of these hexes. Consuming apps (a later rebrand wave) read
|
|
661
|
+
* `FINREG_MODULE_COLORS`; they must not re-declare the literals, which is the
|
|
662
|
+
* whole point of the `no-raw-color-literal` rule the consumers are bound by.
|
|
663
|
+
*/
|
|
664
|
+
|
|
665
|
+
declare const FINREG_MODULE_COLORS: FinregModuleColors;
|
|
666
|
+
|
|
610
667
|
/**
|
|
611
668
|
* WCAG 2.1 contrast-ratio maths.
|
|
612
669
|
*
|
|
@@ -662,4 +719,58 @@ declare function contrastRatio(foreground: string, background: string): number;
|
|
|
662
719
|
/** True when `foreground` on `background` meets `requiredRatio`. */
|
|
663
720
|
declare function meetsContrast(foreground: string, background: string, requiredRatio: number): boolean;
|
|
664
721
|
|
|
665
|
-
|
|
722
|
+
/**
|
|
723
|
+
* Light ink for a dark/saturated brand fill. Also the last-resort value when the
|
|
724
|
+
* brand colour is not a measurable hex (see {@link resolveOnBrand}).
|
|
725
|
+
*/
|
|
726
|
+
declare const ON_BRAND_LIGHT_INK = "#ffffff";
|
|
727
|
+
/**
|
|
728
|
+
* Dark ink for a pale brand fill.
|
|
729
|
+
*
|
|
730
|
+
* Not pure black: a near-black navy carries the brand's own hue, so a pale-blue
|
|
731
|
+
* button reads as designed rather than as a default. Measured 8.83:1 on
|
|
732
|
+
* `#38bdf8` and 9.98:1 on `#FFAB00`.
|
|
733
|
+
*/
|
|
734
|
+
declare const ON_BRAND_DARK_INK = "#03121f";
|
|
735
|
+
/**
|
|
736
|
+
* The best available foreground for content sitting ON `background`.
|
|
737
|
+
*
|
|
738
|
+
* Resolution order:
|
|
739
|
+
* 1. `explicit` — an author's stated brand ink is honoured as given. It is NOT
|
|
740
|
+
* silently replaced, because overriding a deliberate design decision behind
|
|
741
|
+
* the author's back is its own class of bug; the preset contrast guard
|
|
742
|
+
* measures it instead, so a bad explicit value fails CI rather than shipping.
|
|
743
|
+
* 2. A non-hex `background` (e.g. `rgba()`) has no fixed luminance without
|
|
744
|
+
* knowing what it composites over, so no ratio can be computed. Returns
|
|
745
|
+
* {@link ON_BRAND_LIGHT_INK} as an unavoidable last resort — documented and
|
|
746
|
+
* pinned by a test, rather than being the unexamined default for everything.
|
|
747
|
+
* 3. Otherwise the higher-contrast of the two candidate inks, measured with the
|
|
748
|
+
* WCAG 2.1 maths in `contrast.ts`.
|
|
749
|
+
*
|
|
750
|
+
* Exported from the package root so consumers that let USERS supply a brand
|
|
751
|
+
* colour at runtime (per-tenant branding endpoints) can derive the matching
|
|
752
|
+
* foreground with the same maths that guards the shipped presets — the runtime
|
|
753
|
+
* path is how an AA failure re-enters a codebase whose static presets all pass.
|
|
754
|
+
*/
|
|
755
|
+
declare function resolveOnBrand(background: string, explicit?: string): string;
|
|
756
|
+
/**
|
|
757
|
+
* The contrast ratio the derived foreground achieves on `background`, or `null`
|
|
758
|
+
* when `background` is not measurable.
|
|
759
|
+
*
|
|
760
|
+
* Exists so a consumer can ASSERT the pair rather than assume it. Some brand
|
|
761
|
+
* colours cannot carry an AA foreground in either direction — `#008d5c` peaks at
|
|
762
|
+
* 4.47:1 against its best ink — and the only honest answer there is the number,
|
|
763
|
+
* not a boolean that rounds a near-miss up to "compliant".
|
|
764
|
+
*/
|
|
765
|
+
declare function onBrandRatio(background: string, explicit?: string): number | null;
|
|
766
|
+
/**
|
|
767
|
+
* True when `background` can carry an AA-passing foreground at all.
|
|
768
|
+
*
|
|
769
|
+
* A brand colour in the mid-luminance band fails against BOTH inks. Such a
|
|
770
|
+
* colour is not fixable by choosing a better foreground — it needs the fill
|
|
771
|
+
* itself to move — so this distinguishes "we picked the wrong ink" from "no ink
|
|
772
|
+
* works", which are different bugs with different owners.
|
|
773
|
+
*/
|
|
774
|
+
declare function canCarryAccessibleInk(background: string): boolean;
|
|
775
|
+
|
|
776
|
+
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, FINREG_MODULE_COLORS, type FinregModuleColor, type FinregModuleColors, 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 };
|