figma-pixel-kit 0.9.0

package/.claude/skills/figma-pixel-perfect/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: figma-pixel-perfect
+description: Implements read-only Figma screens from figma-pixel-kit output with visual regression validation.
+---
+
+# Figma Pixel Perfect Skill
+
+Use this skill when a task references a `design-ai/<screen-id>/` folder created by Figma Pixel Kit.
+
+## Required behavior
+
+1. Read `prompt-for-claude.md` first.
+2. Use `reference.png` as visual truth.
+3. Use `inventory.md` as the complete checklist.
+4. Use `spec.json` for exact bounds, text and style data.
+5. Use `index.html` only as a pixel preview, not production code.
+6. Do not skip visible elements.
+7. Do not redesign.
+8. Reuse existing project components.
+9. Add `data-figma-screen` to the implemented root.
+10. After coding, run visual compare and fix from `visual-report/fix-prompt.md`.
+
+## Final response checklist
+
+Always report:
+
+- Files changed
+- Components reused
+- New components created, if any
+- Visual compare result
+- Missing/approximate elements, if any

package/.env.example

@@ -0,0 +1,3 @@
+# Optional. You can also save your token once with:
+# figma-pixel-kit token "figd_xxxxxxxxxxxxxxxxx"
+FIGMA_TOKEN=

package/CLAUDE.md

