Figma Fidelity plugin

An Agent Plugins 1.0 bundle for GitHub Copilot app/CLI and compatible VS Code versions. Install once to make the Figma fidelity skill and its Figma/Playwright MCP server definitions available together, including in a new project folder.

This is a community plugin, not an official GitHub, Microsoft or Figma product. Plugin 1.2.0 bundles fidelity skill v3.2, adding executable readiness before source generation and bounded browser recovery. A local checkout/ZIP is not a published marketplace update.

What it does

Figma structured design + screenshot
  -> bootstrap (no source edits) -> actual same-provider browser smoke
  -> approved reference and comparison contract -> verified readiness
  -> implement the initial frontend, or inspect existing code
  -> functional test -> diagnose -> fix -> retest
  -> rendered element comparison -> score -> scoped correction
  -> fresh functional tests -> fresh fidelity comparison
  -> both gates pass on the same source revision -> evidence report

• Implement: propose/approve a stack for an empty folder, verify readiness, then generate once and test; never scaffold before design and browser smoke succeed.
• Audit: compare an existing running UI without editing application code.
• Improve: run bounded functional and fidelity repair loops.
• Batch DOM geometry/style collection alongside the accessibility tree.
• Thirteen explicitly defined operational properties, signed numeric deltas, semantic element checks, and a deterministic scorer.
• Source-hashed persistent loop controller with a shared three-repair budget, evidence checks and regression/plateau/cycle stops.
• Readable HTML reports with score/profile/thresholds, evidence coverage, functional/fidelity gates, signed before/after element results and current-vs-best history. No new scoring engine.

This plugin orchestrates Copilot's tools; it is not an autonomous daemon. The controller requests the next action, and Copilot executes actual tool calls and approved edits. It never creates a real fidelity score without actual reference and app evidence.

Install

Requires a client version supporting Agent Plugins 1.0, Node.js 18+ and npm/npx, an accessible browser installation, Figma access with available MCP quota, and organizational permission to use plugins/MCP. Installing the plugin does not buy a Figma seat or grant file access.

VS Code

1. Run Chat: Install Plugin From Source in the Command Palette.
2. Enter https://github.com/AkashAi7/figma-fidelity-plugin.
3. Review and approve installation. If plugin controls are missing, use a compatible updated VS Code/Copilot version and check chat.plugins.enabled and organization policy.
4. Start a new Agent-mode chat. Under MCP: List Servers, start/authorize the bundled Figma server and enable the plugin tools in Configure Tools.

You do not need to create .vscode/mcp.json in each project. Plugin MCP definitions load through the client. Some clients treat plugin installation as server trust, so review the server commands before installing.

GitHub Copilot CLI

Recommended marketplace installation:

copilot plugin marketplace add AkashAi7/figma-fidelity-plugin
copilot plugin install figma-fidelity@figma-fidelity-marketplace

Direct installation is also available on clients supporting it:

copilot plugin install AkashAi7/figma-fidelity-plugin

Some CLI versions mark direct installs as deprecated; prefer the marketplace route. Use one installation route, not both. Start a new session after installation.

After a new version is published to your configured source, update with copilot plugin update figma-fidelity and reopen the session. A local checkout or ZIP does not update the public marketplace; use the reviewed local package for unpublished changes.

GitHub Copilot app

Open Customize -> Plugins, add https://github.com/AkashAi7/figma-fidelity-plugin as a marketplace source, then install figma-fidelity. The repository contains the marketplace at .github/plugin/marketplace.json.

Alternatively, use the CLI installation in the same user/configuration profile as the app, then open a new app session. A different COPILOT_HOME points at a different configuration; an installation in an unrelated embedded CLI profile is not proof that the app sees it.

First connection

The Playwright package is version-pinned for reproducibility; first startup may download and execute it through npm. The browser profile is isolated. Browser installation/authentication is not bundled. Use test data and local/test apps; do not automate production submissions without explicit approval.

The portable MCP schema does not include a per-tool allowlist. The skill requests only Figma read tools; this is behavioral guidance, not a security boundary. Use client tool selection/organizational policy to disable Figma write tools where needed. The plugin includes no hooks or automatic permission approvals and does not write to Figma, deploy, push code, or upload screenshots as part of its workflow.

