Decision workflow:

Identify project requirements (bundle size, customization, speed)
Review comparison table for best match
Provide installation commands
Recommend component set for the use case

Quick recommendations:

Todo apps / Modern SaaS: shadcn/ui + Tailwind
Quick prototypes: Chakra UI or Mantine
Enterprise dashboards: Material UI or Ant Design
Custom designs: Headless UI + Tailwind
TypeScript-heavy: Mantine

2. Responsive Layout Design

When users need mobile-friendly layouts or responsive components:

Read the patterns guide:

references/responsive-design-patterns.md

Core principles:

Always use mobile-first approach
Follow standard breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)
Use grid for card layouts: grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3
Use flexbox for navigation: flex flex-col md:flex-row
Scale typography: text-sm md:text-base lg:text-lg

3. Tailwind CSS Patterns

When building with Tailwind CSS:

Read Tailwind patterns:

references/tailwind-patterns.md

Common patterns to apply:

Cards: rounded-lg border bg-card text-card-foreground shadow-sm p-6
Buttons: inline-flex items-center justify-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90
Inputs: flex h-10 w-full rounded-md border border-input bg-background px-3 py-2
Dark mode: bg-white dark:bg-slate-950 text-slate-900 dark:text-slate-50

4. shadcn/ui Components

When using shadcn/ui (recommended for most projects):

Read component reference:

references/shadcn-components.md

Essential components for todo apps:

npx shadcn-ui@latest add button card input form dialog badge tabs checkbox

Use provided templates:

Task card: assets/todo-card-template.tsx
Task form: assets/task-form-template.tsx

Pattern: Compose components

import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
import { Button } from "@/components/ui/button"

<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Content</p>
    <Button>Action</Button>
  </CardContent>
</Card>

5. Material UI Implementation

When users choose Material UI:

Read MUI patterns:

references/material-ui-patterns.md

Setup theme first:

import { ThemeProvider, createTheme } from '@mui/material/styles'

const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
  },
})

<ThemeProvider theme={theme}>
  <App />
</ThemeProvider>

Use sx prop for styling:

<Box sx={{ p: 2, mt: 4, borderRadius: 2 }}>

6. Chakra UI Implementation

When users choose Chakra UI:

Read Chakra patterns:

references/chakra-ui-patterns.md

Key advantages:

Style props: <Box bg="blue.500" p={4} borderRadius="md">
Dark mode built-in: useColorMode(), useColorModeValue()
Responsive arrays: <Box w={['100%', '50%', '33%']}>

Layout with Stack:

<VStack spacing={4} align="stretch">
  <Card>Item 1</Card>
  <Card>Item 2</Card>
</VStack>

7. Form Design & Validation

When building forms with validation:

Use template:

assets/task-form-template.tsx

Pattern: React Hook Form + Zod

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"

const schema = z.object({
  title: z.string().min(3),
})

const form = useForm({
  resolver: zodResolver(schema),
})

Always include:

Field labels (<FormLabel>)
Error messages (<FormMessage>)
Helper text (<FormDescription>)
Disabled states for loading
Proper accessibility attributes

8. Accessibility Patterns

Always apply:

Semantic HTML: <button> not <div onClick>
ARIA labels: aria-label="Delete task"
Screen reader text: <span className="sr-only">Hidden</span>
Keyboard navigation: Focus states, tab order
Color contrast: WCAG AA minimum (4.5:1)
Touch targets: Minimum 44x44px

9. Dark Mode Implementation

Tailwind approach:

<div className="bg-white dark:bg-slate-950">
<p className="text-slate-900 dark:text-slate-50">

// Theme toggle
import { useTheme } from "next-themes"
const { theme, setTheme } = useTheme()

Chakra UI approach:

const { colorMode, toggleColorMode } = useColorMode()
const bg = useColorModeValue('white', 'gray.800')

Material UI approach:

const theme = createTheme({
  palette: {
    mode: prefersDarkMode ? 'dark' : 'light',
  },
})

10. Component Templates

When building todo apps or similar UIs:

Available templates:

Task Card (assets/todo-card-template.tsx)
- Includes: Checkbox, priority badges, tags, due dates, dropdown menu
- Variants: Card view, list item view
- Features: Hover states, accessibility
Task Form (assets/task-form-template.tsx)
- Includes: Title, description, priority, due date, tags
- Validation: React Hook Form + Zod
- Variants: Dialog form, inline form

Usage:

# Read template
Read: assets/todo-card-template.tsx

# Adapt to project's design system
# Modify imports and styling as needed

Workflow Guide

For New Projects

Select Design System
- Read: references/design-system-comparison.md
- Consider: Bundle size, customization needs, team experience
- Provide recommendation with rationale
Setup Theme/Config
- Install dependencies
- Configure theme (colors, typography, spacing)
- Setup dark mode if needed
Build Core Components
- Start with layout (Container, Grid)
- Add navigation
- Implement forms
- Create card/list components
Apply Responsive Patterns
- Read: references/responsive-design-patterns.md
- Mobile-first breakpoints
- Test at key viewports
Add Accessibility
- Semantic HTML
- ARIA labels
- Keyboard navigation
- Screen reader support

For Todo App Specifically

Choose design system (recommend shadcn/ui)

Install core components:

npx shadcn-ui@latest add button card input form dialog badge tabs checkbox

Use templates:
- Copy assets/todo-card-template.tsx
- Copy assets/task-form-template.tsx
Customize colors/spacing to match brand
Add responsive layouts from references/responsive-design-patterns.md
Implement dark mode

For Existing Projects

Audit current design system
Identify pain points (bundle size, customization limits, etc.)
If migrating:
- Read comparison guide for alternatives
- Plan incremental migration
- Start with new components
If optimizing:
- Apply patterns from references
- Improve responsiveness
- Add accessibility features

Quick Reference

Common Tasks

"Make this responsive" → Read: references/responsive-design-patterns.md → Apply mobile-first breakpoints → Use grid/flexbox patterns

"Add dark mode" → For Tailwind: Use dark: prefix → For Chakra: Use useColorMode() → For MUI: Configure theme palette mode

"Which UI library?" → Read: references/design-system-comparison.md → Provide recommendation based on requirements

"Build a form with validation" → Use: assets/task-form-template.tsx → Adapt to project's design system → Add custom fields as needed

"Create task card" → Use: assets/todo-card-template.tsx → Modify for specific features

Design Tokens Reference

Spacing scale: 2, 4, 6, 8, 12, 16, 24, 32, 48, 64 (px in 4px increments)

Typography scale: xs (12px), sm (14px), base (16px), lg (18px), xl (20px), 2xl (24px), 3xl (30px)

Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px)

Border radius: sm (4px), md (8px), lg (16px), full (9999px)

Anti-Patterns to Avoid

❌ Desktop-first responsive design (always start mobile) ❌ Hardcoded colors (use design tokens/theme) ❌ Div soup (use semantic HTML) ❌ Missing accessibility (always include ARIA, focus states) ❌ Inconsistent spacing (use design system scale) ❌ Non-interactive elements with onClick (use button/a) ❌ Tiny touch targets on mobile (<44px)

Resources Summary

Tailwind patterns: references/tailwind-patterns.md
shadcn/ui components: references/shadcn-components.md
Material UI patterns: references/material-ui-patterns.md
Chakra UI patterns: references/chakra-ui-patterns.md
Design system comparison: references/design-system-comparison.md
Responsive patterns: references/responsive-design-patterns.md
Task card template: assets/todo-card-template.tsx
Task form template: assets/task-form-template.tsx

frontend-design-system

Frontend Design System

Core Capabilities

1. Design System Selection