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)

# Run directly with npx (no installation needed)
npx design-agent

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

Global Installation

# Install globally
npm install -g design-agent

# Then run anywhere
design-agent --help

Local Installation

# Install in project
npm install design-agent

# Run with npx
npx design-agent

Quick Start

Automatic Setup

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

Manual Setup

# 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

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

Vue.js

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

Storybook Integration

# 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:

{
  "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:

// 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:

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

Storybook

Analyzes Storybook stories for design consistency:

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

CI/CD Integration

GitHub Actions

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

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:

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:

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

# Scan current directory
design-agent

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

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

Advanced Usage

# 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

{
  "scanPaths": ["src", "components"],
  "adapters": ["tailwind"],
  "adapters": {
    "tailwind": {
      "configPath": "tailwind.config.js"
    }
  }
}

Design System Project

{
  "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

# 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 file for details.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions