# 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.2 — early, usable.** Figma → spec, DOM → spec, diff, terminal + HTML report, MCP server,
interaction states. One viewport per run — see [what it doesn't cover](#what-it-checks--and-what-it-doesnt).

## 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`.
All three understand states: `compare_design` takes `states: ["default","hover","focus"]`, `inspect_element` takes a
single `state`, and `inspect_figma` takes `variants: true` to list what a component set designs.

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 … --states hover,focus  # interaction states
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 http://localhost:3000 --selector .btn --state hover   # one rendered state
asdesigned inspect <figma-url> --variants                                # what states are designed
```

### Interaction states

`--states hover,focus,active,disabled` (or `--states all`) compares each state as its own section.

The rendered side forces the matching pseudo-class before reading computed styles — `:focus` and
`:focus-visible` together, so modern focus rings aren't missed. The design side comes from the Figma
**component set's variants**: `State=Hover`, `State=Focused`, and the other spellings designers use
(`Pressed`, `Rest`, `Inactive`) all resolve. Point at the set or at any variant inside it; asdesigned
follows `componentSetId` to find the siblings.

```
Button / Primary  3 variants  1:10

default  1 drift  figma  State=Default  1:11
  border
    ✗ color          design #1d4ed8 → rendered #2563eb (Δ29.43)
  1 drift · 20 match

hover    no drift  figma  State=Hover  1:12
  0 drift · 21 match

focus    skipped  "Button / Primary" has no focus variant (it defines: default, hover) — nothing to compare against

1 drift · 41 match · 2 states compared · 1 skipped
FAIL
```

A state the design doesn't define is **skipped, not failed** — asdesigned won't invent an expected
value. That skip is itself worth reading: no `Focused` variant means the focus ring was never
designed, which is a gap in the design file rather than a bug in the code. If *every* requested state
is undesigned the run reports `NOTHING COMPARED` and exits non-zero, so a states check can't
silently pass by checking nothing.

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.

Interaction states reuse all of that unchanged: one state is one spec pair, so `diff` never had to learn about them.

- `src/spec.ts` — the shared format
- `src/diff.ts` — the comparison
- `src/states.ts` — state vocabulary and Figma variant→state matching
- `src/compare.ts` — one comparison per state, and what to say when a state isn't designed
- `src/readers/figma.ts` — Figma REST → spec, including component-set variants
- `src/readers/dom.ts` — Playwright computed styles → spec, with pseudo-classes forced via CDP
- `src/report.ts`, `src/report-html.ts` — output

## What it checks — and what it doesn't

asdesigned compares one design node against one rendered element, at one viewport, across the UI states you ask for.
That covers the drift that shows up most: padding, sizing, colors, and inherited-font mistakes like the Arial fallback
above — plus hover, focus, active and disabled via [`--states`](#interaction-states).

Interaction states come with one requirement worth stating plainly: **the design has to define them as variants.**
A component set with `State=Hover` resolves; a flat frame, or a file where hover only exists as a prototype
interaction, gives asdesigned nothing to compare and the state is skipped. `inspect <figma-url> --variants` tells you
which states a component actually designs before you check them.

Not covered:

- **Reflow.** One run renders at one viewport — `--viewport WxH`, 1280×800 by default. Checking a component across
  breakpoints means running `compare` once per breakpoint, each against the frame the designer drew for it. There's no
  single command that sweeps them.
- **Motion.** Transition duration and easing aren't compared, so a state's *end* values are checked but not how it
  gets there.
- **Anything that isn't a computed style.** Layout relative to siblings, content, and behaviour are all out of scope.

And one boundary that isn't a roadmap item: **between designed breakpoints there is no design truth.** If the file has a
768 frame and a 1280 frame, nothing in it specifies 900px. asdesigned can tell you a component drifted *at* a width
someone designed — never *between* two of them. No tool that treats the design as the source of truth can.

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