PixelPilot uiux-component-docs.instructions.md

Component Documentation Skill

Generate documentation for components automatically from source code.

---

CORE PRINCIPLE

Rule: Every component should have documentation generated from its source code. Documentation must include props, examples, and design token usage.

---

REACT (REACT-DOCGEN + MARKDOWN)

Setup

npm install -D react-docgen-typescript typescript

Script

// scripts/generate-docs.ts
import * as fs from 'fs';
import * as path from 'path';
import { parse } from 'react-docgen-typescript';

const COMPONENTS_DIR = './src/components';
const DOCS_DIR = './docs/components';

// Ensure docs directory exists
if (!fs.existsSync(DOCS_DIR)) {
  fs.mkdirSync(DOCS_DIR, { recursive: true });
}

// Parser options
const options = {
  savePropValueAsString: true,
  shouldExtractLiteralValuesFromEnum: true,
  shouldRemoveUndefinedFromOptional: true,
  propFilter: (prop: any) => {
    // Filter out HTML attributes
    if (prop.declarations?.length > 0) {
      return prop.declarations.some(
        (d: any) => !d.fileName.includes('node_modules')
      );
    }
    return true;
  },
};

// Find all component files
function findComponents(dir: string): string[] {
  const files: string[] = [];
  
  fs.readdirSync(dir).forEach(file => {
    const fullPath = path.join(dir, file);
    const stat = fs.statSync(fullPath);
    
    if (stat.isDirectory()) {
      files.push(...findComponents(fullPath));
    } else if (file.match(/\.(tsx|ts)$/) && !file.includes('.test.') && !file.includes('.stories.')) {
      files.push(fullPath);
    }
  });
  
  return files;
}

// Generate markdown for a component
function generateMarkdown(component: any): string {
  let md = `# ${component.displayName}\n\n`;
  
  if (component.description) {
    md += `${component.description}\n\n`;
  }
  
  // Props table
  const props = Object.entries(component.props || {});
  if (props.length > 0) {
    md += `## Props\n\n`;
    md += `| Prop | Type | Default | Required | Description |\n`;
    md += `|------|------|---------|----------|-------------|\n`;
    
    props.forEach(([name, prop]: [string, any]) => {
      const type = prop.type?.name || 'unknown';
      const defaultValue = prop.defaultValue?.value || '-';
      const required = prop.required ? '✅' : '❌';
      const description = prop.description || '-';
      
      md += `| \`${name}\` | \`${type}\` | \`${defaultValue}\` | ${required} | ${description} |\n`;
    });
    
    md += '\n';
  }
  
  // Design tokens section
  md += `## Design Tokens Used\n\n`;
  md += `> This component uses the following design tokens:\n\n`;
  md += `\`\`\`css\n`;
  md += `/* Spacing */\n`;
  md += `var(--space-2), var(--space-4)\n\n`;
  md += `/* Colors */\n`;
  md += `var(--accent), var(--text), var(--border)\n\n`;
  md += `/* Radius */\n`;
  md += `var(--radius-md)\n`;
  md += `\`\`\`\n\n`;
  
  // Usage example
  md += `## Usage\n\n`;
  md += `\`\`\`tsx\n`;
  md += `import { ${component.displayName} } from '@/components/${component.displayName}';\n\n`;
  md += `function Example() {\n`;
  md += `  return (\n`;
  md += `    <${component.displayName}\n`;
  
  // Add example props
  props.slice(0, 3).forEach(([name, prop]: [string, any]) => {
    if (prop.required) {
      const exampleValue = getExampleValue(prop.type?.name);
      md += `      ${name}={${exampleValue}}\n`;
    }
  });
  
  md += `    />\n`;
  md += `  );\n`;
  md += `}\n`;
  md += `\`\`\`\n\n`;
  
  return md;
}

function getExampleValue(type: string): string {
  switch (type) {
    case 'string': return '"example"';
    case 'number': return '42';
    case 'boolean': return 'true';
    case 'function':
    case '() => void': return '() => {}';
    default: return '...';
  }
}

// Main execution
const componentFiles = findComponents(COMPONENTS_DIR);

componentFiles.forEach(file => {
  try {
    const components = parse(file, options);
    
    components.forEach(component => {
      if (component.displayName) {
        const markdown = generateMarkdown(component);
        const outputPath = path.join(DOCS_DIR, `${component.displayName}.md`);
        
        fs.writeFileSync(outputPath, markdown);
        console.log(`✅ Generated: ${outputPath}`);
      }
    });
  } catch (error) {
    console.warn(`⚠️ Skipped: ${file}`);
  }
});

// Generate index
const indexContent = `# Component Documentation\n\n` +
  fs.readdirSync(DOCS_DIR)
    .filter(f => f.endsWith('.md') && f !== 'index.md')
    .map(f => `- [${f.replace('.md', '')}](./${f})`)
    .join('\n');

fs.writeFileSync(path.join(DOCS_DIR, 'index.md'), indexContent);
console.log('\n✅ Generated index.md');