@vectoriox/iox-ui 5.10.0 → 5.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.10.0",
+  "version": "5.11.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/design-core/brand.ts

@@ -226,13 +226,18 @@ export function deriveBrandTokens(seed: string, pack: Pick<FlavorPack, 'accentHu
 /** WCAG 2 AA for body text — the gate every quartet pair is held to. */
 export const WCAG_AA_TEXT = 4.5;
 
-export const ACCENT_TOKEN_NAMES = ['accent', 'accent-ink', 'accent-hover', 'accent-text'] as const;
+export const ACCENT_TOKEN_NAMES = [
+    'accent', 'accent-ink', 'accent-hover', 'accent-text', 'inverse-accent', 'inverse-accent-ink',
+] as const;
 export type AccentTokenName = (typeof ACCENT_TOKEN_NAMES)[number];
 
-/** The page backgrounds the accent must read on, light and (optionally) dark. */
+/** The backgrounds the accent must read on, light and (optionally) dark. Without an inverse
+ *  background the inverse pair is not derived — the pack's own stays. */
 export interface AccentBackgrounds {
     bg: string;
     bgDark?: string;
+    inverseBg?: string;
+    inverseBgDark?: string;
 }
 
 const RAMP_ORDER = RAMP_STEPS.map(s => s.step);
@@ -252,7 +257,13 @@ const bestInkHex = (bg: string) =>
  * - dark: the first of brand-300/200/400 an ink clears 4.5:1 on, the same hover rule, and
  *   `accent-text` = the first light step that clears 4.5:1 on `bgDark`
  *
- * Every pair (ink/accent, ink/hover, text/bg) is asserted ≥ 4.5:1 in `brand.spec.ts`.
+ * - `inverse-accent` = the first step from 500 toward the end that reads on `inverseBg` clearing
+ *   4.5:1 on it; `inverse-accent-ink` = the higher-contrast of `brandInk` and the OPPOSITE ramp end
+ *   (the spec's `brandSeed` rule). A step whose best ink still misses 4.5:1 is passed over, so the
+ *   pair is a guarantee rather than a hope. Dark: the same against `inverseBgDark`.
+ *
+ * Every pair (ink/accent, ink/hover, text/bg, inverse ink/inverse accent, inverse accent/inverse
+ * bg) is asserted ≥ 4.5:1 across packs and seeds in `flavor-tokens.spec.ts`.
  */
 export function deriveAccentTokens(
     seed: string,
@@ -289,6 +300,24 @@ export function deriveAccentTokens(
         };
     })() : null;
 
+    const inverseOn = (inverseBg: string) => {
+        const toward = wcagContrastRatio(step(RAMP_ORDER[0]), inverseBg) >= wcagContrastRatio(step(RAMP_ORDER[RAMP_ORDER.length - 1]), inverseBg)
+            ? -1 : 1;
+        const walk = RAMP_ORDER.filter(n => (toward < 0 ? n <= 500 : n >= 500));
+        if (toward < 0) walk.reverse();
+        const rampEnd = step(toward < 0 ? RAMP_ORDER[RAMP_ORDER.length - 1] : RAMP_ORDER[0]);
+        const inkOn = (fill: string) =>
+            (wcagContrastRatio(ink, fill) >= wcagContrastRatio(rampEnd, fill) ? ink : rampEnd);
+        for (const n of walk) {
+            const fill = step(n);
+            if (passesText(fill, inverseBg) && passesText(inkOn(fill), fill)) return { accent: fill, ink: inkOn(fill) };
+        }
+        const fill = step(walk[walk.length - 1]);
+        return { accent: fill, ink: passesText(inkOn(fill), fill) ? inkOn(fill) : bestInkHex(fill) };
+    };
+    const inverse = against.inverseBg ? inverseOn(against.inverseBg) : null;
+    const inverseDark = against.inverseBg && against.inverseBgDark ? inverseOn(against.inverseBgDark) : null;
+
     const row = (name: AccentTokenName, value: string, darkValue?: string): FlavorTokenDef => ({
         name, value, type: 'color', group: 'colour', tier: 'semantic',
         ...(darkValue ? { values: { dark: darkValue } } : {}),
@@ -298,5 +327,9 @@ export function deriveAccentTokens(
         row('accent-ink', light.ink, dark?.ink),
         row('accent-hover', light.hover, dark?.hover),
         row('accent-text', light.text, dark?.text),
+        ...(inverse ? [
+            row('inverse-accent', inverse.accent, inverseDark?.accent),
+            row('inverse-accent-ink', inverse.ink, inverseDark?.ink),
+        ] : []),
     ];
 }

package/src/design-core/design-token.model.ts

@@ -1,15 +1,17 @@
-import { FLAVOR_SPEC } from './flavor-spec.generated';
+import {
+    FLAVOR_SPEC_VERSION, SPEC_AXES, SPEC_FLAVOR_PACKS, SPEC_FONT_ROLES, SPEC_SCHEMES, SPEC_TIER_IDS, SPEC_TOKEN_TYPES,
+} from './flavor-spec.generated';
 
 /**
  * The design-token vocabulary (design-system plan §3a/§3f). Every list here is READ from the
  * generated spec, so the contract has one source: iox-ai-guidance `flavor-spec.v1.json`.
  */
 
-export type DesignTokenType = (typeof FLAVOR_SPEC.tokenTypes)[number];
-export const DESIGN_TOKEN_TYPES: ReadonlyArray<DesignTokenType> = FLAVOR_SPEC.tokenTypes;
+export type DesignTokenType = (typeof SPEC_TOKEN_TYPES)[number];
+export const DESIGN_TOKEN_TYPES: ReadonlyArray<DesignTokenType> = SPEC_TOKEN_TYPES;
 
-export type DesignTokenTier = keyof typeof FLAVOR_SPEC.tiers;
-export const DESIGN_TOKEN_TIERS = Object.keys(FLAVOR_SPEC.tiers) as ReadonlyArray<DesignTokenTier>;
+export type DesignTokenTier = (typeof SPEC_TIER_IDS)[number];
+export const DESIGN_TOKEN_TIERS: ReadonlyArray<DesignTokenTier> = SPEC_TIER_IDS;
 
 /** The spec carries groups per row, not as a list — `design-token.model.spec` pins this list
  *  to exactly the set of groups the spec's rows use. */
@@ -35,12 +37,12 @@ export interface StoredDesignTokenRow extends DesignTokenRow {
     _id?: string;
 }
 
-export type ShapeId = keyof typeof FLAVOR_SPEC.axes.shapes;
-export type DensityId = keyof typeof FLAVOR_SPEC.axes.densities;
-export type MotionId = keyof typeof FLAVOR_SPEC.axes.motions;
-export type DesignMode = (typeof FLAVOR_SPEC.axes.modes)[number];
-export type SchemeId = keyof typeof FLAVOR_SPEC.schemes;
-export type FontRoleToken = (typeof FLAVOR_SPEC.fontRoles)[number]['token'];
+export type ShapeId = keyof typeof SPEC_AXES.shapes;
+export type DensityId = keyof typeof SPEC_AXES.densities;
+export type MotionId = keyof typeof SPEC_AXES.motions;
+export type DesignMode = (typeof SPEC_AXES.modes)[number];
+export type SchemeId = keyof typeof SPEC_SCHEMES;
+export type FontRoleToken = (typeof SPEC_FONT_ROLES)[number]['token'];
 
 /** Everything a studio chose about its look — the `settings.design` row, typed. */
 export interface DesignChoices {
@@ -97,9 +99,7 @@ export interface FlavorPackV2 {
 
 /** The spec's flavors, typed. Assignment here is the compile-time proof that the generated
  *  data fits `FlavorPackV2`. */
-export const SPEC_FLAVORS: ReadonlyArray<FlavorPackV2> = FLAVOR_SPEC.flavors;
-
-export const FLAVOR_SPEC_VERSION: number = FLAVOR_SPEC.version;
+export const SPEC_FLAVORS: ReadonlyArray<FlavorPackV2> = SPEC_FLAVOR_PACKS;
 
 /** The stamp seeded rows carry, so an upgrade can tell the machine's rows from the author's. */
 export function flavorSourceStamp(flavorId: string, version: number = FLAVOR_SPEC_VERSION): string {