Monitoring Design Drift

Track how your site’s design changes over time and catch unintended modifications before they reach production.

What is Design Drift?

Design drift happens when:

• A developer changes a color that should match the design system
• A CSS update unintentionally affects other components
• Third-party scripts inject styles
• Responsive breakpoints break existing layouts

StyleGrab detects these changes by comparing snapshots of extracted design tokens.

Setting Up Monitoring

1. Create a Scheduled Extraction

Set up a cron job or scheduled task to extract tokens regularly:

# Daily extraction at midnight UTC
0 0 * * * curl -X POST https://api.stylegrab.dev/api/extractions \
  -H "Authorization: Bearer $STYLEGRAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com"}'

2. Subscribe to Diff Events

Register a webhook to receive notifications when changes are detected:

curl -X POST https://api.stylegrab.dev/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/design-drift",
    "events": ["diff.detected"]
  }'

3. Review Changes

When drift is detected, you’ll receive:

{
  "event": "diff.detected",
  "data": {
    "extraction_id": "ext_abc123",
    "url": "https://yoursite.com",
    "from_snapshot": "snap_abc123",
    "to_snapshot": "snap_xyz789",
    "changes": {
      "colors_changed": 2,
      "typography_changed": 0,
      "spacing_changed": 1,
      "total_changes": 3
    }
  }
}

Get the full diff:

curl "https://api.stylegrab.dev/api/extractions/ext_abc123/diff?from=snap_abc123&to=snap_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY"

Setting Thresholds

Not all changes are problems. Set up smart alerting:

async function handleDiffDetected(data) {
  const { changes } = data;
  
  // Only alert on significant changes
  if (changes.total_changes < 3) {
    console.log('Minor change, skipping alert');
    return;
  }
  
  // High priority: color changes
  if (changes.colors_changed > 0) {
    await sendSlackAlert('🚨 Color change detected', 'high');
  }
  
  // Medium priority: typography
  if (changes.typography_changed > 0) {
    await sendSlackAlert('⚠️ Typography change detected', 'medium');
  }
  
  // Low priority: spacing only
  if (changes.colors_changed === 0 && changes.typography_changed === 0) {
    await sendSlackAlert('ℹ️ Spacing change detected', 'low');
  }
}

Comparing Environments

Monitor differences between environments:

#!/bin/bash
# compare-envs.sh

# Extract from staging
STAGING=$(curl -s -X POST https://api.stylegrab.dev/api/extractions \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"url": "https://staging.yoursite.com"}' | jq -r '.id')

# Extract from production
PROD=$(curl -s -X POST https://api.stylegrab.dev/api/extractions \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"url": "https://yoursite.com"}' | jq -r '.id')

# Wait for completion
sleep 10

# Get latest snapshots
STAGING_SNAP=$(curl -s "https://api.stylegrab.dev/api/extractions/$STAGING/snapshots" \
  -H "Authorization: Bearer $API_KEY" | jq -r '.data[0].id')
  
PROD_SNAP=$(curl -s "https://api.stylegrab.dev/api/extractions/$PROD/snapshots" \
  -H "Authorization: Bearer $API_KEY" | jq -r '.data[0].id')

# Compare
curl "https://api.stylegrab.dev/api/extractions/$STAGING/diff?from=$PROD_SNAP&to=$STAGING_SNAP" \
  -H "Authorization: Bearer $API_KEY"

Best Practices

1. Baseline Your Design System

Create an extraction from your design system documentation or Storybook:

curl -X POST https://api.stylegrab.dev/api/extractions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"url": "https://design.yoursite.com"}'

Compare production against this baseline to find inconsistencies.

2. Monitor Critical Pages

Focus monitoring on high-value pages:

• Homepage
• Pricing page
• Checkout flow
• Login/signup

3. Ignore Expected Changes

Some changes are intentional (A/B tests, promotions). Track these separately:

# Tag extractions for context
curl -X POST https://api.stylegrab.dev/api/extractions \
  -d '{
    "url": "https://yoursite.com",
    "metadata": {
      "context": "holiday-promo",
      "expected_changes": ["colors"]
    }
  }'

4. Set Up Escalation

// Escalate if changes persist across multiple snapshots
const recentDiffs = await getRecentDiffs(extractionId, { limit: 3 });

if (recentDiffs.every(d => d.changes.colors_changed > 0)) {
  await escalateToDesignTeam('Persistent color drift detected');
}

Next Steps

• Integrate with CI/CD to block deploys with design drift
• Webhook setup for detailed integration options