Skip to content

SKILL.md

Latest commit

 

History

History
132 lines (92 loc) · 5.83 KB

SKILL.md

File metadata and controls

132 lines (92 loc) · 5.83 KB
Raw
name figma-plan-review
description Gate-reviews Figma implementation plans before canvas work begins, then learns from outcomes after. Catches component misuse, missed variables, bad structure, and repeated mistakes. Reads project lessons from CLAUDE.md and evolves its own instructions from cross-project patterns. Trigger on: "review the plan", "check this approach", "plan review", "/figma-plan-review", or before any multi-step figma-use / figma-generate-design work. Also trigger for post-build review: "how did that go", "what did we learn".

Figma Plan Review

Gate that runs BEFORE canvas writes. Learns AFTER implementation finishes. Works alongside figma-use and figma-generate-design — never writes to the canvas itself.

Phase A — Pre-Build Review

User has already discussed requirements and agreed on what to build. This phase reviews the approach before execution starts.

A.1 — Load context

  1. Read ## Figma Plan Review — Project Lessons in CLAUDE.md if it exists. These are hard constraints — a repeated known mistake is a review failure.
  2. Read the ## Learned Review Rules section at the bottom of THIS skill file if it has entries. These are cross-project rules from past experience.

A.2 — Audit the design system

For each distinct UI element in the plan:

  1. Run search_design_system with at least 2 query variations per element. (e.g., "navigation header" AND "top bar" — components are never named what you expect.)
  2. For each match: note the component name, variants, properties, and instance swap slots.
  3. For modifications: run get_metadata + get_screenshot on the existing screen first.

Do not skip this. Planning from assumption instead of audited inventory is the #1 rework cause.

A.3 — Evaluate the plan

Check these in order. For detailed sub-checks, read references/review-checklist.md.

Component selection — FAIL if building from primitives when a component exists, or detaching when properties already cover the use case.

Variable binding — FAIL if hardcoding colors/spacing/type when variables exist.

Structure — FAIL if using absolute positioning where auto layout works, or replacing entire frames when targeted edits would suffice.

Project lessons — FAIL if the plan violates any rule from CLAUDE.md. This check has the highest priority.

Efficiency — WARN if the plan requires excessive sequential use_figma calls that could be batched.

A.4 — Verdict

Any FAIL = NEEDS REVISION. Provide the corrected plan, not just the criticism. List what's wrong, why, and what to do instead. Then re-review the fix.

All PASS = APPROVED. Say so clearly and hand off to figma-use / figma-generate-design.

Phase B — Post-Build Review

After implementation is complete.

B.1 — Assess

  1. get_screenshot the result and compare against the approved plan.
  2. Check for use_figma errors, retries, or manual corrections during the build.
  3. Ask the user: "How does this look? Anything you had to fix manually?"

B.2 — Write project lessons

If anything went wrong or surprised you, append to ## Figma Plan Review — Project Lessons in CLAUDE.md. Create the section if it doesn't exist.

Format — keep entries tight:

### [YYYY-MM-DD] — [Short title]
**Lesson**: [Imperative rule for this design system]
**Applies to**: [Component or pattern name]

These are instructions, not journal entries. Write them as rules a future agent can follow.

B.3 — Evolve the skill

Ask the user: "Did anything from this session apply to all design systems, not just this one?"

If yes: propose a specific addition to the ## Learned Review Rules section at the bottom of THIS SKILL.md file. Show the exact lines to add. If the user approves, write them directly to the skill file.

If no, or the user isn't sure: move on. Don't log it anywhere. If it matters, it'll come up again on another project and the pattern will be obvious.

Gate on new rules: Before writing any rule to this skill, evaluate it as a ruthlessly efficient skill builder who only cares about results and reducing token burn. Apply these filters:

  1. Does it prevent a real rebuild? If the rule only saves a minor fix, it's not worth the tokens to read it on every future invocation. Drop it.
  2. Is it already covered? Check the existing checklist and rules. Redundant rules are pure token waste.
  3. Is it actionable in 1 sentence? If it takes a paragraph to explain, it's not a rule — it's a tutorial. Compress or drop.
  4. Would a competent agent figure this out anyway? Don't codify obvious things. Only codify what repeatedly burns people despite being non-obvious.

Learned Review Rules

Reference-Based Builds

  1. Decompose before planning. Count exact panels, estimate widths in pixels, identify which are fixed vs flex. Write the layout as Panel1(60px) | Panel2(250px) | Panel3(flex) | Panel4(200px) before touching the canvas. "3 columns" vs "4 columns" is a full rebuild if wrong.
  2. Match component granularity to the reference, not the design system. If the reference shows a narrow icon sidebar but the DS only has a full 220px navigation menu, build custom. Don't force-fit oversized DS components with clipping hacks.
  3. Identify what's NOT in the DS early. Comments, activity feeds, error banners, message cards — these are often manual builds. List them upfront so the plan accounts for build time.
  4. One panel per use_figma call, screenshot immediately. A wrong panel caught after 1 call costs 1 retry. Caught after 4 calls costs a full rebuild.