css-is-awesome 1.13.2 → 1.14.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.14.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.14.0...v1.14.1) (2026-09-11)
+
+
+### Bug Fixes
+
+* **package:** ship scripts/audit-pairs.json — the a11y module was broken on every real install ([d7e18ef](https://github.com/Jerry2d3d/css-is-awesome/commit/d7e18efdabfe8eaa9e722f1ac68e4b874d45077b))
+
+# [1.14.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.13.2...v1.14.0) (2026-09-11)
+
+
+### Features
+
+* **mcp:** add validate_theme tool — the real validator, exposed as a tool call ([7a8b497](https://github.com/Jerry2d3d/css-is-awesome/commit/7a8b4971640f6fd6b13148f05288e9e3e76ade10))
+
 ## [1.13.2](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.13.1...v1.13.2) (2026-09-11)
 
 

package/mcp/server.cjs

@@ -685,6 +685,19 @@ const handlers = {
     return { total: matches.length, items: matches };
   },
 
+  // Validates ANY theme CSS against the real token contract + a11y audit —
+  // not scoped to cia's own shipped themes. Works on cia's themes, a fully
+  // custom one built by an agent (e.g. via the derive-theme assemble_prompt
+  // intent), anything — whatever CSS text is passed in. Reuses the same
+  // validateText() the CLI (`npm run validate-themes`) calls, so a pass/fail
+  // here is exactly what `node scripts/theme-validator.js` would report,
+  // not a reimplementation that could quietly drift from it.
+  validate_theme({ css, label } = {}) {
+    if (!css || typeof css !== 'string') throw new Error('validate_theme: css is required');
+    const { validateText, loadContract } = require(path.join(SCRIPTS_DIR, 'theme-validator.js'));
+    return validateText(css, loadContract(), { label: label || undefined });
+  },
+
   // ─── Mixins ────────────────────────────────────────────────────────────
 
   list_mixins({ category, component, limit = 500, offset = 0 } = {}) {
@@ -1327,6 +1340,20 @@ async function startServer() {
     },
   }, async (a) => ok(handlers.search_themes(a || {})));
 
+  server.registerTool('validate_theme', {
+    description:
+      'Validate ANY theme CSS against cia\'s real token contract and WCAG contrast audit — the same check ' +
+      '`npm run validate-themes` runs, exposed as a tool call. Not scoped to cia\'s own themes: works on a ' +
+      'fully custom theme you (or another agent) just built, e.g. via the derive-theme assemble_prompt intent. ' +
+      'Pass compiled CSS (a :root or [data-theme="..."] block) — this does not compile Sass, so give it the ' +
+      'output, not .scss source. Returns missing required tokens (if any, mode "per-file" or "consolidated" ' +
+      'depending on shape) and a11y warnings per contrast pair.',
+    inputSchema: {
+      css: z.string().describe('Compiled theme CSS to validate — the :root/[data-theme] block(s), not .scss source.'),
+      label: z.string().optional().describe('Optional name for the result (e.g. the intended theme name); purely cosmetic.'),
+    },
+  }, async (a) => ok(handlers.validate_theme(a || {})));
+
   // Mixins
   server.registerTool('list_mixins', {
     description: `List all ${MIXIN_COUNT} public @mixins across core, layout, animation, icons, generator, per-component and recipe sources. Filter by category (core/layout/animation/icons/generator/component/recipe) or component name.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.13.2",
+  "version": "1.14.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": {
@@ -70,6 +70,7 @@
     "scripts/theme-contract.json",
     "scripts/theme-validator.js",
     "scripts/theme-a11y.js",
+    "scripts/audit-pairs.json",
     "scripts/icon-validator.js",
     "scripts/icon-contract.json",
     "bin",

package/scripts/audit-pairs.json

@@ -0,0 +1,25 @@
+[
+  { "fg": "--text-primary",   "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "primary body text on the page background" },
+  { "fg": "--text-secondary", "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "secondary body text on the page background" },
+  { "fg": "--text-tertiary",  "bg": "--paper",                  "required": 3.0, "kind": "large-text", "warnIfBelow": 4.5, "note": "tertiary text - legal at large sizes; warn if used as body" },
+  { "fg": "--text-muted",     "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "muted UI text on the page background" },
+  { "fg": "--ink",            "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "native ink on native paper" },
+  { "fg": "--ink-soft",       "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "soft ink on native paper" },
+  { "fg": "--ink-faint",      "bg": "--paper",                  "required": 3.0, "kind": "large-text", "warnIfBelow": 4.5, "note": "faint ink - large/UI only; warn if used as body" },
+  { "fg": "--text-link",      "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "inline link color on the page background" },
+  { "fg": "--text-inverse",   "bg": "--action-primary-default", "required": 4.5, "kind": "text",     "note": "button label on the primary action surface" },
+  { "fg": "--text-inverse",   "bg": "--ai",                     "required": 4.5, "kind": "text",     "note": "inverse text on the AI/brand accent surface" },
+  { "fg": "--success-text",   "bg": "--success-subtle",         "required": 4.5, "kind": "text",     "note": "success message text on its subtle background" },
+  { "fg": "--warning-text",   "bg": "--warning-subtle",         "required": 4.5, "kind": "text",     "note": "warning message text on its subtle background" },
+  { "fg": "--error-text",     "bg": "--error-subtle",           "required": 4.5, "kind": "text",     "note": "error message text on its subtle background" },
+  { "fg": "--info-text",      "bg": "--info-subtle",            "required": 4.5, "kind": "text",     "note": "info message text on its subtle background" },
+  { "fg": "--border-default", "bg": "--paper",                  "required": 3.0, "kind": "non-text", "decorative": true, "note": "default border against the page background - decorative; WCAG 2.2 SC 1.4.11 applies only to graphical objects essential for understanding content" },
+  { "fg": "--border-focus",   "bg": "--paper",                  "required": 3.0, "kind": "non-text", "note": "focus ring against the page background" },
+  { "fg": "--shu",            "bg": "--paper",                  "required": 3.0, "kind": "non-text", "note": "seal accent - must read as a UI mark on paper" },
+
+  { "fg": "--code-ink",       "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "default code text on the code surface" },
+  { "fg": "--code-muted",     "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "code comments on the code surface - read as prose, so full text contrast" },
+  { "fg": "--code-accent",    "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "keyword / accent token on the code surface" },
+  { "fg": "--code-blue",      "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "blue syntax token on the code surface" },
+  { "fg": "--code-green",     "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "green syntax token (strings) on the code surface" }
+]

package/scripts/theme-validator.js

@@ -338,15 +338,22 @@ function validateTokenSet(declared, contract) {
 }
 
 // -----------------------------------------------------------
-// Validate a single file. Auto-detects per-file vs consolidated.
+// Validate raw CSS text. Auto-detects per-file vs consolidated.
 // Returns a unified result shape with either a flat pass/fail
 // (per-file) or a list of per-theme pass/fails (consolidated).
+//
+// `options.label` names the result (shown as `result.file`) and, in the
+// legacy per-file branch, seeds the a11y report's inferred theme name —
+// there's no real file path when validating text handed over directly
+// (e.g. from an MCP tool call), so callers that have one should pass it
+// as label; callers that don't get '(pasted CSS)'.
 // -----------------------------------------------------------
-function validateFile(filePath, contract, options) {
+function validateText(text, contract, options) {
   const opts = options || {};
   const wantA11y = opts.a11y !== false;
+  const label = opts.label || '(pasted CSS)';
   const result = {
-    file: filePath,
+    file: label,
     mode: 'per-file',
     ok: false,
     declaredCount: 0,
@@ -356,14 +363,6 @@ function validateFile(filePath, contract, options) {
     error: null,
   };
 
-  let text;
-  try {
-    text = fs.readFileSync(filePath, 'utf8');
-  } catch (err) {
-    result.error = err.message;
-    return result;
-  }
-
   if (isConsolidated(text)) {
     result.mode = 'consolidated';
     const blocks = extractDataThemeBlocks(text);
@@ -409,12 +408,33 @@ function validateFile(filePath, contract, options) {
   result.missing = v.missing;
   result.ok = v.ok;
   if (wantA11y) {
-    const inferredName = path.basename(path.dirname(filePath)) || path.basename(filePath, '.css');
+    const inferredName = label !== '(pasted CSS)' ? (path.basename(path.dirname(label)) || path.basename(label, '.css')) : 'theme';
     result.a11y = a11y.auditThemeTokens({ name: inferredName, values: root.values });
   }
   return result;
 }
 
+// Reads a file and delegates to validateText, with the file path as the
+// result's label (and a11y's inferred-name source in the legacy branch).
+function validateFile(filePath, contract, options) {
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return {
+      file: filePath,
+      mode: 'per-file',
+      ok: false,
+      declaredCount: 0,
+      missing: [],
+      themes: null,
+      a11y: null,
+      error: err.message,
+    };
+  }
+  return validateText(text, contract, Object.assign({}, options, { label: filePath }));
+}
+
 // -----------------------------------------------------------
 // Reporter
 // -----------------------------------------------------------
@@ -665,6 +685,7 @@ module.exports = {
   extractDataThemeBlocks,
   isConsolidated,
   validateFile,
+  validateText,
   loadContract,
   a11y: a11y,
 };