Frontend Craft

Definitive guide for building distinctive, production-grade Next.js applications with shadcn/ui and Tailwind CSS. Covers the full lifecycle: design philosophy → design system → component architecture → implementation → visual QA → deployment.

Subcommand Router

Arguments: $ARGUMENTS

Route based on first argument:

• •design → Read references/design-philosophy.md and references/design-system-tokens.md, then guide design system creation
• •build → Read references/shadcn-workflow.md, references/nextjs-architecture.md, references/tailwind-patterns.md, then implement
• •test → Read references/testing-visual-qa.md, then run visual QA workflow
• •team → Read workflows/team-implementation.md, then spawn 3-teammate team
• •setup → Read workflows/new-project-setup.md, then set up new project
• •(no argument) → Assess project state and determine which phase to start with

On trigger: Read this SKILL.md. Load reference files ONLY when their topic is needed.

1. Design Philosophy

Every interface needs a point of view. Before writing code, define the aesthetic direction.

Design Brief (fill before coding)

Purpose:      [What problem does this solve?]
Audience:     [Who uses this? Technical, consumer, enterprise?]
Tone:         [Pick ONE: minimal | luxury | brutalist | editorial | playful | organic | retro-futuristic | ...]
Differentiator: [What makes this memorable?]
Constraints:  [Framework, a11y level, perf budget]

Deep reference: references/design-philosophy.md — anti-generic principles, 12 tone directions, 10 font pairings with code, NEVER-use list, color theory.

2. Design System Architecture

The design system lives in CSS variables (globals.css) + components.json (shadcn config).

Token Hierarchy

Primitive     →  Semantic        →  Component
--blue-500       --primary           --button-bg
--gray-100       --muted             --card-bg
--space-4        --section-padding   --dialog-padding

Starter file: assets/globals-template.css — copy to app/globals.css and customize.

Deep reference: references/design-system-tokens.md — complete CSS variable list, color generation from brand color, typography scale, spacing system.

3. Component Workflow (MCP-First)

Use shadcn MCP tools to discover, inspect, and install components. This avoids blind CLI installs and lets you preview before committing.

7-Step Workflow

1. •Discover registries: mcp__shadcn__get_project_registries
2. •Browse components: mcp__shadcn__list_items_in_registries
3. •Search by need: mcp__shadcn__search_items_in_registries (e.g., "date picker")
4. •Inspect details: mcp__shadcn__view_items_in_registries
5. •View examples: mcp__shadcn__get_item_examples_from_registries
6. •Get install cmd: mcp__shadcn__get_add_command_for_items
7. •Install: Run the command via Bash

File Structure

components/
  ui/           ← shadcn primitives (DO NOT modify directly)
  [custom]/     ← composed wrappers (extend here)
features/
  [domain]/
    components/ ← feature-specific UI
    hooks/
    actions/

Rules: Never edit components/ui/* directly — create wrappers. Use cn() for class merging. Extend variants with cva().

Deep reference: references/shadcn-workflow.md — component categories, composition patterns (form+zod, data table, responsive dialog), block patterns.

4. Next.js Architecture

Default to Server Components. Only use 'use client' when you need hooks, event handlers, or browser APIs. Composition pattern: Server Component fetches data, passes to Client Component for interactivity.

Deep reference: references/nextjs-architecture.md — project structure, file conventions, server/client decision tree, data fetching, server actions, route organization, metadata/SEO, middleware.

5. Styling with Tailwind

• •Utility-first. Apply classes directly — no CSS files for component styles.
• •Mobile-first responsive. Base styles → sm: → md: → lg: → xl:
• •Dark mode via CSS variables. shadcn components handle dark mode automatically.
• •No inline styles. Use Tailwind utilities or cn() for everything.

Deep reference: references/tailwind-patterns.md — utility quick-ref, responsive patterns, dark mode strategies, cn() usage, Tailwind v4 @theme, performance rules.

6. Animation & Motion

Always respect prefers-reduced-motion. Use motion-safe: / motion-reduce: Tailwind variants.

Deep reference: references/animation-motion.md — Framer Motion patterns, anime.js v4 quick-ref (CRITICAL: v4 syntax only), performance rules.

7. Accessibility

shadcn/ui components (built on Radix UI) provide focus trapping, keyboard navigation, ARIA attributes, and roving tabindex automatically.

Your responsibility: Semantic HTML, proper headings hierarchy, alt text, sufficient contrast (4.5:1), visible focus indicators, prefers-reduced-motion respect.

Deep reference: references/accessibility-checklist.md — WCAG AA top 10, what Radix handles, keyboard patterns, 15-item shipping checklist.

8. Visual QA Testing

Test your UI using browser automation MCPs without leaving the conversation.

Quick Workflow: Start dev server → Navigate → Screenshot → Resize for responsive (375px, 768px, 1280px, 1920px) → Check console → Performance trace.

Deep reference: references/testing-visual-qa.md — full workflow with MCP tool names, device emulation, performance vitals (LCP/FID/CLS), interactive testing.

9. Agent Team Implementation

For large features (3+ pages, complex interactions), spawn a 3-teammate team:

TDD-for-UI Pipeline (per page)

1. •quality-lead defines visual acceptance criteria
2. •design-system-lead installs shadcn components, configures tokens
3. •ui-lead implements pages (blocked by step 2)
4. •quality-lead runs visual QA at 4 breakpoints (blocked by step 3)
5. •Fix owner addresses issues → quality-lead re-verifies

Deep reference: workflows/team-implementation.md — full spawn instructions, file ownership, task templates. Spawn prompts: workflows/spawn-prompts/ — self-contained prompts for each teammate.

10. New Project Checklist

Starting a new Next.js + shadcn/ui project? Follow workflows/new-project-setup.md:

1. •npx create-next-app@latest (TypeScript, Tailwind, App Router)
2. •npx shadcn@latest init (New York style, CSS variables)
3. •Copy assets/globals-template.css → customize brand colors
4. •Install core components (button, card, input, form, dialog, sonner)
5. •Set up ThemeProvider with next-themes
6. •Configure root layout (fonts, providers, metadata)
7. •Create directory structure (components/, features/, hooks/, types/)
8. •Verify: npm run dev → check dark mode, components, console

Common Issues

• •shadcn install fails: Run mcp__shadcn__get_project_registries first to verify components.json exists
• •Dark mode not working: Ensure ThemeProvider wraps app in root layout, and globals.css has .dark class variables
• •"use client" errors: Only add to components using hooks/events — default to Server Components
• •Tailwind classes not applying: Check content paths in tailwind.config (v3) or CSS imports (v4)
• •Hydration mismatch: Wrap theme-dependent UI in mounted check or use suppressHydrationWarning on <html>

MCP Quick Reference

Reference Navigation