Prep

fig:prep — prepare the page (tidy, section, stub missing cases)

Part of a plugin. The scripts this skill runs ship beside it under ${CLAUDE_PLUGIN_ROOT}. If that path does not resolve, this file was installed on its own — stop and say the plugin itself is needed (claude plugin install fig@byjunyoung), rather than improvising what the scripts do.

Like mise en place in a kitchen: before the design work and the arrows, every ingredient — every frame — gets cut and put where it belongs.

Takes one page of a design file and (1) normalizes frame names to the convention, (2) groups them into feature-level sections and lays them out, and (3) reads what is actually on each screen to find missing cases and stub them as placeholder frames. A tidied page is only half done — connecting the flow with /fig:arrows completes the set.

Prerequisites: always load the figma:figma-use skill before calling use_figma.

Seat check before the first write — call whoami once. Where every plan it lists carries seat: View, stop before any use_figma write and say so: the reading half of this skill runs on a View seat, the writing half needs an Edit seat on the file's plan, and no retry changes that. Where the seats are mixed, go ahead — and if the first write comes back as a permission error, report the seat table and stop rather than retrying.

When to invoke

• "tidy this page to the convention", "fix the frame naming and sections"
• "stub the missing states as placeholders"
• Laying down the skeleton — sections plus placeholders — before designing a new domain's screens

When NOT to invoke

• Creating or syncing flow arrows → /fig:arrows
• Checking for violations only, zero writes → /fig:lint
• Auditing and applying work into the canonical page → /fig:sync
• Designing the screens themselves → figma:figma-generate-design
• Just understanding the file structure → /fig:read

Inputs

• figma_url (required): the page to tidy. Its name decides how strictly the rules apply
• mode (optional): run the tidy. Omitted, /fig:lint runs first to establish the current state and a plan is proposed from it

Where the rules come from — the config file (same source as fig:lint and fig:sync)

The rules are set by figma-conventions.yaml, not by this document. No values are written here.

python3 ${CLAUDE_PLUGIN_ROOT}/_common/scripts/lib/resolve-config.py --js <fileKey>

Sections read: naming (frame and section patterns, state suffixes, required states per screen type) · layout (spacing tokens, column grid, row bucket) · section_style · placeholder_style · pages (strictness, excluded sections, protected numbers).

• Strictness comes from the target page's name. A match in pages.readonly means refuse the work and say so. On pages.free, apply the minimum — frame naming — and leave sectioning and layout alone. Only pages.strict gets the full treatment
• A page matching none of the lists is not promoted to strict; ask the user — not knowing the convention and there being no convention are different things
• On an unfamiliar file with no config, run /fig:setup first to infer the conventions and draft one
• If the team keeps a written guide, point guide_source at it. It is not fetched on every run — it is an input absorbed once

Core conventions (what the config sets, and what this skill knows)

The values live in the config. What follows is the judgement about how to use them.

Repeated common elements — a common page plus a Default annotation, not per-screen placeholders

States and elements that repeat identically across many screens — generic Empty, Error, Loading, a shared empty-result, a shared error, a shared toast or dialog — do not get a placeholder frame on every screen. Copying one pattern as many times as there are screens destroys the single source, and one change then means touching all of them. Instead, gather them:

1. One canonical copy on a dedicated common page — put a single set of those states on the page naming.common_page_pattern points at, prefixed with naming.common_frame_prefix. That is the single source for the repeated pattern. Look for an existing reusable asset first (a design system spinner or feedback component) and only build one when there is none.
2. Each screen gets an annotation on its Default, not a placeholder — instead of empty/error/loading frames per screen, put a Dev Mode annotation on that screen's Default frame referencing the common page. Write it as a markdown link so it jumps on click (the commonRef helper). Nothing invades the layout, and "this screen's empty/error/loading is the common one" survives into handoff.
3. If placeholders are already scattered, remove them and convert — delete the common-natured placeholder frames built per screen, and tidy the [state] and --> arrows that pointed at what was deleted (reconnect broken flows with /fig:arrows). Before deleting, confirm that screen has its own separate Default so the only copy is never destroyed → preview → go.

Deciding common versus screen-specific: if the state repeats identically across many screens, it goes on the common page. If it is that screen's own empty message, its own error, its own interaction result, it stays a per-screen placeholder (step 4). When it is ambiguous, ask about scope — do not sweep screen-specific states into the common pile. A real screen that has already been designed is not a placeholder, so it is neither deleted nor annotated, even if its name ends in -Empty; exclude it and say so.

Canonical state frames on the common page carry the same identifying style as placeholders (dashed border, Placeholder — / TBD). Once the design is filled in, updating that one place counts as updating every screen that references it.

Constraint: local fonts and reparenting — the group+ungroup workaround (confirmed 2026-06-05)

If an existing frame contains text in a local font that is not synced to the cloud, appendChild and insertChild cannot move it into a section — the font fails to load and the whole script is rejected (atomically, so the file is unchanged). loadFontAsync also fails on local fonts.

But figma.group([frame], section) → figma.ungroup(group) does not go through font validation. Making a group as a child of the section drags the frame in with it; ungrouping leaves the frame a direct child of the section — no manual dragging needed. The absorb() helper does exactly this. Two cautions:

1. Decide the coordinate correction from the parent before the group call — if the frame is already a child of that section its coordinates are already relative, and subtracting unconditionally double-counts and throws it outside the section
2. If even group+ungroup fails in that environment, fall back: move the frame's coordinates over the section area, put it in figma.currentPage.selection, and ask the user once to "nudge the selected frame and the section will absorb it"

Newly created placeholders only use configured cloud fonts, so this constraint does not apply — create them as children of the right section from the start.

Establishing the current state is /fig:lint

