@skdx/tokens 0.26.0 → 0.28.0

package/dist/utils/toCss.d.ts

@@ -1,92 +1,53 @@
 import { type Theme } from './theme.js';
 /**
- * Flattens a {@link Theme} into a map of CSS custom property names to values,
- * e.g. `--skdx-color-primary-500`, `--skdx-shadow-color`.
- * The lower-level primitive behind {@link themeToCss} and {@link applyTheme};
- * reach for one of those two instead unless you need the raw variable map
- * (e.g. to diff two themes, or hand to a non-DOM renderer).
- *
- * **Colors only** (plus a theme's optional `typography`/`motion`). The type scale,
- * spacing, radii, shadow geometry and motion come from `foundationToCssVars()`
- * — see {@link Theme} for why. The two maps are disjoint, so a consumer can
- * merge them without a precedence rule.
- *
- * @returns A plain object keyed by CSS custom property name (e.g. `'--skdx-color-primary-500'`), unprefixed by any selector.
- *
+ * Flatten {@link Theme} into `{ '--skdx-…': value }` map. Colors only
+ * (plus optional `typography`/`motion`). @returns Unscoped CSS variables.
  * @example
  * ```ts
  * themeToCssVars(defaultTheme)
  * // => { '--skdx-color-primary-500': '#3d6eef', '--skdx-shadow-color': '2 6 23', … }
  * ```
- *
  * @public
  */
 export declare function themeToCssVars(theme: Theme): Record<string, string>;
-/** Options for {@link themeToCss} controlling how a theme's CSS rule block is generated. @public */
+/** Options for {@link themeToCss}. @public */
 export interface ThemeToCssOptions {
     /**
-     * CSS selector the variables are scoped to.
-     * Defaults to `[data-skdx-theme="<name>"]` so multiple themes can coexist.
+     * CSS selector for variable scope. @default `[data-skdx-theme="<name>"]`
+     * (allows multiple themes to coexist).
      */
     selector?: string;
 }
 /**
- * Renders a {@link Theme} as a CSS rule block ready to inject into a
- * `<style>` tag or write to a `.css` file — the build-time counterpart to
- * {@link applyTheme}'s runtime application.
+ * Render {@link Theme} as CSS rule block (build-time counterpart to {@link applyTheme}).
+ * Colors only; `foundationToCss()` required for complete stylesheet. Emits
+ * `@media (prefers-reduced-motion: reduce)` if theme retunes motion (re-declares
+ * as `0ms` to preserve WCAG 2.3.3 guarantee across higher specificity).
  *
- * **This is not a complete stylesheet on its own.** It emits the theme's
- * colors; `foundationToCss()` emits everything else and must be injected once
- * alongside it.
- *
- * A `@media (prefers-reduced-motion: reduce)` block follows only when the
- * theme retunes motion through `ThemeMotionDeviation` — otherwise the
- * foundation's own block already covers it, and repeating it 38 times was how
- * the old output got to 43% non-color. When it is emitted it re-declares every
- * `--skdx-motion-duration-*` and `--skdx-motion-stagger-*` as `0ms` at this
- * theme's selector, which is what keeps the WCAG 2.3.3 guarantee from being
- * lost to the deviation's higher specificity. The easing curve is left alone:
- * it's a shape, not a duration, and is inert at `0ms`.
- *
- * @param theme - The theme to render.
+ * @param theme - Theme to render.
  * @param options - See {@link ThemeToCssOptions}.
- * @returns A CSS string, e.g. `'[data-skdx-theme="skanda-light"] {\n  --skdx-color-primary-500: #3d6eef;\n  …\n}\n'`.
- *
+ * @returns CSS string.
  * @example
  * ```ts
  * import { foundationToCss, themeToCss, skandaLight } from '@skdx/tokens';
- * import fs from 'node:fs';
- *
- * fs.writeFileSync('skanda-light.css', foundationToCss() + themeToCss(skandaLight));
+ * fs.writeFileSync('skanda.css', foundationToCss() + themeToCss(skandaLight));
  * ```
- *
  * @public
  */
 export declare function themeToCss(theme: Theme, options?: ThemeToCssOptions): string;
 /**
- * Applies a {@link Theme} to an element at runtime by setting its CSS custom
- * properties directly (via `element.style.setProperty`) and stamping
- * `data-skdx-theme="<name>"` plus `data-skdx-mode="<light|dark>"` on it — the
- * mechanism behind live theme preview (e.g. a theme builder, or a runtime
- * brand switcher). Multiple themes can coexist by applying each to a
- * different subtree.
- *
- * Sets the theme's own variables only. The shared tokens are expected to be on
- * the document already (`foundationToCss()` at `:root`) and inherit down into
- * `element` — which is why applying a theme to a subtree re-colors it without
- * re-declaring the type scale for it.
- *
- * @param theme - The theme to apply.
- * @param element - Element to apply the theme to. @default document.documentElement
+ * Apply {@link Theme} at runtime via `element.style.setProperty`, stamping
+ * `data-skdx-theme`/`data-skdx-mode`. Theme-only variables; shared tokens
+ * inherit. Subtree re-colors without re-declaring type scale.
  *
+ * @param theme - Theme to apply.
+ * @param element - Target element. @default document.documentElement
  * @example
  * ```ts
  * import { applyTheme, midnightBrand } from '@skdx/tokens';
- *
  * applyTheme(midnightBrand); // whole page
- * applyTheme(midnightBrand, document.getElementById('preview')!); // scoped subtree
+ * applyTheme(midnightBrand, el); // scoped
  * ```
- *
  * @public
  */
 export declare function applyTheme(theme: Theme, element?: HTMLElement): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skdx/tokens",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Theme contract and design tokens for the SkandaDX design system",
   "license": "MIT",
   "publishConfig": {