design-agent/README.md

Universal AI Design Review Agent - CLI tool for scanning code for design drift

# Design Agent - Universal AI Design Review Agent

A comprehensive CLI tool for scanning code for design drift, supporting Tailwind, design tokens, Storybook, and more. Built with Node.js 20+ and zero external dependencies.

## Features

- **Universal Design Analysis**: Supports multiple design formats and platforms
- **AI-Powered Reviews**: Optional Claude integration for intelligent summaries
- **Slack Integration**: Post Block Kit summaries to Slack channels
- **SARIF Output**: Generate SARIF reports for CI/CD integration
- **Design Token Detection**: Find hardcoded values that should use design tokens
- **Accessibility Checks**: Detect contrast and accessibility issues
- **Customizable Rules**: Configure severity levels and ignore patterns

## Installation

### Quick Start (Recommended)
```bash
# Run directly with npx (no installation needed)
npx design-agent

# Run with options
npx design-agent --sarif --suggest
```

### Global Installation
```bash
# Install globally
npm install -g design-agent

# Then run anywhere
design-agent --help
```

### Local Installation
```bash
# Install in project
npm install design-agent

# Run with npx
npx design-agent
```

## Quick Start

### Automatic Setup
```bash
# Run the setup script for your project
curl -fsSL https://raw.githubusercontent.com/ollyaston/design-agent/main/setup-project.sh | bash
```

### Manual Setup
```bash
# Detect your project environment
npx design-agent --detect

# Run a full scan
design-agent

# Run delta scan (only changed files)
design-agent --delta

# Generate SARIF output
design-agent --sarif

# Include suggested changes
design-agent --suggest
```

## Framework Integration

### React/Next.js
```bash
# Use React template
cp templates/react.config.json design-agent.config.json
npx design-agent audit --full
```

### Vue.js
```bash
# Use Vue template
cp templates/vue.config.json design-agent.config.json
npx design-agent audit --full
```

### Storybook Integration
```bash
# Build Storybook first
npm run build-storybook

# Then run design agent
npx design-agent audit --full

# Use custom config
design-agent --config my-config.json
```

## Configuration

Create a `design-agent.config.json` file in your project root:

```json
{
  "scanPaths": ["src", "components"],
  "adapters": ["tailwind", "tokens", "storybook"],
  "integrations": {
    "slackWebhook": "https://hooks.slack.com/...",
    "github": {
      "enabled": true,
      "token": "ghp_...",
      "repository": "owner/repo"
    }
  },
  "privacy": {
    "sendSourceToAI": false
  }
}
```

## CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `--config <path>` | Config file path | `design-agent.config.json` |
| `--delta` | Run delta scan only | `false` |
| `--full` | Run full scan | `true` |
| `--sarif` | Emit SARIF output | `false` |
| `--baseline <path>` | Baseline file path | `design-agent.baseline.json` |
| `--rules <path>` | Rules file path | `rules.yml` |
| `--suggest` | Include suggested changes | `false` |
| `--help, -h` | Show help | - |
| `--version, -v` | Show version | - |

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `SLACK_WEBHOOK_URL` | Slack webhook for notifications | No |
| `ANTHROPIC_API_KEY` | Claude API key for AI summaries | No |
| `GITHUB_SERVER_URL` | GitHub server URL (for CI links) | No |
| `GITHUB_REPOSITORY` | GitHub repository (for CI links) | No |
| `GITHUB_RUN_ID` | GitHub run ID (for CI links) | No |

## Supported Platforms

### Design Tools
- **Figma**: Design specifications and links
- **Sketch**: Design files and symbols
- **Adobe XD**: Design prototypes
- **Canva**: Design templates

### Development Platforms
- **Tailwind CSS**: Theme tokens and utilities
- **Design Tokens**: JSON-based token systems
- **Storybook**: Component documentation
- **React/Next.js**: Component libraries
- **Vue/Nuxt**: Component frameworks
- **Svelte**: Component systems

