---
name: design-compliance-bot
description: Automated design system compliance checking with Figma integration. Use when you need to (1) check design files against brand guidelines, (2) enforce design consistency across Figma projects, (3) detect violations in colors, typography, spacing, or border-radius, (4) generate compliance reports, (5) set up scheduled design audits, (6) send notifications about design violations to Slack/Discord, or (7) automatically create GitHub issues for compliance failures.
---

# Design Compliance Bot

Automated design system compliance checking for Figma files with rule engine, violation detection, scheduled audits, and notification integration.

## Quick Start

```bash
# Check a Figma file against design rules
design-compliance check --file FILE_KEY --rules design-rules.json

# Generate HTML/PDF report
design-compliance report --file FILE_KEY --output report.html

# Start scheduled checks (cron)
design-compliance schedule --cron "0 9 * * *" --rules design-rules.json

# Send violations to Slack
design-compliance check --file FILE_KEY --slack-webhook URL
```

## Configuration

Create a `design-rules.json` file with your brand guidelines:

```json
{
  "colors": {
    "primary": ["#FF6B35", "#F7931E"],
    "secondary": ["#4ECDC4", "#44A08D"],
    "neutral": ["#2C3E50", "#95A5A6", "#ECF0F1"],
    "allowUnknown": false
  },
  "typography": {
    "families": ["Inter", "Roboto", "SF Pro"],
    "sizes": [12, 14, 16, 18, 24, 32, 48, 64],
    "weights": [400, 500, 600, 700]
  },
  "spacing": {
    "values": [4, 8, 12, 16, 24, 32, 48, 64, 96],
    "tolerance": 2
  },
  "borderRadius": {
    "values": [0, 4, 8, 16, 24],
    "tolerance": 1
  },
  "notifications": {
    "slack": {
      "webhook": "https://hooks.slack.com/...",
      "channel": "#design-violations"
    },
    "discord": {
      "webhook": "https://discord.com/api/webhooks/..."
    }
  },
  "github": {
    "enabled": true,
    "repo": "org/design-system",
    "labels": ["design-compliance", "needs-review"]
  }
}
```

## Environment Variables

Create a `.env` file:

```
FIGMA_ACCESS_TOKEN=your_figma_token
GITHUB_TOKEN=your_github_token
SLACK_WEBHOOK_URL=your_slack_webhook
DISCORD_WEBHOOK_URL=your_discord_webhook
```

## Programmatic Usage

```typescript
import { DesignComplianceBot } from '@openclaw/design-compliance-bot';

const bot = new DesignComplianceBot({
  figmaToken: process.env.FIGMA_ACCESS_TOKEN,
  rules: './design-rules.json'
});

// Check a file
const violations = await bot.check('FILE_KEY');

// Generate report
const report = await bot.generateReport('FILE_KEY', {
  format: 'html',
  output: 'report.html'
});

// Schedule checks
bot.schedule('0 9 * * *', async () => {
  const files = ['FILE_KEY_1', 'FILE_KEY_2'];
  for (const file of files) {
    await bot.check(file);
  }
});
```

## Violation Types

- **Color violations**: Colors not in the approved palette
- **Typography violations**: Unapproved fonts, sizes, or weights
- **Spacing violations**: Padding/margins outside the spacing scale
- **Border radius violations**: Corner radius values not in the system

## Reports

Reports include:

- Total violations by type
- Affected frames and components
- Visual comparison (expected vs actual)
- Severity levels (critical, warning, info)
- Suggested fixes
- Historical trends

## Cron Scheduling

```bash
# Daily at 9 AM
design-compliance schedule --cron "0 9 * * *"

# Every 6 hours
design-compliance schedule --cron "0 */6 * * *"

# Weekdays at 10 AM
design-compliance schedule --cron "0 10 * * 1-5"
```

## GitHub Integration

When enabled, violations automatically create GitHub issues with:

- Description of the violation
- Screenshot of the affected element
- Suggested fix
- Links to design system documentation
- Auto-assignment to design team

## Notification Format

Slack/Discord notifications include:

- File name and link
- Number of violations by type
- Severity summary
- Quick action buttons
- Violation trends (↑↓)

## Advanced Features

### Custom Rules

Extend the rule engine with custom validators:

```typescript
bot.addRule('custom-shadow', {
  validate: (node) => {
    const shadow = node.effects?.find(e => e.type === 'DROP_SHADOW');
    return shadow?.color?.a <= 0.3; // Max 30% opacity
  },
  message: 'Shadow opacity should be ≤30%'
});
```

### Ignore Patterns

Skip certain frames or components:

```json
{
  "ignore": {
    "frames": ["*-WIP", "*-Draft"],
    "components": ["Experimental/*"]
  }
}
```

### Severity Levels

Configure violation severity:

```json
{
  "severity": {
    "colors": "critical",
    "typography.size": "warning",
    "spacing": "info"
  }
}
```

## Integration with OpenClaw

Use with OpenClaw automation:

```typescript
// In your OpenClaw workflow
const { message } = require('openclaw');

async function checkDesignCompliance() {
  const violations = await bot.check(figmaFileKey);
  
  if (violations.length > 0) {
    await message.send({
      target: 'design-team',
      message: `⚠️ Found ${violations.length} design violations!`,
      action: 'send'
    });
  }
}
```

## References

- See [FIGMA_API.md](references/FIGMA_API.md) for Figma API details
- See [RULES_ENGINE.md](references/RULES_ENGINE.md) for rule configuration
- See [EXAMPLES.md](references/EXAMPLES.md) for real-world use cases