figma_handoff_readiness v1.0.0

name: "figma_handoff_readiness" description: "Audit a Figma design file for implementation handoff before a developer or agent builds from it: searchable layer naming, auto layout that holds at real content lengths, variables and tokens bound instead of hard coded values, component states and properties covered, assets and exports flagged, plus a fix pass and a handoff packet. Use when preparing a Figma file for handoff, reviewing a file marked ready for dev, checking Dev Mode readiness, or building from a Figma file and needing to judge if it is build ready."

Purpose

Judge whether a Figma file is ready to build from, fix what blocks the build inside the file, and hand off a packet a builder can work from without guessing. A file that looks finished often fails on names nobody can search, spacing typed as raw numbers, a missing dark mode value, a missing error state, or no dev status at all. This skill runs one audit, one fix pass, and one packet for a defined scope. It does not redesign the screen and it does not invent states or tokens the product does not have.

The audit has 24 checks in 6 domains. Full check definitions live in references/audit-checklist.md. A worked file carried from audit to build ready lives in references/worked-file.md. The packet format lives in references/handoff-packet-template.md.

Workflow

1. Define the scope before auditing

• Name the exact scope: one section or a set of top level frames. Write the Figma names down. Everything outside scope is out, even if it is broken.
• Confirm access and mode: open the file, toggle to Dev Mode with Shift D, and note whether the builder will inspect in Dev Mode or in Design Mode. Dev Mode needs a paid plan with a Full or Dev seat. The inspection path changes what the builder can see, so the packet must match the path they actually have.
• Freeze the target: platform, code framework, token names in code, and the modes the build must cover (light and dark, brands, densities). Get these from the codebase or the ticket, not from the design file alone.

2. Run the 24 check audit

Work through references/audit-checklist.md in domain order and record pass, fail or na for each check id. Score with the bundled tool:

python3 bin/score_handoff.py audit.json

The audit JSON format and a full example sit in references/handoff-packet-template.md. The tool prints a per domain score, names every failed check, flags critical failures as blockers, and returns a verdict: READY (exit 0), NEEDS FIXES (exit 1), or NOT READY (exit 2).

• Naming and structure: no default layer names in scope, slash structure on components such as Button/Primary/Large, frames named by function, text layers named by role or content.
• Auto layout resilience: layout frames use auto layout, resizing is set on purpose, and the long content test in step 3 passes.
• Variables and styles: components bind to variables or styles instead of raw values, semantic variables alias to primitives, every mode is filled, names match code tokens.
• Components and states: states the product can reach exist as variants or properties, changeable parts are exposed as properties, no detached instances in scope, library is published.
• Assets and exports: exports are configured in the file, formats and scales match the target, no placeholder assets remain, file names match the repo.
• Dev Mode and packet: scope carries the right dev status, edge behavior is annotated in the file, components point at code, focus view was checked.

Mark a check pass only from evidence in the file. A claim in chat, a ticket, or a comment thread is not evidence for a file check.

3. Run the long content test

This test catches the bugs that ship most often, so run it even when the rest of the audit looks clean.

• Duplicate the scope or work on a branch copy if the file workflow allows it. Never run destructive text tests on the only copy a builder is reading.
• Replace labels, titles and body copy with the longest real strings the product has: longest product name, longest user name, longest error message on record.
• Test again with strings at about 150 percent of the average label length to cover localization growth.
• Check each auto layout frame: text wraps or truncates by a stated rule, padding keeps its full room, gap stays on the spacing scale, nothing clips, nothing pushes a sibling off the frame, and rows that should wrap do wrap.
• Check text limits honestly: a text layer cannot hold both a max height and a fixed max lines value. If the design needs truncation, write the rule as an annotation instead.
• Restore the real copy and record which frames failed the first pass and what fixed them. That record goes in the packet.

4. Do the fix pass in dependency order

Fix only what the audit failed, in this order, so later work does not undo earlier work:

