@skdx/tokens 0.26.0 → 0.28.0

package/dist/utils/aliases.d.ts

@@ -1,121 +1,51 @@
 /**
- * The semantic alias layer: the vocabulary component skins are allowed to name.
+ * The semantic alias layer: `var()` indirection for component skins.
  *
- * Why this file exists
- * -------------------
- * `@skdx/skins` is forbidden from containing a colour literal — every colour
- * it declares must resolve through a token. But the surface a theme actually
- * defines is small: five ramps (`primary`, `neutral`, `success`, `warning`,
- * `danger`) and ten `semantic` entries. A button skin needs more than that. It
- * needs to say "the background of a pressed primary action" and "the border of
- * an invalid field", and neither exists as a theme-authored token.
+ * Aliases point at ramp steps and semantic entries themes already define. A
+ * theme redeclaring `--skdx-color-primary-600` makes every alias pointing
+ * there re-resolve, so adding a theme costs one line per alias, not 38.
  *
- * The naive fix is to add those names to `SemanticColors` and set them in all
- * 38 themes. That is 38 files edited per alias added, and every one of those
- * edits is a chance for a theme to drift out of step with the others.
+ * Aliases are emitted at `:root`, below theme declarations in the cascade,
+ * letting a theme override an alias when the derivation is mode-dependent.
+ * {@link darkColorAliases} uses this escape hatch for aliases that put ink
+ * directly on the page and need opposite ends of the ramp in dark mode.
  *
- * This layer takes the other option: aliases are **pure `var()` indirection**,
- * declared once at `:root`, pointing at ramp steps and semantic entries the
- * themes already define. No alias holds a colour — it holds the *name of* a
- * colour. So when `[data-skdx-theme="nord-dark"]` redeclares
- * `--skdx-color-primary-600` at its own higher-specificity selector, every alias
- * pointing at that step re-resolves to Nord's value automatically. Adding a
- * theme costs nothing here, and adding an alias costs one line rather than 38.
- *
- * This is also why the aliases are emitted at `:root` rather than inside each
- * theme block: they must sit *below* the theme declarations in the cascade so a
- * theme can still override an alias outright when the derivation is wrong for
- * it. {@link darkColorAliases} is exactly that escape hatch in use: a ramp runs
- * light-to-dark in every theme, so the aliases that put ink directly on the
- * page need the opposite end in dark mode.
- *
- * Choosing the ramp step
- * ----------------------
- * A dark theme's ramp is authored for dark — `NordDark`'s `primary-600` is
- * already a step that works as a filled background on a dark surface, the same
- * way `DefaultTheme`'s is on a light one. So a single step choice per alias is
- * correct in both modes for the *filled* aliases. It does not hold for aliases
- * that put ink or a wash directly on the page — see {@link darkColorAliases},
- * which was written after measuring 22 of 38 themes failing WCAG contrast.
- *
- * @see docs/architecture/skin-token-map.md for the per-property mapping table.
+ * @see packages/skins/README.md for how a skin consumes these aliases.
  */
 /**
- * Every alias, as `[name, value]` pairs where `value` is always a `var()`
- * reference — never a literal. Grouped by the question a skin author asks.
- *
- * Kept as data rather than a hand-written CSS string so
- * `aliases.test.ts` can assert the no-literal rule mechanically over the whole
- * set, which is the only thing standing between this file and the exact class
- * of drift the skins package's Stylelint rule exists to prevent.
+ * Alias entries as `[name, value]` pairs, where `value` is always a `var()` reference.
+ * Kept as data so `aliases.test.ts` can assert the no-literal rule.
  */
 export declare const colorAliases: ReadonlyArray<readonly [string, string]>;
 /**
- * The aliases a dark theme re-points, and what it re-points them to.
- *
- * Why this exists
- * ---------------
- * The base table above picks one ramp step per alias and claims that is correct
- * in both modes. For most aliases it is: a theme authors its ramp for its own
- * mode, so `primary-600` is a usable filled background whichever way the page
- * faces.
- *
- * It is *not* true for the aliases that put ink directly on the page. A ramp
- * runs light at 50 to dark at 950 in every theme, dark ones included — that is
- * what makes a ramp a ramp. So `--skdx-color-text-danger: danger-700` is dark
- * red: correct on a white page, and nearly invisible on a charcoal one. The
- * same applies to every "wash + dark ink" status pairing, and to the neutral
- * fills (`surface-sunken`, `track`, `skeleton`) that assume the page is lighter
- * than they are.
- *
- * Measured before writing this: 22 of the 38 themes had at least one contrast
- * failure, every one of them a dark theme, and every failure in this list.
- * Input text sat at 1.07:1 and the tooltip at 1.00:1.
- *
- * The fix uses the escape hatch the base table was designed around — a theme
- * may override an alias, because `[data-skdx-theme="…"]` outranks `:root`. These
- * overrides are emitted automatically for every theme whose `mode` is `'dark'`,
- * so the cost stays "one line per alias" rather than "one edit per theme", and
- * a new dark theme is correct the day it lands without anyone remembering this
- * file exists.
- *
- * Steps mirror around the middle of the ramp: 700 → 300, 800 → 200, 50 → 950.
- * That keeps the light and dark treatments the same *distance* from their
- * background rather than merely both legible.
+ * Dark-mode alias overrides. Base table picks one ramp step per alias; it fails
+ * for aliases putting ink directly on the page (ramp runs 50–950 in all themes,
+ * so dark-page inks become invisible). These overrides automatically emit for
+ * themes where `mode` is `'dark'`. Steps mirror around ramp center: 700 → 300,
+ * keeping equal distance from background.
  */
 export declare const darkColorAliases: ReadonlyArray<readonly [string, string]>;
 /**
- * Renders {@link darkColorAliases} at `selector`, for a theme whose mode is dark.
- *
- * @param selector - The theme's own selector, e.g. `'[data-skdx-theme="nord-dark"]'`.
+ * Renders {@link darkColorAliases} at the theme selector.
+ * @param selector - Theme selector, e.g. `'[data-skdx-theme="nord-dark"]'`.
  * @public
  */
 export declare function darkAliasesToCss(selector: string): string;
 /**
- * Renders {@link colorAliases} as a `:root` rule block.
- *
- * Emitted *after* `foundationToCss()` and *before* the theme blocks in
- * `@skdx/tokens/css`. Order matters in one direction only: an alias must be
- * able to be overridden by a theme, and `:root` loses to
- * `[data-skdx-theme="…"]` on specificity regardless of source order, so the
- * position here is for readability rather than correctness.
- *
- * @returns A CSS string, e.g. `':root {\n  --skdx-color-action-primary-bg: var(--skdx-color-primary-600);\n  …\n}\n'`.
+ * Renders {@link colorAliases} as a `:root` rule block. `:root` always loses
+ * to `[data-skdx-theme="…"]` on specificity.
  *
+ * @returns CSS string; emitted after `foundationToCss()` and before theme blocks.
  * @example
  * ```ts
  * import { foundationToCss, aliasesToCss } from '@skdx/tokens';
- *
  * fs.writeFileSync('tokens.css', foundationToCss() + aliasesToCss());
  * ```
- *
  * @public
  */
 export declare function aliasesToCss(): string;
 /**
- * {@link colorAliases} as a plain object, for consumers applying tokens through
- * JS rather than a stylesheet (the alias counterpart to `themeToCssVars`).
- *
+ * {@link colorAliases} as a plain object for JS consumers (counterpart to `themeToCssVars`).
  * @public
  */
 export declare function aliasesToCssVars(): Record<string, string>;

