io.github.Maher-Reven/asdesigned

asdesigned

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.

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.

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:

{
  "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 — 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 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 explores similar ground with pixel + element diffing and a viewer. asdesigned is deliberately smaller — one verb, agent-first, 23 kB.

License

MIT