@apollion-dsi/core 5.6.0 → 5.7.0

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

@@ -0,0 +1,60 @@
+import type { Theme } from '../ThemeProvider/ThemeProvider.interface';
+/**
+ * Ground channel (APOLLION-DARK-MODE-ENGINE, decision D7 — ADR-024 §ground).
+ *
+ * Every painted ground (`bgColor`, `<Ground>`, the page canvas) emits a set
+ * of CSS custom properties computed **in JS against the ground's literal**
+ * — in both modes (`light-dark()` pairs): the neutral ink hierarchy, the
+ * readable accent inks, the black/white contrast ink and the ink-alpha
+ * edges. Inks consume `var(--apollion-on-ground-…)` with a canvas-resolved
+ * fallback, so the CSS cascade resolves "the nearest painted ancestor" for
+ * free — no React context, no wrappers, works for consumer containers too.
+ *
+ * Contract: every value is AA (4.5) over the ground it was computed for
+ * (disabled excepted); `auditGroundVars` asserts it in tests.
+ */
+/** Prefix of every ground custom property. */
+export declare const GROUND_VAR_PREFIX = "--apollion-on-ground";
+/** Neutral ink roles published per ground. */
+export declare const GROUND_INK_ROLES: readonly ["primary", "secondary", "muted", "disabled"];
+export type GroundInkRole = (typeof GROUND_INK_ROLES)[number];
+/** Token the root ground (page canvas) is computed from. */
+export declare const ROOT_GROUND_TOKEN = "surface.canvas";
+/** Builds a ground custom-property name: `groundVar('ink', 'primary')` → `--apollion-on-ground-ink-primary`. */
+export declare function groundVar(...path: Array<string | number>): string;
+/** `var(--apollion-on-ground-…, fallback)` reference. */
+export declare function groundVarRef(fallback: string, ...path: Array<string | number>): string;
+/**
+ * Maps an ink token to its ground-relative custom property path, or `null`
+ * when the token is not ground-relative (fills, borders, raw colors):
+ * - `ink.<role>`            → `ink-<role>`
+ * - `<palette>` (base)      → `tx-<palette>` (readable accent over the ground)
+ * - `neutral.<120..180>`    → `neutral-<index>` (text side of the ramp)
+ */
+export declare function groundInkPath(token: string): string[] | null;
+/**
+ * A translucent ground (`wash.*`, `rgba(…, 0.2)`, `transparent`) composites
+ * over whatever is behind it — its inks are the PARENT ground's inks. Such
+ * grounds must not publish the channel (the cascade keeps the ancestor's).
+ */
+export declare function isOpaqueGround(literalGround: string): boolean;
+/**
+ * The ground custom properties for `ground` (a `theme.colors` dot-path token
+ * or a runtime CSS color), each side computed on the matching literal table
+ * and paired with `light-dark()`. Pure; memoize at the call site if hot.
+ */
+export declare function groundVars(theme: Theme, ground: string): Record<string, string>;
+/** One failing pair found by {@link auditGroundVars}. */
+export interface GroundAuditFailure {
+    ground: string;
+    mode: 'light' | 'dark';
+    variable: string;
+    ink: string;
+    ratio: number;
+}
+/**
+ * Test helper (D7 guarantee): for every ground token, computes the ground
+ * inks on both literal tables and reports every pair under the floor.
+ * `disabled` and `edge-*` are WCAG-exempt (non-text / disabled) and skipped.
+ */
+export declare function auditGroundVars(theme: Theme, grounds: readonly string[], minRatio?: number): GroundAuditFailure[];

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

@@ -0,0 +1,7 @@
+/**
+ * Public barrel for the `Ground` module — the ground channel (D7, ADR-024):
+ * every painted ground publishes `--apollion-on-ground-*` custom properties
+ * computed against its own literal, in both modes.
+ */
+export * from './Ground.helpers';
+export * from './Ground';

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

@@ -0,0 +1 @@
+import{a as j}from"../../chunks/chunk-HPM5AX5Z.esm.js";import{a,b,c,d,e,f,g,h,i}from"../../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 GROUND_INK_ROLES,a as GROUND_VAR_PREFIX,j as Ground,c as ROOT_GROUND_TOKEN,i as auditGroundVars,f as groundInkPath,d as groundVar,e as groundVarRef,h as groundVars,g as isOpaqueGround};

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

