FerranGuardia/frontend-craft

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

| Approach | Use When | |----------|----------| | CSS/Tailwind | Hover, focus, state transitions | | Framer Motion | Page transitions, layout animations, gestures | | anime.js v4 | Complex orchestrated sequences, SVG, scroll-triggered |

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:

| Role | Owns | |------|------| | design-system-lead | globals.css, layout.tsx, components/ui/*, tailwind.config.* | | ui-lead | app/(routes)/**, components/*, features/**/components/**, hooks/** | | quality-lead | __tests__/**, *.test.*, screenshots | | Lead (you) | components.json, package.json, tsconfig.json, types/** |

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

| MCP Server | Key Tools | Use For | |------------|-----------|---------| | shadcn | get_project_registries, list_items_in_registries, search_items_in_registries, view_items_in_registries, get_add_command_for_items, get_audit_checklist | Component discovery, installation, audit | | Chrome DevTools | navigate_page, take_screenshot, resize_page, emulate, evaluate_script, list_console_messages, performance_* | Visual QA, responsive testing, performance | | Claude-in-Chrome | navigate, read_page, form_input, computer, get_page_text | Interactive testing, form filling, page reading | | Ref | ref_search_documentation, ref_read_url | Look up Next.js, Tailwind, Radix docs |

---

Reference Navigation

| Need to... | Read | |------------|------| | Define aesthetic direction, pick fonts | references/design-philosophy.md | | Configure CSS variables, tokens, colors | references/design-system-tokens.md | | Structure Next.js app, routing, data fetching | references/nextjs-architecture.md | | Find and install shadcn components | references/shadcn-workflow.md | | Tailwind utility classes, responsive, dark mode | references/tailwind-patterns.md | | Add animations and motion | references/animation-motion.md | | Check accessibility requirements | references/accessibility-checklist.md | | Run visual QA tests | references/testing-visual-qa.md | | Set up a new project | workflows/new-project-setup.md | | Spawn implementation team | workflows/team-implementation.md |