agentleFS
shub-rajputshub-rajput/design-superskills/skills/design-organize/SKILL.md

design-organize

Skill10 starsChanged 33 days agoMITView on GitHub

Use when Figma screens in a section, frame or page need organizing into a clean, labelled layout: rows by flow, sub-sections, screen labels, re-formatting an existing layout, or moving screens between sections. Triggers include "organize these screens", "clean up this section", "label these screens", "group these by flow", "split this into sub-sections", "re-format the layout", or a Figma section or frame link plus layout or grouping instructions.

The file

Show its rules and text

We split this skill into the rules it gives an agent

24 rules. About 0 are common, 16 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈16

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do NOT proceed without it.

    line 38
  2. Distinctive:

    Stop on repeated failure: If same operation fails twice, STOP and read back children before retrying.

    line 46
  3. Distinctive:

    Parse inline preferences first: Check if the user's message already answers any of these:

    line 52
  4. Very specific:

    Page discovery approach: Use a single use_figma call that iterates all pages, trying to find the section AND access its children.

    line 69
  5. Distinctive:

    After finding the page, mention it so the user can catch wrong-page issues early (e.g., "Working on page [page name]").

    line 84
  6. Distinctive:

    Wait for confirmation before continuing to Step 3.

    line 177
  7. Distinctive:

    Do NOT delete existing labels: Always reuse them. This preserves node IDs, custom styling, and user edits.

    line 181
  8. Distinctive:

    If existing labels were found in Step 2, inform the user:

    line 183
  9. Very specific:

    Update .characters only if the label text doesn't match the screen name (and user chose Mode A) or with auto-detected text (Mode B)

    line 190
  10. Distinctive:

    Create new labels only for screens that have no matching existing label

    line 191
  11. Distinctive:

    If there are leftover labels with no matching screen, ask the user before removing them

    line 192
  12. Very specific:

    Gotcha: sub-section children after creation: After creating sub-sections and moving children into them, reading subSection.children via the …

    line 346
  13. Very specific:

    Call get_screenshot on the section/frame.

    line 350
  14. Distinctive:

    All screens horizontally aligned within each section/sub-section

    line 351
  15. Very specific:

    Mode B (auto-detect): call get_screenshot on each screen element (outside use_figma), analyze the content, generate a short descriptive …

    line 363
  16. Distinctive:

    Keep labels short (2-5 words)

    line 366
  17. Very specific:

    Use > as a hierarchy separator for sub-views (e.g., "Share > Link")

    line 367
  18. Distinctive:

    Then, apply labels non-destructively: If existing labels were found in Step 2, reuse them.

    line 372
  19. Distinctive:

    Font fallback: If Inter loading fails, try "Roboto" then "Arial".

    line 502
  20. Very specific:

    Call get_screenshot on the section.

    line 508
  21. Very specific:

    Call get_screenshot on the full section/frame.

    line 554
  22. Distinctive:

    No overlapping or clipped elements

    line 558
  23. Distinctive:

    All sections properly sized

    line 559
  24. Distinctive:

    If the user requests changes, re-run the relevant steps with updated values.

    line 576

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Design Organize

Organize scattered design screens inside a Figma section or frame into a clean, labeled layout with optional sub-section grouping. Works on any node type — frames, groups, images, shapes, vectors. Handles both fresh organization and re-formatting existing layouts.

Validation principle: Every use_figma write step must be followed by a get_screenshot check. Do not stack writes without visual verification. If a screenshot reveals a problem, fix it before proceeding.

Quick Reference

StepWhat
0Prerequisites — Figma MCP required
1Parse user intent, ask only unresolved questions
2Read container, classify children (screens vs labels vs notes)
3Handle existing labels (ask: keep/update/remove)
4Arrange screens + optional sub-section grouping
5Validate arrangement (get_screenshot)
6Add/reposition labels
7Validate labels (get_screenshot)
8Resize section(s) to fit content
9Final validation (get_screenshot)
10Present result, offer adjustments

Step 0: Prerequisites

  1. Figma MCP server — check if mcp__figma__use_figma tool is available. If NOT available, tell the user:

This skill requires the Figma MCP server. Run:

claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp

Then restart Claude Code.

