@skdx/tokens 0.26.0 → 0.28.0

package/dist/utils/foundation.d.ts

@@ -1,79 +1,42 @@
 import { type ThemeControls, type ThemeControlsCoarse, type ThemeMotion, type ThemeRadii, type ThemeShadows, type ThemeSpace, type ThemeTypography } from './theme.js';
 /**
- * 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

package/dist/utils/mode.d.cts

@@ -1,62 +1,31 @@
-/** `localStorage` key the mode preference (`'light' | 'dark' | 'system'`) is read from and written to. @public */
+/** `localStorage` key for mode preference (`'light' | 'dark' | 'system'`). @public */
 export declare const MODE_STORAGE_KEY = "skdx-mode";
-/** `localStorage` key the brand preference (a {@link Brand} name, e.g. `'nord'`) is read from. @public */
+/** `localStorage` key for brand preference (a {@link Brand} name). @public */
 export declare const BRAND_STORAGE_KEY = "skdx-brand";
 /** Options for {@link watchSystemMode}. @public */
 export interface WatchSystemModeOptions {
-    /** Brand whose light/dark pair is applied. Unknown names fall back to the default brand. @default 'skanda' */
+    /** Brand pair to apply (unknown names fall back to default). @default 'skanda' */
     brand?: string;
-    /** Element the resolved theme is applied to. @default document.documentElement */
+    /** Target element for theme. @default document.documentElement */
     element?: HTMLElement;
-    /** Whether to mirror the resolved mode into `localStorage` under {@link storageKey}. @default false */
+    /** Mirror resolved mode to `localStorage`. @default false */
     persist?: boolean;
-    /** `localStorage` key used when `persist` is on. @default MODE_STORAGE_KEY */
+    /** `localStorage` key when `persist` is on. @default MODE_STORAGE_KEY */
     storageKey?: string;
 }
 /**
- * Follows the OS color-scheme preference: applies the brand's theme for the
- * currently resolved mode, then re-applies it whenever the preference flips
- * — the runtime half of "mode: system". Call it once on mount and call the
- * returned function on unmount.
- *
- * Browser-only (it reads `window.matchMedia`); guard it behind a mounted
- * effect in an SSR framework, and pair it with {@link getThemeInitScript} so
- * the first paint already matches.
- *
- * @returns An unsubscribe function that detaches the change listener.
+ * Follow OS color-scheme: apply theme, re-apply on preference change (runtime half
+ * of "mode: system"). Browser-only; guard behind mounted effect in SSR.
+ * Pair with {@link getThemeInitScript} so first paint matches.
  *
+ * @returns Unsubscribe function (detaches listener).
  * @example
  * ```ts
  * import { watchSystemMode } from '@skdx/tokens';
- *
  * const stop = watchSystemMode({ brand: 'nord', persist: true });
- * // later…
  * stop();
  * ```
- *
  * @public
- */
-export declare function watchSystemMode(options?: WatchSystemModeOptions): () => void;
-/** Options for {@link getThemeInitScript}. @public */
-export interface ThemeInitScriptOptions {
-    /** `localStorage` key holding the brand name. @default BRAND_STORAGE_KEY */
-    brandKey?: string;
-    /** `localStorage` key holding `'light' | 'dark' | 'system'`. @default MODE_STORAGE_KEY */
-    modeKey?: string;
-    /** Brand used when nothing is persisted or the persisted name is unknown. @default 'skanda' */
-    fallbackBrand?: string;
-}
-/**
- * Builds the blocking snippet that stamps `data-skdx-theme` and `data-skdx-mode`
- * on `<html>` *before first paint*, so a dark-mode visitor never sees a flash
- * of the light theme. It reads the persisted brand and mode, resolves
- * `'system'` through `prefers-color-scheme`, and maps brand + mode to the
- * theme name your stylesheet is keyed by — the brand→theme-name table is
- * baked into the returned string at call time from {@link brands}.
- *
- * Returns bare JavaScript (no `<script>` wrapper) so each framework can inject
- * it its own way. It only sets attributes, so the page's CSS must already
- * contain a `[data-skdx-theme="…"]` block per theme (see `themeToCss`).
  *
  * @example Next.js (App Router, `app/layout.tsx`)
  * ```tsx
@@ -78,12 +47,31 @@ export interface ThemeInitScriptOptions {
  *   <script>%skdx.themeInit%</script>
  * </head>
  * ```
+ */
+export declare function watchSystemMode(options?: WatchSystemModeOptions): () => void;
+/** Options for {@link getThemeInitScript}. @public */
+export interface ThemeInitScriptOptions {
+    /** `localStorage` key for brand name. @default BRAND_STORAGE_KEY */
+    brandKey?: string;
+    /** `localStorage` key for mode. @default MODE_STORAGE_KEY */
+    modeKey?: string;
+    /** Fallback brand when nothing persisted or unknown. @default 'skanda' */
+    fallbackBrand?: string;
+}
+/**
+ * Blocking snippet that stamps `data-skdx-theme` and `data-skdx-mode` on
+ * `<html>` before first paint (prevents dark-mode flash). Resolves `'system'`
+ * through `prefers-color-scheme`. Returns bare JS (no `<script>` wrapper);
+ * your CSS must have `[data-skdx-theme="…"]` blocks.
  *
- * @example Astro (`src/layouts/Base.astro`)
+ * @example Next.js
+ * ```tsx
+ * <script dangerouslySetInnerHTML={{ __html: getThemeInitScript() }} />
+ * ```
+ * @example Astro
  * ```astro
  * <script is:inline set:html={getThemeInitScript()} />
  * ```
- *
  * @public
  */
 export declare function getThemeInitScript(options?: ThemeInitScriptOptions): string;

