figma-analyze

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

| Format | Example | Detection | | -------------------- | ------------------------------------------------------------- | ----------- | | Figma URL | https://figma.com/design/:fileKey/:fileName?node-id=123-456 | URL pattern | | Component name + URL | Button https://figma.com/... | Name + URL |

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:
2. Component properties (names, types, values)
3. Variables/tokens used
4. Frame names and layer hierarchy

1. Nexus Tokens — Read:
2. packages/tailwind/nexus.css — actual semantic tokens available
3. .claude/rules/shadcn-divergences.md — divergence rules

1. shadcn Reference (if base component identified):
2. 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

| Category | What to Check | | ---------------------- | -------------------------------------------------------------------- | | Property Names | Match code props exactly (variant not Style, size not Scale) | | Property Values | Lowercase (sm, md not Small, Medium) | | Boolean Props | Use has*/is* prefix (hasLeadingIcon not showIcon) | | Layer Names | Standard names (Label, LeadingIcon, TrailingIcon, Spinner) | | Token Usage | Semantic Nexus tokens, no hardcoded values or primitives | | Token Naming | Follows Nexus patterns (see divergence checks below) | | States | Component includes hover, focus, active, disabled states as needed | | Description | Component has AI-readable description | | Compound Structure | Frame names match code exports (PascalCase, no spaces) |

Divergence-Specific Checks

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

| Figma Uses | Should Be | Rule | | ----------------------- | ----------------------------- | ----------------------------- | | destructive/ | error/ | Nexus uses error naming | | accent/ | background-hover or muted | Accent removed in Nexus | | card/ | container/ | Renamed in Nexus | | primary (no suffix) | primary-background | Explicit -background suffix | | hover:/90 or opacity | *-background-hover | Semantic hover tokens | | border-input | border-default | Renamed in Nexus |

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

## Figma Analysis: {ComponentName}

**Base:** {shadcn component or "Custom"}
**Type:** {Simple | Compound}
**Verdict:** {Ready | Needs Updates | Blocked}

---

### Issues

#### Blocking (Must Fix)

{If none: "None"}

1. **{Issue Title}**
   - Location: `{property/layer/token name}`
   - Current: `{what Figma has}`
   - Expected: `{what it should be}`
   - Why: {brief reason}

#### Should Fix

{If none: "None"}

1. **{Issue Title}**
   - Location: `{property/layer/token name}`
   - Current: `{what Figma has}`
   - Expected: `{what it should be}`

---

### Token Mapping

{Only show if there are token issues or divergences}

| Figma Variable  | Nexus Equivalent | Status |
| --------------- | ---------------- | ------ | --- | --- |
| `{figma token}` | `{nexus token}`  | {✅    | ❌  | ⚠️} |

---

### Custom Additions

{Only show if component has props/variants beyond shadcn base}

| Addition | Type                | Convention | Notes |
| -------- | ------------------- | ---------- | ----- | ------------ |
| `{name}` | {Prop/Variant/Slot} | {✅        | ❌}   | {brief note} |

---

### Checklist

- [{x| }] Property names match code
- [{x| }] Property values lowercase
- [{x| }] Layer names standard
- [{x| }] Tokens exist in Nexus
- [{x| }] No divergence violations
- [{x| }] States defined (hover, focus, active, disabled)
- [{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)

## Figma Analysis: Button

**Base:** shadcn/button
**Type:** Simple
**Verdict:** Ready

---

### Issues

#### Blocking (Must Fix)

None

#### Should Fix

None

---

### Checklist

- [x] Property names match code
- [x] Property values lowercase
- [x] Layer names standard
- [x] Tokens exist in Nexus
- [x] No divergence violations
- [x] States defined (hover, focus, active, disabled)
- [x] Has component description

Report with Issues

## Figma Analysis: Button

**Base:** shadcn/button
**Type:** Simple
**Verdict:** Needs Updates

---

### Issues

#### Blocking (Must Fix)

1. **Invalid token reference**
   - Location: `color/destructive-background`
   - Current: `destructive-background`
   - Expected: `error-background`
   - Why: Nexus uses `error` naming, `destructive` tokens don't exist

2. **Property name mismatch**
   - Location: Property `Size`
   - Current: `Size` (PascalCase)
   - Expected: `size` (lowercase)
   - Why: Code prop is `size`, case-sensitive matching required

#### Should Fix

1. **Non-standard layer name**
   - Location: Layer `Button Text`
   - Current: `Button Text`
   - Expected: `Label`

2. **Missing component description**
   - Location: Component description field
   - Current: (empty)
   - Expected: Description following format: "{What} — {Use case}. Variants: {list}."

---

### Token Mapping

| Figma Variable                 | Nexus Equivalent             | Status    |
| ------------------------------ | ---------------------------- | --------- |
| `color/destructive-background` | `--color-error-background`   | ❌ Rename |
| `color/destructive-foreground` | `--color-error-foreground`   | ❌ Rename |
| `color/accent-hover`           | `--color-backg