motif-design 0.1.0

package/runtimes/claude-code/hooks/motif-token-check.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Motif Token Check Hook (HOOK-01)
+ *
+ * PostToolUse hook that flags hardcoded CSS values (colors, spacing,
+ * font-size, border-radius, box-shadow) and suggests design token
+ * alternatives from tokens.css.
+ *
+ * Reads PostToolUse JSON from stdin. Outputs decision JSON on stdout
+ * when violations are found. Exits silently (code 0, no output) when clean.
+ */
+
+const TARGET_EXTENSIONS = ['css', 'tsx', 'jsx', 'vue', 'html'];
+
+/**
+ * Extract the content to check based on tool type.
+ * Write provides full content; Edit provides new_string only.
+ */
+function getContentToCheck(data) {
+  if (data.tool_name === 'Write') {
+    return data.tool_input.content || '';
+  }
+  if (data.tool_name === 'Edit') {
+    return data.tool_input.new_string || '';
+  }
+  return null;
+}
+
+/**
+ * Remove comment lines from content to avoid false positives.
+ * Strips single-line comments (//), block comments, and HTML comments.
+ */
+function stripComments(content) {
+  const lines = content.split('\n');
+  const result = [];
+  let inBlockComment = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Track block comment state
+    if (inBlockComment) {
+      if (trimmed.includes('*/')) {
+        inBlockComment = false;
+      }
+      result.push(''); // Replace with empty line to preserve line numbers
+      continue;
+    }
+
+    if (trimmed.startsWith('/*')) {
+      if (!trimmed.includes('*/')) {
+        inBlockComment = true;
+      }
+      result.push('');
+      continue;
+    }
+
+    if (trimmed.startsWith('//') || trimmed.startsWith('*')) {
+      result.push('');
+      continue;
+    }
+
+    // Strip inline block comments
+    let cleaned = line.replace(/\/\*.*?\*\//g, '');
+    // Strip HTML comments
+    cleaned = cleaned.replace(/<!--.*?-->/g, '');
+
+    result.push(cleaned);
+  }
+
+  return result;
+}
+
+/**
+ * Check content lines for hardcoded CSS values that should use tokens.
+ */
+function checkForViolations(contentLines) {
+  const violations = [];
+
+  const checks = [
+    {
+      name: 'hardcoded color',
+      pattern: /(color|background(?:-color)?|border(?:-color)?|outline-color|fill|stroke)\s*:\s*(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\()/g,
+      skip: (line) => line.includes('var('),
+      suggestion: 'Use var(--color-*) or appropriate color token from tokens.css',
+    },
+    {
+      name: 'hardcoded spacing',
+      pattern: /(margin|padding)(?:-(top|right|bottom|left))?\s*:\s*(\d+)px/g,
+      skip: (line, match) => {
+        // Allow 0px and 1px (common resets)
+        const pxMatch = match.match(/:\s*(\d+)px/);
+        if (pxMatch) {
+          const val = parseInt(pxMatch[1], 10);
+          if (val <= 1) return true;
+        }
+        return line.includes('var(');
+      },
+      suggestion: 'Use var(--space-*) or appropriate spacing token from tokens.css',
+    },
+    {
+      name: 'hardcoded gap',
+      pattern: /gap\s*:\s*(\d+)px/g,
+      skip: (line, match) => {
+        const pxMatch = match.match(/:\s*(\d+)px/);
+        if (pxMatch) {
+          const val = parseInt(pxMatch[1], 10);
+          if (val <= 1) return true;
+        }
+        return line.includes('var(');
+      },
+      suggestion: 'Use var(--space-*) or appropriate spacing token from tokens.css',
+    },
+    {
+      name: 'hardcoded font-size',
+      pattern: /font-size\s*:\s*\d+(?:px|rem|em)/g,
+      skip: (line) => line.includes('var('),
+      suggestion: 'Use var(--text-*) or appropriate font-size token from tokens.css',
+    },
+    {
+      name: 'hardcoded border-radius',
+      pattern: /border-radius\s*:\s*(\d+)(px|%)/g,
+      skip: (line, match) => {
+        // Allow 0px (reset), 50% and 9999px (circles)
+        const radiusMatch = match.match(/:\s*(\d+)(px|%)/);
+        if (radiusMatch) {
+          const val = parseInt(radiusMatch[1], 10);
+          const unit = radiusMatch[2];
+          if (val === 0 && unit === 'px') return true;
+          if (val === 50 && unit === '%') return true;
+          if (val === 9999 && unit === 'px') return true;
+        }
+        return line.includes('var(');
+      },
+      suggestion: 'Use var(--radius-*) or appropriate radius token from tokens.css',
+    },
+    {
+      name: 'hardcoded box-shadow',
+      pattern: /box-shadow\s*:\s*\S/g,
+      skip: (line) => {
+        // Allow var() references and 'none'
+        const shadowMatch = line.match(/box-shadow\s*:\s*([^;}\n]+)/);
+        if (shadowMatch) {
+          const val = shadowMatch[1].trim().toLowerCase();
+          if (val.startsWith('var(') || val === 'none') return true;
+        }
+        return false;
+      },
+      suggestion: 'Use var(--shadow-*) or appropriate shadow token from tokens.css',
+    },
+  ];
+
+  for (let i = 0; i < contentLines.length; i++) {
+    const line = contentLines[i];
+    if (!line.trim()) continue;
+
+    for (const check of checks) {
+      // Reset regex lastIndex for each line
+      check.pattern.lastIndex = 0;
+      let match;
+      while ((match = check.pattern.exec(line)) !== null) {
+        if (check.skip && check.skip(line, match[0])) continue;
+        violations.push({
+          line: i + 1,
+          type: check.name,
+          matched: match[0],
+          suggestion: check.suggestion,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+// Main: read JSON from stdin
+let input = '';
+process.stdin.on('data', (chunk) => (input += chunk));
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+
+    // Extract file path and check extension
+    const filePath = data.tool_input && data.tool_input.file_path;
+    if (!filePath) process.exit(0);
+
+    const ext = filePath.split('.').pop().toLowerCase();
+    if (!TARGET_EXTENSIONS.includes(ext)) {
+      process.exit(0);
+    }
+
+    // Get content to check
+    const content = getContentToCheck(data);
+    if (!content) process.exit(0);
+
+    // Strip comments and check for violations
+    const contentLines = stripComments(content);
+    const violations = checkForViolations(contentLines);
+
+    if (violations.length === 0) {
+      process.exit(0);
+    }
+
+    // Format violation messages
+    const messages = violations.map(
+      (v) => `- Line ${v.line}: [${v.type}] \`${v.matched}\` -- ${v.suggestion}`
+    );
+
+    const output = JSON.stringify({
+      decision: 'block',
+      reason: `Motif token-check: ${violations.length} violation(s) found:\n${messages.join('\n')}`,
+    });
+
+    process.stdout.write(output);
+  } catch (e) {
+    // If JSON parsing fails or any error, exit silently
+    process.exit(0);
+  }
+});

package/runtimes/cursor/README.md

@@ -0,0 +1,24 @@
+# Cursor / Windsurf Runtime Adapter
+
+## Status: NOT BUILT (v1.2 target)
+
+## What Needs to Be Created
+
+1. **rules-snippet.md** — Condensed Motif instructions for `.cursorrules` / `.windsurfrules`
+   - No slash commands (these editors don't support them)
+   - No subagent spawning (single context only)
+   - The entire Motif workflow compressed into rules-file instructions
+   - Include: vertical detection, token generation logic, review checklist
+   
+2. **install mapping** — Simpler than Claude Code:
+   - `core/*` → `.motif/` (just drop it in the project)
+   - Append rules snippet to `.cursorrules` or `.windsurfrules`
+
+## Limitations
+- No fresh context per screen — quality will degrade on 5+ screen projects
+- No parallel research agents — runs sequentially in main context
+- No hooks — no automated enforcement
+- User triggers workflows manually by referencing the files
+
+## Value Proposition
+Even without subagents, the vertical references, differentiation seed, token decision algorithms, and review framework still improve output quality significantly compared to no design system.

package/runtimes/gemini/README.md

@@ -0,0 +1,13 @@
+# Gemini CLI Runtime Adapter
+
+## Status: NOT BUILT (v1.3 target)
+
+## What Needs to Be Created
+
+1. **commands/motif/*.md** — Adapt from Claude Code format to Gemini CLI command format
+2. **config-snippet.md** — Adapt for GEMINI.md injection
+3. Determine Gemini CLI's subagent/task delegation mechanism
+
+## Notes
+- Gemini CLI is still evolving — wait for stable API before building
+- GSD's Gemini support had issues with TOML format conversion — learn from their mistakes

package/runtimes/opencode/README.md

@@ -0,0 +1,28 @@
+# OpenCode Runtime Adapter
+
+## Status: NOT BUILT (v1.1 target)
+
+## What Needs to Be Created
+
+1. **commands/motif/*.md** — Copy from `runtimes/claude-code/commands/motif/`, replace workflow paths:
+   - `.claude/get-motif/` → `.opencode/get-motif/`
+   - Adapt any Claude Code-specific syntax
+
+2. **agents/*.md** — Copy from `runtimes/claude-code/agents/`, adapt:
+   - Replace `Task()` spawning with OpenCode's `agent()` mechanism
+   - Update model profile references to OpenCode's format
+
+3. **config-snippet.md** — Adapt CLAUDE-MD-SNIPPET.md for OpenCode's AGENTS.md format
+
+## Key Differences from Claude Code
+- Subagent spawning uses different syntax
+- Model profiles managed via `opencode.json` instead of Claude Code settings
+- Agent definitions may use different frontmatter format
+- No hooks support (or different hook format) — skip hooks for now
+
+## Testing
+Run full workflow on a test project using OpenCode to verify:
+- Commands resolve correctly
+- Subagents spawn with fresh context
+- State management works
+- Commits follow convention

package/scripts/contrast-checker.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * WCAG 2.1 Contrast Ratio Calculator (SCRP-01)
+ *
+ * Usage: node scripts/contrast-checker.js <color1> <color2>
+ * Colors: hex values with or without # (supports 3-char and 6-char)
+ *
+ * Zero external dependencies -- pure Node.js.
+ */
+
+const args = process.argv.slice(2);
+
+if (args.length < 2) {
+  console.error('Usage: node scripts/contrast-checker.js <color1> <color2>');
+  console.error('  Colors are hex values, e.g. "#000000" "#FFFFFF" or "000" "fff"');
+  process.exit(1);
+}
+
+/**
+ * Parse hex color string to [r, g, b] in 0-255 range.
+ * Supports 3-char (#abc) and 6-char (#abcdef) formats, with or without #.
+ */
+function parseHex(hex) {
+  hex = hex.replace(/^#/, '');
+  if (!/^[0-9a-fA-F]{3}$|^[0-9a-fA-F]{6}$/.test(hex)) {
+    console.error(`Invalid color format: "${hex}". Use 3 or 6 hex digits (e.g. #abc or #abcdef).`);
+    process.exit(1);
+  }
+  if (hex.length === 3) {
+    hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+  }
+  return [
+    parseInt(hex.slice(0, 2), 16),
+    parseInt(hex.slice(2, 4), 16),
+    parseInt(hex.slice(4, 6), 16),
+  ];
+}
+
+/**
+ * Convert sRGB channel (0-255) to linear value.
+ * Uses WCAG 2.1 threshold of 0.04045 (NOT the old 0.03928).
+ */
+function linearize(channel) {
+  const sRGB = channel / 255;
+  return sRGB <= 0.04045
+    ? sRGB / 12.92
+    : Math.pow((sRGB + 0.055) / 1.055, 2.4);
+}
+
+/**
+ * Calculate relative luminance per WCAG 2.1.
+ * L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+ */
+function relativeLuminance(r, g, b) {
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+
+/**
+ * Calculate contrast ratio between two hex colors.
+ * Returns a number (e.g. 21.0, 4.5, etc.)
+ */
+function contrastRatio(hex1, hex2) {
+  const [r1, g1, b1] = parseHex(hex1);
+  const [r2, g2, b2] = parseHex(hex2);
+  const l1 = relativeLuminance(r1, g1, b1);
+  const l2 = relativeLuminance(r2, g2, b2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Format contrast ratio for display.
+ * Rounds to 2 decimal places, removes trailing zeros.
+ */
+function formatRatio(ratio) {
+  // Round to 2 decimals
+  const rounded = Math.round(ratio * 100) / 100;
+  // If it's a whole number, show as N:1
+  if (rounded === Math.floor(rounded)) {
+    return `${rounded}:1`;
+  }
+  return `${rounded}:1`;
+}
+
+// Normalize input colors to have # prefix for display
+function normalizeForDisplay(hex) {
+  hex = hex.replace(/^#/, '').toUpperCase();
+  if (hex.length === 3) {
+    hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+  }
+  return '#' + hex;
+}
+
+const color1 = args[0];
+const color2 = args[1];
+const ratio = contrastRatio(color1, color2);
+
+const aaNormal = ratio >= 4.5;    // WCAG AA normal text (4.5:1)
+const aaLarge  = ratio >= 3;      // WCAG AA large text (3:1)
+const aaaNormal = ratio >= 7;     // WCAG AAA normal text (7:1)
+const aaaLarge  = ratio >= 4.5;   // WCAG AAA large text (4.5:1)
+
+const pass = '\x1b[32mPASS\x1b[0m';
+const fail = '\x1b[31mFAIL\x1b[0m';
+
+console.log(`Colors: ${normalizeForDisplay(color1)} vs ${normalizeForDisplay(color2)}`);
+console.log(`Contrast ratio: ${formatRatio(ratio)}`);
+console.log(`WCAG AA normal text (4.5:1): ${aaNormal ? pass : fail}`);
+console.log(`WCAG AA large text (3:1):    ${aaLarge ? pass : fail}`);
+console.log(`WCAG AAA normal text (7:1):  ${aaaNormal ? pass : fail}`);
+console.log(`WCAG AAA large text (4.5:1): ${aaaLarge ? pass : fail}`);

package/scripts/token-counter.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Approximate Token Counter (SCRP-02)
+ *
+ * Usage: node scripts/token-counter.js [directory]
+ * Defaults to .planning/design/ if no argument provided.
+ *
+ * Walks the target directory recursively, reads all text files,
+ * and reports an approximate token count using the ~4 chars/token heuristic.
+ *
+ * Zero external dependencies -- pure Node.js.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const targetDir = process.argv[2] || '.planning/design/';
+
+// Resolve to absolute path for display consistency
+const resolvedDir = path.resolve(targetDir);
+
+if (!fs.existsSync(resolvedDir)) {
+  console.error(`Directory not found: ${targetDir}`);
+  process.exit(1);
+}
+
+const stat = fs.statSync(resolvedDir);
+if (!stat.isDirectory()) {
+  console.error(`Not a directory: ${targetDir}`);
+  process.exit(1);
+}
+
+/**
+ * Check if a file appears to be binary by looking for null bytes
+ * in the first 512 bytes.
+ */
+function isBinary(filePath) {
+  const fd = fs.openSync(filePath, 'r');
+  const buf = Buffer.alloc(512);
+  const bytesRead = fs.readSync(fd, buf, 0, 512, 0);
+  fs.closeSync(fd);
+  for (let i = 0; i < bytesRead; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Recursively walk a directory, summing character counts of text files.
+ * Returns { chars, files } totals.
+ */
+function walkDir(dir) {
+  let totalChars = 0;
+  let fileCount = 0;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    // Permission denied or other read error -- skip this directory
+    return { chars: 0, files: 0 };
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    // Skip .DS_Store
+    if (entry.name === '.DS_Store') continue;
+
+    if (entry.isDirectory()) {
+      const sub = walkDir(fullPath);
+      totalChars += sub.chars;
+      fileCount += sub.files;
+    } else if (entry.isFile()) {
+      // Skip binary files
+      try {
+        if (isBinary(fullPath)) continue;
+        const content = fs.readFileSync(fullPath, 'utf8');
+        totalChars += content.length;
+        fileCount++;
+      } catch (e) {
+        // Unreadable file -- skip
+        continue;
+      }
+    }
+  }
+
+  return { chars: totalChars, files: fileCount };
+}
+
+/**
+ * Format a number with commas for readability.
+ * e.g. 48320 -> "48,320"
+ */
+function formatNumber(n) {
+  return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+const result = walkDir(resolvedDir);
+const approxTokens = Math.ceil(result.chars / 4);
+
+console.log(`Directory: ${targetDir}`);
+console.log(`Files scanned: ${formatNumber(result.files)}`);
+console.log(`Total characters: ${formatNumber(result.chars)}`);
+console.log(`Approximate tokens: ~${formatNumber(approxTokens)}`);