@@ -0,0 +1,64 @@
+import type { A11yMode, CookieAdapterOptions, ModeDocumentOptions, ModePreference, ModeScriptOptions, ModeStorage, PersistOption, ResolvedMode } from './Mode.interface';
+/**
+ * Mode engine primitives (APOLLION-DARK-MODE-ENGINE, ADR-024) — pure,
+ * dependency-free helpers shared by `ApollionProvider`, the pre-paint script
+ * and server-side recipes (importable from a Next.js `app/layout.tsx`).
+ */
+/** Default storage key of the mode preference; the a11y preset lives under `${key}-a11y`. */
+export declare const MODE_STORAGE_KEY = "apollion-mode";
+/** Default `<html>` attribute carrying the resolved mode. */
+export declare const MODE_ATTRIBUTE = "data-apollion-mode";
+/** Default `<html>` attribute carrying the a11y preset. */
+export declare const A11Y_ATTRIBUTE = "data-apollion-a11y";
+/** `prefers-color-scheme` query the engine follows for `'system'`. */
+export declare const DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+/** Storage key of the a11y preset for a given mode key. */
+export declare function a11yStorageKey(storageKey?: string): string;
+/** Type guard — a valid persisted/URL/cookie mode value. */
+export declare function isModePreference(value: unknown): value is ModePreference;
+/** Type guard — a valid a11y preset name. */
+export declare function isA11yMode(value: unknown): value is Exclude<A11yMode, null>;
+/** SSR-safe read of the OS preference (`false` without `window`/`matchMedia`). */
+export declare function prefersDarkScheme(): boolean;
+/** Resolves a preference into the mode that renders. */
+export declare function resolveMode(preference: ModePreference, systemDark: boolean): ResolvedMode;
+/** `localStorage`-backed adapter; silent on private mode / SSR. */
+export declare function localStorageAdapter(): ModeStorage;
+/** Parses a `Cookie` header / `document.cookie` string for one value. */
+export declare function readCookieValue(cookieHeader: string | null | undefined, name: string): string | null;
+/** `document.cookie`-backed adapter — the server can read the same cookie (`readModeFromCookie`). */
+export declare function cookieAdapter(options?: CookieAdapterOptions): ModeStorage;
+/** Maps the provider's `persist` prop to a storage adapter (`null` = off). */
+export declare function resolveStorage(persist: PersistOption | undefined): ModeStorage | null;
+/**
+ * Server-side read of the persisted mode preference from a `Cookie` header
+ * (App Router: `headers().get('cookie')`; Pages Router: `req.headers.cookie`).
+ * Invalid/missing → `null` (the caller falls back to `defaultMode`).
+ */
+export declare function readModeFromCookie(cookieHeader: string | null | undefined, name?: string): ModePreference | null;
+/** Server-side read of the persisted a11y preset (see {@link readModeFromCookie}). */
+export declare function readA11yFromCookie(cookieHeader: string | null | undefined, name?: string): A11yMode;
+/**
+ * Writes the resolved mode + a11y preset on the document element
+ * (`data-apollion-mode`, `data-apollion-a11y`, `style.colorScheme`) so native
+ * controls, scrollbars and `light-dark()` follow the engine. No-op without an element.
+ */
+export declare function syncDocumentMode(element: HTMLElement | null | undefined, state: {
+    mode: ResolvedMode;
+    a11y: A11yMode;
+}, options?: ModeDocumentOptions): void;
+/** Removes what {@link syncDocumentMode} wrote (provider unmount). */
+export declare function clearDocumentMode(element: HTMLElement | null | undefined, options?: ModeDocumentOptions): void;
+/**
+ * Pre-paint inline script (no-flash): reads the persisted preference
+ * (localStorage or cookie), resolves `'system'` through `matchMedia`, and
+ * writes the same attributes the provider will write — before the first
+ * paint, outside React's tree (so hydration never sees a mismatch). Every
+ * option is JSON-escaped; the body is wrapped in `try/catch`.
+ *
+ * @example
+ * ```tsx
+ * <script dangerouslySetInnerHTML={{ __html: getModeScript({ persist: 'cookie' }) }} />
+ * ```
+ */
+export declare function getModeScript(options?: ModeScriptOptions): string;

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

@@ -0,0 +1,54 @@
+import type { AccessibilityPreset } from '../Colors/Colors.presets';
+/**
+ * What the user asked for: a fixed mode or "follow the operating system".
+ * Persisted as-is (`'system'` stays `'system'`), resolved per render.
+ */
+export type ModePreference = 'light' | 'dark' | 'system';
+/** What actually renders — the preference with `'system'` resolved. */
+export type ResolvedMode = 'light' | 'dark';
+/**
+ * Accessibility axis — orthogonal to the mode (decision D5): any preset
+ * composes with either polarity (`dark` + `colorblind`, `light` +
+ * `high-contrast`, …). `null` = the stock palette.
+ */
+export type A11yMode = AccessibilityPreset | null;
+/**
+ * Minimal storage contract for the mode/a11y preferences. `write(key, null)`
+ * clears the entry. Implementations must never throw (private mode, SSR).
+ */
+export interface ModeStorage {
+    read(key: string): string | null;
+    write(key: string, value: string | null): void;
+}
+/**
+ * Persistence option of the provider: off, the two built-in adapters, or a
+ * custom {@link ModeStorage} (e.g. a server session).
+ */
+export type PersistOption = false | 'localStorage' | 'cookie' | ModeStorage;
+/** Cookie adapter tuning (`cookieAdapter`). */
+export interface CookieAdapterOptions {
+    /** Max-age in seconds. Default: one year. */
+    maxAge?: number;
+    /** Cookie path. Default `'/'`. */
+    path?: string;
+    /** SameSite policy. Default `'Lax'`. */
+    sameSite?: 'Lax' | 'Strict' | 'None';
+    /** Mark the cookie `Secure`. Default: `true` when `sameSite === 'None'`. */
+    secure?: boolean;
+}
+/** Attribute names the engine writes on `<html>` (`syncDocumentMode`). */
+export interface ModeDocumentOptions {
+    /** Resolved-mode attribute. Default `data-apollion-mode`. */
+    attribute?: string;
+    /** A11y-preset attribute. Default `data-apollion-a11y`. */
+    a11yAttribute?: string;
+}
+/** Options of `getModeScript` — the pre-paint `<head>` script (no-flash). */
+export interface ModeScriptOptions extends ModeDocumentOptions {
+    /** Storage key the provider persists under. Default `apollion-mode`. */
+    storageKey?: string;
+    /** Where the preference lives. Default `'localStorage'`. */
+    persist?: 'localStorage' | 'cookie';
+    /** Preference when nothing is stored. Default `'system'`. */
+    defaultMode?: ModePreference;
+}

