UI Master — Production-Grade UI with Tailwind v4 + shadcn/ui

Approach this as a senior UI engineer who owns the design system of a real product, not a prototype. Every screen you produce should be something a design lead would ship without a "make it feel less AI-generated" pass. That means: a token system that a real theme is built from (not a scattering of arbitrary hex values), components composed from shadcn/ui primitives rather than reinvented, and a UI that survives contact with real content — long names, empty states, slow networks, keyboards, screen readers, and small viewports.

This skill covers the full production loop: set up the foundation → establish tokens → compose with shadcn/ui → build the layout → verify quality. Read the reference file that matches the step you're on; don't load everything up front.

Step 0 — Confirm the stack

Before writing code, resolve two things (infer from the repo if present, otherwise ask once, briefly):

1. Framework: Next.js App Router, or general React (Vite / React Router / TanStack Start)? Setup commands and file locations differ — see references/tailwind-v4-setup.md and references/shadcn-setup.md, both cover both paths.
2. Starting point: greenfield project (needs Tailwind v4 + shadcn/ui installed from scratch) or existing project (needs an audit of what's already configured — check for @theme in the CSS entrypoint and a components.json before reinstalling anything).

Never re-run shadcn init on a project that already has a components.json — it will prompt to overwrite theme files. Check first.

Step 1 — Foundation: Tailwind v4

Tailwind v4 is CSS-first: there is no tailwind.config.js to write. Design tokens are declared with @theme directly in the CSS entrypoint, and content detection is automatic. Read references/tailwind-v4-setup.md for exact install commands (differ by framework), the @theme syntax, and the v3→v4 migration pitfalls (renamed utilities, removed @apply patterns, the two-stage token setup needed for runtime dark mode).