package/dist/utils/contrast.d.cts

@@ -3,25 +3,10 @@
  * colors, per the standard formula (https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio).
  * Returns a value from 1 (no contrast) to 21 (black on white).
  *
- * **Throws on anything that is not a hex color.** This used to coerce silently:
- * `hex.replace('#','')` then `Number.parseInt(full, 16)` yields `NaN` for
- * `rgb(0 0 0 / 0.45)`, and `(NaN >> 16) & 255` is `0`, so a translucent value
- * was measured as opaque black. `ant-daybreak`'s `textMuted` scored a perfect
- * 21:1 while rendering at 3.36:1 — a live AA failure passing as a perfect
- * score, which is worse than no guard at all.
- *
- * Throwing rather than compositing is deliberate. Compositing would need a
- * backdrop this function does not have and cannot infer, and it would let the
- * next translucent value into the theme set silently. Rejecting forces every
- * theme to state its colors as measurable values, which makes the whole set
- * auditable by construction instead of by vigilance.
- *
- * `#rgba` and `#rrggbbaa` are rejected too: an alpha channel is exactly the
- * thing that needs a backdrop, and the luminance math below would read those
- * extra digits as colour.
+ * **Throws on anything that is not a hex color.** Compositing would need
+ * a backdrop this function does not have; rejecting forces measurable values.
  *
  * @throws {TypeError} if either argument is not `#rgb` or `#rrggbb`