### File Formats
- **JavaScript/TypeScript**: `.js`, `.jsx`, `.ts`, `.tsx`
- **Vue**: `.vue`
- **Svelte**: `.svelte`
- **CSS**: `.css`, `.scss`, `.less`
- **HTML**: `.html`
- **JSON**: `.json` (design tokens)

## Adapters

### Tailwind CSS
Scans `tailwind.config.js` for theme tokens and detects hardcoded values:

```javascript
// Detects hardcoded colors
<div className="bg-[#ff0000]">  // ❌ Should use theme color
<div className="bg-red-500">    // ✅ Uses theme token
```

### Design Tokens
Scans JSON token files for design system compliance:

```json
{
  "colors": {
    "primary": "#007bff",
    "secondary": "#6c757d"
  }
}
```

### Storybook
Analyzes Storybook stories for design consistency:

```javascript
export const Default = {
  args: {
    color: '#ff0000'  // ❌ Should use design token
  }
};
```

## CI/CD Integration

### GitHub Actions

```yaml
name: Design Review
on: [push, pull_request]

jobs:
  design-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install -g design-agent
      - run: design-agent --sarif
      - uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: design-audit.sarif
```

### GitLab CI

```yaml
design-review:
  stage: test
  image: node:20
  script:
    - npm install -g design-agent
    - design-agent --sarif
  artifacts:
    reports:
      codequality: design-audit.sarif
```

## Slack Integration

Set up a Slack webhook and configure notifications:

```bash
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
design-agent
```

The tool will post a Block Kit summary with:
- Issue count by severity
- Top issues with details
- Links to full reports
- Action buttons for GitHub Actions

## Claude AI Integration

Get AI-powered summaries of your design issues:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
design-agent
```

Claude will analyze your findings and provide:
- Top 5 most important fixes
- Prioritized recommendations
- Context-aware suggestions

## Output Formats

### Markdown Report
- `design-audit-report.md` - Human-readable report
- Includes issue details, suggestions, and summaries

### JSON Report
- `design-audit.json` - Machine-readable data
- Includes metadata, findings, and statistics

### SARIF Report
- `design-audit.sarif` - Standard format for CI/CD
- Compatible with GitHub Security, GitLab, and other tools

## Examples

### Basic Usage
```bash
# Scan current directory
design-agent

# Scan specific paths
design-agent --config custom.json

# Generate all outputs
design-agent --sarif --suggest
```

### Advanced Usage
```bash
# Delta scan with custom baseline
design-agent --delta --baseline my-baseline.json

# Custom rules and suggestions
design-agent --rules custom-rules.yml --suggest

# Full scan with all integrations
SLACK_WEBHOOK_URL="..." ANTHROPIC_API_KEY="..." design-agent
```

### Configuration Examples

#### Tailwind Project
```json
{
  "scanPaths": ["src", "components"],
  "adapters": ["tailwind"],
  "adapters": {
    "tailwind": {
      "configPath": "tailwind.config.js"
    }
  }
}
```

#### Design System Project
```json
{
  "scanPaths": ["packages", "apps"],
  "adapters": ["tokens", "storybook"],
  "adapters": {
    "tokens": {
      "paths": ["tokens/**/*.json"]
    },
    "storybook": {
      "storiesPath": "storybook-static/stories.json"
    }
  }
}
```

## Troubleshooting

### Common Issues

1. **No findings detected**
   - Check if files are in scan paths
   - Verify file extensions are supported
   - Check ignore patterns

2. **Slack notifications not working**
   - Verify webhook URL is correct
   - Check Slack app permissions
   - Test webhook manually

3. **Claude summaries not generated**
   - Verify API key is set
   - Check API key permissions
   - Ensure privacy settings allow AI access

### Debug Mode

```bash
# Enable debug logging
DEBUG=design-agent design-agent

# Verbose output
design-agent --verbose
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](https://github.com/ollyaston/design-agent#readme)
- 🐛 [Issues](https://github.com/ollyaston/design-agent/issues)
- 💬 [Discussions](https://github.com/ollyaston/design-agent/discussions)