package/lib/themes/Mode/ModeScript.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { ModeScriptOptions } from './Mode.interface';
+/**
+ * Pre-paint mode script as a `<head>` element — drop it before any stylesheet
+ * so the resolved mode (and the a11y preset) reach `<html>` before the first
+ * paint. Pair it with `ApollionProvider persist` using the same `storageKey`.
+ *
+ * @example
+ * ```tsx
+ * // Next.js App Router — app/layout.tsx
+ * <head><ApollionModeScript persist="cookie" /></head>
+ * ```
+ */
+export declare function ApollionModeScript(props: ModeScriptOptions): React.ReactElement;

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

@@ -0,0 +1,9 @@
+/**
+ * Public barrel for the `Mode` module (APOLLION-DARK-MODE-ENGINE, ADR-024).
+ *
+ * Dependency-free: importable from server code (`app/layout.tsx`, loaders)
+ * for `readModeFromCookie` / `getModeScript`.
+ */
+export * from './Mode.interface';
+export * from './Mode.helpers';
+export * from './ModeScript';

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

@@ -0,0 +1 @@
+import{a as s}from"../../chunks/chunk-2XTVIQMG.esm.js";import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r}from"../../chunks/chunk-TLIKQFOT.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{c as A11Y_ATTRIBUTE,s as ApollionModeScript,d as DARK_SCHEME_QUERY,b as MODE_ATTRIBUTE,a as MODE_STORAGE_KEY,e as a11yStorageKey,q as clearDocumentMode,l as cookieAdapter,r as getModeScript,g as isA11yMode,f as isModePreference,j as localStorageAdapter,h as prefersDarkScheme,o as readA11yFromCookie,k as readCookieValue,n as readModeFromCookie,i as resolveMode,m as resolveStorage,p as syncDocumentMode};

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

@@ -1,5 +1,5 @@
-import type { SemanticLayer } from './Semantic.interface';
-import type { ColorsThemeInterface } from '../Colors/Colors.interface';
+import type { SemanticColor, SemanticLayer } from './Semantic.interface';
+import type { ColorsThemeInterface, LadderGroups } from '../Colors/Colors.interface';
 import type { SpacingThemeInterface } from '../Spacing/Spacing.interface';
 /**
  * Subset of the structural `Theme` needed to derive the Semantic layer.
@@ -48,4 +48,11 @@ export interface CreateSemanticInput {
  * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3, §5, §9
  * @see ../../docs/CONCEPTS.md §2 Layer Cake
  */
+/**
+ * Surface-ladder slice of Semantic (ADR-023): `surface.*` pairs + `ink.*` +
+ * `edge.*`, read from the structural groups assembled by `createColors` (or
+ * from an explicit ladder — `invertForSurface` passes the opposite polarity's).
+ * Falls back to the anchors for degenerate inputs (jsdom-unreachable paths).
+ */
+export declare function ladderSemantic(colors: CreateSemanticInput['colors'], ladder?: Pick<LadderGroups, 'surface' | 'ink' | 'edge'>): Pick<SemanticColor, 'surface' | 'ink' | 'edge'>;
 export declare function createSemantic(theme: CreateSemanticInput): SemanticLayer;

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

@@ -86,6 +86,31 @@ export interface SemanticColorBrand {
     second: SemanticBrandTokens;
     third: SemanticBrandTokens;
 }
+/**
+ * Surface ladder as bg/text-on pairs (ADR-023). `txtOn` is `ink.primary`,
+ * AA over every ground of the ladder by construction. Maps to
+ * `theme.colors.surface.*` at the structural level.
+ */
+export interface SemanticColorSurface {
+    canvas: SemanticBgPair;
+    sunken: SemanticBgPair;
+    paper: SemanticBgPair;
+    raised: SemanticBgPair;
+    overlay: SemanticBgPair;
+}
+/** Neutral text hierarchy (ADR-023). Maps to `theme.colors.ink.*`. */
+export interface SemanticColorInk {
+    primary: string;
+    secondary: string;
+    muted: string;
+    disabled: string;
+}
+/** Ink-alpha lines (ADR-023). Maps to `theme.colors.edge.*`. */
+export interface SemanticColorEdge {
+    hairline: string;
+    border: string;
+    strong: string;
+}
 /**
  * Color layer of Semantic.
  */
