@skdx/tokens 0.26.0

package/dist/utils/foundation.d.ts

@@ -0,0 +1,300 @@
+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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @example
+ * ```css
+ * .dialog-overlay { z-index: var(--skdx-z-index-overlay); }
+ * .select-content { z-index: var(--skdx-z-index-popover); }
+ * .toast-viewport { z-index: var(--skdx-z-index-toast); }
+ * ```
+ *
+ * @public
+ */
+export declare const zIndex: {
+    readonly base: 0;
+    readonly dropdown: 10;
+    readonly sticky: 20;
+    /** The scrim behind a modal surface. */
+    readonly overlay: 30;
+    /** The modal surface itself — above its own scrim, below any popover opened from inside it. */
+    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.
+     */
+    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.
+ *
+ * @example
+ * ```css
+ * :focus-visible {
+ *   outline: var(--skdx-focus-ring-width) solid var(--skdx-color-semantic-focus-ring);
+ *   outline-offset: var(--skdx-focus-ring-offset);
+ * }
+ * ```
+ *
+ * @public
+ */
+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.
+     */
+    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.
+ *
+ * @example
+ * ```css
+ * .card { border: var(--skdx-border-width-thin) solid var(--skdx-color-semantic-border); }
+ * .card[data-invalid] { border-width: var(--skdx-border-width-thick); }
+ * ```
+ *
+ * @public
+ */
+export declare const borderWidth: {
+    readonly thin: "1px";
+    readonly thick: "2px";
+    readonly thicker: "4px";
+};
+/** 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.
+ *
+ * @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
+ * 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.
+ *
+ * @example
+ * ```css
+ * [data-disabled] { opacity: var(--skdx-opacity-disabled); }
+ * .dialog-overlay { background: var(--skdx-color-semantic-overlay); opacity: var(--skdx-opacity-scrim); }
+ * ```
+ *
+ * @public
+ */
+export declare const opacity: {
+    readonly disabled: "0.5";
+    readonly scrim: "0.6";
+};
+/** 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.
+ *
+ * @example
+ * ```ts
+ * import { breakpoints } from '@skdx/tokens';
+ *
+ * const isDesktop = window.matchMedia(`(min-width: ${breakpoints.lg}px)`).matches;
+ * ```
+ *
+ * @public
+ */
+export declare const breakpoints: {
+    readonly sm: 640;
+    readonly md: 768;
+    readonly lg: 1024;
+    readonly xl: 1280;
+};
+/** The shape of the {@link breakpoints} scale — named viewport widths in pixels. @public */
+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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { foundationToCss, themeToCss, themes } from '@skdx/tokens';
+ *
+ * const css = foundationToCss() + themes.map((t) => themeToCss(t)).join('');
+ * ```
+ *
+ * @public
+ */
+export declare function foundationToCss(): string;

package/dist/utils/foundation.js

@@ -0,0 +1,15 @@
+import{reducedMotionVarNames as m,sectionsToCssVars as a,varsToDeclarations as s}from"./cssVars.js";import{defaultMotion as p}from"./theme.js";var e="skdx",c={fontFamily:"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",fontFamilyMono:"'SF Mono', SFMono-Regular, ui-monospace, Menlo, Consolas, monospace",fontSize:{xs:"0.75rem",sm:"0.875rem",md:"1rem",lg:"1.125rem",xl:"1.25rem","2xl":"1.5rem","3xl":"1.875rem"},fontWeight:{regular:400,medium:500,semibold:600,bold:700},lineHeight:{tight:"1.25",snug:"1.43",normal:"1.5",relaxed:"1.75"},letterSpacing:{tight:"-0.015em",normal:"0em",wide:"0.025em",wider:"0.05em"}},d={1:"0.25rem",2:"0.5rem",3:"0.75rem",4:"1rem",5:"1.25rem",6:"1.5rem",8:"2rem",10:"2.5rem",12:"3rem",16:"4rem"},l={sm:"0.25rem",inner:"0.375rem",md:"0.5rem",lg:"0.75rem",xl:"1rem",full:"9999px"},g={sm:`0 1px 2px 0 ${n(.05)}`,md:`0 4px 6px -1px ${n(.1)}, 0 2px 4px -2px ${n(.1)}`,lg:`0 10px 15px -3px ${n(.1)}, 0 4px 6px -4px ${n(.1)}`,overlay:`0 25px 50px -12px ${n(.25)}`};function n(r){return`rgb(var(--${e}-shadow-color) / calc(${r} * var(--${e}-shadow-strength)))`}var x=p,u={base:0,dropdown:10,sticky:20,overlay:30,modal:35,popover:40,toast:50,max:9999},h={width:"2px",offset:"2px",offsetInset:"calc(-1 * var(--skdx-focus-ring-width))"},y={thin:"1px",thick:"2px",thicker:"4px"},f={control:{height:{sm:"1.875rem",md:"2.25rem",lg:"2.625rem",compact:"2rem"},padding:{sm:"0.625rem",md:`var(--${e}-space-3)`,lg:`var(--${e}-space-4)`},gap:{sm:`var(--${e}-space-1)`,md:`var(--${e}-space-2)`,lg:`var(--${e}-space-2)`}},iconSize:{sm:"1rem",md:"1.25rem",lg:"1.5rem"},indicatorSize:{sm:"1rem",md:"1.25rem",lg:"1.5rem"},item:{height:{sm:"1.75rem",md:"2.25rem",lg:"2.5rem"},gap:"2px"},overlay:{padding:`var(--${e}-space-1)`,radius:`var(--${e}-radius-lg)`,minWidth:"7.5rem"},field:{gap:`var(--${e}-space-1)`,labelGap:`var(--${e}-space-1)`},target:{min:"24px"}},w={control:{height:{sm:"2.25rem",md:"2.75rem",lg:"3rem",compact:"2.75rem"}},item:{height:{sm:"2.25rem",md:"2.75rem",lg:"3rem"}},target:{min:"44px"}},k={disabled:"0.5",scrim:"0.6"},v={sm:640,md:768,lg:1024,xl:1280};function T(){return a([["font",c],["space",d],["radius",l],["shadow",g],["motion",x],["z-index",u],["focus-ring",h],["border-width",y],["opacity",k],...i(f)])}function i(r){let o=t=>r[t];return[["control",o("control")],["icon-size",o("iconSize")],["indicator-size",o("indicatorSize")],["item",o("item")],["overlay",o("overlay")],["field",o("field")],["target",o("target")]]}function R(){return a(i(w))}function C(){let r=T(),o=m(r).map(t=>`    ${t}: 0ms;`);return`:root {
+${s(r)}
+}
+@media (prefers-reduced-motion: reduce) {
+  :root {
+${o.join(`
+`)}
+  }
+}
+@media (pointer: coarse) {
+  :root {
+${s(R(),"    ")}
+  }
+}
+`}export{y as borderWidth,v as breakpoints,R as coarsePointerToCssVars,f as controls,w as controlsCoarse,h as focusRing,C as foundationToCss,T as foundationToCssVars,x as motion,k as opacity,l as radii,g as shadows,d as space,c as typography,u as zIndex};

package/dist/utils/mode.cjs

@@ -0,0 +1 @@
+"use strict";var d=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var S=Object.getOwnPropertyNames;var b=Object.prototype.hasOwnProperty;var O=(t,e)=>{for(var n in e)d(t,n,{get:e[n],enumerable:!0})},k=(t,e,n,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of S(e))!b.call(t,r)&&r!==n&&d(t,r,{get:()=>e[r],enumerable:!(o=u(e,r))||o.enumerable});return t};var E=t=>k(d({},"__esModule",{value:!0}),t);var M={};O(M,{BRAND_STORAGE_KEY:()=>g,MODE_STORAGE_KEY:()=>c,getThemeInitScript:()=>x,watchSystemMode:()=>v});module.exports=E(M);var a=require("../themes/brands.cjs"),f=require("./toCss.cjs"),c="skdx-mode",g="skdx-brand",y="(prefers-color-scheme: dark)";function v(t={}){let{brand:e,element:n,persist:o=!1,storageKey:r=c}=t,s=(e===void 0?void 0:(0,a.getBrand)(e))??a.defaultBrand,i=window.matchMedia(y),h=m=>{let p=m?"dark":"light";if((0,f.applyTheme)(s.themes[p],n),!!o)try{localStorage.setItem(r,p)}catch{}};h(i.matches);let l=m=>h(m.matches);return i.addEventListener("change",l),()=>i.removeEventListener("change",l)}function x(t={}){let{brandKey:e=g,modeKey:n=c,fallbackBrand:o=a.defaultBrand.name}=t,r=Object.fromEntries(a.brands.map(s=>[s.name,[s.themes.light.name,s.themes.dark.name]]));return`(function(){try{var t=${JSON.stringify(r)},f=${JSON.stringify(o)};var b=localStorage.getItem(${JSON.stringify(e)})||f;var m=localStorage.getItem(${JSON.stringify(n)});if(m!=="light"&&m!=="dark")m=matchMedia(${JSON.stringify(y)}).matches?"dark":"light";var p=t[b]||t[f];if(!p)return;var e=document.documentElement;e.setAttribute("data-skdx-theme",p[m==="dark"?1:0]);e.setAttribute("data-skdx-mode",m);}catch(e){}})();`}0&&(module.exports={BRAND_STORAGE_KEY,MODE_STORAGE_KEY,getThemeInitScript,watchSystemMode});

package/dist/utils/mode.d.cts

@@ -0,0 +1,89 @@
+/** `localStorage` key the mode preference (`'light' | 'dark' | 'system'`) is read from and written to. @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 */
+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?: string;
+    /** Element the resolved theme is applied to. @default document.documentElement */
+    element?: HTMLElement;
+    /** Whether to mirror the resolved mode into `localStorage` under {@link storageKey}. @default false */
+    persist?: boolean;
+    /** `localStorage` key used 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.
+ *
+ * @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
+ * <head>
+ *   <script dangerouslySetInnerHTML={{ __html: getThemeInitScript() }} />
+ * </head>
+ * ```
+ *
+ * @example Nuxt (`nuxt.config.ts`)
+ * ```ts
+ * app: { head: { script: [{ innerHTML: getThemeInitScript(), tagPosition: 'head' }] } }
+ * ```
+ *
+ * @example SvelteKit (`src/app.html`) — write the string into the template at
+ * build time, e.g. from a Vite plugin replacing a `%skdx.themeInit%` token:
+ * ```html
+ * <head>
+ *   %sveltekit.head%
+ *   <script>%skdx.themeInit%</script>
+ * </head>
+ * ```
+ *
+ * @example Astro (`src/layouts/Base.astro`)
+ * ```astro
+ * <script is:inline set:html={getThemeInitScript()} />
+ * ```
+ *
+ * @public
+ */
+export declare function getThemeInitScript(options?: ThemeInitScriptOptions): string;

package/dist/utils/mode.d.ts

@@ -0,0 +1,89 @@
+/** `localStorage` key the mode preference (`'light' | 'dark' | 'system'`) is read from and written to. @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 */
+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?: string;
+    /** Element the resolved theme is applied to. @default document.documentElement */
+    element?: HTMLElement;
+    /** Whether to mirror the resolved mode into `localStorage` under {@link storageKey}. @default false */
+    persist?: boolean;
+    /** `localStorage` key used 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.
+ *
+ * @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
+ * <head>
+ *   <script dangerouslySetInnerHTML={{ __html: getThemeInitScript() }} />
+ * </head>
+ * ```
+ *
+ * @example Nuxt (`nuxt.config.ts`)
+ * ```ts
+ * app: { head: { script: [{ innerHTML: getThemeInitScript(), tagPosition: 'head' }] } }
+ * ```
+ *
+ * @example SvelteKit (`src/app.html`) — write the string into the template at
+ * build time, e.g. from a Vite plugin replacing a `%skdx.themeInit%` token:
+ * ```html
+ * <head>
+ *   %sveltekit.head%
+ *   <script>%skdx.themeInit%</script>
+ * </head>
+ * ```
+ *
+ * @example Astro (`src/layouts/Base.astro`)
+ * ```astro
+ * <script is:inline set:html={getThemeInitScript()} />
+ * ```
+ *
+ * @public
+ */
+export declare function getThemeInitScript(options?: ThemeInitScriptOptions): string;

package/dist/utils/mode.js

@@ -0,0 +1 @@
+import{brands as f,defaultBrand as h,getBrand as g}from"../themes/brands.js";import{applyTheme as y}from"./toCss.js";var l="skdx-mode",u="skdx-brand",p="(prefers-color-scheme: dark)";function O(r={}){let{brand:t,element:n,persist:a=!1,storageKey:o=l}=r,e=(t===void 0?void 0:g(t))??h,s=window.matchMedia(p),m=i=>{let c=i?"dark":"light";if(y(e.themes[c],n),!!a)try{localStorage.setItem(o,c)}catch{}};m(s.matches);let d=i=>m(i.matches);return s.addEventListener("change",d),()=>s.removeEventListener("change",d)}function k(r={}){let{brandKey:t=u,modeKey:n=l,fallbackBrand:a=h.name}=r,o=Object.fromEntries(f.map(e=>[e.name,[e.themes.light.name,e.themes.dark.name]]));return`(function(){try{var t=${JSON.stringify(o)},f=${JSON.stringify(a)};var b=localStorage.getItem(${JSON.stringify(t)})||f;var m=localStorage.getItem(${JSON.stringify(n)});if(m!=="light"&&m!=="dark")m=matchMedia(${JSON.stringify(p)}).matches?"dark":"light";var p=t[b]||t[f];if(!p)return;var e=document.documentElement;e.setAttribute("data-skdx-theme",p[m==="dark"?1:0]);e.setAttribute("data-skdx-mode",m);}catch(e){}})();`}export{u as BRAND_STORAGE_KEY,l as MODE_STORAGE_KEY,k as getThemeInitScript,O as watchSystemMode};

package/dist/utils/theme.cjs

@@ -0,0 +1 @@
+"use strict";var n=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var o=Object.getOwnPropertyNames;var a=Object.prototype.hasOwnProperty;var m=(r,t)=>{for(var e in t)n(r,e,{get:t[e],enumerable:!0})},l=(r,t,e,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of o(t))!a.call(r,i)&&i!==e&&n(r,i,{get:()=>t[i],enumerable:!(s=g(t,i))||s.enumerable});return r};var d=r=>l(n({},"__esModule",{value:!0}),r);var c={};m(c,{defaultMotion:()=>h});module.exports=d(c);var h={durationInstant:"0ms",durationFast:"100ms",durationNormal:"200ms",durationSlow:"300ms",easing:"cubic-bezier(0.16, 1, 0.3, 1)",easingExit:"cubic-bezier(0.4, 0, 1, 1)",easingSteady:"cubic-bezier(0.4, 0, 0.2, 1)",easingLinear:"linear",staggerTight:"4ms",staggerLoose:"40ms"};0&&(module.exports={defaultMotion});