@skdx/tokens 0.26.0

package/dist/utils/toCss.d.ts

@@ -0,0 +1,92 @@
+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.
+ *
+ * @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 */
+export interface ThemeToCssOptions {
+    /**
+     * CSS selector the variables are scoped to.
+     * Defaults to `[data-skdx-theme="<name>"]` so multiple themes can 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.
+ *
+ * **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 options - See {@link ThemeToCssOptions}.
+ * @returns A CSS string, e.g. `'[data-skdx-theme="skanda-light"] {\n  --skdx-color-primary-500: #3d6eef;\n  …\n}\n'`.
+ *
+ * @example
+ * ```ts
+ * import { foundationToCss, themeToCss, skandaLight } from '@skdx/tokens';
+ * import fs from 'node:fs';
+ *
+ * fs.writeFileSync('skanda-light.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
+ *
+ * @example
+ * ```ts
+ * import { applyTheme, midnightBrand } from '@skdx/tokens';
+ *
+ * applyTheme(midnightBrand); // whole page
+ * applyTheme(midnightBrand, document.getElementById('preview')!); // scoped subtree
+ * ```
+ *
+ * @public
+ */
+export declare function applyTheme(theme: Theme, element?: HTMLElement): void;

package/dist/utils/toCss.js

@@ -0,0 +1,10 @@
+import{reducedMotionVarNames as d,sectionsToCssVars as m,varsToDeclarations as u}from"./cssVars.js";import{defaultMotion as p}from"./theme.js";function i(n){return m([["color",n.colors],["shadow",n.shadow],["font",n.typography],["motion",n.motion?{...p,...n.motion}:void 0]])}function l(n,o={}){let e=o.selector??`[data-skdx-theme="${n.name}"]`,s=i(n),t=`${e} {
+${u(s)}
+}
+`,r=d(s);if(r.length===0)return t;let a=r.map(c=>`    ${c}: 0ms;`);return t+`@media (prefers-reduced-motion: reduce) {
+  ${e} {
+${a.join(`
+`)}
+  }
+}
+`}function k(n,o=document.documentElement){let e=i(n);for(let[s,t]of Object.entries(e))o.style.setProperty(s,t);o.setAttribute("data-skdx-theme",n.name),o.setAttribute("data-skdx-mode",n.mode)}export{k as applyTheme,l as themeToCss,i as themeToCssVars};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@skdx/tokens",
+  "version": "0.26.0",
+  "description": "Theme contract and design tokens for the SkandaDX design system",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/SkandaDX/ui.skdx/tree/main/packages/tokens#readme",
+  "repository": {
+    "directory": "packages/tokens",
+    "type": "git",
+    "url": "git+https://github.com/SkandaDX/ui.skdx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SkandaDX/ui.skdx/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./themes/*": {
+      "types": "./dist/themes/*.d.ts",
+      "import": "./dist/themes/*.js",
+      "require": "./dist/themes/*.cjs"
+    },
+    "./css": "./dist/tokens.css",
+    "./foundation.css": "./dist/foundation.css",
+    "./themes.css": "./dist/themes.css",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "!dist/**/*.md",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.10",
+    "jsdom": "^29.1.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsup && tsc --emitDeclarationOnly -p tsconfig.build.json && node ../../scripts/declarations-cjs.mjs && node scripts/build-css.mjs && node ../../scripts/minify-css.mjs dist",
+    "typecheck": "tsc --noEmit --incremental --tsBuildInfoFile node_modules/.cache/tsc/typecheck.tsbuildinfo",
+    "export:dtcg": "node scripts/export-dtcg.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}