@vectoriox/iox-ui 5.32.1 → 5.34.0

package/index.d.ts

@@ -1592,6 +1592,21 @@ interface VirtualTraitGroup {
  *  lines with an ellipsis. It composes into the four declarations a line clamp takes; anything else
  *  (`none`, empty, 0) clamps nothing. */
 declare const MAX_LINES_KEY = "maxLines";
+/** The Text Direction trait: `ltr` / `rtl` is the author's choice, unset (or empty) follows the
+ *  parent — `direction` is inherited, so a node with no direction of its own follows an RTL section
+ *  or `<html dir="rtl">` (vectoriox/iox-ui#14). */
+declare const TEXT_DIRECTION_KEY = "textDirection";
+/** Where the trait used to live. Until iox-ui#14 its default `ltr` was serialised onto EVERY node,
+ *  so a stored `direction: ltr` in a node's own styleProps records no choice and compiles nothing;
+ *  a stored `rtl` was always chosen and still compiles. In a sparse layer (a state, a breakpoint)
+ *  only an edit is stored, so there `ltr` too is the author's. */
+declare const LEGACY_DIRECTION_KEY = "direction";
+/**
+ * A saved node's own style map with its legacy `direction` moved onto the Text Direction trait —
+ * `rtl` carried over, the serialised default `ltr` released — so the builder's panel shows what the
+ * node renders. Pure; returns the map unchanged (same reference) when there is nothing to move.
+ */
+declare function migrateLegacyDirection(styleProps: Record<string, any>): Record<string, any>;
 declare function isGradientPaint(value: unknown): boolean;
 /** The whole-value backdrop trait (DS2). A plain key — it is copied, not stripped — but it feeds
  *  the backdrop group's output, so a breakpoint layer that sets it must count as touching it. */
@@ -3137,5 +3152,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { A11yAttribute, A11yTrait, ACCESSIBLE_NAME_TYPES, AOSService, ARIA_CURRENT_PAGE, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, COMPONENT_STATE_SELECTOR, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CURRENT_LINK_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ComponentState, ContainerComponent, ContextStore, DECORATIVE_TYPES, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DIALOG_CLOSE_ABOVE_ATTRIBUTE, DIALOG_NODE_TYPE, DeclarationContext, ENTRANCE_ACTION_TYPES, EXIT_ACTION_TYPES, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, INTERACTION_HIDDEN_ATTRIBUTE, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxDialogComponent, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LEGACY_HOVER_TRANSITION, LinkedContainerComponent, MANAGED_A11Y_ATTRIBUTES, MAX_LINES_KEY, PAGE_STYLE_TOKENS, PAGE_TOKEN_FALLBACKS, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PageStyleField, PageStyleSource, REDUCED_MOTION_QUERY, RESERVED_ALIAS_PREFIX, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_A11Y_OPTIONS, SWIPER_RESPONSIVE_TRAITS, SectionComponent, SwiperModuleName, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, VisibilityActionType, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildInteractionKeyframes, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, closeAboveMediaQuery, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, componentStatesFor, composeVirtualTraits, computeRelative, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describePageStyle, describeSeoFields, dialogCloseAboveMinWidth, effectiveActionType, effectiveTransitionId, entrancePreStateStyle, excludeSelf, feelFor, finalKeyframe, getByPath, getSeoValue, hasHoverState, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isCurrentLink, isExternalOrFragment, isGradientPaint, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, isWholeBackdropSet, keyframePropertyName, keyframeStyleEntries, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, motionAllowed, nearestCommonAncestorId, needsAccessibleName, nodeA11yAttributes, nodeCssId, nodeTraitValue, nodeUsesContext, normalizeAppPath, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, prefersReducedMotion, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetPageStyleField, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveToggleVisibility, resolveValueChain, rewriteViewportUnits, safeSetInput, serializeA11yAttributes, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, statePseudoClass, stateSelectorSuffix, stripSuppressedProps, swiperAutoplayAllowed, swiperModuleNames, syncNodeA11yAttributes, variableAliases, variableItemsFrom, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
+export { A11yAttribute, A11yTrait, ACCESSIBLE_NAME_TYPES, AOSService, ARIA_CURRENT_PAGE, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, COMPONENT_STATE_SELECTOR, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CURRENT_LINK_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ComponentState, ContainerComponent, ContextStore, DECORATIVE_TYPES, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DIALOG_CLOSE_ABOVE_ATTRIBUTE, DIALOG_NODE_TYPE, DeclarationContext, ENTRANCE_ACTION_TYPES, EXIT_ACTION_TYPES, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, INTERACTION_HIDDEN_ATTRIBUTE, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxDialogComponent, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LEGACY_DIRECTION_KEY, LEGACY_HOVER_TRANSITION, LinkedContainerComponent, MANAGED_A11Y_ATTRIBUTES, MAX_LINES_KEY, PAGE_STYLE_TOKENS, PAGE_TOKEN_FALLBACKS, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PageStyleField, PageStyleSource, REDUCED_MOTION_QUERY, RESERVED_ALIAS_PREFIX, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_A11Y_OPTIONS, SWIPER_RESPONSIVE_TRAITS, SectionComponent, SwiperModuleName, TEXT_DIRECTION_KEY, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, VisibilityActionType, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildInteractionKeyframes, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, closeAboveMediaQuery, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, componentStatesFor, composeVirtualTraits, computeRelative, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describePageStyle, describeSeoFields, dialogCloseAboveMinWidth, effectiveActionType, effectiveTransitionId, entrancePreStateStyle, excludeSelf, feelFor, finalKeyframe, getByPath, getSeoValue, hasHoverState, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isCurrentLink, isExternalOrFragment, isGradientPaint, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, isWholeBackdropSet, keyframePropertyName, keyframeStyleEntries, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, migrateLegacyDirection, motionAllowed, nearestCommonAncestorId, needsAccessibleName, nodeA11yAttributes, nodeCssId, nodeTraitValue, nodeUsesContext, normalizeAppPath, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, prefersReducedMotion, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetPageStyleField, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveToggleVisibility, resolveValueChain, rewriteViewportUnits, safeSetInput, serializeA11yAttributes, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, statePseudoClass, stateSelectorSuffix, stripSuppressedProps, swiperAutoplayAllowed, swiperModuleNames, syncNodeA11yAttributes, variableAliases, variableItemsFrom, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
 export type { A11yNodeSource, BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, CurrentLinkOptions, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, InteractionKeyframe, IoxContextSlot, IoxPipe, MatchMediaHost, NodeA11yContext, OverrideBreakpoint, PageStyleFieldState, PageStyleOptions, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, SwiperModuleFlags, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };

package/package.json

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

package/src/composite-core/badge.ts

@@ -66,8 +66,9 @@ const PILL_BASE: Readonly<Record<string, string>> = {
 };
 const PILL_ICON: Readonly<Record<string, string>> = { fontSize: '1em' };
 const PILL_WORDS: Readonly<Record<string, string>> = { width: 'auto', minHeight: 'auto', padding: '0px 0px 0px 0px', margin: '0px 0px 0px 0px' };
-/** The pill's words inherit the pill's type and ink (the contract's inherit-everything text style). */
-const PILL_WORDS_STYLE = 'button-label';
+/** The pill's words wear the pill's OWN label style (Card v2.1): its type from the badge tokens, its leading,
+ *  tracking, case and ink inherited from the pill — never the button's label style. */
+export const PILL_LABEL_STYLE = 'badge-label';
 
 export interface PillOptions {
     text?: string;
@@ -81,7 +82,7 @@ function buildPill(create: CompositeNodeFactory, elementStyle: string, text: str
     writeStyles(pill, PILL_BASE);
     const glyph = create({ key: `${key}-icon`, type: 'Icon', props: { iconClass: icon }, elementStyle: 'icon' });
     writeStyles(glyph, PILL_ICON);
-    const words = create({ key: `${key}-text`, type: 'Text', props: { content: text, tag: 'span' }, elementStyle: PILL_WORDS_STYLE });
+    const words = create({ key: `${key}-text`, type: 'Text', props: { content: text, tag: 'span' }, elementStyle: PILL_LABEL_STYLE });
     writeStyles(words, PILL_WORDS);
     pill.children = [glyph, words];
     return pill;

package/src/composite-core/card.ts

@@ -1,4 +1,4 @@
-import { elementStyleById, LinkType, switchElementStyle } from '@vectoriox/iox-ui/design-core';
+import { COLOR_SCHEME_TRAIT, elementStyleById, LinkType, setColorScheme, switchElementStyle } from '@vectoriox/iox-ui/design-core';
 
 import { BadgeTone, buildBadge } from './badge';
 import {
@@ -119,7 +119,6 @@ enum Scheme {
     Inverse = 'inverse',
 }
 
-const COLOR_SCHEME = 'colorScheme';
 const LINK_TYPE = 'linkType';
 const SAVE_ICON = 'ph ph-bookmark-simple';
 
@@ -336,8 +335,9 @@ function placeBadge(card: CompositeNode, badge: CompositeNode, onMedia: boolean)
     writeStyles(badge, { position: overMedia ? 'absolute' : 'static' });
 }
 
+/** Through design-core's ONE scheme writer — the same setting Section colours edits everywhere. */
 function writeScheme(node: CompositeNode, scheme: Scheme): void {
-    writeProp(node, COLOR_SCHEME, scheme);
+    setColorScheme(node, scheme);
 }
 
 /** Write one role's layout values from a spec (base + layers). */
@@ -424,7 +424,7 @@ function matches(card: CompositeNode, spec: CardLayoutSpec): boolean {
     const content = findByRole(card, CardRole.Content);
     if (content) {
         if (content.elementStyle !== spec.contentStyle || !holds(content, spec.content)) return false;
-        if (!same(readProp(content, COLOR_SCHEME) ?? Scheme.Default, spec.contentScheme)) return false;
+        if (!same(readProp(content, COLOR_SCHEME_TRAIT) ?? Scheme.Default, spec.contentScheme)) return false;
     }
     const title = findByRole(card, CardRole.Title);
     if (title && !holds(title, spec.title)) return false;

package/src/design-core/contrast-audit.ts

@@ -3,6 +3,7 @@ import { WCAG_AA_UI } from './brand-neutrals';
 import { compositeOver, paintColours, parseCssColour, quantizeRgb, Rgba, ringColour } from './colour-eval';
 import { ElementStyle, ELEMENT_STYLES } from './element-styles';
 import { SPEC_CONTRAST_AUDIT, SPEC_INK_SCOPES, SPEC_SCHEMES } from './flavor-spec.generated';
+import { SCHEME_INK } from './node-classes';
 import { DesignTokenLike, ResolvedMode, resolveSchemeTokenValues } from './token-css';
 
 /**
@@ -19,7 +20,10 @@ import { DesignTokenLike, ResolvedMode, resolveSchemeTokenValues } from './token
  *   its focus ring; the form parts the field baseline paints (`contrastAudit.formParts`); the form's
  *   Success / Error notices, in every scheme and container;
  * - a Badge's or Chip's icon through the same `inkScopes`, and text over an image (Card v2's "Image behind
- *   text"): the block's ink over its scrim composited on the WORST-CASE image (`contrastAudit.scrims`).
+ *   text"): the block's ink over its scrim composited on the WORST-CASE image (`contrastAudit.scrims`);
+ * - a container that WEARS a scheme inside a section of any scheme (a Featured card on a plain page): the
+ *   text it holds inherits the scheme's ink (`SCHEME_INK`, iox-ui#15) on the inner scheme's fill, composited
+ *   over the OUTER section — the pairing the token pairs cannot see.
  *
  * WCAG 2: 4.5:1 for text, 3:1 for glyphs, UI boundaries and focus indicators (1.4.11), judged on 8-bit
  * colours. The same audit gates the contract (`colour.mjs auditContrast`, every flavor × tint × a seed
@@ -65,6 +69,8 @@ const GLYPH_GROUP = 'Media';
 const FORMS_GROUP = 'Forms';
 const DEFAULT_SCHEME = 'default';
 const SECTION = 'section';
+/** The element a scheme'd container's running text is reported as (iox-ui#15). */
+export const INHERITED_TEXT = 'inherited text';
 const FIELD = 'field';
 const WHITE: Rgba = { r: 1, g: 1, b: 1, a: 1 };
 const SINGLE_REF = /^var\(--iox-([\w-]+)\)$/;
@@ -187,10 +193,53 @@ export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode:
             }
         }
     }
+    findings.push(...schemedContainerFindings(rows, mode, section, containers.filter((c): c is ElementStyle => !!c)));
     for (const scrim of SCRIMS) findings.push(...scrimFindings(rows, mode, scrim, byId.get(scrim.style)));
     return findings;
 }
 
+/** What a section in `values` paints under its content: its own fill over the page, or the page. */
+function sectionGround(values: Values): Rgba[] {
+    const pageInk = parseCssColour(values['text']);
+    const page = paintColours(values['page-bg'], pageInk);
+    const sectionPaint = paintColours(values['section-bg'], pageInk);
+    return opaque(sectionPaint) ? sectionPaint.map(c => (c.a < 1 ? compositeOver(c, page[0] ?? WHITE) : c)) : page;
+}
+
+/**
+ * A container that wears a NON-default scheme, inside a section of every scheme (vectoriox/iox-ui#15 — the
+ * Featured card is a Card in Brand on a Default page). Its tokens are its own scheme's laid over the outer
+ * section's (what it does not set, it inherits); a translucent fill composites over the OUTER section; the running text it holds (`body`, `lead`, a label: `color: inherit`)
+ * reads the scheme's ink, which is what the scheme-ink rule and `withSchemeInk` make CSS compute.
+ */
+function schemedContainerFindings(rows: ReadonlyArray<DesignTokenLike>, mode: ResolvedMode, section: StyleMap,
+    containers: ReadonlyArray<ElementStyle>): ContrastFinding[] {
+    const out: ContrastFinding[] = [];
+    for (const outer of SCHEME_IDS) {
+        const ground = sectionGround(resolveSchemeTokenValues(rows, mode, outer));
+        for (const inner of SCHEME_IDS.filter(id => id !== DEFAULT_SCHEME)) {
+            const values = resolveSchemeTokenValues(rows, mode, [outer, inner]);
+            const schemeInk = parseCssColour(resolveIn(values, SCHEME_INK), parseCssColour(resolveIn(values, section['color'])));
+            for (const box of containers) {
+                const style = ownStyle(box);
+                const bgs = overAll(paintColours(resolveIn(values, style['backgroundColor']), schemeInk), ground);
+                const ink = style['color'] && style['color'] !== 'inherit' ? parseCssColour(resolveIn(values, style['color']), schemeInk) : schemeInk;
+                if (!ink) continue;
+                for (const g of bgs) {
+                    const bg = quantizeRgb(g);
+                    const f = quantizeRgb(ink.a < 1 ? compositeOver(ink, bg) : ink);
+                    const ratio = wcagContrastRatio(f, bg);
+                    out.push({
+                        scheme: inner, container: `${box.id} in a ${outer} section`, element: INHERITED_TEXT, part: 'text',
+                        fg: toHexColor(f), bg: toHexColor(bg), ratio: Math.round(ratio * 100) / 100, min: WCAG_AA_TEXT, pass: ratio >= WCAG_AA_TEXT - 1e-9,
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}
+
 /** Text over an image: the block's ink — and every token its ink scope pins to it — over the scrim
  *  composited on the WORST-CASE image, in the scheme the block wears. Never over the section: the image
  *  covers it. */

package/src/design-core/flavor-spec.generated.ts

@@ -1348,6 +1348,7 @@ export const SPEC_SCHEMES = {
     "set": {
       "section-bg": "{{accent}}",
       "bg": "{{accent}}",
+      "nav-bg": "{{accent}}",
       "surface": "{{accent-hover}}",
       "surface-2": "{{accent-hover}}",
       "surface-glass": "{{accent-hover}}",
@@ -1371,6 +1372,8 @@ export const SPEC_SCHEMES = {
   }
 } as const;
 
+export const SPEC_SCHEME_INK = "var(--iox-text)" as const;
+
 export const SPEC_A11Y = {
   "reducedMotion": {
     "dur-fast": "0ms",
@@ -2012,6 +2015,23 @@ export const SPEC_ELEMENT_STYLES = [
       "fontWeight": "var(--iox-weight-label)"
     }
   },
+  {
+    "id": "badge-label",
+    "label": "Badge label",
+    "group": "Content blocks",
+    "appliesTo": [
+      "Text"
+    ],
+    "base": {
+      "fontFamily": "var(--iox-font-label)",
+      "fontSize": "var(--iox-badge-size)",
+      "fontWeight": "var(--iox-weight-label)",
+      "lineHeight": "inherit",
+      "letterSpacing": "inherit",
+      "textTransform": "inherit",
+      "color": "inherit"
+    }
+  },
   {
     "id": "media-scrim",
     "label": "Text over image",

package/src/design-core/node-classes.ts

@@ -1,5 +1,5 @@
 import { ELEMENT_STYLE_MARKER_CLASS, elementStyleClass } from './element-styles';
-import { SPEC_SCHEMES } from './flavor-spec.generated';
+import { SPEC_SCHEME_INK, SPEC_SCHEMES } from './flavor-spec.generated';
 
 /**
  * The design-system classes a node renders, in BOTH renderers (builder canvas, engine component
@@ -104,6 +104,54 @@ export function colorSchemeOf(node: DesignClassSource | null | undefined): strin
     return typeof trait === 'string' ? trait : null;
 }
 
+/**
+ * The ink a section colour scheme gives everything inside it (vectoriox/iox-ui#15). A scheme re-declares
+ * tokens only, so without this a Container wearing one kept the colour it INHERITED from the section around
+ * it: a Featured (Brand) card's body text stayed the page's dark ink on the Brand fill, 2.54:1. Two halves,
+ * one rule: `compileSchemeCss` gives every `iox-scheme-*` element `color: var(--iox-text)` (the node rule,
+ * emitted after it at the same specificity, still wins), and {@link withSchemeInk} reads a scheme'd node's
+ * own `inherit` — what the card / box / panel element styles write for "no colour of my own" — as this ink.
+ * The value is the contract's `schemeInk`.
+ */
+export const SCHEME_INK: string = SPEC_SCHEME_INK;
+
+/** The values that mean "no colour of my own" — `color` is inherited, so these equal no declaration. */
+const INHERITED_INK: ReadonlySet<string> = new Set(['inherit', 'unset']);
+
+/**
+ * A node's style map as its renderer compiles it under a section colour scheme: a NON-default scheme turns
+ * an inherited `color` into {@link SCHEME_INK}; anything else — no scheme, an author's own colour, a token —
+ * is returned untouched (the same object). Every render path calls it on every rule it compiles for the
+ * node (base, states, breakpoint layers): the builder's StyleRegistryService and both engine paths.
+ */
+export function withSchemeInk<T extends Record<string, unknown>>(styles: T, scheme: unknown): T {
+    if (!styles || !colorSchemeClass(scheme)) return styles;
+    const color = styles['color'];
+    if (typeof color !== 'string' || !INHERITED_INK.has(color.trim().toLowerCase())) return styles;
+    return { ...styles, color: SCHEME_INK };
+}
+
+/**
+ * Write a node's section colour scheme — THE one writer, so every control that offers Section colours (the
+ * Style panel's Element style block, Card ▸ Card) edits the same setting: the `colorScheme` content trait on
+ * a builder node, `props.colorScheme` on a saved one. False when nothing changed: an unknown id, the value it
+ * already holds, or a builder node with no such trait (a type that offers no scheme).
+ */
+export function setColorScheme(
+    node: { props?: Record<string, unknown> | null; traits?: Array<{ name?: string; default?: unknown }> | null } | null | undefined,
+    id: string,
+): boolean {
+    if (!node || !SCHEME_IDS.has(id) || (colorSchemeOf(node) ?? ColorScheme.Default) === id) return false;
+    if (Array.isArray(node.traits)) {
+        const trait = node.traits.find(t => t?.name === COLOR_SCHEME_TRAIT);
+        if (!trait) return false;
+        trait.default = id;
+        return true;
+    }
+    node.props = { ...(node.props ?? {}), [COLOR_SCHEME_TRAIT]: id };
+    return true;
+}
+
 /** True when the node wears a known element style — the marker is on it. */
 export function hasElementStyleMarker(node: { elementStyle?: string | null } | null | undefined): boolean {
     return elementStyleClass(node?.elementStyle) !== null;

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

@@ -1,5 +1,6 @@
 import { DesignMode } from './design-token.model';
 import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
+import { SCHEME_INK } from './node-classes';
 import { specTokenNames } from './token-names';
 
 /**
@@ -10,7 +11,8 @@ import { specTokenNames } from './token-names';
  *
  * Block order (design-system plan §3e, T8):
  *   1. base            `:root { --iox-*: … }`
- *   2. schemes         `.iox-scheme-<id> { overrides; every var()-referencing token re-declared }`
+ *   2. schemes         `.iox-scheme-<id> { overrides; every var()-referencing token re-declared }`, then the
+ *                      ONE scheme-ink rule `.iox-scheme-subtle, … { color: var(--iox-text) }` (iox-ui#15)
  *   3. reduced motion  `@media (prefers-reduced-motion: reduce)`
  *   4. reduced transparency `@media (prefers-reduced-transparency: reduce)`
  *   5. dark — LAST     `@media (prefers-color-scheme: dark)`
@@ -167,19 +169,29 @@ export function resolveTokenValues(
  * Every token's value INSIDE a section wearing `schemeId`, in one mode — what CSS computes there: the
  * scheme's overrides (`{{token}}` / `{{~token}}` placeholders substituted from the root), every other
  * row as declared, and `var()` references resolved within the section (the §3c re-declaration rule
- * makes that the section's own resolution). `default` (or an unknown id) is the root.
+ * makes that the section's own resolution). `default` (or an unknown id) is the root. A CHAIN
+ * (`['inverse', 'accent']`, outermost first) is an element wearing the last scheme inside elements wearing
+ * the ones before it: a token the inner scheme does not set is the outer one's (custom properties inherit).
  */
 export function resolveSchemeTokenValues(
     tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
     mode: ResolvedMode,
-    schemeId: string,
+    schemeId: string | ReadonlyArray<string>,
 ): Record<string, string> {
     const rows = usableTokens(tokens);
-    const set = schemeId === DEFAULT_SCHEME ? undefined : (SPEC_SCHEMES as Readonly<Record<string, { set: Readonly<Record<string, string>> }>>)[schemeId]?.set;
-    if (!set) return resolveTokenValues(rows, mode);
+    const sets = (typeof schemeId === 'string' ? [schemeId] : schemeId)
+        .map(id => (id === DEFAULT_SCHEME ? undefined : (SPEC_SCHEMES as Readonly<Record<string, { set: Readonly<Record<string, string>> }>>)[id]?.set));
+    if (!sets.some(Boolean)) return resolveTokenValues(rows, mode);
     const root = resolveTokenValues(rows, mode);
     const other = resolveTokenValues(rows, mode === DARK ? LIGHT : DARK);
-    const overrides = new Map(schemeEntries(set, root, other));
+    // Nested (`[outer, inner]` — a Featured card in an Inverse section): each scheme block re-declares the
+    // rows that reference a token, so at every level those are restored before the block's own set.
+    const overrides = new Map<string, string>();
+    for (const set of sets) {
+        if (!set) continue;
+        for (const t of rows) if (modeValue(t, mode).includes(REFERENCE)) overrides.delete(t.name);
+        for (const [name, value] of schemeEntries(set, root, other)) overrides.set(name, value);
+    }
     return resolveTokenValues(rows.map(t => ({ name: t.name, value: overrides.get(t.name) ?? modeValue(t, mode) })), LIGHT);
 }
 
@@ -243,11 +255,27 @@ export function compileSchemeCss(
     if (!rows.length) return '';
     const resolved = resolveTokenValues(rows, LIGHT);
     const other = opposite ?? resolveTokenValues(rows, DARK);
-    return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
-        ...schemeEntries(set, resolved, other),
-        ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
-            .map((t): [string, string] => [t.name, t.value]),
-    ])).filter(Boolean).join('\n');
+    return [
+        ...nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
+            ...schemeEntries(set, resolved, other),
+            ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
+                .map((t): [string, string] => [t.name, t.value]),
+        ])),
+        schemeInkRule(scope),
+    ].filter(Boolean).join('\n');
+}
+
+/**
+ * Every element wearing a scheme takes the scheme's ink (vectoriox/iox-ui#15): the tokens re-resolve inside
+ * it, but `color` is inherited as a COMPUTED value, so without this a scheme'd Container's running text kept
+ * the outer section's ink. One rule, specificity (0,1,0) in every renderer — a builder scope is wrapped in
+ * `:where()` — emitted with the token CSS, BEFORE every node rule: a node's own colour (same specificity,
+ * later) still wins. A node's `color: inherit` is read as this ink by `withSchemeInk`.
+ */
+function schemeInkRule(scope?: string): string {
+    const where = scope ? `:where(${scope}) ` : '';
+    const selectors = nonDefaultSchemes().map(([id]) => `${where}.iox-scheme-${id}`);
+    return selectors.length ? `${selectors.join(', ')} {\n  color: ${SCHEME_INK};\n}` : '';
 }
 
 /** The dark twin of both scheme rules: a re-declared token with a dark value would otherwise pin