apps/v4/registry/new-york-v4/examples/{component}-{pattern}.tsx

mcp__github__get_file_contents(
  owner: "shadcn-ui",
  repo: "ui",
  path: "apps/v4/registry/new-york-v4/examples/{component}-{pattern}.tsx"
)

Read: packages/tailwind/CLAUDE.md              # Token system overview
Read: packages/tailwind/nexus.css              # Semantic tokens (@theme block)
Read: packages/tailwind/variables.css          # Primitive tokens (--nx-*)
Read: packages/tailwind/typography-utilities.css  # Typography classes
Read: .claude/rules/shadcn-divergences.md      # shadcn → Nexus divergences

## 🎨 Figma Blueprint: {ComponentName}

---

### Phase 1: Understand the Component

| Aspect                   | Value              |
| ------------------------ | ------------------ |
| **Type**                 | Simple / Compound  |
| **Radix Primitive**      | {if applicable}    |
| **shadcn Reference**     | [Link](url)        |
| **Nexus Implementation** | {exists / not yet} |

{If component has dependencies, include:}

**⚠️ Required Components:**

This component depends on: **{Component1}**, **{Component2}**, **{Component3}**

Ensure these components exist in your Figma library before proceeding. If not, build them first.

---

**Component Description** (copy to Figma):

> {What it is} — {Primary use case}. {Key behavior}.
> **Variants:** {list}. **States:** {list}.

{For compound components, include description for each part:}

| Part                       | Description                  |
| -------------------------- | ---------------------------- |
| **{ComponentName}**        | {Root container description} |
| **{ComponentName}Trigger** | {Trigger description}        |
| **{ComponentName}Content** | {Content description}        |

---

### Phase 2: Create Frame Structure

Build this layer hierarchy in Figma.

> **Note:** Output ONLY the structure that matches the component type (simple OR compound, not both).

**Simple Component:**

```
{ComponentName} (Component Set)
└── variant=primary, size=md (Default Frame)
    ├── LeadingIcon (Instance) ← optional slot
    ├── Label (Text) ← primary text
    ├── TrailingIcon (Instance) ← optional slot
    └── Spinner (Instance) ← shown when loading=true
```

**Compound Component:**

```
{ComponentName} (Documentation Frame)
├── {ComponentName}Item (Component Set) ← separate component
│   └── isExpanded=false/true
│       ├── {ComponentName}Trigger (Component) ← separate component
│       │   ├── Label (Text)
│       │   └── Chevron (Instance)
│       └── {ComponentName}Content (Component) ← separate component
│           └── ContentFrame (Frame)
```

> **Important:** Each part exported in code must be a **separate Figma component** (not just a frame). This allows independent composition, just like React.

**Standard Layer Names:**

| Purpose          | Name           |
| ---------------- | -------------- |
| Primary text     | `Label`        |
| Secondary text   | `Description`  |
| Left icon slot   | `LeadingIcon`  |
| Right icon slot  | `TrailingIcon` |
| Expand indicator | `Chevron`      |
| Loading spinner  | `Spinner`      |
| Selection mark   | `Indicator`    |
| Dismiss action   | `CloseButton`  |

**Icon Instance Naming:** Use PascalCase matching code imports (e.g., `IconMail`, `IconChevronDown`, not `mail-icon`).

---

### Phase 3: Set Up Properties

Create these component properties in Figma:

| Property          | Type          | Values                                                | Default |
| ----------------- | ------------- | ----------------------------------------------------- | ------- |
| `variant`         | Variant       | primary, secondary, outline, ghost, destructive, link | primary |
| `size`            | Variant       | sm, md, lg, icon                                      | md      |
| `disabled`        | Boolean       | true/false                                            | false   |
| `loading`         | Boolean       | true/false                                            | false   |
| `hasLeadingIcon`  | Boolean       | true/false                                            | false   |
| `leadingIcon`     | Instance Swap | Icon library                                          | —       |
| `hasTrailingIcon` | Boolean       | true/false                                            | false   |
| `trailingIcon`    | Instance Swap | Icon library                                          | —       |

**State Properties:**

