/component-rules

name: component-rules
description: "Triggers when building any UI element in Figma — 'create a card', 'build a nav', 'add a section', 'make a component'. Enforces library-first component lookup, correct Auto Layout structure, and semantic node naming. For visual property binding (colors, text styles, spacing values), defer to figma-style-binding."
disable-model-invocation: false

Component Rules

Governs how Claude constructs UI in Figma. Supplements `figma-generate-design`. For visual property binding, defer to `figma-style-binding`.

---

Rule 1 — Library-first hierarchy

Before building anything, resolve the component source in this order:

1. search_design_system → importComponentByKeyAsync → createInstance()
2. Local file scan → createInstance()
3. Build from scratch — ONLY if nothing matches

Never rebuild primitives the DS provides: Button, Input, Checkbox, Toggle, Badge, Tag, Avatar, Icon, Tab, Breadcrumb, Toast, Alert, Spinner.

// Library import
const comp = await figma.importComponentByKeyAsync("key_from_search");
const instance = comp.createInstance();
parent.appendChild(instance);

// For component sets (variants)
const set = await figma.importComponentSetByKeyAsync("key");
const instance = set.defaultVariant.createInstance();

---

Rule 2 — Auto Layout

Every container must use Auto Layout. Property order matters:

1. Set `layoutMode` FIRST (`"VERTICAL"` or `"HORIZONTAL"`) 2. Set `layoutSizingHorizontal` / `layoutSizingVertical` AFTER `appendChild` 3. Set `layoutMode` BEFORE any `setBoundVariable` call

| Goal | primaryAxisSizing | counterAxisSizing | layoutSizingH | layoutSizingV | |---|---|---|---|---| | Hug both | AUTO | AUTO | HUG | HUG | | Fixed card | FIXED | FIXED | FIXED | FIXED | | Full-width section | AUTO | FIXED | FILL | HUG |

---

Rule 3 — Node naming

Name every node semantically with slash hierarchy. Never leave defaults.

Card / Container    Card / Title    Card / Body    Card / Action Row
Hero / Background   Nav / Link Group   Button / Primary

---

Rule 4 — Incremental building

One section per `use_figma` call. Validate via screenshot after each step. Return all created/mutated node IDs:

return { created: { card: card.id, title: title.id } };