- *
  * @public
  */
 export declare function contrastRatio(hexA: string, hexB: string): number;

package/dist/utils/contrast.d.ts

@@ -3,25 +3,10 @@
  * colors, per the standard formula (https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio).
  * Returns a value from 1 (no contrast) to 21 (black on white).
  *
- * **Throws on anything that is not a hex color.** This used to coerce silently:
- * `hex.replace('#','')` then `Number.parseInt(full, 16)` yields `NaN` for
- * `rgb(0 0 0 / 0.45)`, and `(NaN >> 16) & 255` is `0`, so a translucent value
- * was measured as opaque black. `ant-daybreak`'s `textMuted` scored a perfect
- * 21:1 while rendering at 3.36:1 — a live AA failure passing as a perfect
- * score, which is worse than no guard at all.
- *
- * Throwing rather than compositing is deliberate. Compositing would need a
- * backdrop this function does not have and cannot infer, and it would let the
- * next translucent value into the theme set silently. Rejecting forces every
- * theme to state its colors as measurable values, which makes the whole set
- * auditable by construction instead of by vigilance.
- *
- * `#rgba` and `#rrggbbaa` are rejected too: an alpha channel is exactly the
- * thing that needs a backdrop, and the luminance math below would read those
- * extra digits as colour.
+ * **Throws on anything that is not a hex color.** Compositing would need
+ * a backdrop this function does not have; rejecting forces measurable values.
  *
  * @throws {TypeError} if either argument is not `#rgb` or `#rrggbb`
- *
  * @public
  */
 export declare function contrastRatio(hexA: string, hexB: string): number;

package/dist/utils/cssVars.d.cts

@@ -1,37 +1,15 @@
-/**
- * The one place `--skdx-*` custom property *names* are derived from token
- * object keys.
- *
- * Both halves of the token system emit CSS variables — `themeToCssVars` for
- * the per-theme colors, `foundationToCssVars` for everything shared — and they
- * have to agree byte-for-byte, because a consumer writing
- * `var(--skdx-font-size-md)` cannot tell (and should not care) which half
- * declared it. Two copies of this naming logic would drift the first time
- * someone added a camelCase token, and the failure mode is silent: the
- * variable simply never resolves.
- *
- * @internal
- */
-/** A token group and the `--skdx-<prefix>-…` namespace its keys render under. @internal */
+/** Token group and its `--skdx-<prefix>-…` namespace. @internal */
 export type CssVarSection = [prefix: string, tokens: Record<string, unknown> | undefined];
 /**
- * Flattens token groups into a `{ '--skdx-…': value }` map.
- *
- * A section whose tokens are `undefined` contributes nothing — that is how an
- * optional group (a theme's `typography` or `motion`) opts out without the caller
- * needing a conditional.
- *
- * @internal
+ * Flatten token groups into `{ '--skdx-…': value }` map. Undefined sections
+ * contribute nothing (optional groups opt out without caller conditional). @internal
  */
 export declare function sectionsToCssVars(sections: CssVarSection[]): Record<string, string>;
-/** Renders a var map as the indented declaration lines of a CSS rule block. @internal */
+/** Render vars as indented CSS declarations. @internal */
 export declare function varsToDeclarations(vars: Record<string, string>, indent?: string): string;
 /**
- * The `--skdx-motion-*` variables that a `prefers-reduced-motion: reduce` block
- * has to zero: every duration *and* every stagger. A stagger is a delay, so
- * zeroing the durations without zeroing it would leave a still page that still
- * arrives late.
- *
- * @internal
+ * Motion variables to zero in `prefers-reduced-motion: reduce`: durations
+ * and staggers (staggers are delays; zeroing one without the other leaves
+ * late arrival). @internal
  */
 export declare function reducedMotionVarNames(vars: Record<string, string>): string[];

