---
description: Figma design fidelity and design-to-code workflow
globs:
  - "**/*.{tsx,jsx}"
  - "**/*.{css,scss}"
alwaysApply: true
---

# Figma Design Fidelity

**Assumes:** Design handoff via Figma or an equivalent written spec. Works with `react-styling`, `react-shadcn-components`, `react-ui-decisions`, and `react-responsive-design` when installed.

## The rule

**Build what the Figma (or agreed written spec) shows—not more, not less—unless the user explicitly approves a deviation.**

Every **new** screen or component should trace to a **named frame / component** in Figma or an equivalent spec. If it is not specified, it is **out of scope** until clarified (see **exceptions** below).

## What this means in practice

- Do **not** add UI (decorative or functional) that is **absent** from the design.
- Do **not** remove or **reposition** elements because they seem redundant—**follow the design**.
- Do **not** change **spacing, sizing, colours, typography, or layout** unless the design (or an explicit written override) shows a different treatment.
- Do **not** assume **hover, empty, error, loading (beyond skeleton), or disabled** states—if they are missing in Figma, **ask**.
- Do **not** change **copy**: button labels, headings, table columns, nav items, etc., vs the design without approval.

## Permitted without Figma links

| Element | Implementation |
|--------|----------------|
| **Toast messages** | Use the project’s **existing** toast system only—do not add a parallel toast library for standard cases. |
| **Loading / skeleton** | Use the project’s **Skeleton** (or equivalent) primitive, or the **existing** feature-specific skeleton used in that area. |

Do **not** invent alternate toast or loading UX for standard cases.

## Working with Figma links

When a link (or file + node) is provided:

1. **Inspect the design** (Figma UI or MCP / design context) **before** coding; note frames, **variants**, and **states** shown.
2. **Map** each Figma component to existing UI primitives or feature components; flag gaps before inventing new primitives (see `react-shadcn-components`).
3. **Translate** spacing and sizing from Figma to **Tailwind** using the **nearest** theme tokens (see `react-styling`).
4. If a Figma value has **no** matching token or scale in the theme CSS, **stop and flag it**—extend the theme with agreement, rather than hardcoding arbitrary literals in JSX.

## Missing or ambiguous designs

**Stop and ask** when:

- No Figma (or equivalent spec) exists for a **new** screen or component.
- The file is **incomplete**, **ambiguous**, or **contradicts** existing product UI.
- **Responsive** behaviour is required but **no** mobile/tablet frame (and no written breakpoint spec) exists (see `react-responsive-design`).
- The design shows a pattern **not** representable with current primitives and this was **not** discussed—do not silently ship a one-off.

## Accessibility and Figma

Visual specs must still meet `react-accessibility` (contrast, labels, keyboard). If the design conflicts with WCAG, **flag it** and resolve with design/product before shipping inaccessible UI.