Do NOT proceed without it.

  1. figma-use skill — load figma:figma-use via the Skill tool before any use_figma call.
  2. Figma Section gotchas — critical, cause silent failures:
    • Page discovery: getNodeById() works cross-page — it will find nodes on ANY loaded page, giving false positives. Use figma.currentPage.findOne(n => n.id === "<nodeId>") instead, which only returns nodes that actually live on the current page.
    • Page-level TEXT: Figma stores TEXT nodes placed inside SECTIONs as page-level children — they won't appear in section.children. Scan figma.currentPage.children for TEXT nodes whose absoluteBoundingBox falls within section bounds. These are existing labels (canvas-absolute coords — convert using section.absoluteBoundingBox).
    • Overlapping children: SECTION nodes may discard children that overlap existing frames between calls. Position new nodes to avoid overlaps.
    • Stop on repeated failure: If same operation fails twice, STOP and read back children before retrying.

Step 1: Parse User Intent

The user has already provided a Figma link to a section or frame. Extract fileKey and nodeId from the URL (convert - to : in nodeId).

Parse inline preferences first. Check if the user's message already answers any of these:

  • Labels preference (e.g., "no labels", "auto-label", "label these screens")
  • Grouping preference (e.g., "group by feature", "keep flat")

Only ask about unresolved choices. Combine remaining questions into one AskUserQuestion:

Labels:

  • A) Use element names (default, fast)
  • B) Auto-detect from content (I'll screenshot each element and generate descriptive labels — great for screenshot dumps with meaningless filenames)
  • C) No labels

Skip questions the user already answered inline.

Step 2: Read Container and Classify Children

Find the correct page and read the target node's children. Critical: the section/frame won't be found on the default page — you must iterate all pages.

Page discovery approach: Use a single use_figma call that iterates all pages, trying to find the section AND access its children. When the section is found on the correct page, its children will be populated.

// Use findOne to locate the page that OWNS this node.
// Do NOT use getNodeById — it returns nodes cross-page, giving false positives.
let targetPage = null;
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  if (figma.currentPage.findOne(n => n.id === "<nodeId>")) {
    targetPage = page;
    break;
  }
}

After finding the page, mention it so the user can catch wrong-page issues early (e.g., "Working on page [page name]").

Why findOne: getNodeById() works cross-page once pages load into memory — it returns nodes from ANY page, causing the loop to stop on page 1 regardless of where the section actually lives. findOne only searches descendants of the current page.

Avoid get_metadata for large sections — it can return 300K+ characters exceeding token limits. Use use_figma directly for child classification instead.

Once on the correct page, classify children:

const container = figma.getNodeById("<nodeId>");
const screens = [];
const existingLabels = [];
const existingNotes = [];

for (const child of container.children) {
  if (child.visible === false) continue;

  // Existing label: ANY text node that is a direct child of the container.
  // Do NOT rely on fontSize === 70 — it may return a Symbol for mixed styles
  // or the label may have been created at a different size.
  if (child.type === "TEXT") {
    existingLabels.push({
      id: child.id,
      name: child.name,
      characters: child.characters,
      x: child.x, y: child.y,
      width: child.width, height: child.height
    });
  }
  // Existing note: instance ≤450px wide, or frame named "Dev Note" ≤450px wide
  else if ((child.type === "INSTANCE" && child.width <= 450) ||
           (child.type === "FRAME" && child.name === "Dev Note" && child.width <= 450)) {
    existingNotes.push({ id: child.id, name: child.name, x: child.x, y: child.y });
  }
  // Everything else is a screen
  else {
    screens.push({
      id: child.id, name: child.name,
      x: child.x, y: child.y,
      width: child.width, height: child.height
    });
  }
}

// Also scan the PAGE for TEXT nodes within the section bounds.
// Figma reparents manually-placed section text to the page level —
// these are existing labels and must be detected here.
const sectionBounds = container.absoluteBoundingBox;
if (sectionBounds) {
  for (const node of figma.currentPage.children) {
    if (node.type !== "TEXT" || node.visible === false) continue;
    const nb = node.absoluteBoundingBox;
    if (!nb) continue;
    const insideX = nb.x >= sectionBounds.x && nb.x + nb.width <= sectionBounds.x + sectionBounds.width;
    const insideY = nb.y >= sectionBounds.y && nb.y + nb.height <= sectionBounds.y + sectionBounds.height;
    if (insideX && insideY) {
      existingLabels.push({
        id: node.id, name: node.name,
        characters: node.characters,
        x: node.x, y: node.y,          // canvas-absolute coords
        width: node.width, height: node.height,
        pageLevel: true                 // flag: reposition using canvas coords
      });
    }
  }
}

return {
  screens: screens.sort((a, b) => a.x - b.x || a.y - b.y),
  existingLabels,
  existingNotes: existingNotes.length
};

