@skdx/tokens 0.26.0 → 0.28.0

package/dist/utils/theme.d.cts

@@ -1,24 +1,13 @@
 /**
- * The SkandaDX theme contract.
- *
- * A theme is a plain JSON-serializable object, which makes it the natural
- * output format for a visual theme builder: the builder edits a `Theme`,
- * and `themeToCss()` turns it into CSS custom properties that the styled
- * (branded) component layer consumes.
+ * A theme is a plain JSON-serializable object; `themeToCss()` turns it into CSS custom properties.
  */
 /**
- * The two resolved color modes a theme renders in. A brand pairs one theme
- * per mode (see `brands`); `'system'` is a user *preference* consumers
- * resolve to one of these via `prefers-color-scheme` before picking a theme.
- *
+ * The two resolved color modes a theme renders in (resolved via `prefers-color-scheme`).
  * @public
  */
 export type ThemeColorMode = 'light' | 'dark';
 /**
- * An 11-step color ramp, 50 (lightest) → 950 (darkest), following the
- * Tailwind/Radix step convention. Each key renders as `--skdx-color-<name>-<step>`,
- * e.g. `primary[600]` → `--skdx-color-primary-600`.
- *
+ * 11-step color ramp, 50 (lightest) to 950 (darkest), rendered as `--skdx-color-<name>-<step>`.
  * @public
  */
 export interface ColorScale {
@@ -35,67 +24,57 @@ export interface ColorScale {
     950: string;
 }
 /**
- * Role-based colors resolved from the {@link ThemeColors} scales — reach for
- * these in component styling instead of a raw scale step, so swapping a
- * theme's palette doesn't require touching component CSS.
- *
+ * Role-based colors from {@link ThemeColors}; prefer these over raw scale steps in styling.
  * @public
  */
 export interface SemanticColors {
     /** Page background. */
     background: string;
-    /** Raised surface background (cards, panels). */
+    /** Raised surfaces (cards, panels). */
     surface: string;
-    /** Surface background on hover. */
+    /** Surface on hover. */
     surfaceHover: string;
-    /** Overlay/scrim behind dialogs and drawers, typically translucent. */
+    /** Overlay/scrim behind dialogs and drawers. */
     overlay: string;
-    /** Primary body text color. */
+    /** Primary body text. */
     text: string;
-    /** Secondary/de-emphasized text color. */
+    /** Secondary text. */
     textMuted: string;
-    /** Text color for use on filled/primary backgrounds. */
+    /** Text on filled/primary backgrounds. */
     textInverted: string;
     /** Default border color. */
     border: string;
-    /** Higher-contrast border, e.g. for inputs on hover/focus. */
+    /** Higher-contrast border (inputs on hover/focus). */
     borderStrong: string;
-    /** Focus ring / outline color. */
+    /** Focus ring color. */
     focusRing: string;
 }
-/** The five color scales a theme provides, each rendered as `--skdx-color-<name>-<step>`. @public */
+/** Five color scales, each rendered as `--skdx-color-<name>-<step>`. @public */
 export interface ThemeColors {
-    /** Brand/accent color, e.g. buttons, links, focus states at 500–600. */
+    /** Brand/accent color (buttons, links, focus at 500–600). */
     primary: ColorScale;
-    /** Grays used for text, borders, and surfaces. */
+    /** Text, borders, and surface grays. */
     neutral: ColorScale;
-    /** Positive/confirmation states (e.g. success toasts, valid form fields). */
+    /** Success/confirmation states. */
     success: ColorScale;
-    /** Caution states (e.g. warning banners). */
+    /** Warning/caution states. */
     warning: ColorScale;
-    /** Destructive/error states (e.g. delete buttons, invalid form fields). */
+    /** Danger/error states. */
     danger: ColorScale;
-    /** Role-based colors resolved from the scales above — components should prefer these over raw scale steps. */
+    /** Role-based colors from scales; components prefer these over raw steps. */
     semantic: SemanticColors;
 }
 /**
- * Font stacks, the type scale, and weight/line-height tokens. Rendered as
- * `--skdx-font-*`.
- *
- * **Not part of {@link Theme}** — typography is theme-invariant and lives once
- * in `foundation.ts` (see {@link typography}). A theme selects colors; it does
- * not get to resize the type scale out from under a layout. The two font
- * *stacks* are the sole exception, and only for themes that impersonate a
- * published design language — see {@link ThemeTypographyDeviation}.
- *
+ * Font stacks, type scale, weight/line-height tokens, rendered as `--skdx-font-*`.
+ * Theme-invariant except the two font stacks (see {@link ThemeTypographyDeviation}).
  * @public
  */
 export interface ThemeTypography {
-    /** Body font stack, e.g. `-apple-system, BlinkMacSystemFont, 'Segoe UI', …`. */
+    /** Body font stack. */
     fontFamily: string;
-    /** Monospace stack for code, e.g. `'SF Mono', ui-monospace, …`. */
+    /** Monospace stack for code. */
     fontFamilyMono: string;
-    /** Type scale from `xs` to `3xl`, e.g. `{ xs: '0.75rem', … }`. */
+    /** Type scale `xs` to `3xl`. */
     fontSize: {
         xs: string;
         sm: string;
@@ -105,29 +84,21 @@ export interface ThemeTypography {
         '2xl': string;
         '3xl': string;
     };
-    /** Numeric font weights, e.g. `{ regular: 400, medium: 500, semibold: 600, bold: 700 }`. */
+    /** Font weights: regular, medium, semibold, bold. */
     fontWeight: {
         regular: number;
         medium: number;
         semibold: number;
         bold: number;
     };
-    /**
-     * Unitless-or-CSS line-height values. `snug` is the control step — the
-     * leading a button, tab or menu label takes, tighter than body copy but not
-     * as clipped as `tight`, which is a display-heading value.
-     */
+    /** Line heights. `snug` is the control step (tighter than body, looser than `tight`). */
     lineHeight: {
         tight: string;
         snug: string;
         normal: string;
         relaxed: string;
     };
-    /**
-     * Tracking scale, rendered as `--skdx-font-letter-spacing-<step>`. `tight`
-     * suits large display headings (which look loose at their default
-     * tracking); `wide`/`wider` suit small-caps, overlines and button labels.
-     */
+    /** Tracking scale, rendered as `--skdx-font-letter-spacing-<step>`. */
     letterSpacing: {
         tight: string;
         normal: string;
@@ -136,9 +107,8 @@ export interface ThemeTypography {
     };
 }
 /**
- * Spacing scale (margin, padding, gap). Rendered as `--skdx-space-<step>`.
- * **Not part of {@link Theme}** — lives once in `foundation.ts` (see {@link space}).
- * @public
+ * Spacing scale (margin, padding, gap), rendered as `--skdx-space-<step>`.
+ * Lives once in `foundation.ts` (see {@link space}). @public
  */
 export interface ThemeSpace {
     '1': string;
@@ -153,54 +123,27 @@ export interface ThemeSpace {
     '16': string;
 }
 /**
- * Border-radius scale. Rendered as `--skdx-radius-<size>`.
- * **Not part of {@link Theme}** — lives once in `foundation.ts` (see {@link radii}).
- * @public
+ * Border-radius scale, rendered as `--skdx-radius-<size>`.
+ * Lives once in `foundation.ts` (see {@link radii}). @public
  */
 export interface ThemeRadii {
     sm: string;
-    /**
-     * The radius of a box nested *inside* a larger radiused surface — a menu row
-     * inside an overlay, a segment inside its well, a checkbox box. Sits between
-     * `sm` and `md` rather than at a ramp position of its own, because it is a
-     * relationship (inner to outer) and not a size step.
-     */
+    /** Nested box radius (relationship between `sm` and `md`, not a size step). */
     inner: string;
     md: string;
     lg: string;
     xl: string;
-    /** Fully round, e.g. `9999px` — for pills and circular avatars. */
+    /** Fully round, for pills and circular avatars. */
     full: string;
 }
 /**
- * Control geometry — the metrics a Button, an Input and a Select at the same
- * size all snap to, so they line up on a form row without each stylesheet
- * re-deciding what "md" means.
- *
- * **Not part of {@link Theme}** — lives once in `foundation.ts` (see
- * {@link controls}), for the same reason {@link space} does: density is a
- * property of the design system, not of the brand painted on top of it. A
- * consumer retunes it by setting the emitted custom properties on a subtree:
- *
- * ```css
- * .compact-form { --skdx-control-height-md: 2rem; }
- * ```
- *
- * Values may reference other tokens (`var(--skdx-space-3)`) rather than restate
- * a length, and several deliberately do — that is what keeps a control's
- * padding on the spacing scale instead of beside it.
- *
- * @public
+ * Control geometry: metrics Button, Input and Select snap to.
+ * Lives once in `foundation.ts` (see {@link controls}). @public
  */
 export interface ThemeControls {
-    /** The control itself: the vertical rhythm, and the inline padding and icon gap paired with it. */
+    /** Vertical rhythm, inline padding and icon gap. */
     control: {
-        /**
-         * `compact` is the odd one out and is not a ramp step: it is the square a
-         * pagination link or a SegmentedControl segment takes, which sits inside a
-         * strip rather than on a form row and is a step under `md` in both
-         * reference libraries surveyed.
-         */
+        /** `compact`: pagination/segment square, step below `md` (not a ramp step). */
         height: {
             sm: string;
             md: string;
@@ -218,19 +161,19 @@ export interface ThemeControls {
             lg: string;
         };
     };
-    /** Glyph box inside a control. Proportional to the control, not to the font size, so changing line-height does not resize every icon. */
+    /** Glyph box size, proportional to control (not font size; unaffected by line-height). */
     iconSize: {
         sm: string;
         md: string;
         lg: string;
     };
-    /** Selection indicators — checkbox box, radio dot, slider thumb. Switch pins its own track size; see `switch.css`. */
+    /** Selection indicators: checkbox, radio, slider thumb. Switch sets own track; see `switch.css`. */
     indicatorSize: {
         sm: string;
         md: string;
         lg: string;
     };
-    /** Collection rows — menu items, listbox options, table rows — and the seam between them. */
+    /** Collection row heights (menus, listbox, table) and gaps between. */
     item: {
         height: {
             sm: string;
@@ -245,25 +188,19 @@ export interface ThemeControls {
         radius: string;
         minWidth: string;
     };
-    /** Field furniture — the vertical step from a label to its control, and from a control to its help text. */
+    /** Label-to-control and control-to-help-text gaps. */
     field: {
         gap: string;
         labelGap: string;
     };
-    /** Minimum hit target. WCAG 2.2 §2.5.8 asks for 24×24 CSS px; the coarse-pointer tier raises it to the AAA 44px. */
+    /** Minimum hit target: 24×24 CSS px (WCAG 2.2 §2.5.8); 44px for coarse pointers. */
     target: {
         min: string;
     };
 }
 /**
- * The subset of {@link ThemeControls} that a coarse pointer overrides.
- *
- * Touch input gets larger targets, and `pointer: coarse` is the honest test —
- * a small window on a desktop is still driven by a mouse, and a large tablet is
- * still driven by a finger. Only sizes that are *hit* are listed: padding,
- * gaps, radii and icon boxes are unchanged by how the user is pointing.
- *
- * @public
+ * {@link ThemeControls} overrides for coarse pointers. Only hit-target sizes;
+ * padding, gaps, radii, icons unchanged. @public
  */
 export interface ThemeControlsCoarse {
     control: {
@@ -286,206 +223,113 @@ export interface ThemeControlsCoarse {
     };
 }
 /**
- * Box-shadow scale, including the `overlay` shadow used by dialogs/popovers.
- * Rendered as `--skdx-shadow-<size>`.
- *
- * **Not part of {@link Theme}** — the *geometry* (offsets, blurs, spreads and
- * base alphas) lives once in `foundation.ts` (see {@link shadows}), and each
- * value defers its color to `var(--skdx-shadow-color)` /
- * `var(--skdx-shadow-strength)`, which is what a theme supplies via
- * {@link ThemeShadowColor}. Before this split every theme repeated the same
- * three offsets purely because they were welded to a color literal in the same
- * string.
- *
+ * Box-shadow scale, rendered as `--skdx-shadow-<size>`. Geometry lives once
+ * in `foundation.ts` (see {@link shadows}); color defers to {@link ThemeShadowColor}.
  * @public
  */
 export interface ThemeShadows {
     sm: string;
     md: string;
     lg: string;
-    /** Shadow for elevated overlay surfaces (dialog, popover, dropdown content). */
+    /** Elevated overlay surfaces (dialogs, popovers, dropdowns). */
     overlay: string;
 }
 /**
- * The color half of the shadow contract — the only part of a shadow a theme
- * owns. The geometry it tints lives in {@link shadows}.
- *
- * @public
+ * Shadow color: the only part of {@link shadows} a theme owns;
+ * geometry lives in the base.  @public
  */
 export interface ThemeShadowColor {
-    /**
-     * Space-separated sRGB channels, e.g. `'2 6 23'` — **not** a hex string. It
-     * is substituted into `rgb(<color> / <alpha>)`, which has no hex form.
-     */
+    /** sRGB channels (e.g. `'2 6 23'`), substituted into `rgb(<color> / <alpha>)`. */
     color: string;
     /**
-     * Unitless multiplier applied to every base alpha in {@link shadows}. `'1'`
-     * is the light-theme reference and reproduces the original `skanda-light`
-     * shadows exactly; dark themes run around `'5'` because a shadow has to work
-     * against a dark surface rather than a white page. This is the calibration
-     * knob — it is a look, not a measurement, and is meant to be tuned by eye.
+     * Multiplier for base alphas in {@link shadows}. `'1'` for light themes;
+     * dark themes ~`'5'` (shadow must work on dark surface).
      */
     strength: string;
 }
 /**
- * The font stacks a theme may override — the only part of {@link typography}
- * that isn't fixed system-wide.
- *
- * Deliberately just the two stacks. A theme that merely *looks* different has
- * no business resizing the type scale: a layout that reflows when you switch
- * brand was only ever designed against one scale, and every other brand was
- * hoping. Impersonating a design language, though, means impersonating its
- * typeface — which is why `fluent` and `material-you` declare this and nothing
- * else does.
- *
- * Present on a theme = the deviation. There is no wrapper to opt into.
- *
- * @public
+ * Font stacks a theme may override (only part of {@link typography} not fixed).
+ * Only `fluent` and `material-you` declare it. @public
  */
 export type ThemeTypographyDeviation = Partial<Pick<ThemeTypography, 'fontFamily' | 'fontFamilyMono'>>;
 /**
- * The motion tokens a theme may retune — the four originally-required ones.
- * The optional tokens ({@link ThemeMotion.easingExit}, the staggers, …) are
- * deliberately unreachable: they exist to be uniform, and a theme that split
- * an entrance curve from its matching exit would be shipping a mismatch, not a
- * brand.
- *
- * See {@link ThemeMotion} for why motion is otherwise theme-invariant. Only
- * `material-you`, `fluent` and `ant-daybreak` declare this (plus their dark
- * counterparts, which inherit it through `createTheme`).
- *
- * @public
+ * Motion tokens a theme may retune. Optional ones (exit, staggers) stay uniform.
+ * Only `material-you`, `fluent` and `ant-daybreak` declare. @public
  */
 export type ThemeMotionDeviation = Partial<Pick<ThemeMotion, 'durationFast' | 'durationNormal' | 'durationSlow' | 'easing'>>;
 /**
- * Animation durations, named easing curves, and stagger intervals shared by
- * all components' transitions. Rendered as `--skdx-motion-*`.
- *
- * **Motion is theme-invariant by default, and that is deliberate.** A theme
- * changes what the product *looks* like; it should not change how long the
- * product makes you wait. Timing that shifts under you between brands reads
- * as a bug, not as branding, and it silently changes the WCAG 2.3.3 surface
- * (a 300ms curve and a 500ms curve are not equally forgiving to a vestibular
- * user). Motion therefore lives once in `foundation.ts` (see {@link motion}),
- * not on {@link Theme}. The three brand themes that *do* retune the base curve
- * — `materialBrand`, `antBrand`, `fluentBrand` — declare it through
- * {@link ThemeMotionDeviation}, the narrow escape hatch: each mirrors the
- * published motion spec of the design language it impersonates, which is the
- * whole point of those themes. Everything added below is left un-overridden by
- * every bundled theme, and `ThemeMotionDeviation` cannot reach it.
- *
- * Every field beyond the original four is optional so that adding a token
- * here never breaks a hand-written motion literal downstream;
- * {@link defaultMotion} supplies the value that is actually emitted when one
- * is omitted.
- *
- * @public
+ * Animation durations, easing curves, and staggers rendered as `--skdx-motion-*`.
+ * Theme-invariant by default (timing shift reads as bug, affects vestibular users).
+ * Lives once in `foundation.ts` (see {@link motion}). `materialBrand`, `antBrand`,
+ * `fluentBrand` retune via {@link ThemeMotionDeviation}. @public
  */
 export interface ThemeMotion {
     /**
-     * Zero — for state changes that must feel like data, not animation (a probe
-     * re-rendering, a value updating). Named rather than hardcoded so "this is
-     * deliberately not animated" is legible at the call site.
+     * Zero for state changes that feel like data, not animation (value updates).
      * @default '0ms'
      */
     durationInstant?: string;
-    /** Hover, focus and press micro-interactions — short enough to feel like direct manipulation. */
+    /** Hover/focus/press micro-interactions (direct manipulation). */
     durationFast: string;
-    /** Open/close transitions for inline disclosure, e.g. accordion and collapsible panels. */
+    /** Open/close transitions for inline disclosure (accordion, collapsible). */
     durationNormal: string;
-    /** Larger overlay enter/exit transitions, e.g. dialogs, drawers and popovers. */
+    /** Overlay transitions: dialogs, drawers, popovers. */
     durationSlow: string;
-    /**
-     * The default curve: a fast start with a long, soft landing (an expo-style
-     * decelerate). Feels like something arriving and settling into place, so
-     * use it for anything entering the screen or growing open.
-     */
+    /** Default curve: fast start, soft landing (for entering/opening). */
     easing: string;
     /**
-     * Mirror of {@link ThemeMotion.easing} — a slow start that accelerates away.
-     * Feels like something leaving rather than retreating, so use it for exits,
-     * dismissals and closes, where holding the user's attention on the way out
-     * is exactly what you do not want.
+     * Mirror of {@link ThemeMotion.easing} (slow start, accelerates). For exits.
      * @default 'cubic-bezier(0.4, 0, 1, 1)'
      */
     easingExit?: string;
     /**
-     * A symmetric ease-in-out with no overshoot and no drama. Feels like a
-     * value changing rather than an object moving, so use it for in-place state
-     * changes where nothing enters or leaves: colour swaps, toggles, theme
-     * changes, a control acknowledging that it was pressed.
+     * Symmetric ease-in-out, no overshoot (in-place: color swaps, toggles).
      * @default 'cubic-bezier(0.4, 0, 0.2, 1)'
      */
     easingSteady?: string;
     /**
-     * Constant rate, no acceleration at either end. Feels mechanical, which is
-     * correct for indeterminate loops — a spinner or a shimmer easing at every
-     * cycle boundary reads as a stutter or a stall rather than as progress.
+     * Constant rate (indeterminate loops: spinner, shimmer).
      * @default 'linear'
      */
     easingLinear?: string;
     /**
-     * Per-item delay for a sweep across many elements at once, small enough
-     * that the whole set still reads as one gesture rather than as a sequence.
-     * Use it when the count is large or unbounded — a page-wide theme change, a
-     * grid of icons re-tinting.
+     * Per-item sweep delay (reads as one gesture for large/unbounded lists).
      * @default '4ms'
      */
     staggerTight?: string;
     /**
-     * Per-item delay for a sequence you are meant to actually perceive as a
-     * sequence, where each item arrives distinctly. Use it only for short,
-     * bounded lists — at a dozen items it is already a noticeable wait, and at
-     * fifty it is a loading screen.
+     * Per-item sequence delay (distinct arrival, short/bounded lists only).
      * @default '40ms'
      */
     staggerLoose?: string;
 }
 /**
- * The canonical motion values, and the fallback {@link themeToCss} merges
- * under a theme's own `motion` so that every theme emits the complete
- * `--skdx-motion-*` surface — including the optional tokens no hand-written
- * `Theme` literal declares. Keeping the values here rather than only in
- * `defaultTheme` is what lets a theme opt out of a token without opting out
- * of the CSS variable.
+ * Default motion values; merged under a theme's `motion` so every theme
+ * emits the complete `--skdx-motion-*` surface.
  */
 export declare const defaultMotion: Required<ThemeMotion>;
 /**
- * A complete, plain-JSON-serializable theme — the single object that flows
- * through {@link createTheme}, {@link themeToCss}, and {@link applyTheme}.
- *
- * **A theme is colors.** The type scale, weights, line-heights, tracking, the
- * spacing scale, the radius scale, shadow geometry and motion timing are
- * theme-invariant and live once in `foundation.ts`, emitted at `:root` by
- * {@link foundationToCss}. Every bundled theme used to restate all of them
- * identically — 38 copies of the same 62 lines — which made "what does this
- * theme actually change?" unanswerable without a diff, and made adding a token
- * a 38-file edit.
- *
- * The two escape hatches — `typography` and `motion` — are optional and
- * narrow, for the themes that impersonate a published design language.
- * Declaring one *is* the deviation; there is nothing to opt into.
- *
- * @public
+ * Complete theme object flowing through {@link createTheme}, {@link themeToCss},
+ * and {@link applyTheme}. Contains only colors; type scale, spacing, radii,
+ * shadow, motion are theme-invariant (see `foundation.ts`). `typography` and
+ * `motion` are escape hatches for impersonating design languages. @public
  */
 export interface Theme {
-    /** Unique theme name, e.g. `"skanda-light"`. Used as the `[data-skdx-theme="..."]` selector and the `data-skdx-theme` attribute value. */
+    /** Unique theme name (e.g. `"skanda-light"`), used as `[data-skdx-theme="..."]` selector. */
     name: string;
-    /** Which color mode this theme renders — `applyTheme` stamps it as `data-skdx-mode`. */
+    /** Color mode this theme renders; emitted as `data-skdx-mode` by `applyTheme`. */
     mode: ThemeColorMode;
     colors: ThemeColors;
-    /** The color half of the shared shadow geometry — see {@link ThemeShadowColor}. */
+    /** Shadow color tint; see {@link ThemeShadowColor}. */
     shadow: ThemeShadowColor;
-    /** Font-stack deviation. Absent on all but two bundled themes — see {@link ThemeTypographyDeviation}. */
+    /** Font-stack override (two bundled themes only); see {@link ThemeTypographyDeviation}. */
     typography?: ThemeTypographyDeviation;
-    /** Motion deviation. Absent on all but three bundled themes — see {@link ThemeMotionDeviation}. */
+    /** Motion override (three bundled themes only); see {@link ThemeMotionDeviation}. */
     motion?: ThemeMotionDeviation;
 }
 /**
- * A partial {@link Theme} for describing only what a brand changes from the
- * default — every leaf value at every level is optional. Passed to
- * {@link createTheme}, which deep-merges it onto a base theme.
- *
+ * Partial {@link Theme} describing only what a brand changes. Passed to
+ * {@link createTheme}, which deep-merges onto a base theme.
  * @example
  * ```ts
  * const override: ThemeOverride = {
@@ -493,7 +337,6 @@ export interface Theme {
  *   shadow: { strength: '5' },
  * };
  * ```
- *
  * @public
  */
 export type ThemeOverride = {