@apollion-dsi/core 5.5.0 → 5.7.0

package/lib/themes/Colors/Colors.helpers.d.ts

@@ -1,4 +1,24 @@
 import { AcceptColorType, ColorPalleteInterface, ColorPalleteOverrideInterface, ColorsInput, ColorsType, GrayscaleColorsType, NeutralColorsType, ThemeColorsType } from './Colors.interface';
+/**
+ * OKLch perceptual lerp wrapper.
+ *
+ * Replaces `Color(a).mix(b, t).hex()` (RGB lerp in `color@5`, perceptually
+ * non-uniform — produces luminance "holes" in greyscale ramps) with
+ * `culori.interpolate([a, b], 'oklch')(t)` (OKLch lerp, perceptually
+ * uniform in OKLAB L space).
+ *
+ * Validated via spike `spike/culori-oklch-lerp-parity` (preserved locally —
+ * see ADR-006 §11.5): 0 unexpected regressions across 68 deltas, greyscale
+ * ramp OKLAB L std-dev **19× more uniform** vs RGB lerp.
+ *
+ * `culori.interpolate` in mode `'oklch'` uses `fixupHueShorter` by default
+ * (grill-with-docs validated 2026-05-24) — correct for palette derivation.
+ *
+ * @see ADR-006 §2 (Bottleneck B1), §6 S2
+ * @see PRD-002 §S2
+ * @see ../vendors/Culori/README.md — "Equivalence proof" (the original spike lives on the spike/culori-oklch-lerp-parity branch, never merged)
+ */
+export declare function mixOklch(a: string, b: string, t: number): string;
 /**
  * Convert hex/css string → comma-separated "r,g,b" triplet.
  *
@@ -32,6 +52,16 @@ export declare const HextoRgb: {
 export declare function getOppositeColor(color: AcceptColorType): string;
 /** WCAG AA contrast floor for normal text. */
 export declare const MIN_CONTRAST_AA = 4.5;
+/**
+ * WCAG contrast ratio (1–21) between two colors.
+ *
+ * **Single source of contrast** — shared by `getContrastColor` and
+ * `readableColor` to avoid duplicating the `parse` + `wcagContrast` pair.
+ * Accepts a string or `ColorPalleteInterface` (coerced via `getColor`/`coerceToHex`).
+ * Returns `1` (absence of contrast) if either color fails to parse, keeping
+ * callers in best-effort mode instead of throwing.
+ */
+export declare function contrastRatio(a: AcceptColorType, b: AcceptColorType): number;
 /**
  * Adjusts the lightness (OKLch L) of `color` until it reaches a WCAG contrast
  * floor against `background`, **preserving hue and chroma**.
@@ -220,6 +250,23 @@ export declare function resolveDisabledNeutral(colors: ThemeColorsType): {
 export declare function resolveStructuralNeutrals(colors: ThemeColorsType): {
     muted: string;
 };
+/**
+ * Neutral ramp index seeding the `quiet` palette per polarity — mid-gray on
+ * a light canvas, its inverted counterpart on a dark one.
+ *
+ * @see resolveQuietPalette · APOLLION-BUTTON-NEUTRAL
+ */
+export declare const QUIET_NEUTRAL_INDICES: {
+    readonly light: 70;
+    readonly dark: 110;
+};
+/**
+ * `quiet` palette — a {@link ColorPalleteInterface} built from one Neutral
+ * ramp stop through {@link mountSingleColor}, so it carries the same
+ * perceptual state floor (ADR-012) and AA tonal pair (ADR-018) as the brand
+ * palettes. Assembled once in {@link createColors} → `theme.colors.quiet`.
+ */
+export declare function resolveQuietPalette(colors: ThemeColorsType, input: ColorsInput): ColorPalleteInterface;
 /**
  * Perceptual state floor between `base` and an interaction state (`action`/`active`):
  * minimum WCAG luminance ratio for the shift to be perceptible (ADR-012).
@@ -232,6 +279,36 @@ export declare const MIN_STATE_CONTRAST = 1.3;
  * clearly visible shift measures < 1.3x — the perceptually uniform ΔL does not saturate.
  */
 export declare const STATE_DELTA_L_JND = 0.05;