package/dist/utils/cssVars.d.ts

@@ -1,37 +1,15 @@
-/**
- * The one place `--skdx-*` custom property *names* are derived from token
- * object keys.
- *
- * Both halves of the token system emit CSS variables — `themeToCssVars` for
- * the per-theme colors, `foundationToCssVars` for everything shared — and they
- * have to agree byte-for-byte, because a consumer writing
- * `var(--skdx-font-size-md)` cannot tell (and should not care) which half
- * declared it. Two copies of this naming logic would drift the first time
- * someone added a camelCase token, and the failure mode is silent: the
- * variable simply never resolves.
- *
- * @internal
- */
-/** A token group and the `--skdx-<prefix>-…` namespace its keys render under. @internal */
+/** Token group and its `--skdx-<prefix>-…` namespace. @internal */
 export type CssVarSection = [prefix: string, tokens: Record<string, unknown> | undefined];
 /**
- * Flattens token groups into a `{ '--skdx-…': value }` map.
- *
- * A section whose tokens are `undefined` contributes nothing — that is how an
- * optional group (a theme's `typography` or `motion`) opts out without the caller
- * needing a conditional.
- *
- * @internal
+ * Flatten token groups into `{ '--skdx-…': value }` map. Undefined sections
+ * contribute nothing (optional groups opt out without caller conditional). @internal
  */
 export declare function sectionsToCssVars(sections: CssVarSection[]): Record<string, string>;
-/** Renders a var map as the indented declaration lines of a CSS rule block. @internal */
+/** Render vars as indented CSS declarations. @internal */
 export declare function varsToDeclarations(vars: Record<string, string>, indent?: string): string;
 /**
- * The `--skdx-motion-*` variables that a `prefers-reduced-motion: reduce` block
- * has to zero: every duration *and* every stagger. A stagger is a delay, so
- * zeroing the durations without zeroing it would leave a still page that still
- * arrives late.
- *
- * @internal
+ * Motion variables to zero in `prefers-reduced-motion: reduce`: durations
+ * and staggers (staggers are delays; zeroing one without the other leaves
+ * late arrival). @internal
  */
 export declare function reducedMotionVarNames(vars: Record<string, string>): string[];

package/dist/utils/foundation.d.cts