@@ -93,6 +118,9 @@ export interface SemanticColor {
     feedback: SemanticColorFeedback;
     interface: SemanticColorInterface;
     brand: SemanticColorBrand;
+    surface: SemanticColorSurface;
+    ink: SemanticColorInk;
+    edge: SemanticColorEdge;
 }
 /**
  * Spacing pre-resolved into a CSS string (`'8px'`, `'1rem'`, etc.), generated

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

@@ -1 +1 @@
-import{a}from"../../chunks/chunk-2R6XFFSQ.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 createSemantic};
+import"../../chunks/chunk-IA234JY2.esm.js";import{b as a}from"../../chunks/chunk-6XX3UO2Y.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 createSemantic};

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

@@ -1 +1 @@
-import{a as b}from"../../chunks/chunk-7AFAO7ZS.esm.js";import{a}from"../../chunks/chunk-BRXIFPWB.esm.js";import"../../chunks/chunk-3EOSES4S.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-APD22JEO.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as SurfaceProvider,a as invertForSurface};
+import{a as b}from"../../chunks/chunk-4ZHLV35P.esm.js";import{a}from"../../chunks/chunk-CCONLRLQ.esm.js";import"../../chunks/chunk-6XX3UO2Y.esm.js";import"../../chunks/chunk-PFLBU7HG.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 SurfaceProvider,a as invertForSurface};

package/lib/themes/ThemeProvider/ThemeProvider.d.ts

@@ -1,16 +1,22 @@
 import React from 'react';
 import { ApollionProviderInterface, ApollionThemeContext } from './ThemeProvider.interface';
 /**
- * Reads the active theme and the current mode (`light`/`dark`), and toggles
- * the mode from within any component under the `ApollionProvider`.
+ * Reads the active theme and the mode engine state, and drives both axes —
+ * `setMode` (light / dark / system) and `setA11y` (grayscale / high-contrast /
+ * colorblind / null) — from within any component under the `ApollionProvider`.
  *
  * @throws when used outside an `ApollionProvider`.
  *
  * @example
  * ```tsx
- * const { themeMode, toggleTheme } = useApollionTheme();
- * <Button text={`Mode: ${themeMode}`} onClick={() => toggleTheme()} />
+ * const { resolvedMode, setMode, a11y, setA11y } = useApollionTheme();
+ * <Button text={`Mode: ${resolvedMode}`} onClick={() => setMode(resolvedMode === 'dark' ? 'light' : 'dark')} />
  * ```
  */
 export declare function useApollionTheme(): ApollionThemeContext;
+/**
+ * Optional variant of {@link useApollionTheme} — `null` outside a provider.
+ * Used by `GlobalStyle` and the ground context, which must also render without one.
+ */
+export declare function useApollionThemeOptional(): ApollionThemeContext | null;
 export declare const ApollionProvider: React.FC<ApollionProviderInterface>;

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

@@ -7,8 +7,9 @@ import { ComponentTokensInput, ComponentTokensLayer } from '../Component';
 import { DeepThemeInterface } from '../Deep';
 import { DepthThemeInterface } from '../Depth';
 import type { Dimension } from '../Dimension';
-import { FontInput, FontThemeInterface } from '../Font';
+import { FontInput, FontThemeInterface, TypeWeight } from '../Font';
 import { FoundationLayer } from '../Foundation';
+import type { A11yMode, ModePreference, PersistOption, ResolvedMode } from '../Mode/Mode.interface';
 import { SemanticLayer } from '../Semantic';
 import { SpacingInput, SpacingThemeInterface } from '../Spacing';
 import type { SurfaceMode } from '../Surface';