Important: Store one screen ID (e.g., the first screen's id) as <childId> — you'll use it in the page-switch preamble for all subsequent use_figma calls.

Classification rules:

TypeDetection
Labeltype === "TEXT" in section children OR page-level TEXT whose absoluteBoundingBox falls within section bounds (pageLevel: true)
Note (instance)type === "INSTANCE" AND width <= 450
Note (default)type === "FRAME" AND name === "Dev Note" AND width <= 450
ScreenEverything else that's visible

Step 2b: Version Safety

Before making any changes, ask the user to save a version manually:

Before I start making changes — please save a named version in Figma (File → Save to Version History) so you can revert if needed. Figma has no undo for MCP changes.

Let me know when you're ready to proceed.

Wait for confirmation before continuing to Step 3.

Step 3: Handle Existing Labels and Notes

Do NOT delete existing labels. Always reuse them. This preserves node IDs, custom styling, and user edits.

If existing labels were found in Step 2, inform the user:

Found X existing labels. I'll reposition them above their screens and update the text if needed.

Then in Step 6:

  1. Match each existing label to its nearest screen by x-proximity
  2. Reposition it above the matched screen
  3. Update .characters only if the label text doesn't match the screen name (and user chose Mode A) or with auto-detected text (Mode B)
  4. Create new labels only for screens that have no matching existing label
  5. If there are leftover labels with no matching screen, ask the user before removing them

For existing notes: same approach — reposition, don't delete.

If no existing labels/notes found: skip this step entirely.

Step 4: Arrange Screens

Layout defaults:

SettingDefault
Section padding100px
Label-to-screen gap70px
Screen-to-screen gap200px
Label fontInter Medium, 70pt
Label colorWhite {r:1, g:1, b:1}

Flat layout (default)

Position all screens in a horizontal row:

// Switch page first
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  if (figma.currentPage.findOne(n => n.id === "<childId>")) break;
}

const container = figma.getNodeById("<nodeId>");

// Collect screens only (exclude text labels and notes)
const screens = container.children
  .filter(c => {
    if (c.visible === false) return false;
    if (c.type === "TEXT") return false;
    if (c.type === "INSTANCE" && c.width <= 450) return false;
    if (c.type === "FRAME" && c.name === "Dev Note" && c.width <= 450) return false;
    return true;
  })
  .sort((a, b) => a.x - b.x || a.y - b.y);

// Measure label height dynamically
await figma.loadFontAsync({ family: "Inter", style: "Medium" });
const tempLabel = figma.createText();
tempLabel.fontName = { family: "Inter", style: "Medium" };
tempLabel.fontSize = 70;
tempLabel.characters = "X";
const labelHeight = tempLabel.height;
tempLabel.remove();

const padding = 100;
const labelGap = 70;
// labelsEnabled = true if user chose A or B for labels in Step 1
const startY = <labelsEnabled> ? padding + labelHeight + labelGap : padding;

const screenToScreenGap = 200;

let currentX = padding;

for (const screen of screens) {
  screen.x = currentX;
  screen.y = startY;
  currentX += screen.width + screenToScreenGap;
}

return { arranged: screens.length, mutatedNodeIds: screens.map(s => s.id) };

Sub-section grouping (when user requests or 8+ screens)

For larger sets of screens, offer to group them into sub-sections. This can happen:

  • User asks explicitly (e.g., "group by feature area")
  • Auto-suggest for 8+ screens — analyze labels for common prefixes (text before >) and suggest groups

Grouping flow:

  1. Analyze screen names or auto-detected labels for common prefixes
  2. Present detected groups:

    Suggested groups (from label prefixes):

    • Submissions — 4 screens
    • Onboarding — 3 screens
    • Settings — 3 screens
    • Dashboard — 2 screens

    Layout: Vertical (sections stacked top to bottom) or Horizontal (side by side)?

  3. User confirms or adjusts

Creating sub-sections:

// Switch page
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  if (figma.currentPage.findOne(n => n.id === "<childId>")) break;
}

const parentSection = figma.getNodeById("<sectionId>");

// Create a child section for each group
const subSection = figma.createSection();
subSection.name = "<groupName>";

// Move this group's screens into the sub-section
for (const screen of groupScreens) {
  const node = figma.getNodeById(screen.id);
  subSection.appendChild(node);
}

// Arrange screens horizontally within the sub-section (same logic as flat layout)
// ...