@@ -1,79 +1,42 @@
 import { type ThemeControls, type ThemeControlsCoarse, type ThemeMotion, type ThemeRadii, type ThemeShadows, type ThemeSpace, type ThemeTypography } from './theme.cjs';
 /**
- * The type system: one font stack, one scale, one set of weights,
- * line-heights and tracking steps, shared by every theme.
- *
- * A theme picks colors. It does not get to resize the type scale, because a
- * layout that reflows when you switch brand is a layout that was never
- * designed — it was designed once, against one scale, and every other brand
- * was hoping. The two font *stacks* are the only part a theme can override,
- * and only through {@link ThemeTypographyDeviation}, because impersonating a
- * design language means impersonating its typeface.
- *
+ * The type system: one font stack, scale, weight set, line-heights and
+ * tracking steps, shared by every theme. Only the font stacks are
+ * per-theme overridable, via {@link ThemeTypographyDeviation}.
  * @public
  */
 export declare const typography: ThemeTypography;
 /**
- * The spacing scale — a 4px base with the usual gaps (no `7`, no `9`) so the
- * steps stay memorable rather than exhaustive. Structural: gap and padding are
- * rhythm, and rhythm is a property of the design system, not of the brand
- * painted on top of it.
- *
+ * The spacing scale — a 4px base, structural rather than per-brand: gap and
+ * padding are rhythm, a property of the system, not the brand on top of it.
  * @public
  */
 export declare const space: ThemeSpace;
 /**
- * The corner-radius scale. Shared for the same reason {@link space} is: a
- * component's silhouette is part of the system's shape language, and a brand
- * that rounds its corners differently is a different component library
- * wearing the same class names.
- *
+ * The corner-radius scale, structural like {@link space}: a component's
+ * silhouette is part of the system's shape language, not the brand's.
  * @public
  */
 export declare const radii: ThemeRadii;
 /**
  * The elevation scale — geometry only. Every value defers its color to
  * `var(--skdx-shadow-color)` and scales its alpha by
- * `var(--skdx-shadow-strength)`, both of which a theme supplies (see
- * {@link ThemeShadowColor}).
- *
- * This split is the whole reason shadows can be shared at all. A shadow is one
- * CSS string that welds geometry to a color, so before this every theme
- * restated `0 4px 6px -1px` purely to be able to change `rgb(…)` at the end of
- * it — 38 copies of the same three offsets, and no way to tell a deliberate
- * elevation change from a color change.
- *
- * The base alphas below are the original `skanda-light` values, so a theme
- * with `strength: '1'` renders exactly what it did before the split.
- * Substitution is lazy: these live at `:root`, but `var(--skdx-shadow-color)`
- * resolves against the element the shadow is finally *used* on, so the active
- * `[data-skdx-theme]` block wins. `calc()` is legal in the alpha slot, and an
- * alpha above 1 clamps rather than erroring — which is what keeps a
- * high-strength dark theme from being a footgun.
- *
+ * `var(--skdx-shadow-strength)`, both supplied by a theme (see
+ * {@link ThemeShadowColor}), so 38 themes share one set of offsets instead of
+ * each restating them to vary only the color.
  * @public
  */
 export declare const shadows: ThemeShadows;
 /**
- * The shared animation timing — re-exported from {@link defaultMotion}, which
- * remains the single source so that `themeToCssVars` can keep merging it under
- * a theme's {@link Theme.motion} without importing this module.
- *
- * See {@link ThemeMotion} for why motion is theme-invariant.
- *
+ * The shared animation timing, re-exported from {@link defaultMotion}. See
+ * {@link ThemeMotion} for why motion is theme-invariant.
  * @public
  */
 export declare const motion: Required<ThemeMotion>;
 /**
  * A structural stacking-order scale for overlay-class UI (dropdowns, sticky
- * headers, dialog/popover backdrops, floating content, toasts). Unlike the
- * rest of the token system, z-index isn't a per-brand visual choice — every
- * theme should stack the same way — so it's exported once here rather than
- * duplicated into all 38 {@link Theme} objects. Consumers building an app
- * with multiple concurrent overlay types (e.g. a `Select` opened from inside
- * a `Dialog`, with a `Toast` on top of both) should coordinate their own
- * z-indices against this scale instead of picking ad hoc numbers per
- * component.
+ * headers, dialog/popover backdrops, floating content, toasts) — every theme
+ * stacks the same way, so it's exported once rather than duplicated per theme.
  *
  * @example
  * ```css
@@ -88,27 +51,20 @@ export declare const zIndex: {
     readonly base: 0;
     readonly dropdown: 10;
     readonly sticky: 20;
-    /** The scrim behind a modal surface. */
+    /** Scrim behind modal. */
     readonly overlay: 30;
-    /** The modal surface itself — above its own scrim, below any popover opened from inside it. */
+    /** Modal surface; above scrim, below popovers opened from inside. */
     readonly modal: 35;
     readonly popover: 40;
     readonly toast: 50;