| State    | Implementation                              |
| -------- | ------------------------------------------- |
| Hover    | Background/border color change              |
| Focus    | Focus ring visible                          |
| Active   | Pressed/darker background                   |
| Disabled | `disabled` boolean → reduced opacity        |
| Loading  | `loading` boolean → show Spinner, hide icon |

---

### Phase 4: Apply Design Tokens

Use Figma variables for all values. Map shadcn tokens to Nexus equivalents.

**Spacing & Layout:**

| Element       | Figma Variable      |
| ------------- | ------------------- |
| Padding X     | `spacing/spacing-4` |
| Padding Y     | `spacing/spacing-2` |
| Gap           | `spacing/spacing-2` |
| Border Radius | `radius/md`         |

**Colors (with shadcn → Nexus mapping):**

| Element     | shadcn Token              | Nexus Figma Variable        |
| ----------- | ------------------------- | --------------------------- |
| Background  | `bg-primary`              | `color/primary-background`  |
| Text        | `text-primary-foreground` | `color/primary-foreground`  |
| Hover       | `hover:bg-primary/90`     | `color/primary-hover` ⚡    |
| Active      | `active:bg-primary/80`    | `color/primary-active` ⚡   |
| Border      | `border-input`            | `color/border-default`      |
| Destructive | `bg-destructive`          | `color/error-background` ⚡ |
| Dest. Hover | `hover:bg-destructive/90` | `color/error-hover` ⚡      |

⚡ = Nexus divergence (we use semantic tokens instead of opacity)

{If any token is missing from Nexus, include:}

**⚠️ Tokens Needed:**

- `{token-name}` — {what it's used for}

**Typography:**

| Element    | Figma Style     |
| ---------- | --------------- |
| Body text  | `body/default`  |
| Small text | `body/small`    |
| Label      | `label/default` |

**Auto Layout:**

| Setting   | Value       |
| --------- | ----------- |
| Direction | Horizontal  |
| Align     | Center      |
| Gap       | `spacing-2` |

---

### Phase 5: Build All Variants

**Variant × Size Matrix:**

| Variant     | sm  | default | lg  | icon |
| ----------- | --- | ------- | --- | ---- |
| default     | ○   | ●       | ○   | ○    |
| secondary   | ○   | ○       | ○   | ○    |
| outline     | ○   | ○       | ○   | ○    |
| ghost       | ○   | ○       | ○   | ○    |
| destructive | ○   | ○       | ○   | ○    |
| link        | ○   | ○       | ○   | —    |

● = Start here (default), ○ = Build after, — = Not applicable

---

### Phase 6: Review Examples

Build all usage patterns shown on the shadcn examples page:

**→ [View Examples](https://ui.shadcn.com/create?item={component}-example)**

Review this page and ensure your Figma component supports all patterns shown:

- Basic usage
- With icons (leading, trailing, icon-only)
- Size variations
- Loading states
- Disabled states
- Variant combinations

Create example compositions in Figma that mirror each pattern.

---

### ✅ Verification Checklist

Before handoff, verify:

**Structure:**

- [ ] Frame names use PascalCase matching React exports (`Button`, not `button`)
- [ ] Layer hierarchy mirrors React composition
- [ ] Child layers use standard names (`Label`, `LeadingIcon`, `TrailingIcon`)

**Properties:**

- [ ] Property names match code exactly (`variant`, `size` — not `Style`, `Scale`)
- [ ] Property values are lowercase (`sm`, `md` — not `Small`, `Medium`)
- [ ] Boolean properties use `has*` or `is*` prefix
- [ ] Optional slots have both boolean toggle + instance swap

**Tokens:**

- [ ] All spacing uses `spacing-{n}` variables (no hardcoded px)
- [ ] All colors use semantic tokens (`primary-background`, not `blue-500`)
- [ ] Border radius uses named tokens (`md`, `lg`)

**States:**

- [ ] Hover state shows visual feedback (background/border change)
- [ ] Focus state shows focus ring
- [ ] Active state shows pressed appearance
- [ ] Disabled uses boolean property with reduced opacity
- [ ] Loading shows Spinner, hides icon content

**AI Readability:**

- [ ] Component has description in Figma description field
- [ ] Icon instances use PascalCase names (`IconMail`, not `mail-icon`)