@dloizides/design-tokens 1.3.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/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`. 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
  *
@@ -662,4 +654,58 @@ declare function contrastRatio(foreground: string, background: string): number;
662
654
  /** True when `foreground` on `background` meets `requiredRatio`. */
663
655
  declare function meetsContrast(foreground: string, background: string, requiredRatio: number): boolean;
664
656
 
665
- 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, 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 };
package/dist/index.js CHANGED
@@ -88,6 +88,98 @@ var AML_CSS_VAR_NAMES = {
88
88
  badInk: "--bad-ink"
89
89
  };
90
90
 
91
+ // src/contrast.ts
92
+ var AA_NORMAL_TEXT_RATIO = 4.5;
93
+ var AA_LARGE_TEXT_RATIO = 3;
94
+ var AA_NON_TEXT_RATIO = 3;
95
+ var SRGB_CHANNEL_MAX = 255;
96
+ var GAMMA_LINEAR_THRESHOLD = 0.03928;
97
+ var GAMMA_LINEAR_DIVISOR = 12.92;
98
+ var GAMMA_OFFSET = 0.055;
99
+ var GAMMA_DIVISOR = 1.055;
100
+ var GAMMA_EXPONENT = 2.4;
101
+ var LUMA_COEFFICIENT_RED = 0.2126;
102
+ var LUMA_COEFFICIENT_GREEN = 0.7152;
103
+ var LUMA_COEFFICIENT_BLUE = 0.0722;
104
+ var CONTRAST_FLARE = 0.05;
105
+ var HEX_RADIX = 16;
106
+ var HEX_PAIR_LENGTH = 2;
107
+ var HEX_SHORTHAND_LENGTH = 3;
108
+ var HEX_FULL_LENGTH = 6;
109
+ var CHANNEL_OFFSET_RED = 0;
110
+ var CHANNEL_OFFSET_GREEN = 2;
111
+ var CHANNEL_OFFSET_BLUE = 4;
112
+ function normalizeHexDigits(hex) {
113
+ const clean = hex.trim().replace("#", "").toLowerCase();
114
+ if (clean.length === HEX_SHORTHAND_LENGTH) {
115
+ return `${clean[0] ?? ""}${clean[0] ?? ""}${clean[1] ?? ""}${clean[1] ?? ""}${clean[2] ?? ""}${clean[2] ?? ""}`;
116
+ }
117
+ return clean;
118
+ }
119
+ function parseChannel(digits, offset) {
120
+ const pair = digits.slice(offset, offset + HEX_PAIR_LENGTH);
121
+ return parseInt(pair, HEX_RADIX) / SRGB_CHANNEL_MAX;
122
+ }
123
+ function linearizeChannel(channel) {
124
+ if (channel <= GAMMA_LINEAR_THRESHOLD) {
125
+ return channel / GAMMA_LINEAR_DIVISOR;
126
+ }
127
+ return Math.pow((channel + GAMMA_OFFSET) / GAMMA_DIVISOR, GAMMA_EXPONENT);
128
+ }
129
+ function isHexColor(value) {
130
+ const digits = normalizeHexDigits(value);
131
+ return digits.length === HEX_FULL_LENGTH && /^[0-9a-f]{6}$/.test(digits);
132
+ }
133
+ function relativeLuminance(hex) {
134
+ if (!isHexColor(hex)) {
135
+ throw new Error(`relativeLuminance: not a hex colour: ${hex}`);
136
+ }
137
+ const digits = normalizeHexDigits(hex);
138
+ const red = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_RED));
139
+ const green = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_GREEN));
140
+ const blue = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_BLUE));
141
+ return LUMA_COEFFICIENT_RED * red + LUMA_COEFFICIENT_GREEN * green + LUMA_COEFFICIENT_BLUE * blue;
142
+ }
143
+ function contrastRatio(foreground, background) {
144
+ const first = relativeLuminance(foreground);
145
+ const second = relativeLuminance(background);
146
+ const lighter = Math.max(first, second);
147
+ const darker = Math.min(first, second);
148
+ return (lighter + CONTRAST_FLARE) / (darker + CONTRAST_FLARE);
149
+ }
150
+ function meetsContrast(foreground, background, requiredRatio) {
151
+ return contrastRatio(foreground, background) >= requiredRatio;
152
+ }
153
+
154
+ // src/onBrand.ts
155
+ var ON_BRAND_LIGHT_INK = "#ffffff";
156
+ var ON_BRAND_DARK_INK = "#03121f";
157
+ function resolveOnBrand(background, explicit) {
158
+ if (explicit !== void 0) {
159
+ return explicit;
160
+ }
161
+ if (!isHexColor(background)) {
162
+ return ON_BRAND_LIGHT_INK;
163
+ }
164
+ const lightRatio = contrastRatio(ON_BRAND_LIGHT_INK, background);
165
+ const darkRatio = contrastRatio(ON_BRAND_DARK_INK, background);
166
+ return darkRatio > lightRatio ? ON_BRAND_DARK_INK : ON_BRAND_LIGHT_INK;
167
+ }
168
+ function onBrandRatio(background, explicit) {
169
+ if (!isHexColor(background)) {
170
+ return null;
171
+ }
172
+ const foreground = resolveOnBrand(background, explicit);
173
+ if (!isHexColor(foreground)) {
174
+ return null;
175
+ }
176
+ return contrastRatio(foreground, background);
177
+ }
178
+ function canCarryAccessibleInk(background) {
179
+ const ratio = onBrandRatio(background);
180
+ return ratio !== null && ratio >= AA_NORMAL_TEXT_RATIO;
181
+ }
182
+
91
183
  // src/emit/toCssVars.ts
92
184
  var INDENT = " ";
93
185
  var DEFAULT_DARK_SELECTOR = ':root[data-theme="dark"]';
@@ -111,7 +203,10 @@ function toCssVars(tokens, names, options) {
111
203
  declaration(names.primary, tokens.primary),
112
204
  declaration(names.secondary, tokens.secondary),
113
205
  declaration(names.accent, tokens.accent),
114
- declaration(names.onBrand, tokens.onBrand),
206
+ // Always emitted (when the name map asks for it), never skipped: a missing
207
+ // `--on-brand` sends the stylesheet to its own hardcoded fallback, which is
208
+ // how white-on-pale-brand reached production in the first place.
209
+ declaration(names.onBrand, resolveOnBrand(tokens.primary, tokens.onBrand)),
115
210
  declaration(names.success, tokens.semantic.success),
116
211
  declaration(names.warning, tokens.semantic.warning),
117
212
  declaration(names.error, tokens.semantic.error),
@@ -207,9 +302,6 @@ function toRnTheme(tokens) {
207
302
  // src/emit/toTailwindPreset.ts
208
303
  function addOptionalColors(colors, tokens) {
209
304
  const { semantic } = tokens;
210
- if (tokens.onBrand !== void 0) {
211
- colors["on-brand"] = tokens.onBrand;
212
- }
213
305
  if (semantic.successBg !== void 0) {
214
306
  colors["success-bg"] = semantic.successBg;
215
307
  }
@@ -234,6 +326,7 @@ function toTailwindPreset(tokens) {
234
326
  primary: tokens.primary,
235
327
  secondary: tokens.secondary,
236
328
  accent: tokens.accent,
329
+ "on-brand": resolveOnBrand(tokens.primary, tokens.onBrand),
237
330
  success: tokens.semantic.success,
238
331
  warning: tokens.semantic.warning,
239
332
  error: tokens.semantic.error,
@@ -287,7 +380,6 @@ function toTailwindPreset(tokens) {
287
380
  var UI_TINT_STEP = "100";
288
381
  var UI_MAIN_STEP = "500";
289
382
  var UI_DEEP_STEP = "700";
290
- var DEFAULT_ON_BRAND = "#ffffff";
291
383
  var ON_BRAND_SCALE = "onBrand";
292
384
  var SURFACE_MUTED_SCALE = "surfaceMuted";
293
385
  function flat(value) {
@@ -312,7 +404,7 @@ function toUiTheme(tokens, mode = "light") {
312
404
  primary: flat(tokens.primary),
313
405
  secondary: flat(tokens.secondary),
314
406
  accent: flat(tokens.accent),
315
- [ON_BRAND_SCALE]: flat(tokens.onBrand ?? DEFAULT_ON_BRAND),
407
+ [ON_BRAND_SCALE]: flat(resolveOnBrand(tokens.primary, tokens.onBrand)),
316
408
  [SURFACE_MUTED_SCALE]: flat(modeColors.surfaceMuted ?? modeColors.surface)
317
409
  },
318
410
  semantic: {
@@ -552,69 +644,6 @@ var PRESETS = {
552
644
  digitalkin: DIGITALKIN_TOKENS
553
645
  };
554
646
 
555
- // src/contrast.ts
556
- var AA_NORMAL_TEXT_RATIO = 4.5;
557
- var AA_LARGE_TEXT_RATIO = 3;
558
- var AA_NON_TEXT_RATIO = 3;
559
- var SRGB_CHANNEL_MAX = 255;
560
- var GAMMA_LINEAR_THRESHOLD = 0.03928;
561
- var GAMMA_LINEAR_DIVISOR = 12.92;
562
- var GAMMA_OFFSET = 0.055;
563
- var GAMMA_DIVISOR = 1.055;
564
- var GAMMA_EXPONENT = 2.4;
565
- var LUMA_COEFFICIENT_RED = 0.2126;
566
- var LUMA_COEFFICIENT_GREEN = 0.7152;
567
- var LUMA_COEFFICIENT_BLUE = 0.0722;
568
- var CONTRAST_FLARE = 0.05;
569
- var HEX_RADIX = 16;
570
- var HEX_PAIR_LENGTH = 2;
571
- var HEX_SHORTHAND_LENGTH = 3;
572
- var HEX_FULL_LENGTH = 6;
573
- var CHANNEL_OFFSET_RED = 0;
574
- var CHANNEL_OFFSET_GREEN = 2;
575
- var CHANNEL_OFFSET_BLUE = 4;
576
- function normalizeHexDigits(hex) {
577
- const clean = hex.trim().replace("#", "").toLowerCase();
578
- if (clean.length === HEX_SHORTHAND_LENGTH) {
579
- return `${clean[0] ?? ""}${clean[0] ?? ""}${clean[1] ?? ""}${clean[1] ?? ""}${clean[2] ?? ""}${clean[2] ?? ""}`;
580
- }
581
- return clean;
582
- }
583
- function parseChannel(digits, offset) {
584
- const pair = digits.slice(offset, offset + HEX_PAIR_LENGTH);
585
- return parseInt(pair, HEX_RADIX) / SRGB_CHANNEL_MAX;
586
- }
587
- function linearizeChannel(channel) {
588
- if (channel <= GAMMA_LINEAR_THRESHOLD) {
589
- return channel / GAMMA_LINEAR_DIVISOR;
590
- }
591
- return Math.pow((channel + GAMMA_OFFSET) / GAMMA_DIVISOR, GAMMA_EXPONENT);
592
- }
593
- function isHexColor(value) {
594
- const digits = normalizeHexDigits(value);
595
- return digits.length === HEX_FULL_LENGTH && /^[0-9a-f]{6}$/.test(digits);
596
- }
597
- function relativeLuminance(hex) {
598
- if (!isHexColor(hex)) {
599
- throw new Error(`relativeLuminance: not a hex colour: ${hex}`);
600
- }
601
- const digits = normalizeHexDigits(hex);
602
- const red = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_RED));
603
- const green = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_GREEN));
604
- const blue = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_BLUE));
605
- return LUMA_COEFFICIENT_RED * red + LUMA_COEFFICIENT_GREEN * green + LUMA_COEFFICIENT_BLUE * blue;
606
- }
607
- function contrastRatio(foreground, background) {
608
- const first = relativeLuminance(foreground);
609
- const second = relativeLuminance(background);
610
- const lighter = Math.max(first, second);
611
- const darker = Math.min(first, second);
612
- return (lighter + CONTRAST_FLARE) / (darker + CONTRAST_FLARE);
613
- }
614
- function meetsContrast(foreground, background, requiredRatio) {
615
- return contrastRatio(foreground, background) >= requiredRatio;
616
- }
617
-
618
647
  exports.AA_LARGE_TEXT_RATIO = AA_LARGE_TEXT_RATIO;
619
648
  exports.AA_NON_TEXT_RATIO = AA_NON_TEXT_RATIO;
620
649
  exports.AA_NORMAL_TEXT_RATIO = AA_NORMAL_TEXT_RATIO;
@@ -624,14 +653,19 @@ exports.DEFAULT_CSS_VAR_NAMES = DEFAULT_CSS_VAR_NAMES;
624
653
  exports.DIGITALKIN_TOKENS = DIGITALKIN_TOKENS;
625
654
  exports.EREVNA_TOKENS = EREVNA_TOKENS;
626
655
  exports.KATALOGOS_TOKENS = KATALOGOS_TOKENS;
656
+ exports.ON_BRAND_DARK_INK = ON_BRAND_DARK_INK;
657
+ exports.ON_BRAND_LIGHT_INK = ON_BRAND_LIGHT_INK;
627
658
  exports.PRESETS = PRESETS;
628
659
  exports.UI_DEEP_STEP = UI_DEEP_STEP;
629
660
  exports.UI_MAIN_STEP = UI_MAIN_STEP;
630
661
  exports.UI_TINT_STEP = UI_TINT_STEP;
662
+ exports.canCarryAccessibleInk = canCarryAccessibleInk;
631
663
  exports.contrastRatio = contrastRatio;
632
664
  exports.isHexColor = isHexColor;
633
665
  exports.meetsContrast = meetsContrast;
666
+ exports.onBrandRatio = onBrandRatio;
634
667
  exports.relativeLuminance = relativeLuminance;
668
+ exports.resolveOnBrand = resolveOnBrand;
635
669
  exports.toCssVars = toCssVars;
636
670
  exports.toRnTheme = toRnTheme;
637
671
  exports.toTailwindPreset = toTailwindPreset;