@@ -27,6 +28,13 @@ export interface ThemeInputsInterface {
      * @see ../Dimension/Dimension.props.ts (DIMENSION_MULTIPLIERS calibration)
      */
     dimension?: Dimension;
+    /**
+     * Brand-level origin of the weight ladder (`light` / `regular` /
+     * `stronger`). Resolves `font.fontWeight` from a table instead of asking
+     * the consumer for raw 300/400/… numbers; `regular` is the stock ladder.
+     * Per-call-site `fontWeight` still overrides.
+     */
+    typeWeight?: TypeWeight;
     /**
      * Component token tier overrides (ADR-020). Deep-merged over the
      * defaults — override a single size of a single component without
@@ -82,6 +90,17 @@ export type Theme = {
      * @see ../../docs/adr/ADR-020-component-token-tier.md
      */
     component: ComponentTokensLayer;
+    /**
+     * Mode bridge (ADR-024): the literal light/dark pair behind a projected
+     * theme. Present on every theme the `ApollionProvider` hands out — the
+     * styled tree gets `light-dark()` pairs, `useApollionTheme().theme` gets the
+     * literal of the resolved mode, both tagged with the pair. Engine math
+     * uses `forModes(theme, fn)` to compute on both tables.
+     */
+    modes?: {
+        light: Theme;
+        dark: Theme;
+    };
 };
 export type ThemeMode = 'light' | 'dark';
 export interface ApollionProviderInterface {
@@ -135,23 +154,86 @@ export interface ApollionProviderInterface {
      */
     colors?: ColorsInput;
     /**
-     * When `true` (and the mode is uncontrolled), observes the operating
-     * system's `prefers-color-scheme` to pick the initial `themeMode` and react
-     * to runtime changes. SSR-safe (no-op when there is no `window`).
+     * Mode preference — **controlled**. `'system'` follows `prefers-color-scheme`
+     * (and reacts to runtime changes); `'light'`/`'dark'` pin the mode. When set,
+     * the provider ignores its internal state: the parent is the source of truth
+     * and `setMode` only fires `onModeChange`. Added in 5.7.0 (ADR-024).
+     */
+    mode?: ModePreference;
+    /**
+     * Initial mode preference — **uncontrolled**. Restored from `persist` when a
+     * value is stored. `'system'` = follow the OS.
+     *
+     * @default 'light' (`'system'` when the legacy `useSystemPreference` is on)
+     */
+    defaultMode?: ModePreference;
+    /**
+     * SSR contract: the mode the server rendered with (e.g. from
+     * `readModeFromCookie`). The first client render uses the same value —
+     * hydration never mismatches — and a `'system'` preference is corrected
+     * from `matchMedia` before paint. Without it the client resolves the OS
+     * preference on the first render (fine for client-only apps).
+     */
+    initialMode?: ResolvedMode;
+    /** Fires on every `setMode` with the new **preference** (`'system'` stays `'system'`). */
+    onModeChange?: (mode: ModePreference) => void;
+    /**
+     * Persist the preferences (`mode` under `storageKey`, `a11y` under
+     * `` `${storageKey}-a11y` ``): `'localStorage'`, `'cookie'` (readable by the
+     * server via `readModeFromCookie`), or a custom `ModeStorage` adapter.
+     * Pair with `<ApollionModeScript />` for a no-flash first paint.
      *
      * @default false
      */
+    persist?: PersistOption;
+    /**
+     * Storage key of the mode preference.
+     *
+     * @default 'apollion-mode'
+     */
+    storageKey?: string;
+    /**
+     * Mirror the resolved mode + a11y preset on `<html>` (`data-apollion-mode`,
+     * `data-apollion-a11y`, `style.colorScheme`) so native controls, scrollbars
+     * and `light-dark()` follow the engine. Removed on unmount.
+     *
+     * @default true
+     */
+    syncDocument?: boolean;
+    /**
+     * Attribute name written by `syncDocument` for the resolved mode.
+     *
+     * @default 'data-apollion-mode'
+     */
+    attribute?: string;
+    /**
+     * Accessibility preset — **controlled**. Orthogonal to the mode (D5): the
+     * preset remaps the brand/feedback seeds (`accessibilityPalettes`) and the
+     * engine still derives light + dark from the result, so `dark` +
+     * `colorblind` is a first-class combination. Only applies with `colors`.
+     */
+    a11y?: A11yMode;
+    /**
+     * Initial accessibility preset — **uncontrolled**. Restored from `persist`.
+     *
+     * @default null
+     */
+    defaultA11y?: A11yMode;
+    /** Fires on every `setA11y`. */
+    onA11yChange?: (a11y: A11yMode) => void;
+    /**
+     * @deprecated since 5.7.0 — use `defaultMode="system"` (uncontrolled) or
+     * `mode="system"` (controlled). Still honored: `true` ≡ `defaultMode: 'system'`.
+     */
     useSystemPreference?: boolean;
     /**
-     * Controlled mode. When set, the provider renders this mode and ignores the
-     * internal state and `useSystemPreference` — the source of truth becomes the
-     * parent (e.g. a navbar toggle / `next-themes`). `toggleTheme` then only
-     * fires `onThemeModeChange`, without mutating local state.
+     * @deprecated since 5.7.0 — use `mode` (a controlled preference that also
+     * accepts `'system'`). Still honored as a controlled `'light' | 'dark'`.
      */
     themeMode?: ThemeMode;
     /**
-     * Callback fired by `toggleTheme`. Essential in controlled mode (for the
-     * parent to update its source of truth) and optional in uncontrolled mode.
+     * @deprecated since 5.7.0 — use `onModeChange`. Still fired by `setMode`/
+     * `toggleTheme` with the **resolved** mode.
      */
     onThemeModeChange?: (mode: ThemeMode) => void;
     /**
@@ -188,11 +270,33 @@ export interface ApollionProviderInterface {
      * @see ../Dimension/Dimension.interface.ts
      */
     dimension?: Dimension;
+    /**
+     * Brand-level origin of the weight ladder (`light` / `regular` /
+     * `stronger`). Convenience prop equivalent to `createTheme({ typeWeight })`;
+     * like `dimension`, it only applies when the provider builds the theme.
+     *
+     * @default 'regular' (stock ladder)
+     */
+    typeWeight?: TypeWeight;
     children?: React.ReactNode;
 }
 export interface ApollionThemeContext {
     theme: Theme;
+    /** Current mode preference (`'system'` when following the OS). */
+    mode: ModePreference;
+    /** The mode that renders (preference with `'system'` resolved). */
+    resolvedMode: ResolvedMode;
+    /** Sets the preference; persists it when `persist` is on. */
+    setMode: (mode: ModePreference) => void;
+    /** Current accessibility preset (`null` = stock palette). */
+    a11y: A11yMode;
+    /** Sets the preset; persists it when `persist` is on. */
+    setA11y: (a11y: A11yMode) => void;
+    /** `<html>` attribute carrying the resolved mode (`syncDocument`). */
+    attribute: string;
+    /** @deprecated since 5.7.0 — alias of `resolvedMode`. */
     themeMode: ThemeMode;
+    /** @deprecated since 5.7.0 — use `setMode`. Flips the resolved mode (or sets the given one). */
     toggleTheme: (mode?: ThemeMode) => void;
 }
 export type WithTheme<P> = P & {

package/lib/themes/ThemeProvider/ThemeProvider.modes.d.ts

@@ -0,0 +1,52 @@
+import type { Theme } from './ThemeProvider.interface';
+/**
+ * Mode bridge (APOLLION-DARK-MODE-ENGINE, ADR-024 — spike
+ * `2026-08-22-css-var-mode-bridge`): the styled tree receives ONE theme whose
+ * color leaves are `light-dark(<light>, <dark>)` pairs, so a mode flip is a
+ * `color-scheme` change on `<html>` — zero React re-render, identical class
+ * hashes in both modes, SSR-deterministic. Literal tables stay reachable as
+ * `theme.modes.{light,dark}` for engine math ({@link forModes}).
+ */
+/** The literal light/dark pair behind a projected theme. */
+export interface ThemePair {
+    light: Theme;
+    dark: Theme;
+}
+/** `light-dark(a, b)` — collapsed to the literal when both sides agree (brand stops, runtime colors). */
+export declare function lightDark(light: string, dark: string): string;
+/**
+ * Runs color math on the literal tables of a projected theme and returns the
+ * `light-dark()` pair of the results. On a single (un-projected) theme it is
+ * just `fn(theme)`. Use it anywhere a literal is parsed at render time
+ * (`getContrastColor`, `readableColor`, `HextoRgb`) — those cannot parse a
+ * `light-dark()` string.
+ *
+ * @example
+ * ```ts
+ * color: forModes(theme, (t) => t.colors.getContrastColor(t.colors('primary')));
+ * ```
+ */
+export declare function forModes<T extends string | undefined>(theme: Theme, fn: (literal: Theme) => T): T;
+/**
+ * Projects a literal light/dark pair into the single theme the styled tree
+ * consumes. Only mode-varying color subtrees are paired (`colors`,
+ * `semantic.color`, `foundation.{bg,text,edge}`, `depth`); dimension-driven
+ * subtrees (spacing, font, border, component tokens) are shared by
+ * construction and keep the light references. Pure: a new object, inputs
+ * untouched; `theme.modes` carries the pair.
+ */
+export declare function projectModes(pair: ThemePair): Theme;
+/** A single literal theme tagged with its pair — what `useApollionTheme().theme` hands to JS consumers. */
+export declare function withModes(theme: Theme, pair: ThemePair): Theme;
+/**
+ * Clears the bridge tag so an un-paired (single) theme carries an OWN
+ * `modes: undefined` key. Required because styled-components merges nested
+ * `<ThemeProvider>` themes shallowly (`{ ...outerTheme, ...innerTheme }`):
+ * a single-theme `ApollionProvider` nested under a mode-paired one would
+ * otherwise INHERIT the outer provider's `modes`, and {@link forModes}-based
+ * render math (Button/Link inks) would compute contrast against the outer
+ * seeds instead of the inner theme's — the "dark ink on a custom bg" bug
+ * (ADR-024). Always returns a fresh object with `modes` present-as-undefined
+ * so the shallow merge shadows any inherited pair.
+ */
+export declare function withoutModes(theme: Theme): Theme;

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

@@ -1 +1 @@
-import{a,d as b,e as c}from"../../chunks/chunk-56NEPHUH.esm.js";import"../../chunks/chunk-RU6QRCR7.esm.js";import"../../chunks/chunk-CWRWYU7D.esm.js";import"../../chunks/chunk-2R6XFFSQ.esm.js";import"../../chunks/chunk-TG5BCBO4.esm.js";import"../../chunks/chunk-JOKVE3IX.esm.js";import"../../chunks/chunk-BRXIFPWB.esm.js";import"../../chunks/chunk-3EOSES4S.esm.js";import"../../chunks/chunk-NQBO2D7L.esm.js";import"../../chunks/chunk-3DUB5C4Z.esm.js";import"../../chunks/chunk-KT6QQ3UJ.esm.js";import"../../chunks/chunk-7EGX7BMB.esm.js";import"../../chunks/chunk-OWMRURZT.esm.js";import"../../chunks/chunk-6X6WKZ3Y.esm.js";import"../../chunks/chunk-WGTBX72G.esm.js";import"../../chunks/chunk-IWMEDT6U.esm.js";import"../../chunks/chunk-VMIXRIQ2.esm.js";import"../../chunks/chunk-5HENHW73.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-APD22JEO.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{c as ApollionProvider,a as createTheme,b as useApollionTheme};
+import"../../chunks/chunk-4L2KOZIQ.esm.js";import{a,e as b,g as c}from"../../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-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{c as ApollionProvider,a as createTheme,b as useApollionTheme};

package/lib/themes/index.d.ts

@@ -9,6 +9,8 @@ export * from './Dimension';
 export * from './Font';
 export * from './Foundation';
 export * from './GlobalStyle';
+export * from './Ground';
+export * from './Mode';
 export * from './Semantic';
 export * from './Spacing';
 export * from './Surface';

package/lib/themes/index.esm.js

@@ -1 +1 @@
-import"../chunks/chunk-KL3ATH64.esm.js";import{a as S}from"../chunks/chunk-T6ZB656A.esm.js";import{a as X}from"../chunks/chunk-7AFAO7ZS.esm.js";import{a as Y,d as Z,e as _}from"../chunks/chunk-56NEPHUH.esm.js";import{a as P,b as Q}from"../chunks/chunk-RU6QRCR7.esm.js";import"../chunks/chunk-CWRWYU7D.esm.js";import{a as T}from"../chunks/chunk-2R6XFFSQ.esm.js";import{a as U,b as V}from"../chunks/chunk-TG5BCBO4.esm.js";import{a as M,b as N,c as O}from"../chunks/chunk-JOKVE3IX.esm.js";import{a as W}from"../chunks/chunk-BRXIFPWB.esm.js";import{a as R}from"../chunks/chunk-3EOSES4S.esm.js";import{a as D}from"../chunks/chunk-NQBO2D7L.esm.js";import{a as E}from"../chunks/chunk-3DUB5C4Z.esm.js";import{a as F,b as G,c as H}from"../chunks/chunk-KT6QQ3UJ.esm.js";import{b as I}from"../chunks/chunk-7EGX7BMB.esm.js";import{a as J}from"../chunks/chunk-OWMRURZT.esm.js";import{a as K,b as L}from"../chunks/chunk-6X6WKZ3Y.esm.js";import"../chunks/chunk-WGTBX72G.esm.js";import"../chunks/chunk-IWMEDT6U.esm.js";import"../chunks/chunk-VMIXRIQ2.esm.js";import{a as v,b as w,c as x,d as y,e as z,f as A,g as B,h as C}from"../chunks/chunk-5HENHW73.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-APD22JEO.esm.js";import"../chunks/chunk-GZONWSRB.esm.js";export{_ as ApollionProvider,N as DEFAULT_DIMENSION,M as DIMENSION_MULTIPLIERS,j as DISABLED_NEUTRAL_INDICES,S as GlobalStyle,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,X as SurfaceProvider,C as accessibilityPalettes,D as animation,F as breakpointsValues,A as colorblindPalette,H as createBreakpoints,w as createColors,I as createComponentTokens,J as createDeepTheme,L as createDeth,Q as createFont,R as createFoundation,i as createReadableTextLayer,T as createSemantic,V as createSpacing,Y as createTheme,E as defaultInputBorder,G as defaultInputBreakpoints,v as defaultInputColors,P as defaultInputFont,U as defaultInputSpacing,e as getColor,f as getContrastColor,O as getMultiplierForDimension,b as getOppositeColor,x as grayscalePalette,y as highContrastPalette,W as invertForSurface,K as levelValues,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,B as toDarkColors,Z as useApollionTheme};
+import"../chunks/chunk-EBOJSNZ5.esm.js";import{a as Wa}from"../chunks/chunk-HPM5AX5Z.esm.js";import{a as Xa}from"../chunks/chunk-2XTVIQMG.esm.js";import{a as Ya}from"../chunks/chunk-4ZHLV35P.esm.js";import"../chunks/chunk-4L2KOZIQ.esm.js";import{a as Ua,b as Va}from"../chunks/chunk-MPKFMMCD.esm.js";import{a as Qa,e as Sa,g as Ta}from"../chunks/chunk-BFEEE3TE.esm.js";import{a as va,b as wa,c as xa,d as ya,e as za,f as Aa,g as Ba,h as Ca,i as Da,j as Ea,k as Fa,l as Ga,m as Ha,n as Ia,o as Ja,p as Ka,q as La,r as Ma}from"../chunks/chunk-TLIKQFOT.esm.js";import"../chunks/chunk-IA234JY2.esm.js";import{a as Oa,b as Pa}from"../chunks/chunk-TG5BCBO4.esm.js";import{a as Ra}from"../chunks/chunk-CCONLRLQ.esm.js";import{b as Na}from"../chunks/chunk-6XX3UO2Y.esm.js";import{b as ma}from"../chunks/chunk-BERIBF3O.esm.js";import{a as na}from"../chunks/chunk-YZQXTNVA.esm.js";import"../chunks/chunk-Z7GJDO5T.esm.js";import{a as ra,b as sa,c as ta}from"../chunks/chunk-P7RR4ZHS.esm.js";import{a as oa,b as pa,c as qa}from"../chunks/chunk-JOKVE3IX.esm.js";import"../chunks/chunk-CWRWYU7D.esm.js";import{a as ua}from"../chunks/chunk-PFLBU7HG.esm.js";import{a as ha}from"../chunks/chunk-IPANNHV3.esm.js";import{a as ia}from"../chunks/chunk-3DUB5C4Z.esm.js";import{a as ja,b as ka,c as la}from"../chunks/chunk-KT6QQ3UJ.esm.js";import"../chunks/chunk-3KOZ6RXR.esm.js";import"../chunks/chunk-VMIXRIQ2.esm.js";import{a as _,b as $,c as aa,d as ba,e as ca,f as da,g as ea,h as fa,i as ga}from"../chunks/chunk-JQ66DKSQ.esm.js";import"../chunks/chunk-YC44Q5HI.esm.js";import{a as X,b as Y,c as Z}from"../chunks/chunk-BFABFZI7.esm.js";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-AXUWC2WH.esm.js";import"../chunks/chunk-GZONWSRB.esm.js";export{xa as A11Y_ATTRIBUTE,Xa as ApollionModeScript,Ta as ApollionProvider,ya as DARK_SCHEME_QUERY,pa as DEFAULT_DIMENSION,Y as DEPTH_SHADOW,oa as DIMENSION_MULTIPLIERS,n as DISABLED_NEUTRAL_INDICES,J as EDGE_ALPHA,$ as GROUND_INK_ROLES,_ as GROUND_VAR_PREFIX,Va as GlobalStyle,Ua as GlobalStyleComponent,Wa as Ground,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,wa as MODE_ATTRIBUTE,va as MODE_STORAGE_KEY,l as NEUTRAL_TEXT_INDICES,T as OKABE_ITO,r as QUIET_NEUTRAL_INDICES,k as READABLE_TEXT_PALETTES,aa as ROOT_GROUND_TOKEN,u as STATE_DELTA_L_JND,o as STRUCTURAL_NEUTRAL_INDICES,Ya as SurfaceProvider,ra as TYPE_WEIGHT_LADDERS,K as WASH_ALPHA,za as a11yStorageKey,W as accessibilityPalettes,ha as animation,b as apcaContrast,a as apcaLuminance,ga as auditGroundVars,ja as breakpointsValues,x as clampLightness,La as clearDocumentMode,U as colorblindPalette,g as contrastRatio,Ga as cookieAdapter,la as createBreakpoints,Q as createColors,ma as createComponentTokens,na as createDeepTheme,Z as createDeth,ta as createFont,ua as createFoundation,m as createReadableTextLayer,Na as createSemantic,Pa as createSpacing,Qa as createTheme,ia as defaultInputBorder,ka as defaultInputBreakpoints,P as defaultInputColors,sa as defaultInputFont,Oa as defaultInputSpacing,i as getColor,j as getContrastColor,Ma as getModeScript,qa as getMultiplierForDimension,e as getOppositeColor,R as grayscalePalette,da as groundInkPath,ba as groundVar,ca as groundVarRef,fa as groundVars,S as highContrastPalette,Ra as invertForSurface,Ba as isA11yMode,v as isDarkSurface,Aa as isModePreference,ea as isOpaqueGround,X as levelValues,Ea as localStorageAdapter,c as mixOklch,D as mountActionColors,C as mountBaseColors,A as mountGreyscaleColors,E as mountMainColors,B as mountNeutralColors,z as mountSingleColor,M as oppositePolarity,Ca as prefersDarkScheme,Ja as readA11yFromCookie,Fa as readCookieValue,Ia as readModeFromCookie,h as readableColor,p as resolveDisabledNeutral,Da as resolveMode,O as resolveOppositeLadder,L as resolvePolarity,s as resolveQuietPalette,Ha as resolveStorage,q as resolveStructuralNeutrals,N as resolveSurfaceLadder,w as shiftLightness,Ka as syncDocumentMode,V as toDarkColors,y as toRgbaString,Sa as useApollionTheme};

package/lib/utils/components/Breakpoints/index.esm.js

@@ -1 +1 @@
-import{a,b}from"../../../chunks/chunk-WGTBX72G.esm.js";import"../../../chunks/chunk-G5Z7USXC.esm.js";import"../../../chunks/chunk-APD22JEO.esm.js";import"../../../chunks/chunk-GZONWSRB.esm.js";export{a as BreakpointsContext,b as BreakpointsProvider};
+import{a,b}from"../../../chunks/chunk-3KOZ6RXR.esm.js";import"../../../chunks/chunk-G5Z7USXC.esm.js";import"../../../chunks/chunk-AXUWC2WH.esm.js";import"../../../chunks/chunk-GZONWSRB.esm.js";export{a as BreakpointsContext,b as BreakpointsProvider};

package/lib/utils/components/index.esm.js

@@ -1 +1 @@
-import{a as o,b as r}from"../../chunks/chunk-WGTBX72G.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-APD22JEO.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{o as BreakpointsContext,r as BreakpointsProvider};
+import{a as o,b as r}from"../../chunks/chunk-3KOZ6RXR.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-AXUWC2WH.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{o as BreakpointsContext,r as BreakpointsProvider};

package/lib/vendors/Culori/apca.d.ts

@@ -0,0 +1,24 @@
+/**
+ * APCA (Accessible Perceptual Contrast Algorithm) — `Lc` lightness contrast
+ * for self-illuminated displays, the WCAG 3 candidate metric. First-party port
+ * of the public apca-w3 0.1.9 reference constants (SAPC-4g), kept inside the
+ * in-house color engine (ADR-016) so the dark-polarity invariants of the mode
+ * engine (APOLLION-DARK-MODE-ENGINE) can be asserted without a dependency.
+ *
+ * Sign convention: positive `Lc` = dark text on a light ground; negative =
+ * light text on a dark ground. Magnitude is what the floors compare against
+ * (`|Lc| ≥ 75` body, `≥ 60` secondary, `≥ 45` large text).
+ *
+ * Input: 6- or 3-digit hex (with or without `#`). Anything else → `NaN`
+ * (callers treat `NaN` as "not measurable", never as a pass).
+ *
+ * @see https://github.com/Myndex/apca-w3 (reference implementation + vectors)
+ */
+/** sRGB hex → APCA estimated screen luminance `Y` (simple 2.4 gamma, per SAPC-4g). */
+export declare function apcaLuminance(hex: string): number;
+/**
+ * APCA `Lc` for `text` over `background` (both hex). Polarity-aware: the
+ * exponents differ for dark-on-light vs light-on-dark, and the result is
+ * signed accordingly.
+ */
+export declare function apcaContrast(text: string, background: string): number;