package/dist/utils/mode.d.ts

@@ -1,62 +1,31 @@
-/** `localStorage` key the mode preference (`'light' | 'dark' | 'system'`) is read from and written to. @public */
+/** `localStorage` key for mode preference (`'light' | 'dark' | 'system'`). @public */
 export declare const MODE_STORAGE_KEY = "skdx-mode";
-/** `localStorage` key the brand preference (a {@link Brand} name, e.g. `'nord'`) is read from. @public */
+/** `localStorage` key for brand preference (a {@link Brand} name). @public */
 export declare const BRAND_STORAGE_KEY = "skdx-brand";
 /** Options for {@link watchSystemMode}. @public */
 export interface WatchSystemModeOptions {
-    /** Brand whose light/dark pair is applied. Unknown names fall back to the default brand. @default 'skanda' */
+    /** Brand pair to apply (unknown names fall back to default). @default 'skanda' */
     brand?: string;
-    /** Element the resolved theme is applied to. @default document.documentElement */
+    /** Target element for theme. @default document.documentElement */
     element?: HTMLElement;
-    /** Whether to mirror the resolved mode into `localStorage` under {@link storageKey}. @default false */
+    /** Mirror resolved mode to `localStorage`. @default false */
     persist?: boolean;
-    /** `localStorage` key used when `persist` is on. @default MODE_STORAGE_KEY */
+    /** `localStorage` key when `persist` is on. @default MODE_STORAGE_KEY */
     storageKey?: string;
 }
 /**
- * Follows the OS color-scheme preference: applies the brand's theme for the
- * currently resolved mode, then re-applies it whenever the preference flips
- * — the runtime half of "mode: system". Call it once on mount and call the
- * returned function on unmount.
- *
- * Browser-only (it reads `window.matchMedia`); guard it behind a mounted
- * effect in an SSR framework, and pair it with {@link getThemeInitScript} so
- * the first paint already matches.
- *
- * @returns An unsubscribe function that detaches the change listener.
+ * Follow OS color-scheme: apply theme, re-apply on preference change (runtime half
+ * of "mode: system"). Browser-only; guard behind mounted effect in SSR.
+ * Pair with {@link getThemeInitScript} so first paint matches.
  *
+ * @returns Unsubscribe function (detaches listener).
  * @example
  * ```ts
  * import { watchSystemMode } from '@skdx/tokens';
- *
  * const stop = watchSystemMode({ brand: 'nord', persist: true });
- * // later…
  * stop();
  * ```
- *
  * @public
- */
-export declare function watchSystemMode(options?: WatchSystemModeOptions): () => void;
-/** Options for {@link getThemeInitScript}. @public */
-export interface ThemeInitScriptOptions {
-    /** `localStorage` key holding the brand name. @default BRAND_STORAGE_KEY */
-    brandKey?: string;
-    /** `localStorage` key holding `'light' | 'dark' | 'system'`. @default MODE_STORAGE_KEY */
-    modeKey?: string;
-    /** Brand used when nothing is persisted or the persisted name is unknown. @default 'skanda' */
-    fallbackBrand?: string;
-}
-/**
- * Builds the blocking snippet that stamps `data-skdx-theme` and `data-skdx-mode`
- * on `<html>` *before first paint*, so a dark-mode visitor never sees a flash
- * of the light theme. It reads the persisted brand and mode, resolves
- * `'system'` through `prefers-color-scheme`, and maps brand + mode to the
- * theme name your stylesheet is keyed by — the brand→theme-name table is
- * baked into the returned string at call time from {@link brands}.
- *
- * Returns bare JavaScript (no `<script>` wrapper) so each framework can inject
- * it its own way. It only sets attributes, so the page's CSS must already
- * contain a `[data-skdx-theme="…"]` block per theme (see `themeToCss`).
  *
  * @example Next.js (App Router, `app/layout.tsx`)
  * ```tsx
@@ -78,12 +47,31 @@ export interface ThemeInitScriptOptions {
  *   <script>%skdx.themeInit%</script>
  * </head>
  * ```
+ */
+export declare function watchSystemMode(options?: WatchSystemModeOptions): () => void;
+/** Options for {@link getThemeInitScript}. @public */
+export interface ThemeInitScriptOptions {
+    /** `localStorage` key for brand name. @default BRAND_STORAGE_KEY */
+    brandKey?: string;
+    /** `localStorage` key for mode. @default MODE_STORAGE_KEY */
+    modeKey?: string;
+    /** Fallback brand when nothing persisted or unknown. @default 'skanda' */
+    fallbackBrand?: string;
+}
+/**
+ * Blocking snippet that stamps `data-skdx-theme` and `data-skdx-mode` on
+ * `<html>` before first paint (prevents dark-mode flash). Resolves `'system'`
+ * through `prefers-color-scheme`. Returns bare JS (no `<script>` wrapper);
+ * your CSS must have `[data-skdx-theme="…"]` blocks.
  *
- * @example Astro (`src/layouts/Base.astro`)
+ * @example Next.js
+ * ```tsx
+ * <script dangerouslySetInnerHTML={{ __html: getThemeInitScript() }} />
+ * ```
+ * @example Astro
  * ```astro
  * <script is:inline set:html={getThemeInitScript()} />
  * ```
- *
  * @public
  */
 export declare function getThemeInitScript(options?: ThemeInitScriptOptions): string;