-    /**
-     * Escape hatch for the one thing that must sit above everything, e.g. a
-     * debug overlay or an "app is offline" banner. Deliberately far above
-     * `toast` so app code never has to guess a bigger number.
-     */
+    /** Escape hatch for the one thing that must sit above everything, e.g. a debug overlay. */
     readonly max: 9999;
 };
 /** The shape of the {@link zIndex} scale — a map of named stacking layers (`sticky`, `overlay`, `popover`, `toast`, …) to their numeric `z-index`. @public */
 export type ZIndexScale = typeof zIndex;
 /**
- * Structural focus-ring geometry (width/offset) — the *color* half of the
- * focus-ring contract is themed per brand ({@link SemanticColors.focusRing}),
- * but the ring's thickness and offset are a layout constant every theme
- * should share, so they live here rather than being repeated as identical
- * values across all 38 bundled themes.
+ * Structural focus-ring geometry (width/offset). The ring's *color* is themed
+ * per brand ({@link SemanticColors.focusRing}); thickness/offset are shared.
  *
  * @example
  * ```css
@@ -124,30 +80,17 @@ export declare const focusRing: {
     readonly width: "2px";
     readonly offset: "2px";
     /**
-     * The offset a *clipping* container hands down to its children.
-     *
-     * An outline is painted outward from the border edge and is clipped by an
-     * ancestor's `overflow` exactly like any other overflowing paint — which
-     * sliced the ring off inside every control group that rounds its corners by
-     * clipping. Because `outline-offset` is read from a custom property, such a
-     * container sets this on itself and every descendant ring moves *inside* the
-     * border box, where nothing can reach it. One declaration per clipping
-     * container, no per-part focus rules.
-     *
-     * Negative by exactly the ring width, which lands it flush against the
-     * inside of the edge rather than floating in from it.
+     * Offset for clipping containers; moves ring inside border-box so overflow
+     * doesn't clip. Negative ring width, flush inside edge.
      */
     readonly offsetInset: "calc(-1 * var(--skdx-focus-ring-width))";
 };
 /** The shape of the {@link focusRing} geometry — the structural `width`/`offset` of the focus ring (its color is themed separately). @public */
 export type FocusRingScale = typeof focusRing;
 /**
- * Border thicknesses. Structural for the same reason {@link focusRing}'s
- * geometry is: a brand changes border *color* (see
- * {@link SemanticColors.border}), not how many pixels thick a hairline is.
- * Three steps only — a hairline, an emphasis weight (focus/selected/invalid
- * outlines drawn without the focus ring), and a heavy weight for deliberate
- * structural rules. There is no `0`: that's `border: none`, not a token.
+ * Border thicknesses, structural like {@link focusRing}: a brand changes
+ * border *color* ({@link SemanticColors.border}), not hairline width. No `0`
+ * step — that's `border: none`, not a token.
  *
  * @example
  * ```css
@@ -165,37 +108,25 @@ export declare const borderWidth: {
 /** The shape of the {@link borderWidth} scale — `thin`/`thick`/`thicker` border thicknesses. @public */
 export type BorderWidthScale = typeof borderWidth;
 /**
- * The shared control geometry — heights, paddings, icon boxes, row heights and
- * overlay insets. See {@link ThemeControls} for why this is structural rather
- * than per-brand, and for the retuning escape hatch.
- *
- * The ladder is an even 6px step (30/36/42) and every rung sits inside the
- * range the two reference libraries surveyed occupy. Several values are
- * `var()` references rather than lengths on purpose: a control's inline
- * padding *is* a step of {@link space}, and restating `0.75rem` here would let
- * the two drift. The exceptions are the four numbers that are deliberately off
- * a scale — `padding.sm` (10px), `height.compact` (32px), `item.gap` (2px) and
- * `target.min` (24px) — each documented where it is declared.
- *
+ * The shared control geometry — heights, paddings, icon boxes, row heights
+ * and overlay insets. See {@link ThemeControls} for why this is structural
+ * rather than per-brand, and for the retuning escape hatch. Values are
+ * `var()` references where they equal a {@link space} step, so the two can't
+ * drift; the few off-scale exceptions are documented where declared.
  * @public
  */
 export declare const controls: ThemeControls;
 /**
- * What a coarse pointer overrides. Emitted by {@link foundationToCss} as a
- * `@media (pointer: coarse)` block; see {@link ThemeControlsCoarse} for why
+ * What a coarse pointer overrides, emitted as a `@media (pointer: coarse)`
+ * block by {@link foundationToCss}; see {@link ThemeControlsCoarse} for why
  * only hit sizes are listed.
- *
  * @public
  */
 export declare const controlsCoarse: ThemeControlsCoarse;
 /**
- * The two opacities the system actually has an opinion about. Deliberately
- * *not* a 0–100 ramp: an arbitrary ramp invents decisions nobody made, while
- * these two are real, repeated cross-component choices — how faded a disabled
- * control is, and how much a modal scrim dims the page behind it.
- *
- * Scrim *color* is themed ({@link SemanticColors.overlay}); this is the
- * structural strength of the dim, so every brand's scrim occludes equally.
+ * The two opacities the system has an opinion about — disabled fade and
+ * modal scrim dim — not an arbitrary 0–100 ramp. Scrim *color* is themed
+ * ({@link SemanticColors.overlay}); this is the structural dim strength.
  *
  * @example
  * ```css
@@ -212,16 +143,9 @@ export declare const opacity: {
 /** The shape of the {@link opacity} scale — the `disabled` and `scrim` opacities. @public */
 export type OpacityScale = typeof opacity;
 /**
- * Viewport widths, in pixels, as **TypeScript exports only** — deliberately
- * not emitted as CSS custom properties by {@link foundationToCss}. A custom
- * property cannot be used in a `@media` query's condition (`@media (min-width:
- * var(--x))` is invalid CSS), so a `--skdx-breakpoint-*` variable would be a
- * token that looks usable and isn't. Consume these from JS/TS, or from a
- * build step that inlines the number into your own media queries.
- *
- * The components themselves are headless and ship no responsive behavior;
- * this exists so consumers building a styled layer on top don't have to
- * invent their own set.
+ * Viewport widths, in pixels, as **TypeScript exports only** — not emitted as
+ * CSS custom properties, since `@media (min-width: var(--x))` is invalid CSS.
+ * Consume from JS/TS or inline into your own media queries.
  *
  * @example
  * ```ts
@@ -242,51 +166,31 @@ export declare const breakpoints: {
 export type BreakpointScale = typeof breakpoints;
 /**
  * Flattens every shared token into a map of CSS custom property names to
- * values — the foundation's counterpart to `themeToCssVars`. Together the two
- * maps are the complete `--skdx-*` surface, and they never overlap.
- *
- * {@link breakpoints} is not included — see its docs for why a breakpoint
- * can't be a CSS custom property.
+ * values — the foundation's counterpart to `themeToCssVars`. Together they
+ * are the complete `--skdx-*` surface, and never overlap. {@link breakpoints}
+ * is excluded, since a breakpoint can't be a CSS custom property.
  *
  * @returns A plain object keyed by CSS custom property name (e.g. `'--skdx-space-4'`), unprefixed by any selector.
- *
  * @public
  */
 export declare function foundationToCssVars(): Record<string, string>;
 /**
  * The control metrics a coarse pointer overrides, as a var map — the
  * `@media (pointer: coarse)` counterpart to {@link foundationToCssVars}.
- *
- * Exported because `@skdx/skins` renders its own no-tokens fallback copy of
- * both blocks from these functions rather than restating the values, which is
- * the only thing that keeps the two in step.
- *
+ * Exported so `@skdx/skins` can render its fallback copy from these
+ * functions instead of restating the values.
  * @public
  */
 export declare function coarsePointerToCssVars(): Record<string, string>;
 /**
  * Renders every shared token as a `:root`-scoped `--skdx-*` rule block — the
  * theme-invariant counterpart to {@link themeToCss}. **Inject this exactly
- * once**, then inject `themeToCss(theme)` per theme alongside it. Without it
- * the type scale, spacing, radii, shadow geometry and motion are simply
- * absent, because no theme declares them any more.
- *
- * Followed by a `@media (prefers-reduced-motion: reduce)` block that
- * re-declares every `--skdx-motion-duration-*` and `--skdx-motion-stagger-*` as
- * `0ms`. Components are headless and animate nothing themselves, so honoring
- * the preference has to happen where the durations are *defined* rather than
- * where they're used — this way a consumer who writes `transition-duration:
- * var(--skdx-motion-duration-normal)` gets WCAG 2.3.3 behavior for free instead
- * of having to remember the media query at every call site. The easing curve
- * is left alone: it's a shape, not a duration, and is inert at `0ms`. A theme
- * that retunes motion via `ThemeMotionDeviation` emits its own copy of this
- * block, so the guarantee survives the escape hatch.
+ * once**, then `themeToCss(theme)` per theme alongside it.
  *
- * Then a `@media (pointer: coarse)` block re-declaring the hit sizes from
- * {@link controlsCoarse}, for the same reason: the preference has to be honored
- * where the metric is *defined*, so a consumer who writes
- * `block-size: var(--skdx-control-height-md)` gets a touch-sized control without
- * having to remember the query.
+ * Also emits a `@media (prefers-reduced-motion: reduce)` block zeroing every
+ * motion duration/stagger at the definition site (WCAG 2.3.3 for free at every
+ * call site, no per-consumer media query), and a `@media (pointer: coarse)`
+ * block re-declaring the hit sizes from {@link controlsCoarse} the same way.
  *
  * @example
  * ```ts