@@ -0,0 +1,32 @@
+# Figma Pixel Kit Project Rules
+
+Use these rules when implementing designs from `design-ai/<screen-id>/`.
+
+## Source priority
+
+1. `reference.png` is the visual truth.
+2. `inventory.md` is the required element checklist.
+3. `spec.json` contains exact bounds, text and style data.
+4. `index.html` is only a pixel-preview reference, not production code.
+
+## Implementation rules
+
+- Do not implement directly from a raw Figma URL.
+- Do not redesign.
+- Do not simplify the UI.
+- Do not skip visible elements.
+- Reuse existing project components before creating new primitives.
+- Work section by section.
+- Add `data-figma-screen="<node-id>"` to the implemented root element.
+- After implementation, run `figma-pixel-kit compare`.
+- Fix visual differences using `visual-report/fix-prompt.md`.
+
+## Final response format
+
+Always report:
+
+- Files changed
+- Components reused
+- New components created, if any
+- Visual diff result
+- Missing or approximate elements, if any

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ozan Zengin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,317 @@
+# figma-pixel-kit
+
+[![npm version](https://img.shields.io/npm/v/figma-pixel-kit.svg)](https://www.npmjs.com/package/figma-pixel-kit)
+[![CI](https://github.com/ozanzeng/figma-pixel-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/ozanzeng/figma-pixel-kit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node](https://img.shields.io/node/v/figma-pixel-kit.svg)](https://nodejs.org)
+
+Figma selected node -> HTML preview + implementation inventory + Claude prompt + Playwright/pixelmatch visual diff.
+
+This package is designed for frontend developers who want to give an AI assistant a clean implementation package instead of a raw Figma link.
+
+> **Validated on a real 18-screen board — every auto-verifiable screen matched the Figma render at ≤ 2.9 % pixel diff.** See the [real-world example](#real-world-example).
+
+## Why this exists
+
+Handing a raw Figma link to an AI assistant (or another developer) is a recipe for guesswork. The link alone carries no reliable measurements, so spacing, font sizes and dimensions get approximated; icons that already exist in a library (lucide, font-awesome, …) get hand-redrawn as inline SVG; shared chrome like the sidebar, header and breadcrumb gets re-coded on every screen; and — worst of all — there is no objective way to tell whether the result actually matches the design. The result is screens that look "roughly right" and a slow, subjective back-and-forth review.
+
+figma-pixel-kit was built to remove that guesswork. It turns a selected Figma node into a **clean, structured implementation package** — exact bounds and styles, parsed Auto Layout, a reusable-component map, detected library icons, downloaded image assets, and a ready-to-paste AI prompt — and then **closes the loop** with a pixel-level visual diff against the real Figma render, so "does it match?" becomes a number instead of an opinion.
+
+## Why use it
+
+- **Pixel-accurate inputs, not guesses.** Every element ships with exact bounds, colors, typography and parsed Auto Layout (paste-ready flexbox) — the AI implements real values instead of eyeballing a screenshot.
+- **No redrawn icons.** Library icons (lucide / font-awesome / feather / heroicons / material / phosphor / tabler) are detected and mapped to their package import; real raster assets are downloaded to `assets/`. Nothing is hand-traced as inline SVG.
+- **Build shared components once.** Component instances are grouped across the whole board with a prop-schema (TypeScript interface), so the sidebar/header/breadcrumb are built once and reused — never re-coded per screen.
+- **`reference.png` is the source of truth.** The actual Figma render is exported at 2x; the node→div preview is only a diagnostic. You always have an objective target.
+- **Verification built in.** `compare` runs Playwright + pixelmatch at the same scale as the reference, reports a diff ratio and a hotspot map, and produces a `fix-prompt.md` you can feed straight back to the AI for targeted fixes.
+- **AI- and editor-agnostic.** Works with Claude / Claude Code / Copilot Chat / any assistant, and drops VS Code + Claude skill helpers into your project automatically. No Cursor required.
+- **Zero-setup auth.** A Figma Personal Access Token is all you need to start (OAuth browser sign-in is also supported).
+
+## Results
+
+In practice this collapses the design-to-code loop from "implement → subjective review → repeat" into "implement from exact specs → measure the diff → fix only the hotspots." The AI starts much closer to pixel-perfect (real spacing, real icons, reused components) and every remaining gap is a measured number, not a debate.
+
+Verified end-to-end on a real 5-screen board: **448 component instances reduced to 65 reusable components** with generated prop APIs, **120/241 elements with parsed Auto Layout**, reference PNGs exported at 2x, and pixel diffs that line up 1:1 with the app.
+
+## Real-world example
+
+A worked example on a real **18-screen board** — a multi-step wizard flow (upload → preview → processing → result) — taken from a single Figma node to a pixel-verified implementation in an existing React + Redux app.
+
+**1. Extract the whole board** — one command auto-detects the screens:
+
+```bash
+figma-pixel-kit "https://www.figma.com/design/FILE_KEY/App?node-id=2188-2868"
+# → design-ai/<board>/ with implementation-plan.md, component-library.md,
+#   and one package per detected screen under screens/
+```
+
+**2. Implement screen by screen** — hand the assistant each screen's prompt:
+
+```txt
+design-ai/<board>/screens/<screen-id>/prompt-for-claude.md
+```
+
+**3. Verify each screen** against the Figma render:
+
+```bash
+figma-pixel-kit compare "<screen-id>" \
+  --url "http://localhost:5173" \
+  --selector "[data-figma-screen='<node-id>']"
+```
+
+**What it produced.** Of the **8 screens that are directly auto-verifiable**, **all 8 pass** pixel diff at **≤ 2.9 %** — 6 full-text PASS and 2 ignore-text PASS (the residual delta is font rendering + mock data, not layout or color). The other 10 screens were **correctly classified by their app-side blocker** (local tab state, data fixtures, feature flags) rather than any defect in the generated package — and the kit even **flagged one screen the design defines but the codebase never implemented**.
+
+| # | Screen (UI pattern) | Result |
+|----|---------------------|--------|
+| 01 | Results grid | ✅ Aligned — **PASS @1.9 %** (ignore-text); cards rebuilt |
+| 02 | Resolution modal — primary tab | ✅ Modal chrome fixed (counter, footer, typography) |
+| 03 | Resolution modal — all-separate state | ✅ "All separate" box → neutral grey |
+| 04 | Resolution modal — mixed selection | ✅ Shared-component variant |
+| 05 | Shared-items panel | ✅ Item card rebuilt (pill, chip, status icons) |
+| 06 | File upload — empty dropzone | ✅ Dropzone 273px; ⚠️ one tab is feature-gated |
+| 07 | List table | ⚠️ Chrome aligned; table is data-fixture-dependent |
+| 08 | Preview — full content | ✅ **PASS @2.8 %** (frame height corrected) |
+| 09 | Upload progress list | ✅ Well-built; depends on local upload state |
+| 10 | AI processing — in progress | ✅ **PASS @2.4 %** |
+| 11 | Processing complete | ✅ **PASS @2.5 %** |
+| 12 | Result — success | ✅ **PASS @2.9 %** |
+| 13 | Result — error | ✅ **PASS @2.3 %** (ignore-text); balance fixture set |
+| 14 | Cancel confirmation modal | ❌ Not in codebase — net-new screen the design defines (kit flagged the gap) |
+| 15 | Cancelled state | ✅ **PASS @2.1 %** |
+| 16 | Loading / progress | ✅ **PASS @2.1 %** |
+| 17 | Templates grid | ✅ Aligned; depends on local tab state |
+| 18 | Blank-start variant | ✅ Content = #06; global chrome not drawn by harness |
+
+**Reading the numbers**
+
+- **PASS @ X %** — pixelmatch diff ratio against the 2× Figma render; lower is closer. Every passing screen is ≤ 2.9 %.
+- **ignore-text** — text regions masked so browser-vs-Figma font rendering doesn't dominate the ratio; used where the only residual delta is type rendering or mock data.
+- **⚠️ / data-gated** — visually aligned, but the screen's content comes from app state / fixtures / feature flags, so it isn't auto-pixel-compared (a harness limitation, not a package defect).
+- **❌** — the design defines a screen with no code counterpart yet; the kit surfaced the gap.
+
+## What it generates
+
+For every selected Figma node URL, it creates:
+
+```txt
+design-ai/<screen-id>/
+  reference.png            # Figma render at 2x — the visual truth
+  figma-node.json          # raw Figma node response
+  spec.json                # exact bounds/styles + frame.scale + component instance markers
+  inventory.md             # complete element checklist (instances flagged ↻)
+  index.html               # pixel-perfect preview (embeds reference.png)
+  debug-render.html        # diagnostic node-to-div render (backgrounds + image fills)
+  styles.css               # CSS for debug-render.html
+  inspect.md               # diagnostic summary of rendered/skipped node types
+  prompt-for-claude.md     # implementation prompt for the AI assistant
+  visual-test.spec.ts      # optional Playwright snapshot template
+  component-library.md     # shared components used here (only if instances exist)
+  components.json          # structured component data (only if instances exist)
+  assets/                  # downloaded image fills (only if any)
+```
+
+After visual comparison it creates:
+
+```txt
+design-ai/<screen-id>/visual-report/
+  reference.png
+  actual.png
+  diff.png
+  report.json
+  fix-prompt.md
+```
+
+## Which file do I give to the AI?
+
+This is the whole point of the package — you hand the AI **one file**, not a raw Figma link. That file references everything else in the same folder.
+
+**Single screen** → give the assistant:
+
+```txt
+design-ai/<screen-id>/prompt-for-claude.md
+```
+
+`prompt-for-claude.md` is a complete, self-contained implementation prompt. It tells the AI to use `reference.png` as the visual truth, read measurements from `spec.json`, check every element against `inventory.md`, import the icons listed in `assets.md`, reuse the shared components in `component-library.md`, and finish with a `compare` run. All of those files live next to it in the same `<screen-id>/` folder, so the AI can open them directly.
+
+> Prompt to paste: *"Implement this screen. Read and follow `design-ai/<screen-id>/prompt-for-claude.md`. `reference.png` is the visual source of truth."*
+
+**A whole board (multiple screens)** → start with the plan, then go screen by screen:
+
+```txt
+design-ai/<board>/implementation-plan.md      # 1) read this FIRST
+design-ai/<board>/component-library.md         # 2) build shared components once (Phase 0)
+design-ai/<board>/screens/<screen-id>/prompt-for-claude.md   # 3) one screen at a time
+```
+
+`implementation-plan.md` lists the shared components to build first (so the sidebar/header/breadcrumb are written once) and then the screen order. Do **one screen per task** — don't dump all screens into a single prompt.
+
+**Fixing diffs** → after the AI implements a screen and you run `compare`, hand back:
+
+```txt
+design-ai/<screen-id>/visual-report/fix-prompt.md   # + reference.png, actual.png, diff.png
+```
+
+`fix-prompt.md` already contains the measured diff ratio and the hotspot regions, so the AI can fix only what's off instead of re-doing the screen.
+
+> Works with Claude, Claude Code, GitHub Copilot Chat, or any AI assistant. The files are plain Markdown/JSON/PNG — no special integration needed.
+
+## Local development install
+
+Until this package is published to npm, install it locally:
+
+```bash
+cd figma-pixel-kit
+npm install
+npm run install:browsers   # one-time: install the Chromium build used by compare
+npm link
+```
+
+Then go to your frontend project root and run:
+
+```bash
+figma-pixel-kit token "figd_xxxxxxxxxxxxxxxxx"
+figma-pixel-kit doctor   # optional: verify the token works against the Figma API
+```
+
+After that, normal usage is only:
+
+```bash
+figma-pixel-kit "https://www.figma.com/design/FILE_KEY/File-Name?node-id=2188-2879&m=dev"
+```
+
+## Real npx usage after npm publish
+
+After publishing the package to npm as `figma-pixel-kit`, this will work:
+
+```bash
+npx figma-pixel-kit "https://www.figma.com/design/FILE_KEY/File-Name?node-id=2188-2879&m=dev"
+```
+
+## One-time project integration
+
+The first export automatically creates safe helper files if they do not exist:
+
+```txt
+FIGMA_PIXEL_KIT.md
+.vscode/figma-pixel-kit.instructions.md
+.vscode/tasks.json or .vscode/figma-pixel-kit.tasks.example.json
+.claude/skills/figma-pixel-perfect/SKILL.md
+```
+
+You can also run it manually:
+
+```bash
+figma-pixel-kit init
+```
+
+## Visual compare
+
+After the AI implements the screen in your app, add the generated selector to the root element:
+
+```tsx
+<section data-figma-screen="2188:2879">
+  ...
+</section>
+```
+
+Run your frontend app:
+
+```bash
+npm run dev
+```
+
+Then compare:
+
+```bash
+figma-pixel-kit compare "app-1-2188-2879" \
+  --url "http://localhost:3000" \
+  --selector "[data-figma-screen='2188:2879']"
+```
+
+Give `visual-report/fix-prompt.md`, `reference.png`, `actual.png`, and `diff.png` back to the AI assistant for targeted fixes.
+
+The app is captured at the same scale `reference.png` was exported with (`spec.json` → `frame.scale`), so pixels line up 1:1. Useful extra flags:
+
+```bash
+# Ignore font/text rendering differences — diff only layout, color and spacing:
+figma-pixel-kit compare "<screen-id>" --url "http://localhost:3000" --ignore-text
+
+# Export the reference at 1x for faster CI runs (also affects compare capture scale):
+figma-pixel-kit "<figma-node-url>" --scale 1
+```
+
+## Token storage
+
+Token lookup order:
+
+1. `FIGMA_TOKEN` environment variable
+2. `.env` file in the current project
+3. `~/.figma-pixel-kit/config.json` created by `figma-pixel-kit token "figd_xxx"`
+
+Do not commit your Figma token.
+
+## VS Code workflow
+
+This package does not require Cursor. It creates VS Code helper instructions under `.vscode/` and Claude skill rules under `.claude/skills/`.
+
+Use the generated `prompt-for-claude.md` with Claude/Claude Code/GitHub Copilot Chat/any AI assistant inside VS Code.
+
+
+## v0.4 notes
+
+- `inspect` command added.
+- `index.html` is now a pixel-perfect reference preview using `reference.png`.
+- `debug-render.html` contains the experimental node-to-div HTML renderer.
+- `inspect.md` is generated after export and summarizes rendered/skipped node types.
+
+
+## v0.5 notes
+
+- `implement` command added.
+- `implement` runs export and prints a clean VS Code/Claude handoff checklist.
+- Use: `figma-pixel-kit implement "<figma-node-url>"`
+
+
+## v0.6 notes
+
+- Auto board detection added to the main command.
+- If the selected Figma node contains multiple 1440px-wide frames, the CLI treats it as a board.
+- `analyze` command added.
+- Board exports produce:
+  - `board-analysis.json`
+  - `screens.md`
+  - `implementation-plan.md`
+  - `component-library.md` and `components.json`
+  - one package per detected screen under `screens/`
+
+
+## v0.7 notes
+
+- **Pixel-perfect compare fixed.** `reference.png` is exported at 2x and `compare` now captures the app at the same `deviceScaleFactor`, so pixelmatch compares like-for-like instead of a 2x image against a 1x one. The scale is persisted in `spec.json` (`frame.scale`). Size mismatches are flagged instead of being silently padded, and hotspot coordinates are reported in logical (CSS) px.
+- **Shared component reuse.** Component instances are grouped across screens by their Figma component / variant set. Boards emit `component-library.md` + `components.json`, the implementation plan gets a "Phase 0 — build shared components first" section, and every screen's `inventory.md` / `spec.json` flags instances so the AI reuses one component instead of re-coding it per screen.
+- **Mobile / custom widths.** Board detection is no longer locked to 1440px. Use `--mobile` or `--screen-width / --width-tolerance / --min-height / --max-height` on the main/`export`/`analyze`/`implement` commands.
+- **Better debug render.** `debug-render.html` now draws container/frame background fills, strokes, and image fills (downloaded into `assets/`), and uses the root frame's fill as the page background.
+- **URLs & robustness.** Branch URLs resolve to the branch key; prototype/community URLs and node-ids in the URL fragment are handled; the Figma API retries on 429/5xx with clearer error hints; `compare` validates numeric flags, uses `--wait-until` (default `load`) with a fallback, and prints a friendly message if Chromium is missing. `doctor` is documented. Set `FIGMA_PIXEL_KIT_DEBUG=1` for stack traces.
+
+
+## v0.8 notes (from the critical-suggestions pass)
+
+- **`visual-test.spec.ts` is honest now.** A prominent header explains it is a *self-baseline* regression test (catches drift after first run) and does **not** validate against the Figma `reference.png` — use `compare` for that. Viewport + `deviceScaleFactor` match the reference scale.
+- **`compare --ignore-text`.** Masks text element regions (from `spec.json`) identically in both images before diffing, so the browser-vs-Figma font rendering mismatch no longer dominates the ratio. Trade-off: it also hides genuine text bugs, so it is opt-in and reported in `report.json` / `fix-prompt.md`.
+- **`--scale <1-4>`.** Reference export scale is now configurable and persisted; `compare` reads it. Use `--scale 1` for faster CI.
+- **Chunked board rendering.** Board screens are pre-rendered in small chunks (fewer round-trips than one-call-per-screen) while staying under Figma's per-request render-time budget — a single all-screens call returns `Render timeout, try requesting fewer or smaller images` for large 2x desktop screens. If a chunk times out it splits to single ids, and anything still missing is rendered per-screen. (Verified on a real 5-screen 1440×820 board.)
+- **Repeated-pattern detection.** `component-library.md` now lists copy-pasted blocks that repeat 3+ times but are *not* Figma components — strong candidates to turn into one reusable component.
+- **Exact-frame-width rule** added to `prompt-for-claude.md`, plus a note that preview artifacts (`index.html`, `debug-render.html`, `assets/`) must not ship to production.
+
+> Note on `/nodes` depth: the tool intentionally fetches the full node tree — component instances, bounds and styles live deep in the tree, so limiting depth would silently drop the data the inventory/component features rely on. The call already avoids heavy vector geometry (no `geometry=paths`), so it is already lean.
+
+
+## v0.9 notes
+
+- **Auto Layout parsing.** Figma Auto Layout (`layoutMode`, spacing, padding, alignment, wrap) is parsed into a ready flexbox block on each `spec.json` element (`layout.css` is paste-ready), plus `layoutChild` sizing (FILL/HUG/FIXED). The AI implements exact flex instead of guessing from coordinates. Also surfaced in `inventory.md`.
+- **Variant mapping → prop APIs.** Component variants and properties become a structured prop schema; `component-library.md` now emits a ready TypeScript prop interface per component (enums from variant axes, booleans, text, and `React.ReactNode` slots for instance-swaps).
+- **Constraint metadata.** Each element carries its Figma `constraints` (pin/stretch) for responsive intent.
+- **OAuth login.** Browser sign-in: `oauth-setup <client_id> <client_secret>` once, then `figma-pixel-kit login` opens the browser and captures the token automatically via a loopback callback (`http://localhost:7113/callback`); tokens auto-refresh. `logout` clears them. Requests use `Authorization: Bearer` for OAuth and `X-Figma-Token` for PATs. Personal Access Tokens (`token`) still work unchanged.
+  - Requires your own Figma app (the `client_secret` stays in your local `~/.figma-pixel-kit/config.json`). For a publicly distributed npm build you'd front the token exchange with a small hosted service so the secret isn't shipped — PAT remains the zero-setup option.
+
+_Verified end-to-end on a real 5-screen board: 448 instances → 65 components with prop APIs, 120/241 elements with parsed Auto Layout, reference PNGs at 2x._

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "figma-pixel-kit",
+  "version": "0.9.0",
+  "description": "Figma node to HTML preview, AI implementation package and Playwright visual diff CLI.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "author": "Ozan Zengin <oznzengin@gmail.com>",
+  "homepage": "https://github.com/ozanzeng/figma-pixel-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ozanzeng/figma-pixel-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ozanzeng/figma-pixel-kit/issues"
+  },
+  "bin": {
+    "figma-pixel-kit": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "CLAUDE.md",
+    ".claude",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "export": "node src/cli.js export",
+    "compare": "node src/cli.js compare",
+    "init": "node src/cli.js init",
+    "help": "node src/cli.js --help",
+    "install:browsers": "playwright install chromium",
+    "test": "node tests/core-selftest.mjs",
+    "test:visual": "playwright test"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.60.0",
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.60.0",
+    "pngjs": "^7.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "figma",
+    "playwright",
+    "visual-regression",
+    "pixel-perfect",
+    "html",
+    "claude",
+    "vscode"
+  ]
+}