@skdx/tokens 0.26.0

package/dist/utils/theme.d.cts

@@ -0,0 +1,503 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ *
+ * @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`.
+ *
+ * @public
+ */
+export interface ColorScale {
+    50: string;
+    100: string;
+    200: string;
+    300: string;
+    400: string;
+    500: string;
+    600: string;
+    700: string;
+    800: string;
+    900: string;
+    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.
+ *
+ * @public
+ */
+export interface SemanticColors {
+    /** Page background. */
+    background: string;
+    /** Raised surface background (cards, panels). */
+    surface: string;
+    /** Surface background on hover. */
+    surfaceHover: string;
+    /** Overlay/scrim behind dialogs and drawers, typically translucent. */
+    overlay: string;
+    /** Primary body text color. */
+    text: string;
+    /** Secondary/de-emphasized text color. */
+    textMuted: string;
+    /** Text color for use on filled/primary backgrounds. */
+    textInverted: string;
+    /** Default border color. */
+    border: string;
+    /** Higher-contrast border, e.g. for inputs on hover/focus. */
+    borderStrong: string;
+    /** Focus ring / outline color. */
+    focusRing: string;
+}
+/** The five color scales a theme provides, each rendered as `--skdx-color-<name>-<step>`. @public */
+export interface ThemeColors {
+    /** Brand/accent color, e.g. buttons, links, focus states at 500–600. */
+    primary: ColorScale;
+    /** Grays used for text, borders, and surfaces. */
+    neutral: ColorScale;
+    /** Positive/confirmation states (e.g. success toasts, valid form fields). */
+    success: ColorScale;
+    /** Caution states (e.g. warning banners). */
+    warning: ColorScale;
+    /** Destructive/error states (e.g. delete buttons, invalid form fields). */
+    danger: ColorScale;
+    /** Role-based colors resolved from the scales above — components should prefer these over raw scale 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}.
+ *
+ * @public
+ */
+export interface ThemeTypography {
+    /** Body font stack, e.g. `-apple-system, BlinkMacSystemFont, 'Segoe UI', …`. */
+    fontFamily: string;
+    /** Monospace stack for code, e.g. `'SF Mono', ui-monospace, …`. */
+    fontFamilyMono: string;
+    /** Type scale from `xs` to `3xl`, e.g. `{ xs: '0.75rem', … }`. */
+    fontSize: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+        '3xl': string;
+    };
+    /** Numeric font weights, e.g. `{ regular: 400, medium: 500, semibold: 600, bold: 700 }`. */
+    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.
+     */
+    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.
+     */
+    letterSpacing: {
+        tight: string;
+        normal: string;
+        wide: string;
+        wider: string;
+    };
+}
+/**
+ * Spacing scale (margin, padding, gap). Rendered as `--skdx-space-<step>`.
+ * **Not part of {@link Theme}** — lives once in `foundation.ts` (see {@link space}).
+ * @public
+ */
+export interface ThemeSpace {
+    '1': string;
+    '2': string;
+    '3': string;
+    '4': string;
+    '5': string;
+    '6': string;
+    '8': string;
+    '10': string;
+    '12': string;
+    '16': string;
+}
+/**
+ * Border-radius scale. Rendered as `--skdx-radius-<size>`.
+ * **Not part of {@link Theme}** — 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.
+     */
+    inner: string;
+    md: string;
+    lg: string;
+    xl: string;
+    /** Fully round, e.g. `9999px` — 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
+ */
+export interface ThemeControls {
+    /** The control itself: the vertical rhythm, and the inline padding and icon gap paired with it. */
+    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.
+         */
+        height: {
+            sm: string;
+            md: string;
+            lg: string;
+            compact: string;
+        };
+        padding: {
+            sm: string;
+            md: string;
+            lg: string;
+        };
+        gap: {
+            sm: string;
+            md: string;
+            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. */
+    iconSize: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+    /** Selection indicators — checkbox box, radio dot, slider thumb. Switch pins its own track size; see `switch.css`. */
+    indicatorSize: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+    /** Collection rows — menu items, listbox options, table rows — and the seam between them. */
+    item: {
+        height: {
+            sm: string;
+            md: string;
+            lg: string;
+        };
+        gap: string;
+    };
+    /** Floating surfaces: menus, popovers, dialogs. */
+    overlay: {
+        padding: string;
+        radius: string;
+        minWidth: string;
+    };
+    /** Field furniture — the vertical step from a label to its control, and from a control to its help text. */
+    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. */
+    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
+ */
+export interface ThemeControlsCoarse {
+    control: {
+        height: {
+            sm: string;
+            md: string;
+            lg: string;
+            compact: string;
+        };
+    };
+    item: {
+        height: {
+            sm: string;
+            md: string;
+            lg: string;
+        };
+    };
+    target: {
+        min: string;
+    };
+}
+/**
+ * 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.
+ *
+ * @public
+ */
+export interface ThemeShadows {
+    sm: string;
+    md: string;
+    lg: string;
+    /** Shadow for elevated overlay surfaces (dialog, popover, dropdown content). */
+    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
+ */
+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.
+     */
+    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.
+     */
+    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
+ */
+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
+ */
+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
+ */
+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.
+     * @default '0ms'
+     */
+    durationInstant?: string;
+    /** Hover, focus and press micro-interactions — short enough to feel like direct manipulation. */
+    durationFast: string;
+    /** Open/close transitions for inline disclosure, e.g. accordion and collapsible panels. */
+    durationNormal: string;
+    /** Larger overlay enter/exit transitions, e.g. dialogs, drawers and 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.
+     */
+    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.
+     * @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.
+     * @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.
+     * @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.
+     * @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.
+     * @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.
+ */
+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
+ */
+export interface Theme {
+    /** Unique theme name, e.g. `"skanda-light"`. Used as the `[data-skdx-theme="..."]` selector and the `data-skdx-theme` attribute value. */
+    name: string;
+    /** Which color mode this theme renders — `applyTheme` stamps it as `data-skdx-mode`. */
+    mode: ThemeColorMode;
+    colors: ThemeColors;
+    /** The color half of the shared shadow geometry — see {@link ThemeShadowColor}. */
+    shadow: ThemeShadowColor;
+    /** Font-stack deviation. Absent on all but two bundled themes — see {@link ThemeTypographyDeviation}. */
+    typography?: ThemeTypographyDeviation;
+    /** Motion deviation. Absent on all but three bundled themes — 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.
+ *
+ * @example
+ * ```ts
+ * const override: ThemeOverride = {
+ *   colors: { primary: { 500: '#7c3aed', 600: '#6d28d9' }, semantic: { focusRing: '#7c3aed' } },
+ *   shadow: { strength: '5' },
+ * };
+ * ```
+ *
+ * @public
+ */
+export type ThemeOverride = {
+    [K in keyof Theme]?: Theme[K] extends object ? {
+        [K2 in keyof Theme[K]]?: Theme[K][K2] extends object ? Partial<Theme[K][K2]> : Theme[K][K2];
+    } : Theme[K];
+};