asdesigned

# asdesigned

[![npm](https://img.shields.io/npm/v/asdesigned?color=2563eb)](https://www.npmjs.com/package/asdesigned)
[![CI](https://github.com/Maher-Reven/asdesigned/actions/workflows/ci.yml/badge.svg)](https://github.com/Maher-Reven/asdesigned/actions/workflows/ci.yml)
[![MIT](https://img.shields.io/badge/license-MIT-black)](LICENSE)

Is it as designed? Diff a rendered UI component against its Figma source and see exactly what drifted.
Built for coding agents: give Claude Code or Cursor the tool and they can check their own work against the design.

<!-- demo gif: run `vhs demo/demo.tape` and commit demo/asdesigned.gif -->
![asdesigned demo](demo/asdesigned.gif)

```
asdesigned compare https://www.figma.com/design/<key>/<file>?node-id=12-345 \
      --url http://localhost:3000 --selector .btn-primary
```

```
design   figma  Button / Primary  1:4
rendered dom  <button class="btn-primary">  .btn-primary

box
  ✗ width          design 120px → rendered 112px (−8px)
padding
  ✗ left           design 16px → rendered 12px (−4px)
  ✗ right          design 16px → rendered 12px (−4px)
border
  ✗ color          design #1d4ed8 → rendered #2563eb (Δ29.43)
typography
  ✗ fontFamily     design "Inter" → rendered "Arial"
  ✗ fontWeight     design 600 → rendered 500 (−100)

6 drift · 20 match
FAIL  (tolerance ±1px, color Δ≤4)
```

That output is real — `examples/button.html` against a real Figma component. Five of those six were planted.
The sixth wasn't: `<button>` elements don't inherit `font-family`, so the page quietly fell back to Arial.
Nobody sees that in a screenshot review. The diff does.

Figma gives you the intent. The browser gives you the reality. asdesigned compares the two — and your coding agent can call it to check its own work.

**Status: v0.1 — early, usable.** Figma → spec, DOM → spec, diff, terminal + HTML report, MCP server.

## Install

```
npx asdesigned --help            # no install
npm i -g asdesigned              # or install the `asdesigned` command globally
npx playwright install chromium   # one-time: the browser used to render pages
```

Set `FIGMA_TOKEN` (a Figma personal access token with *file content: read*) in your environment or a `.env` file.

## Use it from an agent (MCP)

asdesigned ships an MCP server so Claude Code, Cursor, and other MCP clients can call it directly.
Tools: `compare_design`, `inspect_element`, `inspect_figma`.

Claude Code — `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "asdesigned": {
      "command": "npx",
      "args": ["-y", "asdesigned", "asdesigned-mcp"],
      "env": { "FIGMA_TOKEN": "figd_…" }
    }
  }
}
```

Cursor — `.cursor/mcp.json`, same shape.

A skill file describing when and how an agent should reach for the tool lives in
[`skills/asdesigned/SKILL.md`](skills/asdesigned/SKILL.md) — drop it into your agent's skills folder.

## Use it from the terminal

```
asdesigned compare <figma-url> --url http://localhost:3000 --selector .btn-primary
asdesigned compare <figma-url> --url … --selector … --html report.html   # self-contained visual report
asdesigned compare <figma-url> --url … --selector … --json               # for CI / scripts
asdesigned inspect http://localhost:3000 --selector .btn-primary
asdesigned inspect <figma-url>
```

Exit code is `1` when drift is found, so `compare` works as a CI check.

## How it works

Both sides are normalized into one flat `StyleSpec` — px numbers, RGBA colors, every field optional — and a pure
diff compares them with sensible tolerances (±1px, small color distance, zero tolerance on font weight).
Fields missing on one side are reported but don't fail the run; only real drift does.

- `src/spec.ts` — the shared format
- `src/diff.ts` — the comparison
- `src/readers/figma.ts` — Figma REST → spec
- `src/readers/dom.ts` — Playwright computed styles → spec
- `src/report.ts`, `src/report-html.ts` — output

## Development

```
npm install
npm test
npm run build
node dist/cli.js --help
```

`ASDESIGNED_BROWSER=/path/to/chrome` uses an existing Chrome/Chromium instead of Playwright's download.

## How it relates to other tools

- **Figma's MCP server** gives agents the design. **Chrome DevTools MCP** gives agents the browser. asdesigned is the
  missing verb between them: *compare*.
- **Visual regression tools** (Percy, Chromatic, pixel diffs) compare screenshots of your app to earlier screenshots of
  your app. asdesigned compares your app to the *design*, and reports properties, not pixels — so the result is a fix,
  not a heatmap.
- [`design-drift`](https://github.com/ehdrms785/design-drift) explores similar ground with pixel + element diffing and a
  viewer. asdesigned is deliberately smaller — one verb, agent-first, 23 kB.

## License

MIT