1. Names first. Renaming is cheap and every later step gets easier when search works.
2. Variables next. Replace raw fills, spacing and radius values inside components with variables. Fill missing mode values. Use Dev Mode suggested variables as a hunt list: a suggestion means a raw value sits where a variable already exists.
3. Layout after variables, because gap and padding can bind to number variables. Set flow, wrap, resizing, and min or max limits.
4. Components after layout. Add missing variants for real product states, expose boolean, text, instance swap and slot properties for changeable parts, set preferred instances on swaps, and replace detached copies with real instances.
5. Assets after components. Set export configurations on the final layers, confirm format and scale per asset, and settle source image versus layer export for each photo.
6. Publish the library last, after the final component or variable change. Then confirm instances in scope resolve to the published version.

If a fix needs a product decision (a state that does not exist, a token that has no code match, copy that has no final form), stop on that check, mark it fail, and name the decision and its owner in the packet. Do not invent the state, the token or the copy to make the score pass.

5. Set the handoff state in Dev Mode

• Mark only the audited scope as ready for dev. In Dev Mode, select the section or frames and use Mark as ready for dev. The dev status value is READY_FOR_DEV. Add a status description that says what changed since the last handoff.
• Clear the status from anything that is not in scope or not finished. A ready flag on work in progress sends builders into a moving file.
• Add annotations in the file for behavior a frame cannot show: empty, error, loading and overflow behavior, truncation rules, sorting, timing, and any Ignore auto layout use. Use Annotate (Shift T) and Measure (Shift M) in Dev Mode so the notes live with the design.
• Link the build to code: add Code Connect mappings where they exist, or attach dev resource links to code, Storybook or docs on the components. Record in the packet whether mappings are Code Connect UI or CLI mappings, because only CLI mappings show code snippets in the Inspect panel.
• Open focus view for each ready design from the Ready for dev view and read it as the builder will: Inspect panel, layers, version history. If focus view shows stray work, the scope is wrong. Fix the scope and check again.

6. Ship the packet and close the loop

• Fill in references/handoff-packet-template.md for the scope: scope names, focus view link, audit score and JSON, build order, token mapping, component to code table, asset rules, behavior notes, and open questions with owners.
• Attach the packet to the ticket or pull request and put a copy at the front of the Figma file or in the section description, so the next builder finds it from either side.
• State the verdict plainly: READY, NEEDS FIXES with the failed checks named, or NOT READY with blockers named. Never soften a NOT READY into a ready with notes.
• After the build merges, move the dev status to COMPLETED and file any design bugs against the packet scope name.

Output Contract

For an audit request, produce:

1. The audit JSON with a value for every check id, plus the tool output: score, per domain results, failed checks, blockers, and verdict.
2. A fix list grouped by domain, each item tied to a check id, with owner (fix in file, or product decision needed) noted.

For a handoff request, produce all of the above plus:

1. The completed handoff packet from references/handoff-packet-template.md.
2. Confirmation that the dev status, annotations, and focus view check were done in the file, with the status description text quoted.

If access blocks part of the work (no edit access, no Dev Mode seat, unpublished library you cannot publish), report exactly which checks could not be verified and mark them na with the reason. Do not guess them as pass.

Operating Rules

1. Verify every factual claim about Figma behavior against Figma Help Center or Developer Docs material. Plan, seat and shortcut details change, so check the current docs when a detail decides a check.
2. Never mark a scope ready for dev to hit a deadline. A critical failure means NOT READY, even at a high percentage score.
3. Never invent a component state, a token, a mode value, or final copy to close a check. Missing product decisions are reported, not filled in.
4. Keep fixes inside the defined scope and inside the file you were asked to prepare. Redesigns, library wide renames outside scope, and token architecture changes are separate jobs that need their own go ahead.
5. Do not detach instances, flatten components, or delete layers to make a check pass. Those moves destroy the link between design and code that the audit exists to protect.
6. Treat generated code snippets from Dev Mode as a starting reference, not as production code. The handoff is the names, variables, states and behavior notes that let a builder write the real code.
7. Write the packet in plain language a builder can act on without a meeting. If a note needs a meeting to explain it, the note is not finished.