figma-pencil-fsd-tailwind4

What this skill does

# Figma / Pencil to FSD + Tailwind 4

Turn design files into code without breaking the host repository's architecture, design system, or accessibility guarantees. This skill is framework-agnostic; the rules below apply equally to any modern React stack and degrade gracefully when optional pieces (RSC, primitive library, FSD linter) are missing.

## Assumptions

This skill works in any frontend repository that satisfies:

- A modern component-based framework (React, or any framework with a comparable component model).
- Tailwind CSS. Token rules target v4 (CSS-first, `@theme`, OKLCH). For v3 projects, fall back to the project's existing config and skip v4-only sections.
- Feature-Sliced Design (or a comparable layered architecture). Layer names may vary by repository; the canonical names are `app`, `pages`, `widgets`, `features`, `entities`, `shared`.
- A primitive component library is optional. When one is present (shadcn/ui, Radix, Mantine, Headless UI, or any in-house design system), reuse it instead of re-implementing primitives.
- Server / Client component split is optional. The RSC guidance applies only when the project uses a framework with that distinction.

If any assumption does not hold, defer to the host repository's contract first.

## Workflow

1. Check for a repository contract before generating code. See `references/project-contracts.md`. Local rules override every default in this skill.
2. Scope the work to one frame, screen, or component. Refuse "translate the whole file".
3. Analyze the design: tokens, components, layout intent, repeated patterns, states.
4. Decompose into FSD layers on paper before writing code. Decide Server vs Client boundaries only if the host framework uses them. See `references/fsd-mapping.md` and `references/rsc-boundaries.md`.
5. Reconcile design variables with project tokens. Do not silently add new tokens. See `references/tailwind-tokens.md`.
6. Reuse existing primitives from the project's component library before creating new ones in `shared/ui`.
7. Generate code layer by layer: `shared` primitives → `entities` → `features` → `widgets` → `pages` → `app-shell` (when present) → `app`. Keep route entries thin.
8. Implement every state shown in the design plus the standard ones: default, hover, focus-visible, active, disabled, loading, empty, error.
9. Verify accessibility against `references/accessibility-checklist.md`.
10. Run the validation checklist below before reporting the task complete.

## Layer mapping (summary)

Detailed rules in `references/fsd-mapping.md`.

- `shared` — primitives, tokens, helpers, formatters, API clients, hooks, types.
- `entities` — domain models and small domain UI.
- `features` — user actions and interactive flows.
- `widgets` — large composed sections reused across pages.
- `pages` — page composition only.
- `app-shell` (optional) — persistent layout frame around multiple pages (public or authenticated).
- `app` — route entry points, providers, global styles.

When a component could belong to more than one layer, pick the highest reusable layer that does not violate import direction.

## Server vs Client (when applicable)

Skip this section entirely if the host framework does not have a Server/Client component split. Detailed rules in `references/rsc-boundaries.md`.

- Default to Server Components.
- Mark a component as client only when it needs state, refs, effects, event handlers, or browser-only APIs.
- Push the client marker to the smallest possible leaf, never to a whole page or shell.
- Data fetching belongs on the server side (page-level fetch, server actions), not in client-side effects when a server fetch is possible.

## Design analysis rules

- Identify what is repeated, global, or page-specific.
- Map every design variable to an existing semantic token. Flag mismatches for design review — do not invent tokens.
- Respect auto layout, naming, and component reuse in the source design.
- Prefer the smallest accurate scope: selected frame, selected screen, or selected component.
- Do not generate code until the design is decomposed into tokens, blocks, layers, and (if applicable) Server/Client boundaries.
- Produce a short implementation plan before code generation when the design is non-trivial.

## Figma path

Detailed rules in `references/figma-mcp-workflow.md`.

- Prefer MCP-extracted context: variables, components, layout, selected node tree, local assets.
- Reuse project components and Code Connect mappings when available.
- Use local asset URLs from the MCP payload directly. Do not invent placeholders when real assets are present.
- Translate auto layout into Flexbox utilities, not absolute positioning.

## Pencil path

Detailed rules in `references/pencil-workflow.md`. This path is experimental compared to Figma MCP.

- Keep the `.pen` file in the same workspace as the code, under version control when it is source of truth.
- Reuse Pencil variables and components before inventing new values.
- Generate code from a structured plan, then refactor into FSD layers. Do not commit single-component dumps.

## Tailwind 4 rules

Detailed rules in `references/tailwind-tokens.md`.

- Tokens live in a single global stylesheet under `@theme { ... }`. No JS-side `theme.extend` in v4 projects.
- Use semantic tokens for colors, spacing, radius, typography, shadows. Pair every fill token with its `*-foreground` counterpart.
- Each meaning resolves to exactly one token. No `primary-2`, `surface-alt` drift.
- Never add a new token without explicit design-system approval. For one-offs use arbitrary values (`bg-[oklch(...)]`) and leave a `TODO(design)` comment.
- Light and dark themes share token names; override values inside a `.dark` selector (or the project's chosen dark variant).
- Inline `style={{ ... }}` is allowed only for values that cannot be known at author time (dynamic position, scroll-driven values, animated values). Static styling always goes through utilities.
- Do not introduce custom CSS files unless the project contract requires them.

## Accessibility rules

Detailed rules in `references/accessibility-checklist.md`. Mandatory on every design-to-code task.

- Native semantic HTML first. `<button>` for actions, `<a>` for navigation, `<form>` with labels.
- Every interactive element is keyboard-reachable with a visible `focus-visible` ring.
- Icon-only buttons carry `aria-label`. Images carry `alt`.
- Contrast at minimum 4.5:1 for body text, in both light and dark themes.
- Composite widgets (dialog, menu, tabs, combobox) come from a tested primitive library, not hand-rolled ARIA.

## Validation checklist

Each item must be verifiable. If you cannot verify it, say so explicitly.

- FSD import direction holds. Verify with the project's linter (ESLint, Steiger, dependency-cruiser, or equivalent) or by grepping imports from `shared/**` upward.
- `shared` imports nothing from higher layers.
- Route entry files contain composition only, no business logic.
- Shell logic does not leak page-specific behavior.
- Repeated UI has been extracted to `shared`, `entities`, `widgets`, or `features` as appropriate.
- Server/Client boundaries (when applicable) are correct: the client marker is on the smallest possible leaf, data fetching is on the server.
- Every required state is implemented: default, hover, focus-visible, active, disabled, loading, empty, error.
- Responsive behavior matches the breakpoints provided by the design. Assumptions are documented when the design covers only one breakpoint.
- Tokens are used instead of copied literals. No raw hex/oklch in components except marked one-offs.
- Accessibility checklist passes. Run an automated tool when available (axe, Lighthouse, or equivalent) plus a manual keyboard pass.
- Repo-specific architecture rules (`project-contracts.md`) have been checked and respected.
- Project commands pass: type-check, lint, and unit tests for affected files. Use the project's actual commands; do not invent.

## References

Read these when