Skip to content

vcyvox/driftwatch

BranchesTags

Repository files navigation

DriftwatchJS 🎯

Catch design drift before your users do.
Compare your live UI against Figma — automatically.

npm install -g driftwatchjs

npm version License: MIT Node.js

The Problem

Your designer hands off a beautiful Figma file. Your dev team implements it pixel-perfect. Three months later — after dozens of features, hotfixes, and "quick tweaks" — your live UI has silently drifted from the design. Wrong font sizes. Slightly off colors. Button padding that no longer matches. Nobody caught it.

DriftwatchJS automates this review. It fetches your Figma specs, visits your live UI with a real browser, and tells you exactly what's different — with a beautiful report.

How It Works

1. Tag your components     →   <button data-driftwatch="Sign In Button">
2. Run driftwatchjs check  →   Figma API + Playwright capture + CSS diff
3. Open the report         →   drift-reports/drift-report.html

That's it. No screenshots. No pixel-diffing. Pure CSS property comparison — so it works at every breakpoint and is immune to anti-aliasing noise.

Quick Start

1. Install

npm install -g driftwatchjs
# Playwright Chromium downloads automatically on install

2. Initialize your config

cd your-project/
driftwatchjs init
# Creates driftwatch.config.json

3. Edit your config

Open driftwatch.config.json and fill in your details:

{
  "figmaFileKey": "abc123XYZ",
  "figmaToken":   "figd_your_personal_access_token",
  "figmaNodeIds": ["737:9476", "2216:6154"],
  "baseUrl":      "http://localhost:3000",
  "breakpoints":  [375, 768, 1280],
  "out":          "./drift-reports"
}

4. Tag your components

Add data-driftwatch="ComponentName" to any element you want tracked:

<!-- React / JSX -->
<Typography data-driftwatch="Login Heading" variant="h2">
  Sign in to Your Account
</Typography>

<Button data-driftwatch="Sign In Button" type="submit">
  Sign In
</Button>
<!-- Plain HTML -->
<h1 data-driftwatch="Hero Heading">Welcome</h1>
<button data-driftwatch="CTA Button">Get Started</button>

5. Run the check

driftwatchjs check
  ✓ Figma data fetched — 142 components found (via nodeIds)
  ✓ Live UI captured — 7 elements found
  ✓ Comparison complete
  ✓ Report saved to ./drift-reports/

  ────────────────────────────────────────────────────
  📊 DRIFT SUMMARY

  Drift Score:      71%
  Total Checked:   7 components
  Clean:           ✓ 5 components
  Drifted:         ✖ 2 components

  ● Critical:  2 issues
  ● Warning:   1 issue

  🔍 DRIFTED COMPONENTS

  Sign In Button
    ● color: rgb(255, 255, 255) → should be #f5f5f5
    ● fontSize: 14px → should be 16px

  Login Heading
    ● fontWeight: 600 → should be 700

Two Modes

Mode 1: Manual (Recommended for Component Testing)

Tag specific elements with data-driftwatch. You control exactly what gets compared.

{
  "mode": "manual"
}
<input data-driftwatch="Email Input" name="email" />
<input data-driftwatch="Password Input" name="password" />
<button data-driftwatch="Sign In Button">Sign In</button>

Best for: Targeted component audits, form elements, specific design system components.

Mode 2: Auto-Scan (Recommended for Full Page/Module Testing)

No need to tag anything. Driftwatch automatically scans all visible elements inside a container selector.

{
  "mode": "auto-scan",
  "selector": "#dashboard"
}

Elements are named automatically by tag + index: h1-1, button-1, input-2, etc.

Best for: Scanning entire pages, dashboards, or layout sections quickly.

Full Config Reference

{
  "figmaFileKey": "S6h31XxPKNCNSP4uLZOkiR",
  "figmaToken":   "figd_your_token_here",
  "figmaNodeIds": ["737:9476", "2216:6154"],
  "baseUrl":      "http://localhost:3000",
  "breakpoints":  [375, 768, 1280],
  "out":          "./drift-reports",
  "threshold":    0.05,
  "mode":         "manual",
  "selector":     null,
  "auth": {
    "loginUrl":          "http://localhost:3000/login",
    "usernameSelector":  "input[name='email']",
    "passwordSelector":  "input[name='password']",
    "submitSelector":    "button[type='submit']",
    "username":          "your-email@example.com",
    "password":          "your-password",
    "waitAfterLogin":    3000
  }
}
Field Type Required Description
figmaFileKey string ✅ Your Figma file key (from the URL: figma.com/file/{KEY}/...)
figmaToken string ✅ Figma personal access token (Settings → Personal access tokens)
figmaNodeIds string[] ⭐ Recommended Specific node IDs to fetch — faster and avoids rate limits
baseUrl string ✅ Your local dev server URL
breakpoints number[] optional Viewport widths to test (default: [1280])
out string optional Output directory for reports (default: ./drift-reports)
threshold number optional Tolerance ratio for minor differences (default: 0.05)
mode "manual" | "auto-scan" optional Element capture mode (default: "manual")
selector string auto-scan only CSS selector for the auto-scan container (e.g. "main", "#app")
auth object optional Auth config for login-protected pages (see below)

Auth Config — Protected Pages

If your app requires login, add the auth block:

{
  "auth": {
    "loginUrl":         "http://localhost:3000/login",
    "usernameSelector": "input[name='email']",
    "passwordSelector": "input[name='password']",
    "submitSelector":   "button[type='submit']",
    "username":         "test@example.com",
    "password":         "testPassword123",
    "waitAfterLogin":   3000
  }
}

