Implement Figma → Next.js 16 + shadcn/ui

Files (7)

• SKILL.md
• button-base-component.tsx · examples/
• base-vs-template.md · references/
• subagent-specs.md · references/
• token-chain-rules.md · references/
• IMPLEMENTATION_REPORT.template.md · templates/
• figma-project.local.example.md · templates/

SKILL.md (first lines)

# Implement Figma → Next.js 16 + shadcn/ui

## Purpose

Convert Figma designs from the Ureca Shadcn team library into production-ready
Next.js 16 + shadcn/ui component code with deterministic token chain resolution,
Light/Dark mode fidelity, and visual verification.

## Three Immutable Rules

These rules apply to every implementation without exception:

1. **`codeSyntax.WEB` is the only canonical key** — never use `codeSyntax.ANDROID`, raw hex, or
   variable names directly as class names
2. **Token resolution order: `usage → semantic → primitive`** — always trace the full chain
   before falling back to raw values
3. **Mode branching only in `semantic` collection** — Light/Dark splits happen exclusively at the
   semantic layer; primitives are mode-neutral

Violation of any of these rules is a defect, not a style choice.

---

## Step 1: Verify Figma MCP Connection

Confirm `mcp__figma__get_metadata` is callable before doing anything else. If the tool is
unavailable, stop immediately and inform the user:

> "Figma MCP가 이 세션에서 연결되어 있지 않습니다. ~/.claude/mcp.json 또는 프로젝트
> .mcp.json에 Figma MCP 설정을 확인해주세요."

Do not attempt any Figma reads without MCP access.

---

## Step 2: Parse Figma Input

Extract `fileKey` and `nodeId` from the user input:

- `figma.com/design/:fileKey/:title?node-id=:nodeId` → convert `-` to `:` in nodeId
- `figma.com/design/:fileKey/branch/:branchKey/...` → use branchKey as fileKey
- `figma.com/make/:makeFileKey/:title` → use makeFileKey as fileKey
- If only fileKey given without nodeId → ask the user which node to implement before continuing

---

## Step 3: Read Figma Data

Call all four tools before analysis — do not interleave reads with interpretation:

```
1. mcp__figma__get_metadata(fileKey, nodeId)
   → node name, type, parent frame, dimensions

2. mcp__figma__get_variable_defs(fileKey)
   → all variable collections: usage / semantic / primitive + codeSyntax.WEB for each

3. mcp__figma__get_design_context(fileKey, nodeId)
   → component structure, boundVariables, named styles, fills, strokes, effects

4. mcp__figma__get_screenshot(fileKey, nodeId)
   → visual reference image (save URL/path for fidelity reviewer)
```

**MCP Error Handling:**

If any individual tool call fails:
- `get_metadata` fails → stop; node cannot be identified. Report error and ask user to verify the URL.
- `get_variable_defs` fails → continue without token data. Mark all tokens as unresolved. Use raw values only and note in report.
- `get_design_context` fails → stop; component structure cannot be determined. Report error to user.
- `get_screenshot` fails → continue. Note "automated fidelity review unavailable" in IMPLEMENTATION_REPORT.md.

---

## Step 4: Classify Node — Base Component or Template

Determine the node type before generating any code. See `references/base-vs-template.md`
for full criteria.

**Base component signals:**
- Lives in a component set or is a main component in the team library
- Single, well-defined interaction pattern (Button, Input, Badge, Select, etc.)
- Has defined component properties (variant, size, disabled, icon booleans)

**Template / Example signals:**
- Frame named "Example", "Preview", "Usage", "Demo", "Playground", or similar
- Composition of multiple base components arranged in a page-like layout
- Contains placeholder text, sample data, or lorem ipsum
- No component properties defined

If classified as **template/example**, report before proceeding:

> "⚠️ 이 노드는 base library component가 아닌 example/template composition입니다.
> 포함된 base component: [list]
> 각 base component를 개별 구현할지, 전체 composition을 구현할지 선택해주세요."

Wait for explicit user confirmation.

---

## Step 5: Resolve Token Chain

For every visual property (fill, stroke, effect, spacing, radius, typography):

**Resolution priority:**

```
1. boundVariables → follow variable ID to get_variable_defs entry
   └─ check codeSyntax.WEB → usage alias (e.g. "bg-background") → USE DIRECTLY

2. If codeSyntax.WEB points to another variable (alias chain):
   └─ resolve to semantic variable → check semantic collection modes
      ├─ Light mode value: semantic → primitive → codeSyntax.WEB
      └─ Dark mode value: same path via dark mode entry

3. Named text/effect styles → use style's codeSyntax.WEB

4. Raw fills/strokes/effects → use inline value + mark as "raw: no token binding"
```

From ureca-corp/claude, MIT.

More from ureca-corp/claude