css-is-awesome 1.19.0 → 1.19.1

package/AGENTS.md

@@ -365,7 +365,7 @@ Either way it exposes **33 tools** across 8 families:
   into a complete theme.css — every required token the file lacks inherits from a shipped base theme (`--base`,
   default boilerplate), unmapped paths pass through verbatim and are reported, a `--dark` file or paired
   `color-light`/`color-dark` groups become `light-dark()`, and the validator + WCAG audit run before anything is
-  written. Same function as the MCP `theme_from_tokens` tool. Run any verb with `--help`. (`cia init` remains
+  written. Same function as the MCP `theme_from_tokens` tool; `npx cia theme map [--json] [--path <token.path>]` prints the design-token → cia-token mapping that verb applies (same data as the MCP `get_token_map` tool), for anyone who needs to map one token name the way the converter would. Run any verb with `--help`. (`cia init` remains
   planned.)
 - **JSON token export** — Tokens Studio-format sample in `figma-tokens/tokens.json`; it round-trips through `cia theme from-tokens` (paired light/dark groups → one `light-dark()` theme).
 - **`llm.txt`** — at the repo root and served from the docs site; single-fetch

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.19.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.19.0...v1.19.1) (2026-09-23)
+
+
+### Bug Fixes
+
+* **cli:** paired light/dark modes carried only colours; export the in-process entry point ([f1fe71f](https://github.com/Jerry2d3d/css-is-awesome/commit/f1fe71f8a91a8e7bf59e0b9e830585701beb9160))
+
+
+### Features
+
+* **site:** cross-link the posts that explain a browser-support row (B6.4) ([44f40d8](https://github.com/Jerry2d3d/css-is-awesome/commit/44f40d8bf278113a81f7f2b643ad52390fb1af25))
+
 # [1.19.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.18.0...v1.19.0) (2026-09-19)
 
 

package/README.md

@@ -417,7 +417,7 @@ Full detail: [`/docs/testing`](https://cssisawesome.com/docs/testing/).
 
 **Stable, [published on npm](https://www.npmjs.com/package/css-is-awesome)** (first published 2026-09-01). The mixin API, functions, token contract, and theme architecture are stable and under strict SemVer — breaking changes require a major bump. See [`VERSIONING.md`](./VERSIONING.md) for the policy.
 
-The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, and the 33-tool MCP server (now also available zero-install via the companion [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package). The npm package ships ZERO runtime JavaScript by hard rule — nothing in it is loaded by a page; its Node tooling (CLI, MCP server, validators) never reaches the browser.
+The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, the in-browser [Playground](https://cssisawesome.com/playground/), the design-tokens on-ramp (`npx cia theme from-tokens` / `theme map`), and the 33-tool MCP server (now also available zero-install via the companion [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package). The npm package ships ZERO runtime JavaScript by hard rule — nothing in it is loaded by a page; its Node tooling (CLI, MCP server, validators) never reaches the browser.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full history and [MIGRATION.md](./MIGRATION.md) for the v0.7 → v0.8 and v0.8 → v1.0 upgrade paths.
 

package/dist/tokens.d.ts

@@ -1,4 +1,4 @@
-// Generated from scripts/theme-contract.json on 2026-09-19.
+// Generated from scripts/theme-contract.json on 2026-09-23.
 // Do not edit by hand. Run `npm run build:token-types` to regenerate.
 
 /** Every CSS custom property cia themes are required to declare. */

package/llm.txt

@@ -198,4 +198,4 @@ Humans first. AI's role is to compose, not to lead the pitch.
 
 ---
 
-*Generated 2026-05-21 for cia v0.8. Updated 2026-05-23 for the v1.0 architecture lock, 2026-08-30 for the theme single-source rework (24 themes, 127+36 contract, themeable spacing, `:root, :root[data-theme]` selector), and 2026-09-04 for the shipped recipes count (5), the mobile-nav mixin family, and the dropdown popover guard. Update when the API surface changes.*
+*Generated 2026-05-21 for cia v0.8. Updated 2026-05-23 for the v1.0 architecture lock, 2026-08-30 for the theme single-source rework (24 themes, 127+36 contract, themeable spacing, `:root, :root[data-theme]` selector), 2026-09-04 for the shipped recipes count (5), the mobile-nav mixin family, and the dropdown popover guard, and 2026-09-19 for the 32-recipe book, 33-tool MCP, contract 1.2 (127 + 41 in 10 features), the playground and the design-tokens on-ramp. Update when the API surface changes.*

package/mcp/server.cjs

@@ -34,13 +34,13 @@
  *     "mcpServers": {
  *       "css-is-awesome": {
  *         "command": "node",
- *         "args": ["K:/Repo/css-is-awesome/mcp/server.cjs"]
+ *         "args": ["node_modules/css-is-awesome/mcp/server.cjs"]
  *       }
  *     }
  *   }
  *
- * Aligned with the canonical sibling MCP shape: ui-ux-builder, ideas-master,
- * video-maker. Response envelope is `{ total, items }` for list/search;
+ * Aligned with the canonical sibling MCP shape used across our other servers.
+ * Response envelope is `{ total, items }` for list/search;
  * get_* tools return the full record.
  */
 
@@ -1402,7 +1402,8 @@ async function startServer() {
       '{ "--token": value } map. Format is auto-detected. Every REQUIRED contract token the file does not supply ' +
       'is inherited from a shipped base theme (default boilerplate) and listed in report.inherited, so the output ' +
       'is always contract-complete; unmapped paths are emitted verbatim and listed in report.unmapped, never ' +
-      'dropped. Pass `dark` (same format) or a single file with paired color-light/color-dark groups to get ' +
+      'dropped. Pass `dark` (same format), or one file with paired top-level groups — `light`/`dark` (each a full '
+      + 'token set) or `color-light`/`color-dark` (each a colour set) — to get ' +
       'light-dark() values. Returns { css, report, validation } — validation is the same result validate_theme ' +
       'gives, run on the CSS before you write it anywhere.',
     inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.19.0",
+  "version": "1.19.1",
   "description": "A token-driven SCSS design system with light/dark theming, semantic color tokens, and a 800+ LOC mixin API.",
   "homepage": "https://github.com/Jerry2d3d/css-is-awesome#readme",
   "bugs": {
@@ -41,6 +41,10 @@
     "./scss/main": "./scss/main.scss",
     "./scss/tokens": "./scss/tokens.scss",
     "./scss/mixins": "./scss/_mixins.scss",
+    "./scripts/tokens-to-theme.cjs": "./scripts/tokens-to-theme.cjs",
+    "./scripts/tokens-to-theme": "./scripts/tokens-to-theme.cjs",
+    "./scripts/theme-validator.js": "./scripts/theme-validator.js",
+    "./mcp/server.cjs": "./mcp/server.cjs",
     "./scss/generator": "./scss/_generator.scss",
     "./scss/utilities": "./scss/_utilities.scss",
     "./scss/animations": "./scss/_animations.scss",

package/scripts/tokens-to-theme.cjs

@@ -48,8 +48,11 @@
 // LIGHT + DARK
 //   Pass `dark` (a second tokens object, same format) and every colour token
 //   that differs becomes `light-dark(light, dark)` with `color-scheme: light dark`.
-//   A single Tokens Studio file with paired top-level groups (`color-light` +
-//   `color-dark`, or `light` + `dark`) is split the same way automatically.
+//   A single file with paired top-level groups is split automatically, and the
+//   two conventions mean different things: `color-light`/`color-dark` name a
+//   COLOUR SET (children are colours), while `light`/`dark` name a MODE whose
+//   group holds a FULL token set — colours, spacing, fonts, component
+//   overrides — which merges beside any groups shared outside the pair.
 //   Without a dark side the block is single-mode: `color-scheme: <mode>`
 //   (`mode`, default light).
 // ============================================================================
@@ -490,6 +493,17 @@ function applyPathAliases(p) {
 
 /** Returns { token, mapped: true } or { token, mapped: false } (verbatim fallback). */
 function mapPath(tokenPath, contract) {
+  if (typeof tokenPath !== 'string' || !tokenPath.trim()) {
+    throw new Error('mapPath: first argument must be a non-empty token path, e.g. "color.text.primary"');
+  }
+  // The contract is optional: omit it and the installed one is loaded. It used
+  // to be required, but only the generic-rule branch touched it — so a path in
+  // the explicit table appeared to work and the mistake surfaced later as a
+  // TypeError on some other path. Fail clearly or not at all.
+  if (contract == null) contract = loadContract(path.join(__dirname, '..'));
+  else if (!contract.all || typeof contract.all.has !== 'function') {
+    throw new Error('mapPath: second argument must be a contract from loadContract(); omit it to load the installed contract automatically');
+  }
   if (TOKEN_MAP[tokenPath]) return { token: TOKEN_MAP[tokenPath], mapped: true };
   const aliased = applyPathAliases(tokenPath);
   if (TOKEN_MAP[aliased]) return { token: TOKEN_MAP[aliased], mapped: true };
@@ -498,6 +512,26 @@ function mapPath(tokenPath, contract) {
   // camelCase segments → kebab (linkHover → link-hover), one more try.
   const kebab = `--${aliased.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/\./g, '-').toLowerCase()}`;
   if (contract.all.has(kebab)) return { token: kebab, mapped: true };
+  // Flat per-component form: `component.btn-radius` → `--btn-radius`. The
+  // explicit table carries the nested shape (`component.button.radius`), and
+  // it is tried first; this catches exporters that flatten the group instead.
+  // Generic-rule first means this can never shadow a real `--component-*`.
+  const flat = aliased.replace(/^components?\./, '');
+  if (flat !== aliased) {
+    const body = flat.replace(/\./g, '-').toLowerCase();
+    // `component.btn-radius` → `--btn-radius`.
+    if (contract.all.has(`--${body}`)) return { token: `--${body}`, mapped: true };
+    // The contract names per-component overrides two ways: radius trails the
+    // component (`--card-radius`) but shadow, border and duration lead it
+    // (`--shadow-card`). A flat exporter cannot know which, so try the swap:
+    // `card-shadow` → `--shadow-card`, `button-hover-duration` →
+    // `--duration-button-hover`. Only accepted if it is a real token.
+    const cut = body.lastIndexOf('-');
+    if (cut > 0) {
+      const swapped = `--${body.slice(cut + 1)}-${body.slice(0, cut)}`;
+      if (contract.all.has(swapped)) return { token: swapped, mapped: true };
+    }
+  }
   return { token: generic, mapped: false };
 }
 
@@ -530,16 +564,35 @@ function loadBase(ciaRoot, base) {
 // ---------------------------------------------------------------------------
 // Paired-mode detection for a single Tokens Studio / DTCG file
 // ---------------------------------------------------------------------------
-const PAIRS = [['color-light', 'color-dark'], ['light', 'dark'], ['colors-light', 'colors-dark']];
+// Two different conventions look alike and must NOT be treated alike:
+//
+//   `color-light` / `color-dark`  name a COLOUR SET. The group's children are
+//        colours (`color-light.brand.primary`), so they nest under `color.`.
+//   `light` / `dark`              name a MODE. The group holds a FULL token
+//        set — `color.*`, `spacing.*`, `font.*`, `component.*` — so its
+//        children merge at the TOP level, beside any shared groups.
+//
+// Wrapping a mode group in `color.` (which this did for every pair until
+// 2026-09-19) silently mis-routed every non-colour group: `spacing.unit`
+// became `color.spacing.unit` → `--spacing-unit`, so the theme lost its
+// density knob while `validation.ok` stayed true, because the required token
+// was quietly inherited from the base theme instead. Reported by a consumer
+// against boilerplate's canonical DTCG layout.
+const PAIRS = [
+  { light: 'color-light', dark: 'color-dark', wrap: 'color' },
+  { light: 'colors-light', dark: 'colors-dark', wrap: 'color' },
+  { light: 'light', dark: 'dark', wrap: null },
+];
 
 function splitPairedModes(tokens) {
   if (!isPlainObject(tokens)) return null;
-  for (const [l, d] of PAIRS) {
+  for (const { light: l, dark: d, wrap } of PAIRS) {
     if (isPlainObject(tokens[l]) && isPlainObject(tokens[d])) {
       const rest = {};
       for (const [k, v] of Object.entries(tokens)) if (k !== l && k !== d) rest[k] = v;
-      const light = { ...rest, color: tokens[l] };
-      const dark = { ...rest, color: tokens[d] };
+      // Mode-specific groups win over shared ones on a key collision.
+      const light = wrap ? { ...rest, [wrap]: tokens[l] } : { ...rest, ...tokens[l] };
+      const dark = wrap ? { ...rest, [wrap]: tokens[d] } : { ...rest, ...tokens[d] };
       return { light, dark, groups: [l, d] };
     }
   }