Driftwatch will:

  1. Navigate to loginUrl
  2. Fill in credentials
  3. Click the submit button
  4. Wait waitAfterLogin ms for the redirect
  5. Verify the login succeeded (if still on the login page, throws a clear error)
  6. Then proceed to capture your target page using the authenticated session

Remove the auth block entirely if your target page doesn't require login.

Figma Node IDs — Avoid Rate Limits

The Figma /files endpoint is aggressively rate-limited. If you hit 429 Too Many Requests, the fix is simple: add figmaNodeIds to your config.

How to find node IDs:

  1. Open your Figma file
  2. Right-click a frame or component → Copy link
  3. The link looks like: ...?node-id=2216-6154
  4. Convert the dash to a colon: 2216:6154
{
  "figmaNodeIds": ["2216:6154", "737:9476"]
}

Driftwatch will batch all IDs into a single API call instead of fetching the entire file — much faster and far less likely to be rate-limited.

CLI Reference

# Run drift check (uses ./driftwatch.config.json)
driftwatchjs check

# Skip Figma API — capture and report live styles only
driftwatchjs check --skip-figma

# Use a different config file
driftwatchjs check --config ./my-config.json

# Override the target URL
driftwatchjs check --url http://localhost:3001

# Override the output directory
driftwatchjs check --out ./reports

# Create a starter config
driftwatchjs init

Report Output

After every run, two files are written to ./drift-reports/ (or your configured out dir):

drift-report.html

A dark-themed, interactive HTML report with:

  • 📊 Drift score (0–100%)
  • 📸 Screenshots at each breakpoint
  • 🔍 Per-component drift cards with property-level diffs
  • 🔴 🟡 🔵 Severity badges (Critical / Warning / Info)

drift-report.json

Machine-readable JSON — perfect for CI parsing:

{
  "summary": {
    "totalComponents": 7,
    "driftedComponents": 2,
    "cleanComponents": 5,
    "driftScore": 71,
    "critical": 2,
    "warning": 1,
    "info": 0
  },
  "components": [...]
}

CI/CD Integration

DriftwatchJS exits with code 1 when critical drift is detected, code 0 when clean. Drop it into any CI pipeline:

GitHub Actions

# .github/workflows/drift.yml
name: Design Drift Check

on:
  push:
    branches: [main, staging]
  pull_request:

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install DriftwatchJS
        run: npm install -g driftwatchjs

      - name: Start dev server
        run: npm run dev &
        # Wait for server to be ready
      - run: npx wait-on http://localhost:3000

      - name: Run drift check
        run: driftwatchjs check
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}

      - name: Upload drift report
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: drift-report
          path: drift-reports/

Store your Figma token as FIGMA_TOKEN in GitHub → Settings → Secrets.

Exit Codes

Exit Code Meaning
0 ✅ No critical drift — pipeline continues
1 ❌ Critical drift detected — pipeline fails

Severity Levels

Severity Properties Impact
🔴 Critical color, fontSize, fontFamily Visible to users immediately
🟡 Warning borderRadius, padding*, fontWeight, gap Subtle layout differences
🔵 Info letterSpacing, lineHeight, opacity, width, height, borderColor, borderWidth Minor variations

Only critical drift causes a CI pipeline failure (exit 1).

Troubleshooting

429 Too Many Requests

Figma is rate-limiting your requests. Fix: Add figmaNodeIds to your config to fetch only the nodes you need instead of the entire file.

{ "figmaNodeIds": ["2216:6154", "737:9476"] }

Invalid Figma token

Your figmaToken is wrong or expired. Fix: Go to Figma → Settings → Personal access tokens → create a new token with file_content:read scope.

Login failed: still on login page

Wrong credentials or the login form selector is incorrect. Fix: Check username, password, usernameSelector, passwordSelector in your auth config. Test the selectors in your browser's DevTools.

net::ERR_CONNECTION_REFUSED

Your dev server isn't running. Fix: Start your dev server first (npm run dev), then run driftwatchjs check.

No data-driftwatch attributes found

No tagged elements on the page. Fix: Either add data-driftwatch="Name" attributes to your components, or switch to "mode": "auto-scan" in your config.

Failed to generate report

Output directory can't be written. Fix: Check write permissions on the out directory. Try "out": "./drift-reports".

Monorepo Structure

driftwatchjs/
├── packages/
│   ├── cli/
│   │   ├── bin/driftwatch.js   → CLI entry point (commander.js)
│   │   └── src/capture.js      → Playwright DOM capture (manual + auto-scan)
│   ├── core/
│   │   └── src/index.js        → Figma API + CSS comparator + report generator
│   ├── reporter/
│   │   └── src/                → HTML + JSON report templates
│   └── extension/              → Browser extension (coming soon)
├── scripts/
│   └── demo.js                 → End-to-end demo runner
├── driftwatch.config.example.json
└── README.md

Roadmap

  • 🔌 Browser extension — tag elements visually, no code changes needed
  • 📱 Mobile viewport testing — test multiple breakpoints in parallel
  • 🎨 Color tolerance — delta-E color comparison for near-match colors
  • 🧩 Storybook integration — compare components directly against Storybook stories
  • 📧 Slack / Teams notifications — drift alerts in your team chat
  • 🌐 Cloud hosted reports — share drift reports via URL

Contributing

Found a bug? Have an idea? PRs and issues are very welcome.

git clone https://github.com/vcyvox/driftwatch.git
cd driftwatch
npm install
npm run check   # runs the CLI against the example config

Please follow the existing code style (ESM, no TypeScript, JSDoc comments).

License

MIT © Vicky

About

Figma → Live UI Drift Detector. Catch visual regressions before your users do.

Topics

cli open-source frontend devtools figma playwright design-drift

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages