Figma Analyze

Purpose

Analyze an existing Figma component against Nexus conventions. Validates design-code parity, token usage, and AI readability. Outputs a focused issues list with fixes.

Input

Extract from URL:

• fileKey — from path segment after /design/
• nodeId — from node-id param, convert 123-456 → 123:456

Data Sources

Figma (via MCP)

mcp__figma__get_design_context(fileKey, nodeId)  → Props, structure, generated code
mcp__figma__get_variable_defs(fileKey, nodeId)   → Tokens/variables used
mcp__figma__get_metadata(fileKey, nodeId)        → Frame names, hierarchy
mcp__figma__get_screenshot(fileKey, nodeId)      → Visual reference (optional)

Nexus Token System

Read: packages/tailwind/nexus.css           → Semantic tokens (source of truth)
Read: .claude/rules/shadcn-divergences.md   → shadcn → Nexus mapping rules

shadcn Reference (if applicable)

WebFetch: https://ui.shadcn.com/r/styles/default/{component}.json

Workflow

Phase 1: Gather All Context

In parallel:

1. Figma Design — Call MCP tools to get:

   • Component properties (names, types, values)
   • Variables/tokens used
   • Frame names and layer hierarchy

2. Nexus Tokens — Read:

   • packages/tailwind/nexus.css — actual semantic tokens available
   • .claude/rules/shadcn-divergences.md — divergence rules

3. shadcn Reference (if base component identified):

   • Fetch from registry to compare props/variants

Phase 2: Run All Checks

Analyze Figma against Nexus conventions. Check each category and only note issues.

Check Categories

Divergence-Specific Checks

Cross-reference Figma variables against shadcn-divergences.md:

Token Existence Check

For each Figma variable, verify it exists in nexus.css:

Figma: color/primary-background → Check: --color-primary-background exists? ✓
Figma: color/accent-hover → Check: --color-accent-hover exists? ✗ (use background-hover)

Phase 3: Generate Report

Output a focused report with issues grouped by severity.

Output Format

markdown
1## Figma Analysis: {ComponentName}
2
3**Base:** {shadcn component or "Custom"}
4**Type:** {Simple | Compound}
5**Verdict:** {Ready | Needs Updates | Blocked}
6
7---
8
9### Issues
10
11#### Blocking (Must Fix)
12
13{If none: "None"}
14
151. **{Issue Title}**
16   - Location: `{property/layer/token name}`
17   - Current: `{what Figma has}`
18   - Expected: `{what it should be}`
19   - Why: {brief reason}
20
21#### Should Fix
22
23{If none: "None"}
24
251. **{Issue Title}**
26   - Location: `{property/layer/token name}`
27   - Current: `{what Figma has}`
28   - Expected: `{what it should be}`
29
30---
31
32### Token Mapping
33
34{Only show if there are token issues or divergences}
35
36| Figma Variable  | Nexus Equivalent | Status |
37| --------------- | ---------------- | ------ | --- | --- |
38| `{figma token}` | `{nexus token}`  | {✅    | ❌  | ⚠️} |
39
40---
41
42### Custom Additions
43
44{Only show if component has props/variants beyond shadcn base}
45
46| Addition | Type                | Convention | Notes |
47| -------- | ------------------- | ---------- | ----- | ------------ |
48| `{name}` | {Prop/Variant/Slot} | {✅        | ❌}   | {brief note} |
49
50---
51
52### Checklist
53
54- [{x| }] Property names match code
55- [{x| }] Property values lowercase
56- [{x| }] Layer names standard
57- [{x| }] Tokens exist in Nexus
58- [{x| }] No divergence violations
59- [{x| }] States defined (hover, focus, active, disabled)
60- [{x| }] Has component description

Severity Guidelines

Blocking

Issues that break code generation or cause runtime errors:

• Property name doesn't match code prop (case-sensitive)
• Token doesn't exist in Nexus (will fail compilation)
• Compound frame name doesn't match export
• Required prop missing

Should Fix

Issues that degrade quality but don't break builds:

• Non-standard layer names (affects AI readability)
• Missing description
• Using deprecated token names (still works but inconsistent)

Examples

Clean Report (No Issues)

markdown
1## Figma Analysis: Button
2
3**Base:** shadcn/button
4**Type:** Simple
5**Verdict:** Ready
6
7---
8
9### Issues
10
11#### Blocking (Must Fix)
12
13None
14
15#### Should Fix
16
17None
18
19---
20
21### Checklist
22
23- [x] Property names match code
24- [x] Property values lowercase
25- [x] Layer names standard
26- [x] Tokens exist in Nexus
27- [x] No divergence violations
28- [x] States defined (hover, focus, active, disabled)
29- [x] Has component description

Report with Issues

markdown
1## Figma Analysis: Button
2
3**Base:** shadcn/button
4**Type:** Simple
5**Verdict:** Needs Updates
6
7---
8
9### Issues
10
11#### Blocking (Must Fix)
12
131. **Invalid token reference**
14   - Location: `color/destructive-background`
15   - Current: `destructive-background`
16   - Expected: `error-background`
17   - Why: Nexus uses `error` naming, `destructive` tokens don't exist
18
192. **Property name mismatch**
20   - Location: Property `Size`
21   - Current: `Size` (PascalCase)
22   - Expected: `size` (lowercase)
23   - Why: Code prop is `size`, case-sensitive matching required
24
25#### Should Fix
26
271. **Non-standard layer name**
28   - Location: Layer `Button Text`
29   - Current: `Button Text`
30   - Expected: `Label`
31
322. **Missing component description**
33   - Location: Component description field
34   - Current: (empty)
35   - Expected: Description following format: "{What} — {Use case}. Variants: {list}."
36
37---
38
39### Token Mapping
40
41| Figma Variable                 | Nexus Equivalent             | Status    |
42| ------------------------------ | ---------------------------- | --------- |
43| `color/destructive-background` | `--color-error-background`   | ❌ Rename |
44| `color/destructive-foreground` | `--color-error-foreground`   | ❌ Rename |
45| `color/accent-hover`           | `--color-background-hover`   | ❌ Rename |
46| `color/primary-background`     | `--color-primary-background` | ✅        |
47
48---
49
50### Checklist
51
52- [ ] Property names match code
53- [x] Property values lowercase
54- [ ] Layer names standard
55- [ ] Tokens exist in Nexus
56- [ ] No divergence violations
57- [ ] Has component description

Error Handling

Key References