// Sub-section fill: darken parent fill ~30% for visual contrast
if (parentSection.fills && parentSection.fills.length > 0) {
  const parentFill = parentSection.fills[0];
  if (parentFill.type === "SOLID") {
    subSection.fills = [{ type: "SOLID", color: {
      r: parentFill.color.r * 0.7,
      g: parentFill.color.g * 0.7,
      b: parentFill.color.b * 0.7
    }}];
  } else {
    subSection.fills = [...parentSection.fills];
  }
}

parentSection.appendChild(subSection);

Positioning sub-sections (vertical stacking — default for 3+ groups):

const sectionGap = 100;
let currentY = padding;

for (const subSection of subSections) {
  subSection.x = padding;
  subSection.y = currentY;
  currentY += subSection.height + sectionGap;
}

Positioning sub-sections (horizontal — for 2 groups or when user prefers):

let currentX = padding;

for (const subSection of subSections) {
  subSection.x = currentX;
  subSection.y = padding;
  currentX += subSection.width + sectionGap;
}

Gotcha: sub-section children after creation. After creating sub-sections and moving children into them, reading subSection.children via the parent node may return empty arrays. To access sub-section children reliably, navigate via a known child ID: figma.getNodeById(childId).parent gives you the sub-section with populated children.

Step 5: Validate Arrangement

Call get_screenshot on the section/frame. Verify:

  • All screens horizontally aligned within each section/sub-section
  • Consistent spacing between screens
  • Sub-sections properly stacked (vertical or horizontal)
  • No overlapping elements

Fix any issues before proceeding.

Step 6: Add/Reposition Labels

First, determine the label text for each screen based on the user's label mode choice:

  • Mode A (element names): label text = screen.name
  • Mode B (auto-detect): call get_screenshot on each screen element (outside use_figma), analyze the content, generate a short descriptive label. Build a map: [{ screenId, labelText }, ...]

Auto-detect label guidelines:

  • Keep labels short (2-5 words)
  • Use > as a hierarchy separator for sub-views (e.g., "Share > Link")
  • Focus on the primary content, not UI chrome
  • For modals: name the modal (e.g., "Delete Confirmation")
  • For settings: name the category (e.g., "Notifications")

Then, apply labels non-destructively. If existing labels were found in Step 2, reuse them. Only create new text nodes for screens that don't have a matching label.

// Switch page first
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  const section = figma.getNodeById("<nodeId>");
  if (section && section.children && section.children.length > 0) break;
}

await figma.loadFontAsync({ family: "Inter", style: "Medium" });

const container = figma.getNodeById("<nodeId>");

// Collect screens and existing labels
const screens = [];
const existingLabels = [];
for (const child of container.children) {
  if (child.visible === false) continue;
  if (child.type === "TEXT") {
    existingLabels.push(child);
  } else if (!(child.type === "INSTANCE" && child.width <= 450) &&
             !(child.type === "FRAME" && child.name === "Dev Note" && child.width <= 450)) {
    screens.push(child);
  }
}

// Scan page-level TEXT nodes ONCE (Figma reparents section text to page)
const sectionBounds = container.absoluteBoundingBox;
if (sectionBounds) {
  for (const node of figma.currentPage.children) {
    if (node.type !== "TEXT" || node.visible === false) continue;
    const nb = node.absoluteBoundingBox;
    if (!nb) continue;
    if (nb.x >= sectionBounds.x && nb.x + nb.width <= sectionBounds.x + sectionBounds.width &&
        nb.y >= sectionBounds.y && nb.y + nb.height <= sectionBounds.y + sectionBounds.height) {
      node._pageLevel = true; // flag for coordinate conversion
      existingLabels.push(node);
    }
  }
}

screens.sort((a, b) => a.x - b.x || a.y - b.y);

// labelTexts is an array of strings, one per screen (from Mode A or B)
// Mode A: use screen names directly. Mode B: use auto-detected labels from Step 6.
const labelTexts = /* Mode A */ screens.map(s => s.name);
// OR for Mode B: labelMap is built earlier from get_screenshot analysis
// const labelTexts = screens.map(s => labelMap.get(s.id) || s.name);

// Get section's absolute position (needed for page-level labels)
const sectionAbs = container.absoluteBoundingBox;

// Match existing labels to screens by x-proximity, then reuse them
const usedLabels = new Set();
const mutatedIds = [];

