@jablonowski/dsb-tokens 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jablonowski/dsb-tokens",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "",
   "license": "MIT",
   "author": "Mateusz Jablonowski",
@@ -9,7 +9,11 @@
   "scripts": {
     "build": "style-dictionary build --config config.js",
     "release": "npm run build && npm version patch && npm publish --access public",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "lint:json": "node scripts/validate-json.js",
+    "lint:schema": "node scripts/validate-schema.js",
+    "lint": "npm run lint:json && npm run lint:schema",
+    "test": "node --test test/tokens.test.js",
+    "ci": "npm run lint && npm run build && npm test"
   },
   "repository": {
     "type": "git",

package/scripts/validate-json.js

@@ -0,0 +1,31 @@
+// @ts-check
+'use strict';
+
+/**
+ * Layer 1 — JSON syntax validation
+ * Checks that tokens/tokens.json is well-formed JSON.
+ * Exits with code 1 and prints the parse error on failure.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const FILE = path.resolve(__dirname, '../tokens/tokens.json');
+
+let raw;
+try {
+  raw = fs.readFileSync(FILE, 'utf8');
+} catch (err) {
+  console.error(`[validate-json] Cannot read file: ${FILE}`);
+  console.error(err.message);
+  process.exit(1);
+}
+
+try {
+  JSON.parse(raw);
+  console.log('[validate-json] ✓ tokens.json is valid JSON');
+} catch (err) {
+  console.error('[validate-json] ✗ tokens.json is not valid JSON');
+  console.error(err.message);
+  process.exit(1);
+}

package/scripts/validate-schema.js

@@ -0,0 +1,137 @@
+// @ts-check
+'use strict';
+
+/**
+ * Layer 2 — Token schema validation
+ *
+ * Recursively walks tokens.json and enforces the Style Dictionary
+ * three-tier token schema:
+ *
+ *   Token leaf:  { "value": string, "comment"?: string }  — no other keys
+ *   Group node:  any key whose value is an object (not a leaf)
+ *   Group comment: a "comment" string on a group node — allowed, skipped
+ *
+ * Additional format rules applied to leaf values:
+ *   • References  — must match  {path.to.token}  (curly-brace syntax)
+ *   • Hex colors  — must be     #rrggbb  (6-digit lowercase hex)
+ *   • RGBA colors — must match  rgba(r, g, b, a)
+ *
+ * Implements the validation step recommended by:
+ * https://martinfowler.com/articles/design-token-based-ui-architecture.html
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const FILE = path.resolve(__dirname, '../tokens/tokens.json');
+
+// ─── Regex patterns ───────────────────────────────────────────────────────────
+
+const RE_REFERENCE = /^\{[\w./#-]+\}$/;
+const RE_HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+const RE_RGBA      = /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*[\d.]+\s*\)$/;
+
+// ─── Recursive validator ──────────────────────────────────────────────────────
+
+/**
+ * @param {unknown} node
+ * @param {string}  nodePath  Dot-notation path for error reporting
+ * @param {string[]} errors   Accumulated error messages
+ */
+function validateNode(node, nodePath, errors) {
+  if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+    errors.push(`${nodePath}: expected an object node, got ${Array.isArray(node) ? 'array' : typeof node}`);
+    return;
+  }
+
+  const obj = /** @type {Record<string, unknown>} */ (node);
+
+  if ('value' in obj) {
+    validateLeaf(obj, nodePath, errors);
+  } else {
+    // Group node — recurse into every child except the optional 'comment' string
+    for (const [key, child] of Object.entries(obj)) {
+      if (key === 'comment') {
+        if (typeof child !== 'string') {
+          errors.push(`${nodePath}.comment: group comment must be a string`);
+        }
+        continue;
+      }
+      validateNode(child, nodePath ? `${nodePath}.${key}` : key, errors);
+    }
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} token
+ * @param {string}  tokenPath
+ * @param {string[]} errors
+ */
+function validateLeaf(token, tokenPath, errors) {
+  // 1. Value must be a string (Style Dictionary uses string values for all types)
+  if (typeof token.value !== 'string') {
+    errors.push(`${tokenPath}: 'value' must be a string, got ${typeof token.value}`);
+  }
+
+  // 2. No unexpected keys — only 'value' and 'comment' are allowed on a leaf
+  const ALLOWED = new Set(['value', 'comment']);
+  for (const key of Object.keys(token)) {
+    if (!ALLOWED.has(key)) {
+      errors.push(`${tokenPath}: unexpected key '${key}' on token leaf (only 'value' and 'comment' are allowed)`);
+    }
+  }
+
+  if (typeof token.value !== 'string') return; // already reported above
+
+  const val = token.value;
+
+  // 3. Reference syntax: value is entirely a {path.to.token} reference
+  if (val.startsWith('{')) {
+    if (!RE_REFERENCE.test(val)) {
+      errors.push(`${tokenPath}: malformed reference '${val}' — expected format: {category.group.name}`);
+    }
+    return; // no further format checks on references
+  }
+
+  // 4. Hex color format
+  if (val.startsWith('#')) {
+    if (!RE_HEX_COLOR.test(val)) {
+      errors.push(`${tokenPath}: hex color '${val}' must be exactly 6 hex digits (e.g. #1a7f3c)`);
+    }
+    return;
+  }
+
+  // 5. RGBA color format
+  if (val.startsWith('rgba')) {
+    if (!RE_RGBA.test(val)) {
+      errors.push(`${tokenPath}: rgba value '${val}' is malformed`);
+    }
+    return;
+  }
+
+  // All other formats (px, %, s, plain numbers, keywords like 'ease', 'transparent') are valid as-is
+}
+
+// ─── Run ──────────────────────────────────────────────────────────────────────
+
+let tokens;
+try {
+  tokens = JSON.parse(fs.readFileSync(FILE, 'utf8'));
+} catch (err) {
+  console.error(`[validate-schema] Cannot read/parse ${FILE}`);
+  console.error(err.message);
+  process.exit(1);
+}
+
+const errors = [];
+validateNode(tokens, '', errors);
+
+if (errors.length === 0) {
+  console.log(`[validate-schema] ✓ Token schema is valid`);
+} else {
+  console.error(`[validate-schema] ✗ Found ${errors.length} schema error(s):\n`);
+  for (const e of errors) {
+    console.error(`  • ${e}`);
+  }
+  process.exit(1);
+}

package/test/tokens.test.js

@@ -0,0 +1,179 @@
+'use strict';
+
+/**
+ * Layer 3 — Style Dictionary output tests
+ *
+ * Asserts that the built dist/css/variables.css contains the expected
+ * CSS custom property declarations. Requires `npm run build` to have
+ * run first (the CI workflow handles this ordering).
+ *
+ * Variable names are verified against the actual component CSS files in
+ * components/src/components/ — e.g. button.component.css uses
+ * var(--ds-component-button-border-radius) and var(--ds-decisions-font-weight-medium).
+ *
+ * Test selection covers:
+ *   • A raw color option (tier 1)
+ *   • A raw non-color option to verify unit conversion (border-radius full → 50%)
+ *   • A decision alias resolved via var() (tier 2, with outputReferences: true)
+ *   • A component float alias resolved via var() (tier 3)
+ *   • A three-tier alias chain: component → decision → option
+ */
+
+const { describe, it, before } = require('node:test');
+const assert = require('node:assert/strict');
+const fs     = require('fs');
+const path   = require('path');
+
+const CSS_FILE = path.resolve(__dirname, '../dist/css/variables.css');
+
+let css = '';
+
+describe('Style Dictionary output — dist/css/variables.css', () => {
+  before(() => {
+    assert.ok(
+      fs.existsSync(CSS_FILE),
+      `Build output not found at ${CSS_FILE}. Run 'npm run build' before running tests.`
+    );
+    css = fs.readFileSync(CSS_FILE, 'utf8');
+    assert.ok(css.length > 0, 'CSS output file must not be empty');
+  });
+
+  // ─── Tier 1 — Options: raw values ─────────────────────────────────────────
+
+  describe('Tier 1 — Options: raw values', () => {
+    it('exports neutral-900 as #111111 (darkest neutral)', () => {
+      assert.match(css, /--ds-color-options-neutral-900:\s*#111111/);
+    });
+
+    it('exports neutral-0 as #ffffff (white)', () => {
+      assert.match(css, /--ds-color-options-neutral-0:\s*#ffffff/);
+    });
+
+    it('exports error red-500 as #d93025', () => {
+      assert.match(css, /--ds-color-options-red-500:\s*#d93025/);
+    });
+
+    it('exports success green-700 as #1a7f3c', () => {
+      assert.match(css, /--ds-color-options-green-700:\s*#1a7f3c/);
+    });
+
+    it('exports rgba black overlay (a40) with correct alpha', () => {
+      // rgba(0, 0, 0, 0.4)  — used for modal backdrop
+      assert.match(css, /--ds-color-options-black-a40:\s*rgba\(0,\s*0,\s*0,\s*0\.4\)/);
+    });
+
+    it('exports border-radius full as 50% (not 9999px)', () => {
+      assert.match(css, /--ds-border-radius-options-full:\s*50%/);
+    });
+
+    it('exports easing standard as "ease"', () => {
+      assert.match(css, /--ds-easing-options-standard:\s*ease/);
+    });
+  });
+
+  // ─── Tier 2 — Decisions: alias references via var() ───────────────────────
+
+  describe('Tier 2 — Decisions: var() alias references', () => {
+    it('color.text.primary references options neutral-900', () => {
+      // decisions.color.text.primary → {color.options.neutral.900}
+      assert.match(
+        css,
+        /--ds-decisions-color-text-primary:\s*var\(--ds-color-options-neutral-900\)/
+      );
+    });
+
+    it('color.text.inverse references options neutral-0', () => {
+      // decisions.color.text.inverse → {color.options.neutral.0}
+      assert.match(
+        css,
+        /--ds-decisions-color-text-inverse:\s*var\(--ds-color-options-neutral-0\)/
+      );
+    });
+
+    it('color.feedback.error.icon references options red-500', () => {
+      assert.match(
+        css,
+        /--ds-decisions-color-feedback-error-icon:\s*var\(--ds-color-options-red-500\)/
+      );
+    });
+
+    it('font.size.md references options font-size-14', () => {
+      // decisions.font.size.md → {font.size.options.14}
+      assert.match(
+        css,
+        /--ds-decisions-font-size-md:\s*var\(--ds-font-size-options-14\)/
+      );
+    });
+
+    it('font.weight.medium references options font-weight-medium', () => {
+      assert.match(
+        css,
+        /--ds-decisions-font-weight-medium:\s*var\(--ds-font-weight-options-medium\)/
+      );
+    });
+
+    it('border.radius.lg references options border-radius-6', () => {
+      // decisions.border.radius.lg → {border.radius.options.6}
+      assert.match(
+        css,
+        /--ds-decisions-border-radius-lg:\s*var\(--ds-border-radius-options-6\)/
+      );
+    });
+
+    it('border.radius.full references options border-radius-full', () => {
+      assert.match(
+        css,
+        /--ds-decisions-border-radius-full:\s*var\(--ds-border-radius-options-full\)/
+      );
+    });
+  });
+
+  // ─── Tier 3 — Components: three-tier alias chain ──────────────────────────
+
+  describe('Tier 3 — Components: three-tier var() chains', () => {
+    it('button.borderRadius references decisions border-radius-lg', () => {
+      // component.button.borderRadius → {decisions.border.radius.lg}
+      // camelCase borderRadius → kebab border-radius confirmed in button.component.css
+      assert.match(
+        css,
+        /--ds-component-button-border-radius:\s*var\(--ds-decisions-border-radius-lg\)/
+      );
+    });
+
+    it('button.primary.background references decisions color.text.primary', () => {
+      // component.button.primary.background → {decisions.color.text.primary}
+      assert.match(
+        css,
+        /--ds-component-button-primary-background:\s*var\(--ds-decisions-color-text-primary\)/
+      );
+    });
+
+    it('button.primary.text references decisions color.text.inverse', () => {
+      assert.match(
+        css,
+        /--ds-component-button-primary-text:\s*var\(--ds-decisions-color-text-inverse\)/
+      );
+    });
+
+    it('input.borderRadius references decisions border-radius-lg', () => {
+      assert.match(
+        css,
+        /--ds-component-input-border-radius:\s*var\(--ds-decisions-border-radius-lg\)/
+      );
+    });
+
+    it('modal.backdrop references decisions color.overlay.backdrop', () => {
+      assert.match(
+        css,
+        /--ds-component-modal-backdrop:\s*var\(--ds-decisions-color-overlay-backdrop\)/
+      );
+    });
+
+    it('tag.success.background references decisions feedback.success.surface', () => {
+      assert.match(
+        css,
+        /--ds-component-tag-success-background:\s*var\(--ds-decisions-color-feedback-success-surface\)/
+      );
+    });
+  });
+});