Server names are distinct to avoid overwriting existing figma or playwright definitions. If you already have equivalent servers, choose one tool set for the run rather than using both. Do not copy OAuth tokens into the plugin or this repository.

Invoke

Ordinary chat invocation works without relying on slash-menu readiness:

Use the figma-ux-fidelity skill from the figma-fidelity plugin
in IMPLEMENT mode.

Figma frame: <paste the frame URL including node-id>
Project: this folder
Profile: wireframe

Bootstrap the v3.2 controller before any source generation.
Discover and bind the bundled Figma and browser tools.
Retrieve structured design context and a matching screenshot.
If this folder is empty, propose a minimal stack before scaffolding.
Run the full same-provider browser smoke; use bounded approved
startup recovery if needed, never a screenshot-only fallback.
Agree all selected routes/states and narrow/full-width checks.
Verify readiness, implement once, then use the controller for
actual functional testing, measured fidelity scoring and repair.
After every visual edit, repeat functional checks before remeasuring.
Stop after three repair batches or when both gates pass.
Generate a local HTML fidelity report and give me its clickable path,
including if intake is blocked. Preserve source-bound screenshot references.
Do not replace missing Figma access with a guessed design.

For a completed visual design, use Profile: high-fidelity. For existing code use IMPROVE, or AUDIT for no edits.

Where plugin skill slash commands are supported, select the discovered command, commonly /figma-fidelity:figma-ux-fidelity. Clients can display names differently; ordinary chat is the portable invocation path. If Skill ... is not ready to run appears, use ordinary chat and inspect the actual skill-load result rather than repeatedly reinstalling.

The plugin skill is the source of the runbook. An older standalone personal skill with the same name may also be discoverable: explicitly select the plugin-provided skill, or remove/disable the old installation only after reviewing it. Installation does not delete your existing skills.

Preflight and quota behavior

Skills do not make unavailable host tools callable. Confirm actual discovery and a real read from the requested frame, not just that configuration exists.

New operational gate: exact runbook and dependency-free preflight.mjs validate required inputs, actual design tree/image/normalized inventory, approved selected-screen contract, and same-provider/session browser navigation, exact viewport, screenshot, AX, DOM/style/readiness, type/click/keyboard state changes and console/network observations. Startup is at most three attempts (60 seconds each, 180 seconds total), separate from app repairs. Preserve the original error: Chrome exit 13 alone does not establish its cause.

$skill = ".\skills\figma-ux-fidelity"
$run = "<approved NEW run directory>"
node "$skill\scripts\loop.mjs" bootstrap "$run\config.json" "$run\state.json"
node "$skill\scripts\probe.mjs"
# Execute actual host smoke; record startup attempt(s), raw outputs and receipt per runbook.
node "$skill\scripts\loop.mjs" attempt "$run\state.json" "$run\attempt-1.json"
node "$skill\scripts\loop.mjs" ready "$run\state.json" "$run\contract.json" "$run\preflight.json"
# IMPLEMENT only after allowImplementation:true; AUDIT/IMPROVE preserve baseline.
node "$skill\scripts\loop.mjs" implemented "$run\state.json" "$run\contract.json"

Launcher-only recovery may choose an existing Edge installation using supported --browser msedge, an approved --executable-path, and/or --headless in a scoped client override. Keep --isolated; no global config/auth/permission changes, signed-in profiles, security bypasses, browser downloads without permission, or policy evasion. Full smoke must be repeated after config/session changes. An approved equivalent Playwright provider must satisfy the entire matrix and name its provenance; another process's screenshots do not establish that the original MCP works. Portable default MCP configuration is intentionally unchanged.

Each selected screen needs specified controls/error states and narrow/full-width checks. Use acceptance patterns for Login/Home/My Policies/Policy Details/File a Claim only when selected, including actual file input/filename/preview/limits, real filter list changes and navigation/deep-link/Back. Do not invent insurance facts from another product's frame. Extra fixtures/remote fonts require approval; unknown backend actions remain demo/unimplemented, not fake successes.