+/**
+ * Infers the surface mode from the luminance of `baseLight` (the theme's page
+ * surface): if white contrasts more than black against it, the surface is
+ * dark → states lighten; otherwise (or without `baseLight`), they darken (the
+ * historical light behavior).
+ */
+export declare function isDarkSurface(baseLight?: string): boolean;
+/**
+ * Shifts the OKLch lightness of `color` by `delta` (result clamped to `[0, 1]`),
+ * hue and chroma preserved — the surface-ladder primitive
+ * (`paper = canvas + ΔL`, APOLLION-DARK-MODE-ENGINE). Unparsable input passes
+ * through untouched.
+ */
+export declare function shiftLightness(color: string, delta: number): string;
+/**
+ * Clamps the OKLch lightness of `color` into `[min, max]` (hue/chroma
+ * preserved). Returns the input **verbatim** when already inside the range —
+ * the halation floors (`CANVAS_MIN_L`, `INK_MAX_L`) must not re-quantize
+ * colors that already comply. Unparsable input passes through.
+ */
+export declare function clampLightness(color: string, range: {
+    min?: number;
+    max?: number;
+}): string;
+/**
+ * `rgba(r, g, b, a)` string for `color` at `alpha` (clamped to `[0, 1]`) — the
+ * edge/wash primitive (ink at 10–20 % over any ground). Unparsable input
+ * passes through.
+ */
+export declare function toRgbaString(color: string, alpha: number): string;
 /**
  * Derives the 5-stop palette (`ColorPalleteInterface`) from a seed via **OKLch
  * perceptual lerp**, with a **mode-aware perceptual state floor** on the

package/lib/themes/Colors/Colors.interface.d.ts

@@ -58,7 +58,85 @@ interface ActionColorsInterface<T> {
     warning?: T;
     danger?: T;
 }
-export type ColorsInput<T = ColorSeedInputType> = ContrastColorsInterface & DeepColorsInterface & BrandColorsInterface<T> & ActionColorsInterface<T> & MainColorsInterface<T>;
+/** Theme polarity — the single mode switch of the engine (`isDarkSurface(baseLight)`). */
+export type Polarity = 'light' | 'dark';
+/**
+ * Grounds, from the page canvas up the tonal-elevation ladder. In both
+ * polarities `paper` is lighter than `canvas` (dark surfaces gain luminance
+ * with elevation — the shadow attenuates, the tonal step carries depth).
+ */
+export interface SurfaceLadder {
+    /** Page ground (`baseLight`; floored off pure black in dark). */
+    canvas: string;
+    /** Recessed area (wells, table stripes, inset rails). */
+    sunken: string;
+    /** Card / input / table ground — the default component surface. */
+    paper: string;
+    /** Raised element over paper (menus, popovers). */
+    raised: string;
+    /** Top of the ladder (modal / dialog panel). */
+    overlay: string;
+    /** Backdrop behind overlays; the consumer applies the opacity. */
+    scrim: string;
+}
+/** Neutral text hierarchy — each role is AA over `surface.paper` and `surface.canvas` (except `disabled`, WCAG-exempt). */
+export interface InkLadder {
+    primary: string;
+    secondary: string;
+    muted: string;
+    disabled: string;
+}
+/** Lines — `ink.primary` at a fixed alpha, legible on any ground of the ladder. */
+export interface EdgeLadder {
+    hairline: string;
+    border: string;
+    strong: string;
+}
+/** Interaction washes — `ink.primary` at a fixed alpha, polarity-tuned for perceptibility. */
+export interface WashLadder {
+    hover: string;
+    pressed: string;
+    selected: string;
+}
+/** The four ladder groups as assembled on `theme.colors`. */
+export interface LadderGroups {
+    surface: SurfaceLadder;
+    ink: InkLadder;
+    edge: EdgeLadder;
+    wash: WashLadder;
+}
+/** Verbatim override of any ladder role (applied over the derivation, never re-derived). */
+export interface LadderOverride {
+    surface?: Partial<SurfaceLadder>;
+    ink?: Partial<InkLadder>;
+    edge?: Partial<EdgeLadder>;
+    wash?: Partial<WashLadder>;
+}
+interface LadderInputInterface {
+    /**
+     * Per-polarity verbatim ladder overrides (ADR-023). Keyed by polarity so the
+     * same input survives `toDarkColors` — `light` applies when the theme's
+     * `baseLight` is a light ground, `dark` when it is dark.
+     *
+     * @example
+     * ```ts
+     * createTheme({ colors: { ladder: { dark: { surface: { paper: '#1a1a19' } } } } });
+     * ```
+     */
+    ladder?: {
+        light?: LadderOverride;
+        dark?: LadderOverride;
+    };
+}
+/** What the ladder derivation reads — anchors + the neutral ramp (light scrim) + optional overrides. */
+export type LadderInput = ContrastColorsInterface & DeepColorsInterface & LadderInputInterface & {
+    neutral?: Record<NeutralColorsType, string>;
+};
+export type SurfaceRole = keyof SurfaceLadder;
+export type InkRole = keyof InkLadder;
+export type EdgeRole = keyof EdgeLadder;
+export type WashRole = keyof WashLadder;
+export type ColorsInput<T = ColorSeedInputType> = ContrastColorsInterface & DeepColorsInterface & LadderInputInterface & BrandColorsInterface<T> & ActionColorsInterface<T> & MainColorsInterface<T>;
 type ColorVariantNamesType = 'dark' | 'action' | 'light' | 'active';
 type FunctionColorsType = 'primary' | 'secondary' | 'tertiary';
 type FeedbackColorsType = 'success' | 'information' | 'warning' | 'danger';
