frontend-refactor

name	frontend-refactor
description	Refactor any frontend into a modern, production-grade interface using shadcn/ui, Tailwind CSS, and Radix UI. Covers design philosophy, token systems, component architecture (atomic design), layout patterns, progress feedback tiers, error/empty states, animation standards, dark mode, and a 10-step refactoring process with deliverables checklist.
user-invokable	true
args	[{"name":"target","description":"The project or area to refactor (optional)","required":false}]

First: Use the frontend-design skill for design principles and anti-patterns.

Your task is to refactor the frontend into a modern, production-grade interface built on shadcn/ui components with Tailwind CSS and Radix UI primitives.

1. Design Philosophy

Core Principles

• Consistency Is Trust. Every element behaves predictably across the entire application.
• Clarity Over Cleverness. Every screen answers: "Where am I?", "What can I do here?", "What just happened?"
• Progressive Disclosure. Show only what's needed at each moment.
• Feedback Is Mandatory. Every user action produces immediate, visible feedback.
• Accessibility Is Non-Negotiable. WCAG 2.1 AA. Keyboard navigation, screen reader support, proper ARIA, sufficient contrast, focus management, reduced-motion support.
• Mobile-First, Responsive Always. Functional and attractive from 320px to 2560px.
• Performance Is a Feature. Lazy-load, code-split, skeleton states over spinners.

Material Design Alignment (Without Material Dependency)

Apply these principles using shadcn/ui + Tailwind — no Material UI imports:

• Elevation & Depth: Consistent shadow scales communicating hierarchy.
• Motion with Purpose: Every animation guides attention or communicates state change.
• Surface & Container Hierarchy: Background colors, borders, and shadows distinguish layers.
• Intentional Density: Dense for dashboards, comfortable for forms.

2. shadcn/ui Component System

Design Token System

:root {
  --radius: 0.625rem;
  --background: ;
  --foreground: ;
  --card: ;
  --primary: ;
  --secondary: ;
  --muted: ;
  --accent: ;
  --destructive: ;
  --border: ;
  --input: ;
  --ring: ;
  --success: ;
  --warning: ;
  --info: ;
  --duration-fast: 100ms;
  --duration-normal: 200ms;
  --duration-slow: 300ms;
}

Rules:

• Zero arbitrary values. No text-[13px], no p-[7px], no bg-[#3a7fc2].
• Theme-aware colors only. Use text-foreground, bg-primary, etc. Never raw Tailwind colors.
• Consistent spacing increments. Pick a base unit (4px or 8px) and stick to it.

3. Layout Architecture

Application Shell

┌─────────────────────────────────────────────────────────┐
│  Top Bar: Logo | Breadcrumb trail | Global actions      │
├────────────┬────────────────────────────────────────────┤
│  Sidebar   │  Main Content Area                         │
│  (nav)     │  ┌──────────────────────────────────────┐  │
│            │  │ Page Header: Title + Actions         │  │
│            │  ├──────────────────────────────────────┤  │
│            │  │ Page Content                         │  │
│            │  └──────────────────────────────────────┘  │
└────────────┴────────────────────────────────────────────┘

• Use shadcn/ui Sidebar for primary navigation.
• Use Breadcrumb on every page.
• Deep linking: every view has a unique URL.

4. Component Composition (Atomic Design)

components/
├── ui/              # shadcn/ui primitives
├── atoms/           # StatusDot, CurrencyDisplay, Timestamp
├── molecules/       # SearchInput, UserBadge, StatCard
├── organisms/       # DataTable, FilterPanel, ActivityFeed
├── templates/       # DashboardLayout, FormPageLayout
└── feedback/        # Progress, loading, and status components

5. Visual Consistency Standards

Interaction States (every interactive element)

State	Visual Treatment
Default	Base styling
Hover	Subtle background shift or shadow increase
Focus	Visible focus ring (ring-2 ring-ring ring-offset-2)
Active/Pressed	Slight scale reduction or darkened background
Disabled	Reduced opacity, cursor-not-allowed
Loading	Replace content with spinner, maintain dimensions

6. Progress Feedback & Loading States

Three Feedback Tiers

Tier	Latency	Pattern
Tier 1: Instant	< 300ms	Optimistic UI + toast
Tier 2: Brief	300ms – 3s	Button loading, skeletons, inline progress
Tier 3: Extended	> 3s	Full progress modal with step detail

Decision Matrix

Operation	Latency	Pattern
Toggle, checkbox	Instant	Optimistic UI + toast
Save form (few fields)	< 1s	Button loading + toast
Data table load	1–3s	Full table skeleton
File upload (large)	5s–5m	Progress modal with ETA
Report generation	3s–60s	Progress modal with steps
AI/ML processing	5s–5m	Progress modal with activity log

7. Error States & Empty States

• Error Boundaries: Contextual error message + retry.
• Empty States: Icon + heading + description + CTA. Distinct from loading states.
• Form Validation: React Hook Form + Zod. Errors below fields, not in alerts/toasts.

8. Animation & Transition Standards

Purpose	Duration	Easing
State feedback	100–150ms	ease-in-out
Reveal content	150–250ms	ease-out
Navigate context	200–350ms	ease-in-out
Attract attention	300–600ms	ease-out or spring
Progress indication	Continuous	linear

Respect prefers-reduced-motion. No animation exceeds 500ms unless continuous.

9. Dark Mode & Theming

• All colors reference CSS custom properties.
• No flash of unstyled content on theme switch.
• Test every component in both themes.

10. Refactoring Process

Execute in this order:

1. Audit — Catalog every component, screenshot current state.
2. Install shadcn/ui — Set up Tailwind, tokens, cn() utility.
3. Build application shell — Sidebar, navigation, breadcrumbs.
4. Create feedback components — Progress modal, toasts, skeletons.
5. Migrate page by page — Replace with shadcn/ui equivalents.
6. Eliminate duplication — Consolidate into atomic layers.
7. Add animations — Apply transition standards.
8. Dark mode pass — Verify every page.
9. Accessibility audit — axe-core + manual testing.
10. Final validation — Visual regression, responsive, Lighthouse.

11. Deliverables Checklist

• All UI built on shadcn/ui primitives
• Design tokens defined; zero arbitrary Tailwind values
• Consistent navigation, breadcrumbs, page headers
• Atomic design component library
• All six interaction states on every element
• Async feedback per decision matrix
• Operations >3s use progress modal
• Empty states and error states designed
• Forms use react-hook-form + zod
• Animations respect prefers-reduced-motion
• Dark mode works flawlessly
• WCAG 2.1 AA verified
• Responsive: 320px, 768px, 1024px, 1440px, 2560px
• Lighthouse ≥ 90
• No banned naming patterns (no Enhanced, Improved, New, Old)