No browser/design readiness → BLOCKED, local HTML, unknown functional status, deferred fidelity, concrete resume action. Screenshot-only work is PARTIAL / NOT ASSESSED, not "closely matches" or "interactions tested." Controller receipt checks enforce the agent workflow, not a security sandbox or proof that tool outputs are truthful. Existing v3 states/read reports remain compatible and labeled legacy/no-preflight; new defaults require fresh readiness. Explicit synthetic mode is for regression fixtures only.

• Missing tool/server/client support -> stop with the missing capability.
• Figma OAuth/file permission error -> complete authorized access; never bypass it.
• Exhausted plan quota -> stop without repeated retries; plugin installation cannot increase quota.
• Public preview without structured reference -> not a substitute for numerical Figma fidelity.
• Immutable Figma reference -> cache once for the approved run; recapture the changing app after each repair.

An explicitly authorized structured export plus matching screenshot can be an alternative evidence source, but must be labeled as an export-based run, not live Figma MCP.

Acceptance and limitations

Default acceptance: overall >=90/100, each category >=80, each slice >=85, required coverage 100%, weighted coverage >=95%, all critical checks passing, and all four functional gates passing on the same implementation as the fidelity capture.

Web-only units: CSS px, not native iOS pt or Android dp. New suggested geometry tolerance is 2 CSS px and font-size tolerance 1 CSS px. Color difference is explicitly CIE76 (suggested deltaE76 <=2 after calibration), not CIEDE2000 and not WCAG contrast. Unsupported paint/font/transform situations remain unresolved.

The 13-property list is this plugin's operational rubric, not a claim about another team's implementation. Accessibility snapshots do not contain complete CSS geometry/colors; DOM and style evidence are required. A high fidelity score does not prove usability, full accessibility conformance, or pixel identity.

Included resources

Run the dependency-free Node tests from a checkout:

node --test .\skills\figma-ux-fidelity\scripts\evaluate.test.mjs .\skills\figma-ux-fidelity\scripts\workflow.test.mjs .\skills\figma-ux-fidelity\scripts\report.test.mjs .\skills\figma-ux-fidelity\scripts\preflight.test.mjs
node skills/figma-ux-fidelity/scripts/replay.mjs

Synthetic replay exercises mechanics, not live Figma/browser access. Local runtime evidence belongs in the application's approved artifact directory, not in this plugin repository.

Open the fidelity score as a report

The controller automatically generates report.html and report.json after every valid CLI initialization/step, including accepted, blocked, budget and regression handoffs. JSON stdout contains the clickable report.reportPath / report.reportUrl. Copilot should include that path in its final reply.

To generate from existing evidence (Node.js 18+, no extra dependencies):

$skill = ".\skills\figma-ux-fidelity"
$run = "<approved local artifact directory>"
node "$skill\scripts\report.mjs" state "$run\contract.json" "$run\state.json" --out "$run\human-report-001"
node "$skill\scripts\report.mjs" runs "$run\contract.json" "$run\fidelity-0\report.json" "$run\fidelity-1\report.json" --out "$run\human-report-002"
node "$skill\scripts\report.mjs" blocked "Missing Figma access; no assessment performed" --out "$run\blocked-report-001"

Use original raw observation JSON, not score summaries. Omit AFTER for a single run, or append ordered observations for history. The output directory must be new; originals are never overwritten. Missing evidence is NOT ASSESSED, not a pretend zero; a measured zero stays zero. Source mismatch or any failure gate cannot appear accepted. The report says UI/UX implementation fidelity, not overall usability.

HTML is self-contained, accessible, light/dark themed and printable with Print → Save as PDF. Screenshots are preserved as inert source-bound evidence references, not embedded images or claimed pixel diffs. All reports remain local and private; no automatic uploading/sharing. Keep them in gitignored artifacts directories, and never publish private user evidence. See the reporting contract for input limits, state verification and error behavior.

Sources and license

• Agent Plugins in GitHub Copilot
• Copilot plugin reference
• VS Code Agent Plugins
• Figma MCP access and quotas
• Microsoft Playwright MCP

Plugin code and documentation: MIT. Referenced/installed third-party services and packages retain their own licenses and terms; this repository does not redistribute their source.