for (let i = 0; i < screens.length; i++) {
  const screen = screens[i];
  const newText = labelTexts[i];

  // Find the closest unused existing label
  let bestLabel = null;
  let bestDist = Infinity;
  for (const label of existingLabels) {
    if (usedLabels.has(label.id)) continue;
    const dist = Math.abs(label.x - screen.x);
    if (dist < bestDist) { bestDist = dist; bestLabel = label; }
  }

  if (bestLabel && bestDist < 2000) {
    // REUSE existing label — update text and reposition
    const fontName = bestLabel.fontName;

    // fontName returns a Symbol if the text has mixed fonts — can't reuse
    if (typeof fontName === "symbol" || fontName === figma.mixed) {
      // Mixed fonts — delete and create fresh
      bestLabel.remove();
      const label = figma.createText();
      label.fontName = { family: "Inter", style: "Medium" };
      label.fontSize = 70;
      label.characters = newText;
      label.fills = [{ type: "SOLID", color: { r: 1, g: 1, b: 1 } }];
      container.appendChild(label);
      label.x = screen.x;
      label.y = screen.y - 70 - label.height;
      mutatedIds.push(label.id);
      usedLabels.add(bestLabel.id);
    } else {
      // Load the EXACT font the existing label uses, not Inter
      await figma.loadFontAsync(fontName);
      if (bestLabel.characters !== newText) {
        bestLabel.characters = newText;
      }
      // Page-level labels use canvas-absolute coords
      if (bestLabel._pageLevel && sectionAbs) {
        bestLabel.x = sectionAbs.x + screen.x;
        bestLabel.y = sectionAbs.y + screen.y - 70 - bestLabel.height;
      } else {
        bestLabel.x = screen.x;
        bestLabel.y = screen.y - 70 - bestLabel.height;
      }
      usedLabels.add(bestLabel.id);
      mutatedIds.push(bestLabel.id);
    }
  } else {
    // CREATE new label only for screens with no matching existing label
    const label = figma.createText();
    label.fontName = { family: "Inter", style: "Medium" };
    label.fontSize = 70;
    label.characters = newText;
    label.fills = [{ type: "SOLID", color: { r: 1, g: 1, b: 1 } }];
    container.appendChild(label);
    label.x = screen.x;
    label.y = screen.y - 70 - label.height;
    mutatedIds.push(label.id);
  }
}

// Leftover labels with no matching screen — ask user before removing
const orphanedLabels = existingLabels.filter(l => !usedLabels.has(l.id));

return {
  reused: usedLabels.size,
  created: mutatedIds.length - usedLabels.size,
  orphaned: orphanedLabels.map(l => ({ id: l.id, text: l.characters })),
  mutatedNodeIds: mutatedIds
};

Font fallback: If Inter loading fails, try "Roboto" then "Arial". Inform the user which font was used.

Key rule: NEVER delete existing labels without explicit user consent. The code above reuses existing text nodes by updating .characters and repositioning. New text nodes are only created for screens that don't have a nearby existing label. Orphaned labels (no matching screen) are reported back — ask the user what to do with them.

Step 7: Validate Labels

Call get_screenshot on the section. Verify:

  • Labels appear above each screen, not overlapping
  • Label text is readable
  • Label spacing is consistent

Fix any issues before proceeding.

Step 8: Resize Section(s) to Fit Content

Calculate content bounds and resize. If sub-sections were created, resize each sub-section first, then the parent.

// Switch page first
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  if (figma.currentPage.findOne(n => n.id === "<childId>")) break;
}

// Resize a section to fit its content
function resizeToFit(section) {
  let maxX = 0, maxY = 0;
  for (const child of section.children) {
    const right = child.x + child.width;
    const bottom = child.y + child.height;
    if (right > maxX) maxX = right;
    if (bottom > maxY) maxY = bottom;
  }
  const padding = 100;
  section.resizeWithoutConstraints(maxX + padding, maxY + padding);
}

const parent = figma.getNodeById("<sectionId>");

// If sub-sections exist, resize each first
for (const child of parent.children) {
  if (child.type === "SECTION") resizeToFit(child);
}

// Then resize parent
resizeToFit(parent);

return { resized: true };

Step 9: Final Validation

Call get_screenshot on the full section/frame. Verify:

  • Screens aligned within each section/sub-section
  • Labels positioned above each screen with consistent gap
  • Sub-sections properly stacked and styled
  • No overlapping or clipped elements
  • All sections properly sized

Fix any issues before showing the user.

Step 10: Present Result

Show the user the final screenshot and summarize:

Done. Organized X screens into Y section(s) with labels.

Spacing defaults used:

  • Label gap: 70px | Screen gap: 200px | Padding: 100px

Want to adjust spacing, grouping, or layout direction?

Next step: Want to add dev notes? (I can invoke design-annotations)

If the user requests changes, re-run the relevant steps with updated values.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.