To see what is out of line before tidying, call /fig:lint. Every check, every criterion, and all the audit code live there — detection is separated from repair, and this skill only repairs.

The [membership], [bounds], [frame overlap], [section overlap], and [naming] entries in the lint report are this skill's work list. Carry them straight into the step 2 plan.

The criteria are not repeated here. Two copies drift apart at the first revision.

Procedure

1. Collect the conventions and the inventory

• Resolve the config — settle this run's basis with resolve-config.py --js <fileKey>
• Decide strictness from the target page's name (stop and report on pages.readonly)
• Collect frame and section names, coordinates, and sizes with page-level get_metadata
• Identify each screen from its screenshot (batched five at a time, in parallel) — never guess from the name alone
• If sections already exist, read their fill and name pattern and follow them

2. Propose the plan (preview required)

Present renames, section composition, and layout as a table:

| current name | → new name | section |

• When sections could reasonably be composed more than one way (merged versus split), offer the options
• Flag frames whose identity is uncertain with an explicit guessed label
• Write nothing before the user's go

3. Execute (split into steps)

Never all at once — verify after each step before the next:

1. Rename — font-independent, safe to do in bulk
2. Create sections — empty sections at the target position and size. Immediately after creation, send them to the bottom of z-order with figma.currentPage.insertChild(0, s) (otherwise a new section covers existing frames with a white background)
3. Place frames — move coordinates over the section area, on the layout grid. Keep gaps uniform using the spacing tokens (the same effect as Tidy Up)
4. Absorb — figma.group([frame], section) → figma.ungroup() (font-independent; see the Constraint section above). Confirm parent and relative coordinates from metadata afterwards
5. Resize sections — sections do not auto-resize. The resizeSection() helper handles it with layout.section_resize_margin padding. Check for overlap with neighbours immediately after resizing — if the stretched section's bottom or right invades the row below or beside it (most likely with a vertically long list-state stack), push the invaded section out by the row gap in layout and re-check. This is the most common accident when placeholders grow a section
6. Renumber — once the arrangement is settled, reassign NN. in bulk with renumber(). pages.protected_numbers are left as they are
7. Reorder layers (optional) — align layer panel order with canvas position (an insertChild reorder within one parent, so no font constraint). Not required by the convention, so skipped by default and done only on request

4. Detect missing cases → placeholders (preview required)

First split common from specific — a missing case that repeats identically across many screens (generic Empty, Error, Loading) does not get a per-screen placeholder; it follows the "repeated common elements" section above (common page plus a Default annotation). Only screen-specific cases get placeholders as below.

Check on two axes:

(a) State variant checklist — naming.required_states is the basis. Settle the screen type (list, form, search) from the screen's content, then compare against that type's list. If the config has none, use the fallback below and note that in the report:

Pick the placeholder's state suffix from naming.states — never invent one.

(b) Interaction result screens — read the actual UI elements from the screenshot and check whether the screen you land on after pressing them exists:

Present the missing list as a table, including which clue each was inferred from → placeholders are created after a go. Where the policy is undecided, write TBD (needs confirmation): … into the placeholder's description — never draw an invented behaviour as though it were settled.

5. Verify and hand off

The mandatory last action of this step — call /fig:lint (via the Skill tool). Once writing is done (creating, duplicating, moving, placing), always call /fig:lint and get STRUCT PASS and FLOW PASS — unconditionally if clone or move was involved. Fix what it reports and call again; never report completion without a PASS.

No inline self-check audit lives here. Holding the same check in two places means one gets fixed and they drift — the verdict always comes from /fig:lint alone.

• Never PASS on an isolated screenshot. node.screenshot() and single-node captures render a frame on its own and cannot catch a parent or canvas-position error — the frame looks perfectly fine by itself. The first pass is /fig:lint's measurements; the second is a screenshot of the whole section node, not an isolated frame. When clone or move was involved, this is almost always where the accident shows
• Output the per-section handoff URLs — https://figma.com/design/{fileKey}/?node-id={section id with : replaced by -}. This matches the "share section URLs for handoff, not individual frames" checklist
• End the output with: the list of guessed labels needing confirmation, the list of TBD policies, and what comes next — the flow with /fig:arrows, and /fig:handoff once the screens are drawn

Implementation — the tidy helper preamble

Write scripts use ${CLAUDE_PLUGIN_ROOT}/_common/scripts/prep-ops.js as a preamble. Concatenate the config line, the whole file, and the actual calls, then hand it to use_figma.

Constraints

• Preview → go before writing — renames/sections/layout (step 2) and the placeholder list (step 4) each need their own go
• Sections matching pages.exclude_sections are untouched at every step: rename, move, resize, placeholder
• No more than ten operations per call, verifying with metadata or screenshots between steps
• clone() and createFrame default their parent to currentPage, not the original node's section. To land inside a section you must absorb (group+ungroup) and then set coordinates — otherwise the node stays page-level, and section-relative coordinates written onto it are read as absolute and it shoots off somewhere else. Right after duplicating or creating: confirm the parent (f.parent.type === "SECTION"), absorb, set coordinates, audit bounds — that is one set. Never finish on an isolated screenshot alone (see step 5)
• A screenshot of an empty section does not render overlapping non-child frames (you get a white box) — verify absorption by querying the frame's parent instead
• Never write an unsourced policy into a placeholder as though it were settled — behaviour without evidence is all TBD

Notes

• The detection tables in (a) and (b) are a starting point, not the whole of it — the real work is reading each screen and asking, for that screen, "if I press this, what should I see?"
• Frame coordinates change right after tidying, so if the page already had flow arrows, propose a /fig:arrows sync alongside
• A placeholder is only finished when the real design replaces it and the dashed border and "Placeholder —" text are removed — the name stays as it is