@@ -72,7 +150,9 @@ type GrayscaleColorType<S extends GrayscaleColorsType = GrayscaleColorsType> = `
 type NeutralColorType<S extends NeutralColorsType = NeutralColorsType> = `neutral.${S}`;
 export type BgColorsTypes = ColorWithVariantType | GrayscaleColorType | NeutralColorType | BrandColorsType | ContrastColorsType
 /** Mode-aware soft fill assembled in `createColors`. */
- | 'muted';
+ | 'muted'
+/** Surface ladder roles (ADR-023) — grounds, inks, edges and washes. */
+ | `surface.${SurfaceRole}` | `ink.${InkRole}` | `edge.${EdgeRole}` | `wash.${WashRole}`;
 export type ColorsType = BgColorsTypes | null;
 export type ThemeColorsType<T = ColorPalleteInterface> = BrandColorsInterface<T> & MainColorsInterface<T> & ActionColorsInterface<T> & ContrastColorsInterface & DeepColorsInterface & {
     neutral?: Record<NeutralColorsType, string>;
@@ -103,5 +183,24 @@ export type ColorsThemeInterface = ThemeColorsType & {
      * Borders/placeholders: direct Neutral ramp (`neutral.40` / `neutral.70`).
      */
     muted: string;
+    /**
+     * Quiet interaction palette — a full six-stop palette derived from the
+     * Neutral ramp (mode-aware seed, `neutral.70` light / `neutral.110` dark)
+     * so chrome CTAs (`Button color="neutral"`) get rest/hover/pressed stops
+     * without borrowing a brand hue. The `neutral` scale itself stays a ramp.
+     */
+    quiet: ColorPalleteInterface;
+    /**
+     * Surface ladder (ADR-023) — mode-aware grounds (`canvas` → `overlay`),
+     * resolved at theme assembly from the contrast anchors; `paper` is lighter
+     * than `canvas` in both polarities. Dot-path resolvable (`bgColor="surface.paper"`).
+     */
+    surface: SurfaceLadder;
+    /** Neutral text hierarchy, AA over `surface.paper`/`canvas` (ADR-023). */
+    ink: InkLadder;
+    /** Ink-alpha lines, legible on any ground (ADR-023). */
+    edge: EdgeLadder;
+    /** Ink-alpha interaction washes (ADR-023). */
+    wash: WashLadder;
 };
 export {};

package/lib/themes/Colors/Colors.ladder.d.ts

@@ -0,0 +1,98 @@
+import type { LadderGroups, LadderInput, Polarity, WashLadder } from './Colors.interface';
+/**
+ * Surface ladder — the mode-aware role layer for grounds, inks, edges and
+ * washes (APOLLION-DARK-MODE-ENGINE, ADR-023).
+ *
+ * Every role is derived from the contrast anchors (`baseLight` → canvas,
+ * `baseDark` → ink) in OKLch, keyed by the theme's **polarity**
+ * ({@link resolvePolarity}) — the same single switch that already drives
+ * `disabled`/`muted` and the ADR-012 state floors. `toDarkColors` flips the
+ * anchors, so the dark ladder falls out of the same formulas: paper is
+ * *lighter* than the canvas in both modes (tonal elevation), edges and washes
+ * are the primary ink at a fixed alpha (they work on any ground), and the
+ * halation floors keep the dark canvas off pure black and the dark ink off
+ * pure white.
+ *
+ * **Purity + idempotence (ADR-002 §9):** reads nothing external, does not
+ * mutate the input, same input → byte-equivalent output. Mirrored
+ * byte-for-byte in `@apollion-dsi/tokens` (`builders/ladder.ts`, Strangler
+ * Fig parity).
+ *
+ * @see ../../docs/adr/ADR-023-surface-ladder-mode-aware-elevation.md
+ * @see ../../../../docs/references/dark-mode-ladder-spec.md (derivation spec)
+ */
+/** OKLch lightness deltas from the canvas, per surface role. */
+export declare const LADDER_DELTAS: {
+    readonly sunken: -0.025;
+    readonly paper: 0.06;
+    readonly raised: 0.09;
+    readonly overlay: 0.12;
+};
+/**
+ * Halation floors: a dark canvas never reaches pure black (OLED smear / glare
+ * margin) and a dark primary ink never reaches pure white (glyph bloom for
+ * astigmatic readers).
+ */
+export declare const HALATION_FLOORS: {
+    readonly CANVAS_MIN_L: 0.13;
+    readonly INK_MAX_L: 0.95;
+};
+/** Mix ratios of `ink.primary` toward the canvas for the secondary inks. */
+export declare const INK_MIX: {
+    readonly secondary: 0.22;
+    readonly muted: 0.4;
+    readonly disabled: 0.6;
+};
+/**
+ * APCA `|Lc|` floors per ink role over `surface.paper` (WCAG 3 candidate
+ * tiers: 75 body, 60 secondary, 45 large/secondary text). WCAG 2's 4.5:1
+ * under-weights light-on-dark pairs — a muted dark-mode ink can pass 4.5:1 and
+ * still sit below Lc 45 — so the ink derivation clears BOTH metrics.
+ */
+export declare const INK_APCA_MIN: {
+    readonly primary: 75;
+    readonly secondary: 60;
+    readonly muted: 45;
+};
+/** Alpha of `ink.primary` per edge role (ink-alpha lines work on any ground). */
+export declare const EDGE_ALPHA: {
+    readonly hairline: 0.1;
+    readonly border: 0.2;
+    readonly strong: 0.32;
+};
+/** Alpha of `ink.primary` per wash role, per polarity (dark needs a stronger wash to be perceptible). */
+export declare const WASH_ALPHA: Readonly<Record<Polarity, Readonly<Record<keyof WashLadder, number>>>>;
+/**
+ * The theme's polarity — `'dark'` when white contrasts more than black
+ * against `baseLight` (the page ground), `'light'` otherwise (and without
+ * `baseLight`). Single source of truth for every mode-aware derivation.
+ */
+export declare function resolvePolarity(colors: LadderInput): Polarity;
+/** Opposite polarity — used by `invertForSurface` (negative = the other ladder). */
+export declare function oppositePolarity(polarity: Polarity): Polarity;
+/**
+ * Resolves the four ladder groups (`surface` / `ink` / `edge` / `wash`) for
+ * the given structural anchors.
+ *
+ * @param colors - Contrast anchors (+ `neutral` ramp for the light scrim).
+ * @param override - Optional verbatim override keyed by polarity
+ *   (`ColorsInput.ladder`): the entry matching the resolved polarity is
+ *   applied over the derived roles, never re-derived. Keyed by polarity so it
+ *   survives `toDarkColors`.
+ *
+ * @example
+ * ```ts
+ * const { surface, ink } = resolveSurfaceLadder({ baseLight: '#0b0b0b', baseDark: '#f9f9f7', deepLight: '#000' });
+ * surface.paper; // '#181818' — lighter than the #0b0b0b canvas
+ * ink.primary;   // '#eeeeec' — never pure white
+ * ```
+ */
+export declare function resolveSurfaceLadder(colors: LadderInput, override?: LadderInput['ladder']): LadderGroups;
+/**
+ * The ladder of the **opposite** polarity for the same theme — the canonical
+ * anchor swap (`baseLight↔baseDark`, `deepLight↔deepDark`, the same swap as
+ * `toDarkColors`) run through {@link resolveSurfaceLadder}. Used by
+ * `invertForSurface`: negative-on-light is the dark ladder, negative-on-dark
+ * the light one (closes the ADR-006 §3.6 E6 parking).
+ */
+export declare function resolveOppositeLadder(colors: LadderInput): LadderGroups;

package/lib/themes/Colors/Colors.presets.d.ts

@@ -54,6 +54,29 @@ export declare const OKABE_ITO: {
  * is preserved.
  */
 export declare function colorblindPalette(base?: ColorsInput): ColorsInput;
+/**
+ * **Canonical dark** transform (ADR-010) — swaps only the contrast/deep anchors
+ * (`baseLight↔baseDark`, `deepLight↔deepDark`); every other slot (brand,
+ * functional, feedback) passes through untouched. The engine is mode-aware by
+ * construction (ADR-012 state floors, ADR-018 `onLight`, `getContrastColor`/
+ * `isDarkSurface`), so every derived stop resolves correctly from the swapped
+ * anchors alone.
+ *
+ * Sibling of the accessibility presets above, but a different axis (mode, not
+ * a11y) — deliberately absent from {@link accessibilityPalettes}. Falls back to
+ * {@link defaultInputColors} **per missing anchor** (mirroring
+ * {@link highContrastPalette}), so a partial `base` still yields a dark theme
+ * distinct from light instead of degenerating to `undefined` anchors.
+ *
+ * @example
+ * ```ts
+ * const light = createTheme({ colors });
+ * const dark = createTheme({ colors: toDarkColors(colors) });
+ * ```
+ *
+ * @see ADR-010 (canonical dark contract) · ADR-019 (tokens pipeline parity)
+ */
+export declare function toDarkColors(base?: ColorsInput): ColorsInput;
 /**
  * Registry of accessibility presets keyed by name — handy for wiring a theme
  * dropdown without a manual `switch`.

package/lib/themes/Colors/index.d.ts

@@ -8,3 +8,5 @@ export * from './Colors.interface';
 export * from './Colors.helpers';
 export * from './Colors.props';
 export * from './Colors.presets';
+export * from './Colors.ladder';
+export { apcaContrast, apcaLuminance } from '../../vendors/Culori/apca';

package/lib/themes/Colors/index.esm.js

@@ -1 +1 @@
-import{a as v,b as w,c as x,d as y,e as z,f as A,g as B}from"../../chunks/chunk-3RNWYCCU.esm.js";import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u}from"../../chunks/chunk-E3MSXQXV.esm.js";import"../../chunks/chunk-TQJTHPA3.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{j as DISABLED_NEUTRAL_INDICES,a as HextoRgb,c as MIN_CONTRAST_AA,n as MIN_STATE_CONTRAST,h as NEUTRAL_TEXT_INDICES,z as OKABE_ITO,g as READABLE_TEXT_PALETTES,o as STATE_DELTA_L_JND,k as STRUCTURAL_NEUTRAL_INDICES,B as accessibilityPalettes,A as colorblindPalette,w as createColors,i as createReadableTextLayer,v as defaultInputColors,e as getColor,f as getContrastColor,b as getOppositeColor,x as grayscalePalette,y as highContrastPalette,t as mountActionColors,s as mountBaseColors,q as mountGreyscaleColors,u as mountMainColors,r as mountNeutralColors,p as mountSingleColor,d as readableColor,l as resolveDisabledNeutral,m as resolveStructuralNeutrals};
+import{a as P,b as Q,c as R,d as S,e as T,f as U,g as V,h as W}from"../../chunks/chunk-U525YXTZ.esm.js";import{a as F,b as G,c as H,d as I,e as J,f as K,g as L,h as M,i as N,j as O}from"../../chunks/chunk-STSRIPD6.esm.js";import{A as y,B as z,C as A,D as B,E as C,F as D,G as E,c as a,d as b,e as c,f as d,g as e,h as f,i as g,j as h,k as i,l as j,m as k,n as l,o as m,p as n,q as o,r as p,s as q,t as r,u as s,v as t,w as u,x as v,y as w,z as x}from"../../chunks/chunk-XVPUSCK5.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{n as DISABLED_NEUTRAL_INDICES,J as EDGE_ALPHA,G as HALATION_FLOORS,d as HextoRgb,I as INK_APCA_MIN,H as INK_MIX,F as LADDER_DELTAS,f as MIN_CONTRAST_AA,t as MIN_STATE_CONTRAST,l as NEUTRAL_TEXT_INDICES,T as OKABE_ITO,r as QUIET_NEUTRAL_INDICES,k as READABLE_TEXT_PALETTES,u as STATE_DELTA_L_JND,o as STRUCTURAL_NEUTRAL_INDICES,K as WASH_ALPHA,W as accessibilityPalettes,b as apcaContrast,a as apcaLuminance,x as clampLightness,U as colorblindPalette,g as contrastRatio,Q as createColors,m as createReadableTextLayer,P as defaultInputColors,i as getColor,j as getContrastColor,e as getOppositeColor,R as grayscalePalette,S as highContrastPalette,v as isDarkSurface,c as mixOklch,D as mountActionColors,C as mountBaseColors,A as mountGreyscaleColors,E as mountMainColors,B as mountNeutralColors,z as mountSingleColor,M as oppositePolarity,h as readableColor,p as resolveDisabledNeutral,O as resolveOppositeLadder,L as resolvePolarity,s as resolveQuietPalette,q as resolveStructuralNeutrals,N as resolveSurfaceLadder,w as shiftLightness,V as toDarkColors,y as toRgbaString};

package/lib/themes/Component/Component.interface.d.ts

@@ -49,6 +49,19 @@ export interface ButtonSizeTokens {
     px: SpacingAlias;
     borderRadius: BorderRadiusKey;
 }
+/**
+ * Defaults of `Text` when the call site omits the prop
+ * (`theme.component.text.*`, APOLLION-COMPONENT-TEXT). Explicit props and the
+ * `variant` bundle still win; these fill the gaps.
+ */
+export interface TextTokens {
+    /** Weight of bare `<Text>` (the `regular` step of the ladder by default). */
+    fontWeight: FontWeightKey;
+    /** Optional default size alias; variants keep their own sizes. */
+    fontSize?: FontSizeKey;
+    /** Optional default ink token (`ink.primary` by default). */
+    color?: string;
+}
 /** Per-size tokens of the `InputSelect` (`theme.component.inputSelect.size.*`). */
 export interface InputSelectSizeTokens {
     py: SpacingAlias;
@@ -82,12 +95,17 @@ export interface ComponentTokensLayer {
     inputSelect: {
         size: Record<'expansive' | 'medium' | 'compact' | 'micro', InputSelectSizeTokens>;
     };
+    text: TextTokens;
 }
 /** Deep-partial consumer override shape accepted by `createComponentTokens`. */
+type SizedComponents = Exclude<keyof ComponentTokensLayer, 'text'>;
 export type ComponentTokensInput = {
-    [K in keyof ComponentTokensLayer]?: {
+    [K in SizedComponents]?: {
         size?: {
             [S in keyof ComponentTokensLayer[K]['size']]?: Partial<ComponentTokensLayer[K]['size'][S]>;
         };
     };
+} & {
+    text?: Partial<TextTokens>;
 };
+export {};

package/lib/themes/Component/index.d.ts

@@ -14,5 +14,5 @@
  *
  * @see ../../../docs/adr/ADR-020-component-token-tier.md
  */
-export type { BorderRadiusKey, ButtonSizeTokens, ComponentTokensInput, ComponentTokensLayer, FontWeightKey, InputSelectSizeTokens, InputSizeTokens, LineHeightKey, SelectSizeTokens, SwitchSizeTokens, } from './Component.interface';
+export type { BorderRadiusKey, ButtonSizeTokens, ComponentTokensInput, ComponentTokensLayer, FontWeightKey, InputSelectSizeTokens, InputSizeTokens, LineHeightKey, SelectSizeTokens, SwitchSizeTokens, TextTokens, } from './Component.interface';
 export { createComponentTokens } from './Component.helpers';

package/lib/themes/Component/index.esm.js

@@ -1 +1 @@
-import{b as a}from"../../chunks/chunk-7EGX7BMB.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createComponentTokens};
+import{b as a}from"../../chunks/chunk-BERIBF3O.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createComponentTokens};

package/lib/themes/Deep/index.esm.js

@@ -1 +1 @@
-import{a}from"../../chunks/chunk-OWMRURZT.esm.js";import"../../chunks/chunk-3RNWYCCU.esm.js";import"../../chunks/chunk-E3MSXQXV.esm.js";import"../../chunks/chunk-TQJTHPA3.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createDeepTheme};
+import{a}from"../../chunks/chunk-YZQXTNVA.esm.js";import"../../chunks/chunk-U525YXTZ.esm.js";import"../../chunks/chunk-STSRIPD6.esm.js";import"../../chunks/chunk-XVPUSCK5.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createDeepTheme};

package/lib/themes/Depth/Depth.props.d.ts

@@ -3,4 +3,18 @@ import { ColorsThemeInterface } from '../Colors';
 export declare const levelValues: {
     [key in DepthAliasTypes]: string;
 };
+/**
+ * Shadow ink per polarity (ADR-023): light keeps the historical
+ * `neutral.180 @ 0.15`; dark drops to the black anchor (`deepLight` after the
+ * canonical swap) at a heavier alpha — a tinted-neutral shadow is a pale glow
+ * on a dark ground, and the tonal ladder step carries the elevation instead.
+ */
+export declare const DEPTH_SHADOW: {
+    readonly light: {
+        readonly alpha: 0.15;
+    };
+    readonly dark: {
+        readonly alpha: 0.4;
+    };
+};
 export declare const createDeth: (colors: ColorsThemeInterface) => (value: DepthInterface) => string;

package/lib/themes/Depth/index.esm.js

@@ -1 +1 @@
-import{a,b}from"../../chunks/chunk-6X6WKZ3Y.esm.js";import"../../chunks/chunk-TQJTHPA3.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as createDeth,a as levelValues};
+import"../../chunks/chunk-Z7GJDO5T.esm.js";import{a,b,c}from"../../chunks/chunk-BFABFZI7.esm.js";import"../../chunks/chunk-U525YXTZ.esm.js";import"../../chunks/chunk-STSRIPD6.esm.js";import"../../chunks/chunk-XVPUSCK5.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as DEPTH_SHADOW,c as createDeth,a as levelValues};

package/lib/themes/Font/Font.interface.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Brand-level origin of the weight ladder (APOLLION-TYPE-WEIGHT). Analogous
+ * to `dimension` for size: the four semantic weights (`light` / `regular` /
+ * `bold` / `stronger`) resolve to CSS numbers from the origin, so a brand
+ * that reads lighter or heavier overall says it once instead of remapping
+ * `font.fontWeight` by hand. `regular` is the stock ladder.
+ */
+export type TypeWeight = 'light' | 'regular' | 'stronger';
 /** Token keys of the typographic size scale (ADR-011). */
 export type FontSizeKey = 'nano' | 'micro' | 'xs' | 'small' | 'medium' | 'large' | 'xl' | 'xxl' | 'giant' | 'colossal' | 'gargantua';
 /**

package/lib/themes/Font/Font.props.d.ts

@@ -1,5 +1,12 @@
-import { FontInput, FontThemeInterface } from './Font.interface';
+import { FontInput, FontThemeInterface, TypeWeight } from './Font.interface';
 import { Dimension } from '../Dimension';
+/**
+ * Weight ladder per {@link TypeWeight} origin. `regular` is byte-identical to
+ * the stock `defaultInputFont.fontWeight` (no visual change unless a brand
+ * opts in); `light` starts the ladder one step lighter, `stronger` one step
+ * heavier, keeping four distinct steps.
+ */
+export declare const TYPE_WEIGHT_LADDERS: Record<TypeWeight, FontInput['fontWeight']>;
 export declare const defaultInputFont: FontInput;
 /**
  * Build the resolved `theme.font` from a {@link FontInput}.
@@ -27,4 +34,4 @@ export declare const defaultInputFont: FontInput;
  * @see ./Spacing/Spacing.props.ts#createSpacing (mirrored dimension semantics)
  * @see ../../docs/adr/ADR-011-typography-fixed-root-dimension-rem.md §3.2
  */
-export declare function createFont({ fontSize: baseScale, ...rest }: FontInput, dimension?: Dimension): FontThemeInterface;
+export declare function createFont({ fontSize: baseScale, ...rest }: FontInput, dimension?: Dimension, typeWeight?: TypeWeight): FontThemeInterface;

package/lib/themes/Font/index.esm.js

@@ -1 +1 @@
-import{a,b}from"../../chunks/chunk-RU6QRCR7.esm.js";import"../../chunks/chunk-JOKVE3IX.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as createFont,a as defaultInputFont};
+import{a,b,c}from"../../chunks/chunk-P7RR4ZHS.esm.js";import"../../chunks/chunk-JOKVE3IX.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as TYPE_WEIGHT_LADDERS,c as createFont,b as defaultInputFont};

package/lib/themes/Foundation/Foundation.interface.d.ts

@@ -27,6 +27,9 @@
  * - `bg.warning`   ← `semantic.color.feedback.warning.bg`
  * - `bg.info`      ← `semantic.color.feedback.information.bg`
  * - `bg.brand`     ← `semantic.color.brand.first.default.surface` (brand color / `main`)
+ * - `bg.canvas` · `bg.sunken` · `bg.paper` · `bg.raised` · `bg.overlay`
+ *                  ← `semantic.color.surface.<role>.bg` (ADR-023 surface ladder,
+ *                  mode-aware: `paper` is lighter than `canvas` in both polarities)
  */
 export interface FoundationBg {
     primary: string;
@@ -37,6 +40,11 @@ export interface FoundationBg {
     warning: string;
     info: string;
     brand: string;
+    canvas: string;
+    sunken: string;
+    paper: string;
+    raised: string;
+    overlay: string;
 }
 /**
  * Short aliases for text colors "on" a Foundation background. The suffix
@@ -58,6 +66,24 @@ export interface FoundationText {
     onMain: string;
     onOpposite: string;
     onComplementary: string;
+    /** Neutral text hierarchy over the surface ladder (ADR-023) — AA over `bg.paper`/`bg.canvas`. */
+    primary: string;
+    secondary: string;
+    muted: string;
+    /** WCAG-exempt disabled ink (no contrast floor). */
+    disabled: string;
+}
+/**
+ * Ink-alpha lines (ADR-023) — legible on any ground of the ladder. Named
+ * `edge` (not `border`) to stay clear of the composite `border` token group.
+ * - `edge.hairline` ← `semantic.color.edge.hairline` (dividers, card outline)
+ * - `edge.border`   ← `semantic.color.edge.border`   (inputs, ≥ 3:1 over paper)
+ * - `edge.strong`   ← `semantic.color.edge.strong`   (emphasis rules)
+ */
+export interface FoundationEdge {
+    hairline: string;
+    border: string;
+    strong: string;
 }
 /**
  * Short spacing aliases. They map to Semantic spacing while preserving the
@@ -86,5 +112,6 @@ export interface FoundationSpacing {
 export interface FoundationLayer {
     bg: FoundationBg;
     text: FoundationText;
+    edge: FoundationEdge;
     spacing: FoundationSpacing;
 }

package/lib/themes/Foundation/index.esm.js

@@ -1 +1 @@
-import"../../chunks/chunk-CWRWYU7D.esm.js";import{a}from"../../chunks/chunk-3EOSES4S.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createFoundation};
+import"../../chunks/chunk-CWRWYU7D.esm.js";import{a}from"../../chunks/chunk-PFLBU7HG.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createFoundation};

package/lib/themes/GlobalStyle/GlobalStyle.d.ts

@@ -1,7 +1,25 @@
+import React from 'react';
 import { DefaultTheme, RuleSet } from '../../vendors/StyledComponents';
-export declare const GlobalStyleComponent: import("react").NamedExoticComponent<import("styled-components").ExecutionProps & {
+interface GlobalStyleProps {
     theme: DefaultTheme;
     extend?: RuleSet<{
         theme: DefaultTheme;
     }>;
-}>;
+    /** `<html>` attribute carrying the resolved mode (from the provider). */
+    $attribute?: string;
+    /** Preference is `'system'` → also follow `prefers-color-scheme` when no attribute is set yet. */
+    $system?: boolean;
+}
+export declare const GlobalStyleComponent: React.NamedExoticComponent<import("styled-components").ExecutionProps & GlobalStyleProps>;
+/**
+ * Global stylesheet of the Design System: normalize, fixed root, the
+ * `color-scheme` rules that drive the mode bridge, and the page ground +
+ * primary ink from the surface ladder. Reads the provider (when present) for
+ * the attribute name and the `'system'` preference.
+ */
+export declare function GlobalStyle(props: {
+    extend?: RuleSet<{
+        theme: DefaultTheme;
+    }>;
+}): React.ReactElement;
+export {};

package/lib/themes/GlobalStyle/index.d.ts

@@ -1,4 +1,8 @@
 /**
  * Public barrel for the `GlobalStyle` module.
+ *
+ * `GlobalStyle` reads the provider (attribute name, `'system'` preference)
+ * and renders `GlobalStyleComponent`; the raw component stays exported for
+ * consumers that render it outside a provider.
  */
-export { GlobalStyleComponent as GlobalStyle } from './GlobalStyle';
+export { GlobalStyle, GlobalStyleComponent } from './GlobalStyle';

package/lib/themes/GlobalStyle/index.esm.js

@@ -1 +1 @@
-import{a}from"../../chunks/chunk-T6ZB656A.esm.js";import"../../chunks/chunk-APD22JEO.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as GlobalStyle};
+import{a,b}from"../../chunks/chunk-MPKFMMCD.esm.js";import"../../chunks/chunk-BFEEE3TE.esm.js";import"../../chunks/chunk-TLIKQFOT.esm.js";import"../../chunks/chunk-IA234JY2.esm.js";import"../../chunks/chunk-TG5BCBO4.esm.js";import"../../chunks/chunk-CCONLRLQ.esm.js";import"../../chunks/chunk-6XX3UO2Y.esm.js";import"../../chunks/chunk-BERIBF3O.esm.js";import"../../chunks/chunk-YZQXTNVA.esm.js";import"../../chunks/chunk-Z7GJDO5T.esm.js";import"../../chunks/chunk-P7RR4ZHS.esm.js";import"../../chunks/chunk-JOKVE3IX.esm.js";import"../../chunks/chunk-CWRWYU7D.esm.js";import"../../chunks/chunk-PFLBU7HG.esm.js";import"../../chunks/chunk-IPANNHV3.esm.js";import"../../chunks/chunk-3DUB5C4Z.esm.js";import"../../chunks/chunk-KT6QQ3UJ.esm.js";import"../../chunks/chunk-3KOZ6RXR.esm.js";import"../../chunks/chunk-VMIXRIQ2.esm.js";import"../../chunks/chunk-JQ66DKSQ.esm.js";import"../../chunks/chunk-YC44Q5HI.esm.js";import"../../chunks/chunk-BFABFZI7.esm.js";import"../../chunks/chunk-U525YXTZ.esm.js";import"../../chunks/chunk-STSRIPD6.esm.js";import"../../chunks/chunk-XVPUSCK5.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-AXUWC2WH.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as GlobalStyle,a as GlobalStyleComponent};

package/lib/themes/Ground/Ground.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+export interface GroundProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * The ground this subtree sits on — a `theme.colors` token
+     * (`'surface.paper'`, `'main'`, `'neutral.10'`) or a runtime CSS color.
+     * Painted as the element's background and published as the ground
+     * custom properties for every descendant ink.
+     */
+    bg: string;
+    /** Paint the background (default) or only publish the ground channel (`false`). */
+    paint?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * Escape hatch of the ground channel (D7): declares the ground of a subtree
+ * the Design System did not paint itself (a consumer `styled.div` with its
+ * own background, a third-party surface). Components painted through
+ * `bgColor` publish the channel automatically — reach for `<Ground>` only
+ * when the ground is painted outside the factories.
+ *
+ * @example
+ * ```tsx
+ * <Ground bg="#0b2a3a" paint={false} style={{ background: 'url(hero.jpg)' }}>
+ *   <Text>Readable over the photo's average tone</Text>
+ * </Ground>
+ * ```
+ */
+export declare function Ground({ bg, paint, style, children, ...rest }: GroundProps): React.ReactElement;