real-prototypes-skill 0.1.0

package/.claude/skills/real-prototypes-skill/scripts/validate-output.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+/**
+ * POST-GENERATION VALIDATION
+ *
+ * This script validates that the generated prototype:
+ * 1. Uses ONLY colors from the extracted design tokens
+ * 2. Uses the correct font families
+ * 3. Doesn't contain any "made up" colors
+ *
+ * Exit codes:
+ *   0 = All validations passed
+ *   1 = Validation failed - colors don't match
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REFERENCES_DIR = 'references';
+const PROTOTYPE_DIR = 'prototype';
+
+// Colors that are always allowed (CSS basics)
+const ALLOWED_BASE_COLORS = [
+  '#fff', '#ffffff', '#000', '#000000',
+  'transparent', 'inherit', 'currentColor'
+];
+
+// Tailwind color classes that might sneak through
+const FORBIDDEN_TAILWIND_PATTERNS = [
+  /\b(teal|cyan|emerald|violet|purple|pink|rose|fuchsia|indigo)-\d{2,3}\b/,
+  /\bbg-(teal|cyan|emerald|violet|purple|pink|rose|fuchsia|indigo)/,
+  /\btext-(teal|cyan|emerald|violet|purple|pink|rose|fuchsia|indigo)/,
+  /\bborder-(teal|cyan|emerald|violet|purple|pink|rose|fuchsia|indigo)/
+];
+
+function log(type, message) {
+  const icons = {
+    error: '❌',
+    warning: '⚠️',
+    success: '✅',
+    info: 'ℹ️'
+  };
+  console.log(`${icons[type] || '•'} ${message}`);
+}
+
+function loadDesignTokens() {
+  const tokensPath = path.join(REFERENCES_DIR, 'design-tokens.json');
+  if (!fs.existsSync(tokensPath)) {
+    throw new Error('design-tokens.json not found. Run validation-prerequisites.js first.');
+  }
+  return JSON.parse(fs.readFileSync(tokensPath, 'utf8'));
+}
+
+function getAllowedColors(tokens) {
+  const allowed = new Set(ALLOWED_BASE_COLORS);
+
+  // Add all colors from rawColors
+  if (tokens.rawColors) {
+    tokens.rawColors.forEach(([color]) => {
+      allowed.add(color.toLowerCase());
+    });
+  }
+
+  // Add all categorized colors
+  function extractColors(obj) {
+    if (!obj) return;
+    if (typeof obj === 'string' && obj.startsWith('#')) {
+      allowed.add(obj.toLowerCase());
+    } else if (typeof obj === 'object') {
+      Object.values(obj).forEach(extractColors);
+    }
+  }
+
+  extractColors(tokens.colors);
+
+  return allowed;
+}
+
+function extractColorsFromCode(code) {
+  const colors = new Set();
+
+  // Extract hex colors
+  const hexMatches = code.match(/#[0-9a-fA-F]{3,8}/g) || [];
+  hexMatches.forEach(color => colors.add(color.toLowerCase()));
+
+  // Extract rgb/rgba colors
+  const rgbMatches = code.match(/rgba?\([^)]+\)/g) || [];
+  rgbMatches.forEach(color => colors.add(color.toLowerCase()));
+
+  return colors;
+}
+
+function findForbiddenTailwindClasses(code) {
+  const forbidden = [];
+
+  FORBIDDEN_TAILWIND_PATTERNS.forEach(pattern => {
+    const matches = code.match(pattern);
+    if (matches) {
+      forbidden.push(...matches);
+    }
+  });
+
+  return [...new Set(forbidden)];
+}
+
+function validateGeneratedFile(filePath, allowedColors, tokens) {
+  const code = fs.readFileSync(filePath, 'utf8');
+  const result = {
+    file: filePath,
+    passed: true,
+    invalidColors: [],
+    forbiddenClasses: [],
+    warnings: []
+  };
+
+  // Check for colors not in design tokens
+  const usedColors = extractColorsFromCode(code);
+  usedColors.forEach(color => {
+    // Normalize 3-digit hex to 6-digit
+    let normalizedColor = color;
+    if (/^#[0-9a-f]{3}$/i.test(color)) {
+      normalizedColor = `#${color[1]}${color[1]}${color[2]}${color[2]}${color[3]}${color[3]}`;
+    }
+
+    if (!allowedColors.has(normalizedColor) && !allowedColors.has(color)) {
+      result.invalidColors.push(color);
+      result.passed = false;
+    }
+  });
+
+  // Check for forbidden Tailwind classes
+  const forbiddenClasses = findForbiddenTailwindClasses(code);
+  if (forbiddenClasses.length > 0) {
+    result.forbiddenClasses = forbiddenClasses;
+    result.passed = false;
+  }
+
+  // Check if primary color is being used
+  const primaryColor = tokens.colors?.primary;
+  if (primaryColor && !code.includes(primaryColor)) {
+    result.warnings.push(`Primary color ${primaryColor} not found in file - buttons/links may have wrong color`);
+  }
+
+  // Check for font family usage
+  const fontFamily = tokens.fonts?.primary;
+  if (fontFamily && !code.toLowerCase().includes(fontFamily.toLowerCase().split(',')[0])) {
+    result.warnings.push(`Primary font "${fontFamily}" not found in file`);
+  }
+
+  return result;
+}
+
+function findPrototypeFiles(dir, files = []) {
+  const items = fs.readdirSync(dir);
+
+  items.forEach(item => {
+    const fullPath = path.join(dir, item);
+    const stat = fs.statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      // Skip node_modules and .next
+      if (item !== 'node_modules' && item !== '.next') {
+        findPrototypeFiles(fullPath, files);
+      }
+    } else if (
+      item.endsWith('.tsx') ||
+      item.endsWith('.jsx') ||
+      item.endsWith('.ts') ||
+      item.endsWith('.css')
+    ) {
+      files.push(fullPath);
+    }
+  });
+
+  return files;
+}
+
+function generateReport(results, tokens) {
+  const report = {
+    timestamp: new Date().toISOString(),
+    passed: results.every(r => r.passed),
+    summary: {
+      filesChecked: results.length,
+      filesPassed: results.filter(r => r.passed).length,
+      filesFailed: results.filter(r => !r.passed).length,
+      totalInvalidColors: results.reduce((sum, r) => sum + r.invalidColors.length, 0),
+      totalForbiddenClasses: results.reduce((sum, r) => sum + r.forbiddenClasses.length, 0)
+    },
+    allowedPrimaryColor: tokens.colors?.primary,
+    allowedFontFamily: tokens.fonts?.primary,
+    results: results
+  };
+
+  const reportPath = path.join(REFERENCES_DIR, 'output-validation-report.json');
+  fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+
+  return report;
+}
+
+function suggestFixes(results, tokens) {
+  const allInvalidColors = [...new Set(results.flatMap(r => r.invalidColors))];
+  const allForbiddenClasses = [...new Set(results.flatMap(r => r.forbiddenClasses))];
+
+  if (allInvalidColors.length === 0 && allForbiddenClasses.length === 0) {
+    return null;
+  }
+
+  console.log('\n📝 SUGGESTED FIXES:\n');
+
+  if (allInvalidColors.length > 0) {
+    console.log('Invalid colors found - replace with these design token colors:');
+    console.log('');
+
+    allInvalidColors.forEach(invalidColor => {
+      const suggestion = findClosestColor(invalidColor, tokens);
+      console.log(`  ${invalidColor} → ${suggestion.color} (${suggestion.category})`);
+    });
+  }
+
+  if (allForbiddenClasses.length > 0) {
+    console.log('\nForbidden Tailwind classes - use inline styles with hex values:');
+    console.log('');
+
+    allForbiddenClasses.forEach(cls => {
+      console.log(`  "${cls}" → style={{ color: "${tokens.colors?.primary || '#1c64f2'}" }}`);
+    });
+  }
+
+  return { invalidColors: allInvalidColors, forbiddenClasses: allForbiddenClasses };
+}
+
+function findClosestColor(targetColor, tokens) {
+  // Simple suggestion based on color characteristics
+  const hex = targetColor.startsWith('#') ? targetColor : null;
+  if (!hex) return { color: tokens.colors?.primary || '#1c64f2', category: 'primary' };
+
+  const rgb = hexToRgb(hex);
+  if (!rgb) return { color: tokens.colors?.primary || '#1c64f2', category: 'primary' };
+
+  const brightness = (rgb.r * 299 + rgb.g * 587 + rgb.b * 114) / 1000;
+
+  // Suggest based on brightness
+  if (brightness > 240) {
+    return { color: tokens.colors?.background?.white || '#ffffff', category: 'background.white' };
+  } else if (brightness > 200) {
+    return { color: tokens.colors?.background?.light || '#f6f6f5', category: 'background.light' };
+  } else if (brightness > 150) {
+    return { color: tokens.colors?.border?.default || '#e7e7e6', category: 'border' };
+  } else if (brightness > 100) {
+    return { color: tokens.colors?.text?.secondary || '#6b7280', category: 'text.secondary' };
+  } else if (brightness > 50) {
+    return { color: tokens.colors?.text?.primary || '#191918', category: 'text.primary' };
+  } else {
+    return { color: tokens.colors?.sidebar?.dark || '#0e2933', category: 'sidebar' };
+  }
+}
+
+function hexToRgb(hex) {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result ? {
+    r: parseInt(result[1], 16),
+    g: parseInt(result[2], 16),
+    b: parseInt(result[3], 16)
+  } : null;
+}
+
+async function runValidation(options = {}) {
+  console.log('\n' + '='.repeat(60));
+  console.log('🔍 POST-GENERATION VALIDATION');
+  console.log('='.repeat(60) + '\n');
+
+  // Load design tokens
+  let tokens;
+  try {
+    tokens = loadDesignTokens();
+    log('success', `Loaded design tokens (${tokens.totalColorsFound || 'unknown'} colors)`);
+  } catch (error) {
+    log('error', error.message);
+    return { passed: false, errors: [error.message] };
+  }
+
+  // Get allowed colors
+  const allowedColors = getAllowedColors(tokens);
+  log('info', `${allowedColors.size} colors in allowed palette`);
+
+  // Find all prototype files
+  const prototypeDir = options.prototypeDir || PROTOTYPE_DIR;
+  if (!fs.existsSync(prototypeDir)) {
+    log('error', `Prototype directory not found: ${prototypeDir}`);
+    return { passed: false, errors: ['Prototype directory not found'] };
+  }
+
+  const files = findPrototypeFiles(path.join(prototypeDir, 'src'));
+  log('info', `Found ${files.length} source files to validate`);
+
+  // Validate each file
+  const results = [];
+  files.forEach(file => {
+    const result = validateGeneratedFile(file, allowedColors, tokens);
+    results.push(result);
+
+    if (!result.passed) {
+      log('error', `${path.relative(prototypeDir, file)}`);
+      if (result.invalidColors.length > 0) {
+        console.log(`     Invalid colors: ${result.invalidColors.join(', ')}`);
+      }
+      if (result.forbiddenClasses.length > 0) {
+        console.log(`     Forbidden classes: ${result.forbiddenClasses.join(', ')}`);
+      }
+    } else if (result.warnings.length > 0) {
+      log('warning', `${path.relative(prototypeDir, file)}`);
+      result.warnings.forEach(w => console.log(`     ${w}`));
+    } else {
+      log('success', `${path.relative(prototypeDir, file)}`);
+    }
+  });
+
+  // Generate report
+  const report = generateReport(results, tokens);
+
+  // Show fixes if needed
+  if (!report.passed) {
+    suggestFixes(results, tokens);
+  }
+
+  // Final summary
+  console.log('\n' + '='.repeat(60));
+  if (report.passed) {
+    console.log('✅ OUTPUT VALIDATION PASSED');
+    console.log('   All colors match the captured design tokens');
+  } else {
+    console.log('❌ OUTPUT VALIDATION FAILED');
+    console.log(`   ${report.summary.totalInvalidColors} invalid colors found`);
+    console.log(`   ${report.summary.totalForbiddenClasses} forbidden Tailwind classes found`);
+    console.log('\n   Fix the issues above and run validation again.');
+  }
+  console.log('='.repeat(60) + '\n');
+
+  return {
+    passed: report.passed,
+    report: report
+  };
+}
+
+// CLI interface
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const options = {};
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--dir' && args[i + 1]) {
+      options.prototypeDir = args[i + 1];
+      i++;
+    }
+  }
+
+  runValidation(options).then(result => {
+    process.exit(result.passed ? 0 : 1);
+  });
+}
+
+module.exports = { runValidation };

package/.claude/skills/real-prototypes-skill/scripts/validate-prerequisites.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+/**
+ * PRE-GENERATION VALIDATION
+ *
+ * This script MUST pass before any prototype generation can begin.
+ * It validates that all required reference materials exist and are complete.
+ *
+ * Exit codes:
+ *   0 = All validations passed, safe to proceed
+ *   1 = Validation failed, DO NOT proceed with generation
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REFERENCES_DIR = 'references';
+
+// Minimum requirements for generation
+const REQUIREMENTS = {
+  minColors: 10,
+  minFonts: 1,
+  requiredColorCategories: ['primary', 'text', 'background', 'border'],
+  requiredFiles: [
+    'design-tokens.json',
+    'manifest.json'
+  ]
+};
+
+class ValidationError extends Error {
+  constructor(message, category) {
+    super(message);
+    this.category = category;
+  }
+}
+
+function log(type, message) {
+  const icons = {
+    error: '❌',
+    warning: '⚠️',
+    success: '✅',
+    info: 'ℹ️'
+  };
+  console.log(`${icons[type] || '•'} ${message}`);
+}
+
+function validateFileExists(filePath, description) {
+  const fullPath = path.join(REFERENCES_DIR, filePath);
+  if (!fs.existsSync(fullPath)) {
+    throw new ValidationError(
+      `Missing required file: ${filePath}\n   ${description}`,
+      'file'
+    );
+  }
+  return fullPath;
+}
+
+function validateDesignTokens() {
+  log('info', 'Validating design tokens...');
+
+  const tokensPath = validateFileExists(
+    'design-tokens.json',
+    'Run comprehensive-capture.js first to extract design tokens'
+  );
+
+  const tokens = JSON.parse(fs.readFileSync(tokensPath, 'utf8'));
+  const errors = [];
+
+  // Check total colors
+  const totalColors = tokens.totalColorsFound || Object.keys(tokens.rawColors || {}).length;
+  if (totalColors < REQUIREMENTS.minColors) {
+    errors.push(`Insufficient colors: found ${totalColors}, need at least ${REQUIREMENTS.minColors}`);
+  }
+
+  // Check required color categories
+  REQUIREMENTS.requiredColorCategories.forEach(category => {
+    if (!tokens.colors || !tokens.colors[category]) {
+      errors.push(`Missing color category: ${category}`);
+    } else if (category === 'primary' && !tokens.colors.primary) {
+      errors.push('Primary color not identified');
+    }
+  });
+
+  // Check fonts
+  if (!tokens.fonts || !tokens.fonts.families || tokens.fonts.families.length < REQUIREMENTS.minFonts) {
+    errors.push('No font families extracted');
+  }
+
+  // Check for specific critical colors
+  if (!tokens.colors?.primary) {
+    errors.push('Primary/accent color not identified - buttons and links will use wrong color');
+  }
+  if (!tokens.colors?.sidebar?.dark && !tokens.colors?.sidebar?.bg) {
+    // Not an error, just a warning
+    log('warning', 'Sidebar color not identified - may need manual verification');
+  }
+
+  if (errors.length > 0) {
+    throw new ValidationError(
+      `Design tokens incomplete:\n   ${errors.join('\n   ')}`,
+      'tokens'
+    );
+  }
+
+  log('success', `Design tokens valid (${totalColors} colors, ${tokens.fonts.families.length} fonts)`);
+  return tokens;
+}
+
+function validateManifest() {
+  log('info', 'Validating capture manifest...');
+
+  const manifestPath = validateFileExists(
+    'manifest.json',
+    'Run comprehensive-capture.js first to create manifest'
+  );
+
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const errors = [];
+
+  if (!manifest.platform?.baseUrl) {
+    errors.push('Missing platform baseUrl in manifest');
+  }
+
+  if (!manifest.pages || manifest.pages.length === 0) {
+    errors.push('No pages captured in manifest');
+  }
+
+  // Validate each page has screenshots
+  manifest.pages?.forEach(page => {
+    if (!page.captures || page.captures.length === 0) {
+      errors.push(`Page "${page.name}" has no captures`);
+    }
+  });
+
+  if (errors.length > 0) {
+    throw new ValidationError(
+      `Manifest incomplete:\n   ${errors.join('\n   ')}`,
+      'manifest'
+    );
+  }
+
+  log('success', `Manifest valid (${manifest.pages.length} pages, ${manifest.totalScreenshots || 'unknown'} screenshots)`);
+  return manifest;
+}
+
+function validateScreenshots(pageName = null) {
+  log('info', 'Validating screenshots...');
+
+  const screenshotDir = path.join(REFERENCES_DIR, 'screenshots');
+  if (!fs.existsSync(screenshotDir)) {
+    throw new ValidationError(
+      'Screenshots directory missing',
+      'screenshots'
+    );
+  }
+
+  const screenshots = fs.readdirSync(screenshotDir).filter(f => f.endsWith('.png'));
+
+  if (screenshots.length === 0) {
+    throw new ValidationError(
+      'No screenshots found in references/screenshots/',
+      'screenshots'
+    );
+  }
+
+  // If specific page requested, check it exists
+  if (pageName) {
+    const pageScreenshot = screenshots.find(s =>
+      s.startsWith(pageName) || s.includes(pageName)
+    );
+    if (!pageScreenshot) {
+      throw new ValidationError(
+        `No screenshot found for page: ${pageName}\n   Available: ${screenshots.join(', ')}`,
+        'screenshots'
+      );
+    }
+  }
+
+  // Check screenshot file sizes (should be > 10KB for valid captures)
+  const smallScreenshots = screenshots.filter(s => {
+    const stats = fs.statSync(path.join(screenshotDir, s));
+    return stats.size < 10000; // 10KB minimum
+  });
+
+  if (smallScreenshots.length > 0) {
+    log('warning', `Small screenshots detected (may be incomplete): ${smallScreenshots.join(', ')}`);
+  }
+
+  log('success', `Screenshots valid (${screenshots.length} files)`);
+  return screenshots;
+}
+
+function validateComponentStyles() {
+  log('info', 'Validating component styles...');
+
+  const stylesPath = path.join(REFERENCES_DIR, 'component-styles.json');
+
+  if (!fs.existsSync(stylesPath)) {
+    log('warning', 'component-styles.json not found - component matching may be less accurate');
+    return null;
+  }
+
+  const styles = JSON.parse(fs.readFileSync(stylesPath, 'utf8'));
+  log('success', 'Component styles found');
+  return styles;
+}
+
+function generateValidationReport(results) {
+  const report = {
+    timestamp: new Date().toISOString(),
+    passed: results.passed,
+    errors: results.errors,
+    warnings: results.warnings,
+    summary: {
+      totalColors: results.tokens?.totalColorsFound || 0,
+      primaryColor: results.tokens?.colors?.primary || 'NOT FOUND',
+      fontFamily: results.tokens?.fonts?.primary || 'NOT FOUND',
+      pagesCaptures: results.manifest?.pages?.length || 0,
+      totalScreenshots: results.screenshots?.length || 0
+    }
+  };
+
+  const reportPath = path.join(REFERENCES_DIR, 'validation-report.json');
+  fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+
+  return report;
+}
+
+async function runValidation(options = {}) {
+  console.log('\n' + '='.repeat(60));
+  console.log('🔍 PRE-GENERATION VALIDATION');
+  console.log('='.repeat(60) + '\n');
+
+  const results = {
+    passed: true,
+    errors: [],
+    warnings: [],
+    tokens: null,
+    manifest: null,
+    screenshots: null
+  };
+
+  try {
+    // 1. Validate design tokens (CRITICAL)
+    results.tokens = validateDesignTokens();
+  } catch (error) {
+    results.passed = false;
+    results.errors.push(error.message);
+    log('error', error.message);
+  }
+
+  try {
+    // 2. Validate manifest (CRITICAL)
+    results.manifest = validateManifest();
+  } catch (error) {
+    results.passed = false;
+    results.errors.push(error.message);
+    log('error', error.message);
+  }
+
+  try {
+    // 3. Validate screenshots (CRITICAL)
+    results.screenshots = validateScreenshots(options.pageName);
+  } catch (error) {
+    results.passed = false;
+    results.errors.push(error.message);
+    log('error', error.message);
+  }
+
+  try {
+    // 4. Validate component styles (OPTIONAL but recommended)
+    results.componentStyles = validateComponentStyles();
+  } catch (error) {
+    results.warnings.push(error.message);
+    log('warning', error.message);
+  }
+
+  // Generate report
+  const report = generateValidationReport(results);
+
+  // Final summary
+  console.log('\n' + '='.repeat(60));
+  if (results.passed) {
+    console.log('✅ VALIDATION PASSED - Safe to proceed with generation');
+    console.log('='.repeat(60));
+    console.log('\nKey values for generation:');
+    console.log(`  Primary color: ${report.summary.primaryColor}`);
+    console.log(`  Font family: ${report.summary.fontFamily}`);
+    console.log(`  Screenshots: ${report.summary.totalScreenshots}`);
+  } else {
+    console.log('❌ VALIDATION FAILED - DO NOT proceed with generation');
+    console.log('='.repeat(60));
+    console.log('\nErrors that must be fixed:');
+    results.errors.forEach((e, i) => console.log(`  ${i + 1}. ${e}`));
+    console.log('\nRun comprehensive-capture.js to fix these issues.');
+  }
+  console.log('');
+
+  return results;
+}
+
+// CLI interface
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const options = {};
+
+  // Parse arguments
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--page' && args[i + 1]) {
+      options.pageName = args[i + 1];
+      i++;
+    }
+  }
+
+  runValidation(options).then(results => {
+    process.exit(results.passed ? 0 : 1);
+  });
+}
+
+module.exports = { runValidation };