css-is-awesome 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+# [1.18.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.17.0...v1.18.0) (2026-09-19)
+
+
+### Bug Fixes
+
+* **site:** playground editor no longer boots from stale text when a share link decodes early ([3f0748f](https://github.com/Jerry2d3d/css-is-awesome/commit/3f0748f28b8a70471f1f61485733872c6ccdd6a9))
+
+
+### Features
+
+* **contract:** feature groups for optional tokens — contract 1.2 ([cc98e1f](https://github.com/Jerry2d3d/css-is-awesome/commit/cc98e1f9397ae89ef65b70557a942b5b561a0f85))
+
 # [1.17.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.16.1...v1.17.0) (2026-09-19)
 
 

package/CONTRACT.md

@@ -306,6 +306,25 @@ Paper themes declare these as `none` / `transparent` so a swap to a glass or pho
 
 ---
 
+## Optional tokens by feature (contract 1.2)
+
+Every optional token belongs to exactly one **feature** in `scripts/theme-contract.json` (`features`), so a validator, installer or agent can say *"this theme is missing the tokens for print"* instead of listing all 41 optional names. The validator's info line reports counts per feature; `--show-optional` lists them grouped. `npm run check:contract` fails the build if an optional token is in no feature, in two, or if a feature names a required token.
+
+| Feature | Tokens | Enables |
+| --- | --- | --- |
+| `density` | `--space-unit` | The density knob: shipped themes derive every --space-N from this one unit via calc(); set it to tighten or open up the whole UI (theme editor slider). |
+| `spacing-aliases` | `--space-2xs`, `--space-xs`, `--space-sm`, `--space-md`, `--space-lg`, `--space-xl` | T-shirt spacing names (2xs–xl) for consumer CSS that prefers them; the library reads the numbered scale, so these are pure aliases. |
+| `print` | `--print-ink`, `--print-paper`, `--print-line`, `--print-muted` | A themed printed page: cia.print-base rebinds ink/surface/border/code tokens onto this palette inside @media print. Without them the ink-on-white default applies. |
+| `component-radius` | `--btn-radius`, `--card-radius`, `--input-radius`, `--modal-radius`, `--badge-radius`, `--tag-radius` | Per-component corner radius overrides (buttons, cards, inputs, modals, badges, tags) without rebuilding SCSS; each falls back to the generic --radius-* scale. |
+| `component-shadows` | `--shadow-button`, `--shadow-card`, `--shadow-dropdown`, `--shadow-input-focus`, `--shadow-modal`, `--shadow-popover`, `--shadow-tooltip`, `--shadow-text` | Per-component elevation overrides; each falls back to the generic --shadow-* scale. |
+| `component-motion` | `--duration-button-hover`, `--duration-modal-open`, `--duration-toast-slide` | Per-component durations for button hover, modal open and toast slide; each falls back to the generic --duration-* scale. |
+| `surfaces-extended` | `--background-elevated`, `--background-hero`, `--background-overlay`, `--background-scrim` | Extra background layers (elevated, hero, overlay, scrim) for themes that want more than the required surface set; each falls back to a required surface. |
+| `borders-extended` | `--border-card`, `--border-divider`, `--border-focus-ring`, `--border-input` | Per-context border colours (card, divider, focus ring, input); each falls back to --border-default / --border-focus. |
+| `logo` | `--logo-default`, `--logo-mark`, `--logo-monochrome`, `--logo-wordmark` | Theme-aware logo assets (default, mark, monochrome, wordmark) as url() or SVG data values for the icon/brand mixins. |
+| `touch-target` | `--touch-target-min` | Minimum interactive target size read by form and button mixins (WCAG 2.2 SC 2.5.8); the library default is 24px. |
+
+---
+
 ## Print (optional)
 
 Four tokens describing the printed page. They're **optional** — `cia.print-base` (included once, at the stylesheet root) emits every one of them on `:root` inside `@media print` with a clean ink-on-white default, and every print rule reads them via `var(--print-*)`. A theme MAY override them in its own `@media print` block for a paper identity (Press does, for a newsprint look); a theme that sets none of them prints the plain default.

package/VERSIONING.md

@@ -43,6 +43,7 @@ Additive, non-breaking changes.
 | New public CSS class                                         | `.cia-grid-auto-fit` added                        |
 | New public SCSS mixin                                        | `m.cluster($gap)` added                           |
 | New optional token added to contract (`"1"` → `"1.1"`)       | `--dropdown-offset-y` added to component section  |
+| Contract metadata added (e.g. the `features` map, `"1.1"` → `"1.2"`, 2026-09-18) | Additive keys — old validators ignore them |
 | Required token relaxed to optional (contract minor bump)      | `--space-unit` required → optional, contract `"1"` → `"1.1"` (2026-09-18) |
 | New theme or recipe shipped                                  | `prism` family added; `mobile-nav` recipe added   |
 | New utility class (`.cia-*`)                                 | `.cia-text-balance` added                         |

package/llm.txt

@@ -104,7 +104,7 @@ Newspaper by day, hacker terminal by night. Most design systems give you dark mo
 | Mobile playbook (layouts, dropdown doctrine, lessons) | `src/app/docs/mobile/page.tsx` |
 | Browser support matrix (Baseline floor + progressive tiers) | `src/app/docs/browser-support/page.tsx` |
 | Theme authoring (full walkthrough) | `src/app/docs/authoring/themes/page.tsx` |
-| Theme contract (127 required + 41 optional, machine-readable) | `scripts/theme-contract.json` |
+| Theme contract (127 required + 41 optional grouped into 10 features, machine-readable) | `scripts/theme-contract.json` |
 | Theme pairing (`<link media>` recipe) | `src/app/docs/themes/pairing/page.tsx` |
 | CopyButton JS recipe | `src/app/docs/recipes/copy-button/page.tsx` |
 | Anchor positioning recipe | `src/app/docs/recipes/anchor-positioning/page.tsx` |

package/mcp/server.cjs

@@ -426,6 +426,12 @@ function loadTokenContract() {
     return { required: [], optional: [], byName: {}, byCategory: {} };
   }
   const optional = Array.isArray(contract.optional) ? contract.optional : [];
+  // Contract 1.2: optional tokens are grouped by the feature they enable.
+  const features = contract.features && typeof contract.features === 'object' ? contract.features : {};
+  const featureOf = {};
+  for (const [feature, def] of Object.entries(features)) {
+    for (const t of (def && Array.isArray(def.tokens)) ? def.tokens : []) featureOf[t] = feature;
+  }
 
   const byName = {};
   const byCategory = {};
@@ -460,11 +466,11 @@ function loadTokenContract() {
   }
   for (const t of optional) {
     const category = categorize(t);
-    byName[t] = { name: t, category, required: false };
+    byName[t] = { name: t, category, required: false, feature: featureOf[t] || null };
     (byCategory[category] = byCategory[category] || []).push(t);
   }
 
-  return { required: contract.required, optional, byName, byCategory };
+  return { required: contract.required, optional, features, byName, byCategory };
 }
 
 /**
@@ -854,6 +860,8 @@ const handlers = {
       name: entry.name,
       category: entry.category,
       required: entry.required,
+      // Contract 1.2: the feature an OPTIONAL token enables (null for required).
+      feature: entry.required ? null : (entry.feature || null),
       themeValues,
       referencedBy: referencedBy.slice(0, 20),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "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": {

package/scripts/theme-contract.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.1",
-  "description": "Authoritative token contract for css-is-awesome themes. Every theme.css MUST declare every token in `required`. Tokens in `optional` are reported by the validator as info, never as failures \u2014 the library or the theme generator supplies a default. Source of truth is CONTRACT.md (human-readable) and public/theme.css (Sketchbook reference). Contract 1.1 (2026-09-18): --space-unit relaxed from required to optional; it had been added as required in library 1.12.0, which VERSIONING.md forbids in a MINOR.",
+  "version": "1.2",
+  "description": "Authoritative token contract for css-is-awesome themes. Every theme.css MUST declare every token in `required`. Tokens in `optional` are reported by the validator as info, never as failures \u2014 the library or the theme generator supplies a default. Source of truth is CONTRACT.md (human-readable) and public/theme.css (Sketchbook reference). Contract 1.1 (2026-09-18): --space-unit relaxed from required to optional; it had been added as required in library 1.12.0, which VERSIONING.md forbids in a MINOR. Contract 1.2 (2026-09-18): `features` groups every optional token by the capability it enables, so a validator or installer can say \"missing the tokens for print\" instead of listing all optional tokens.",
   "required": [
     "--action-primary-active",
     "--action-primary-default",
@@ -172,5 +172,98 @@
     "--space-xs",
     "--tag-radius",
     "--touch-target-min"
-  ]
+  ],
+  "features": {
+    "density": {
+      "enables": "The density knob: shipped themes derive every --space-N from this one unit via calc(); set it to tighten or open up the whole UI (theme editor slider).",
+      "tokens": [
+        "--space-unit"
+      ]
+    },
+    "spacing-aliases": {
+      "enables": "T-shirt spacing names (2xs\u2013xl) for consumer CSS that prefers them; the library reads the numbered scale, so these are pure aliases.",
+      "tokens": [
+        "--space-2xs",
+        "--space-xs",
+        "--space-sm",
+        "--space-md",
+        "--space-lg",
+        "--space-xl"
+      ]
+    },
+    "print": {
+      "enables": "A themed printed page: cia.print-base rebinds ink/surface/border/code tokens onto this palette inside @media print. Without them the ink-on-white default applies.",
+      "tokens": [
+        "--print-ink",
+        "--print-paper",
+        "--print-line",
+        "--print-muted"
+      ]
+    },
+    "component-radius": {
+      "enables": "Per-component corner radius overrides (buttons, cards, inputs, modals, badges, tags) without rebuilding SCSS; each falls back to the generic --radius-* scale.",
+      "tokens": [
+        "--btn-radius",
+        "--card-radius",
+        "--input-radius",
+        "--modal-radius",
+        "--badge-radius",
+        "--tag-radius"
+      ]
+    },
+    "component-shadows": {
+      "enables": "Per-component elevation overrides; each falls back to the generic --shadow-* scale.",
+      "tokens": [
+        "--shadow-button",
+        "--shadow-card",
+        "--shadow-dropdown",
+        "--shadow-input-focus",
+        "--shadow-modal",
+        "--shadow-popover",
+        "--shadow-tooltip",
+        "--shadow-text"
+      ]
+    },
+    "component-motion": {
+      "enables": "Per-component durations for button hover, modal open and toast slide; each falls back to the generic --duration-* scale.",
+      "tokens": [
+        "--duration-button-hover",
+        "--duration-modal-open",
+        "--duration-toast-slide"
+      ]
+    },
+    "surfaces-extended": {
+      "enables": "Extra background layers (elevated, hero, overlay, scrim) for themes that want more than the required surface set; each falls back to a required surface.",
+      "tokens": [
+        "--background-elevated",
+        "--background-hero",
+        "--background-overlay",
+        "--background-scrim"
+      ]
+    },
+    "borders-extended": {
+      "enables": "Per-context border colours (card, divider, focus ring, input); each falls back to --border-default / --border-focus.",
+      "tokens": [
+        "--border-card",
+        "--border-divider",
+        "--border-focus-ring",
+        "--border-input"
+      ]
+    },
+    "logo": {
+      "enables": "Theme-aware logo assets (default, mark, monochrome, wordmark) as url() or SVG data values for the icon/brand mixins.",
+      "tokens": [
+        "--logo-default",
+        "--logo-mark",
+        "--logo-monochrome",
+        "--logo-wordmark"
+      ]
+    },
+    "touch-target": {
+      "enables": "Minimum interactive target size read by form and button mixins (WCAG 2.2 SC 2.5.8); the library default is 24px.",
+      "tokens": [
+        "--touch-target-min"
+      ]
+    }
+  }
 }

package/scripts/theme-validator.js

@@ -342,7 +342,19 @@ function validateTokenSet(declared, contract) {
   for (const optional of Array.isArray(contract.optional) ? contract.optional : []) {
     if (!declared.has(optional)) optionalMissing.push(optional);
   }
-  return { ok: missing.length === 0, missing, optionalMissing, declaredCount: declared.size };
+  // Contract 1.2: group by the feature each optional token enables, so the
+  // report can say "missing the tokens for print" instead of listing 41 names.
+  const featureOf = {};
+  const features = contract.features && typeof contract.features === 'object' ? contract.features : {};
+  for (const [feature, def] of Object.entries(features)) {
+    for (const t of (def && Array.isArray(def.tokens)) ? def.tokens : []) featureOf[t] = feature;
+  }
+  const optionalMissingByFeature = {};
+  for (const t of optionalMissing) {
+    const f = featureOf[t] || 'other';
+    (optionalMissingByFeature[f] = optionalMissingByFeature[f] || []).push(t);
+  }
+  return { ok: missing.length === 0, missing, optionalMissing, optionalMissingByFeature, declaredCount: declared.size };
 }
 
 // -----------------------------------------------------------
@@ -367,6 +379,7 @@ function validateText(text, contract, options) {
     declaredCount: 0,
     missing: [],
     optionalMissing: [],
+    optionalMissingByFeature: {},
     themes: null,
     a11y: null,
     error: null,
@@ -389,6 +402,7 @@ function validateText(text, contract, options) {
         declaredCount: v.declaredCount,
         missing: v.missing,
         optionalMissing: v.optionalMissing,
+        optionalMissingByFeature: v.optionalMissingByFeature,
         a11y: null,
       };
       if (wantA11y) theme.a11y = a11y.auditThemeTokens({ name: b.name, values: b.values });
@@ -417,6 +431,7 @@ function validateText(text, contract, options) {
   result.declaredCount = v.declaredCount;
   result.missing = v.missing;
   result.optionalMissing = v.optionalMissing;
+  result.optionalMissingByFeature = v.optionalMissingByFeature;
   result.ok = v.ok;
   if (wantA11y) {
     const inferredName = label !== '(pasted CSS)' ? (path.basename(path.dirname(label)) || path.basename(label, '.css')) : 'theme';
@@ -456,11 +471,18 @@ function relForDisplay(p) {
 
 // Optional tokens a theme leaves to the library default. Info only — shown as
 // a count, or listed with --show-optional. Never affects the exit code.
-function optionalInfo(optionalMissing, indent) {
+function optionalInfo(optionalMissing, byFeature, indent) {
   const list = Array.isArray(optionalMissing) ? optionalMissing : [];
   if (!list.length) return;
-  console.log(`${indent}${dim(`i ${list.length} optional token(s) not declared — library default applies`)}`);
-  if (SHOW_OPTIONAL) for (const token of list) console.log(`${indent}    ${dim(token)}`);
+  const groups = byFeature && typeof byFeature === 'object' ? byFeature : {};
+  const summary = Object.entries(groups).map(([f, ts]) => `${f} ${ts.length}`).join(' · ');
+  console.log(`${indent}${dim(`i ${list.length} optional token(s) not declared — library default applies${summary ? ` (${summary})` : ''}`)}`);
+  if (SHOW_OPTIONAL) {
+    for (const [f, ts] of Object.entries(groups)) {
+      console.log(`${indent}    ${dim(f + ':')}`);
+      for (const token of ts) console.log(`${indent}      ${dim(token)}`);
+    }
+  }
 }
 
 function reportResult(result) {
@@ -483,7 +505,7 @@ function reportResult(result) {
         console.log(
           `    ${green('✓')} [data-theme="${t.name}"] ${dim(`(${t.declaredCount} tokens)`)}`
         );
-        optionalInfo(t.optionalMissing, '      ');
+        optionalInfo(t.optionalMissing, t.optionalMissingByFeature, '      ');
       } else {
         const n = t.missing.length;
         console.log(
@@ -502,7 +524,7 @@ function reportResult(result) {
     console.log(
       `${green('✓')} ${bold(rel)} ${dim(`passes (${result.declaredCount} tokens declared)`)}`
     );
-    optionalInfo(result.optionalMissing, '    ');
+    optionalInfo(result.optionalMissing, result.optionalMissingByFeature, '    ');
     return;
   }
 
@@ -583,7 +605,7 @@ function printUsage() {
     '  --all              validate every theme.css under public/ (CI mode)',
     '  --no-a11y          skip the WCAG 2.2 AA contrast audit',
     '  --allow-a11y-fail  do NOT exit non-zero on a11y FAILs (report only)',
-    '  --show-optional    list optional contract tokens a theme leaves to the library default (info only)',
+    '  --show-optional    list optional contract tokens a theme leaves to the library default, grouped by feature (info only)',
     '  --strict           accepted for backwards compatibility (no-op; FAIL is now the default)',
     '',
     'Exit codes:',