From 30cbaf8ad5e29407fa2f73d81fe2634b4fe0c231 Mon Sep 17 00:00:00 2001 From: Felipe Cardoso Date: Sun, 2 Nov 2025 12:32:01 +0100 Subject: [PATCH] Add documentation for component creation and design system structure - **Component Creation Guide:** Document best practices for creating reusable, accessible components using CVA patterns. Includes guidance on when to compose vs create, decision trees, templates, prop design, testing checklists, and real-world examples. - **Design System README:** Introduce an organized structure for the design system documentation with quick navigation, learning paths, and reference links to key topics. Includes paths for quick starts, layouts, components, forms, and AI setup. --- frontend/docs/COMPONENT_GUIDE.md | 802 ----------- frontend/docs/DESIGN_SYSTEM.md | 645 --------- frontend/docs/design-system/00-quick-start.md | 456 ++++++ frontend/docs/design-system/01-foundations.md | 909 ++++++++++++ frontend/docs/design-system/02-components.md | 1228 +++++++++++++++++ frontend/docs/design-system/03-layouts.md | 586 ++++++++ .../design-system/04-spacing-philosophy.md | 708 ++++++++++ .../design-system/05-component-creation.md | 874 ++++++++++++ frontend/docs/design-system/06-forms.md | 838 +++++++++++ .../docs/design-system/07-accessibility.md | 704 ++++++++++ .../docs/design-system/08-ai-guidelines.md | 574 ++++++++ frontend/docs/design-system/99-reference.md | 599 ++++++++ frontend/docs/design-system/README.md | 304 ++++ 13 files changed, 7780 insertions(+), 1447 deletions(-) delete mode 100755 frontend/docs/COMPONENT_GUIDE.md delete mode 100644 frontend/docs/DESIGN_SYSTEM.md create mode 100644 frontend/docs/design-system/00-quick-start.md create mode 100644 frontend/docs/design-system/01-foundations.md create mode 100644 frontend/docs/design-system/02-components.md create mode 100644 frontend/docs/design-system/03-layouts.md create mode 100644 frontend/docs/design-system/04-spacing-philosophy.md create mode 100644 frontend/docs/design-system/05-component-creation.md create mode 100644 frontend/docs/design-system/06-forms.md create mode 100644 frontend/docs/design-system/07-accessibility.md create mode 100644 frontend/docs/design-system/08-ai-guidelines.md create mode 100644 frontend/docs/design-system/99-reference.md create mode 100644 frontend/docs/design-system/README.md diff --git a/frontend/docs/COMPONENT_GUIDE.md b/frontend/docs/COMPONENT_GUIDE.md deleted file mode 100755 index e56f544..0000000 --- a/frontend/docs/COMPONENT_GUIDE.md +++ /dev/null @@ -1,802 +0,0 @@ -# Component Guide - -**Project**: Next.js + FastAPI Template -**Version**: 1.0 -**Last Updated**: 2025-10-31 - ---- - -## Table of Contents - -1. [shadcn/ui Components](#1-shadcn-ui-components) -2. [Custom Components](#2-custom-components) -3. [Component Composition](#3-component-composition) -4. [Customization](#4-customization) -5. [Accessibility](#5-accessibility) - ---- - -## 1. shadcn/ui Components - -### 1.1 Overview - -This project uses [shadcn/ui](https://ui.shadcn.com), a collection of accessible, customizable components built on Radix UI primitives. Components are copied into the project (not installed as npm dependencies), giving you full control. - -**Installation Method:** -```bash -npx shadcn@latest add button card input table dialog -``` - -### 1.2 Core Components - -#### Button - -```typescript -import { Button } from '@/components/ui/button'; - -// Variants - - - - - - -// Sizes - - - - - -// States - - - -// As Link - -``` - -#### Card - -```typescript -import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card'; - - - - Users - Manage system users - - -

Card content goes here

- - - - - -``` - -#### Dialog / Modal - -```typescript -import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogTrigger } from '@/components/ui/dialog'; - - - - - - - - Delete User - - Are you sure you want to delete this user? This action cannot be undone. - - - - - - - - -``` - -#### Form - -```typescript -import { Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage } from '@/components/ui/form'; -import { Input } from '@/components/ui/input'; -import { useForm } from 'react-hook-form'; - -const form = useForm(); - -
- - ( - - Email - - - - Your email address - - - )} - /> - - - -``` - -#### Table - -```typescript -import { Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell } from '@/components/ui/table'; - - - - - Name - Email - Role - - - - {users.map((user) => ( - - {user.name} - {user.email} - {user.role} - - ))} - -
-``` - -#### Toast / Notifications - -```typescript -import { toast } from 'sonner'; - -// Success -toast.success('User created successfully'); - -// Error -toast.error('Failed to delete user'); - -// Info -toast.info('Processing your request...'); - -// Loading -toast.loading('Saving changes...'); - -// Custom -toast('Event has been created', { - description: 'Monday, January 3rd at 6:00pm', - action: { - label: 'Undo', - onClick: () => console.log('Undo'), - }, -}); -``` - -#### Tabs - -```typescript -import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs'; - - - - Profile - Password - Sessions - - - - - - - - - - - -``` - ---- - -## 2. Custom Components - -### 2.1 Layout Components - -#### Header - -```typescript -import { Header } from '@/components/layout/Header'; - -// Usage (in layout.tsx) -
- -// Features: -// - Logo/brand -// - Navigation links -// - User menu (avatar, name, dropdown) -// - Theme toggle -// - Mobile menu button -``` - -#### PageContainer - -```typescript -import { PageContainer } from '@/components/layout/PageContainer'; - - -

Page Title

-

Page content...

- - -// Provides: -// - Consistent padding -// - Max-width container -// - Responsive layout -``` - -#### PageHeader - -```typescript -import { PageHeader } from '@/components/common/PageHeader'; - -Create User} -/> -``` - -### 2.2 Data Display Components - -#### DataTable - -Generic, reusable data table with sorting, filtering, and pagination. - -```typescript -import { DataTable } from '@/components/common/DataTable'; -import { ColumnDef } from '@tanstack/react-table'; - -// Define columns -const columns: ColumnDef[] = [ - { - accessorKey: 'name', - header: 'Name', - }, - { - accessorKey: 'email', - header: 'Email', - }, - { - id: 'actions', - cell: ({ row }) => ( - - ), - }, -]; - -// Use DataTable - -``` - -#### LoadingSpinner - -```typescript -import { LoadingSpinner } from '@/components/common/LoadingSpinner'; - -// Sizes - - - - -// With text - -

Loading users...

- -``` - -#### EmptyState - -```typescript -import { EmptyState } from '@/components/common/EmptyState'; - -} - title="No users found" - description="Get started by creating a new user" - action={ - - } -/> -``` - -### 2.3 Admin Components - -#### UserTable - -```typescript -import { UserTable } from '@/components/admin/UserTable'; - - console.log(user)} -/> - -// Features: -// - Search -// - Filters (role, status) -// - Sorting -// - Pagination -// - Bulk selection -// - Bulk actions (activate, deactivate, delete) -``` - -#### UserForm - -```typescript -import { UserForm } from '@/components/admin/UserForm'; - -// Create mode - router.push('/admin/users')} -/> - -// Edit mode - toast.success('User updated')} -/> - -// Features: -// - Validation with Zod -// - Field errors -// - Loading states -// - Cancel/Submit actions -``` - -#### OrganizationTable - -```typescript -import { OrganizationTable } from '@/components/admin/OrganizationTable'; - - - -// Features: -// - Search -// - Member count display -// - Actions (edit, delete, view members) -``` - -#### BulkActionBar - -```typescript -import { BulkActionBar } from '@/components/admin/BulkActionBar'; - - handleBulkAction(action, selectedUserIds)} - onClearSelection={() => setSelectedUserIds([])} - actions={[ - { value: 'activate', label: 'Activate' }, - { value: 'deactivate', label: 'Deactivate' }, - { value: 'delete', label: 'Delete', variant: 'destructive' }, - ]} -/> - -// Displays: -// - Selection count -// - Action dropdown -// - Confirmation dialogs -// - Progress indicators -``` - -### 2.4 Settings Components - -#### ProfileSettings - -```typescript -import { ProfileSettings } from '@/components/settings/ProfileSettings'; - - console.log('Updated:', updatedUser)} -/> - -// Fields: -// - First name, last name -// - Email (readonly) -// - Phone number -// - Avatar upload (optional) -// - Preferences -``` - -#### PasswordSettings - -```typescript -import { PasswordSettings } from '@/components/settings/PasswordSettings'; - - - -// Fields: -// - Current password -// - New password -// - Confirm password -// - Option to logout all other devices -``` - -#### SessionManagement - -```typescript -import { SessionManagement } from '@/components/settings/SessionManagement'; - - - -// Features: -// - List all active sessions -// - Current session badge -// - Device icons -// - Location display -// - Last used timestamp -// - Revoke session button -// - Logout all other devices button -``` - -#### SessionCard - -```typescript -import { SessionCard } from '@/components/settings/SessionCard'; - - revokeSession(session.id)} -/> - -// Displays: -// - Device icon (desktop/mobile/tablet) -// - Device name -// - Location (city, country) -// - IP address -// - Last used (relative time) -// - "This device" badge if current -// - Revoke button (disabled for current) -``` - -### 2.5 Chart Components - -#### BarChartCard - -```typescript -import { BarChartCard } from '@/components/charts/BarChartCard'; - - -``` - -#### LineChartCard - -```typescript -import { LineChartCard } from '@/components/charts/LineChartCard'; - - -``` - -#### PieChartCard - -```typescript -import { PieChartCard } from '@/components/charts/PieChartCard'; - - -``` - ---- - -## 3. Component Composition - -### 3.1 Form + Dialog Pattern - -```typescript - - - - Create User - - Add a new user to the system - - - { - setIsOpen(false); - queryClient.invalidateQueries(['users']); - }} - onCancel={() => setIsOpen(false)} - /> - - -``` - -### 3.2 Card + Table Pattern - -```typescript - - -
-
- Users - Manage system users -
- -
- - - - - -``` - -### 3.3 Tabs + Settings Pattern - -```typescript - - - Account Settings - - - - - Profile - Password - Sessions - - - - - - - - - - - - - -``` - -### 3.4 Bulk Actions Pattern - -```typescript -function UserList() { - const [selectedIds, setSelectedIds] = useState([]); - const { data: users } = useUsers(); - - return ( -
- {selectedIds.length > 0 && ( - setSelectedIds([])} - /> - )} - -
- ); -} -``` - ---- - -## 4. Customization - -### 4.1 Theming - -Colors are defined in `tailwind.config.ts` using CSS variables: - -```typescript -// tailwind.config.ts -export default { - theme: { - extend: { - colors: { - border: 'hsl(var(--border))', - background: 'hsl(var(--background))', - foreground: 'hsl(var(--foreground))', - primary: { - DEFAULT: 'hsl(var(--primary))', - foreground: 'hsl(var(--primary-foreground))', - }, - // ... - }, - }, - }, -}; -``` - -**Customize colors in `globals.css`:** -```css -@layer base { - :root { - --primary: 222.2 47.4% 11.2%; - --primary-foreground: 210 40% 98%; - /* ... */ - } - - .dark { - --primary: 210 40% 98%; - --primary-foreground: 222.2 47.4% 11.2%; - /* ... */ - } -} -``` - -### 4.2 Component Variants - -Add new variants to existing components: - -```typescript -// components/ui/button.tsx -const buttonVariants = cva( - 'base-classes', - { - variants: { - variant: { - default: '...', - destructive: '...', - outline: '...', - // Add custom variant - success: 'bg-green-600 text-white hover:bg-green-700', - }, - }, - } -); - -// Usage - -``` - -### 4.3 Extending Components - -Create wrapper components: - -```typescript -// components/common/ConfirmDialog.tsx -interface ConfirmDialogProps { - title: string; - description: string; - confirmLabel?: string; - onConfirm: () => void; - onCancel: () => void; -} - -export function ConfirmDialog({ - title, - description, - confirmLabel = 'Confirm', - onConfirm, - onCancel, -}: ConfirmDialogProps) { - return ( - - - - {title} - {description} - - - - - - - - ); -} -``` - ---- - -## 5. Accessibility - -### 5.1 Keyboard Navigation - -All shadcn/ui components support keyboard navigation: -- `Tab`: Move focus -- `Enter`/`Space`: Activate -- `Escape`: Close dialogs/dropdowns -- Arrow keys: Navigate lists/menus - -### 5.2 Screen Reader Support - -Components include proper ARIA labels: - -```typescript - - -
- Loading users... -
- - -``` - -### 5.3 Focus Management - -Dialog components automatically manage focus: -- Focus trap inside dialog -- Return focus on close -- Focus first focusable element - -### 5.4 Color Contrast - -All theme colors meet WCAG 2.1 Level AA standards: -- Normal text: 4.5:1 contrast ratio -- Large text: 3:1 contrast ratio - ---- - -## Conclusion - -This guide covers the essential components in the project. For more details: -- **shadcn/ui docs**: https://ui.shadcn.com -- **Radix UI docs**: https://www.radix-ui.com -- **TanStack Table docs**: https://tanstack.com/table -- **Recharts docs**: https://recharts.org - -For implementation examples, see `FEATURE_EXAMPLES.md`. diff --git a/frontend/docs/DESIGN_SYSTEM.md b/frontend/docs/DESIGN_SYSTEM.md deleted file mode 100644 index 865a098..0000000 --- a/frontend/docs/DESIGN_SYSTEM.md +++ /dev/null @@ -1,645 +0,0 @@ -# FastNext Template Design System - -**Version**: 1.0 -**Last Updated**: November 2, 2025 -**Theme**: Modern Minimal (via [tweakcn.com](https://tweakcn.com)) -**Status**: Production Ready - ---- - -## Table of Contents - -1. [Overview](#overview) -2. [Color System](#color-system) -3. [Typography](#typography) -4. [Spacing & Layout](#spacing--layout) -5. [Shadows](#shadows) -6. [Border Radius](#border-radius) -7. [Components](#components) -8. [Dark Mode](#dark-mode) -9. [Accessibility](#accessibility) -10. [Best Practices](#best-practices) - ---- - -## Overview - -This design system is built on **shadcn/ui** component library with **Tailwind CSS 4**, using the **OKLCH color space** for superior perceptual uniformity and accessibility. - -### Technology Stack - -- **Framework**: Next.js 15 + React 19 -- **Styling**: Tailwind CSS 4 (CSS-first configuration) -- **Components**: shadcn/ui (New York style) -- **Color Space**: OKLCH -- **Icons**: lucide-react -- **Fonts**: Geist Sans + Geist Mono - -### Design Principles - -1. **Minimal & Clean** - Simple, uncluttered interfaces -2. **Accessible First** - WCAG AA compliance minimum -3. **Consistent** - Predictable patterns across the application -4. **Performant** - Optimized for speed and efficiency -5. **Responsive** - Mobile-first approach - ---- - -## Color System - -Our color system uses **OKLCH** (Oklab LCH) color space for: -- Perceptual uniformity across light and dark modes -- Better accessibility with predictable contrast -- More vibrant colors without sacrificing legibility - -### Semantic Color Tokens - -All colors follow the **background/foreground** convention: -- `background` - The background color -- `foreground` - The text color on that background - -#### Primary Colors - -**Purpose**: Main brand color, CTAs, primary actions - -```css -Light: --primary: oklch(0.6231 0.1880 259.8145) /* Blue */ -Dark: --primary: oklch(0.6231 0.1880 259.8145) /* Same blue */ -``` - -**Usage**: -```tsx - -Link -``` - -#### Secondary Colors - -**Purpose**: Secondary actions, less prominent UI elements - -```css -Light: --secondary: oklch(0.9670 0.0029 264.5419) /* Light gray-blue */ -Dark: --secondary: oklch(0.2686 0 0) /* Dark gray */ -``` - -#### Muted Colors - -**Purpose**: Backgrounds for disabled states, subtle UI elements - -```css -Light: --muted: oklch(0.9846 0.0017 247.8389) -Dark: --muted: oklch(0.2393 0 0) -``` - -**Usage**: -- Disabled button backgrounds -- Skeleton loaders -- TabsList backgrounds -- Switch backgrounds (unchecked) - -#### Accent Colors - -**Purpose**: Hover states, focus indicators, highlights - -```css -Light: --accent: oklch(0.9514 0.0250 236.8242) -Dark: --accent: oklch(0.3791 0.1378 265.5222) -``` - -**Usage**: -```tsx -Item -``` - -#### Destructive Colors - -**Purpose**: Error states, delete actions, warnings - -```css -Light: --destructive: oklch(0.6368 0.2078 25.3313) /* Red */ -Dark: --destructive: oklch(0.6368 0.2078 25.3313) /* Same red */ -``` - -**Usage**: -```tsx - -Error message -``` - -#### Card & Popover - -**Purpose**: Elevated surfaces (cards, popovers, dropdowns) - -```css -Light: --card: oklch(1.0000 0 0) /* White */ -Dark: --card: oklch(0.2686 0 0) /* Dark gray */ - -Light: --popover: oklch(1.0000 0 0) /* White */ -Dark: --popover: oklch(0.2686 0 0) /* Dark gray */ -``` - -#### Border & Input - -**Purpose**: Borders, input field borders - -```css -Light: --border: oklch(0.9276 0.0058 264.5313) -Dark: --border: oklch(0.3715 0 0) - -Light: --input: oklch(0.9276 0.0058 264.5313) -Dark: --input: oklch(0.3715 0 0) -``` - -#### Focus Ring - -**Purpose**: Focus indicators for keyboard navigation - -```css -Light: --ring: oklch(0.6231 0.1880 259.8145) /* Primary blue */ -Dark: --ring: oklch(0.6231 0.1880 259.8145) -``` - -### Chart Colors - -For data visualization, we provide 5 harmonious chart colors: - -```css ---chart-1: oklch(0.6231 0.1880 259.8145) /* Blue */ ---chart-2: oklch(0.5461 0.2152 262.8809) /* Purple-blue */ ---chart-3: oklch(0.4882 0.2172 264.3763) /* Deep purple */ ---chart-4: oklch(0.4244 0.1809 265.6377) /* Violet */ ---chart-5: oklch(0.3791 0.1378 265.5222) /* Deep violet */ -``` - -### Color Usage Guidelines - -**DO**: -- ✅ Use semantic tokens (`bg-primary`, `text-destructive`) -- ✅ Test color combinations with contrast checkers -- ✅ Use `muted` for subtle backgrounds -- ✅ Use `accent` for hover states - -**DON'T**: -- ❌ Use arbitrary color values (`bg-blue-500`) -- ❌ Mix OKLCH with RGB/HSL in the same context -- ❌ Use `primary` for large background areas -- ❌ Override foreground colors without checking contrast - ---- - -## Typography - -### Font Families - -```css ---font-sans: Geist Sans, system-ui, -apple-system, sans-serif ---font-mono: Geist Mono, ui-monospace, monospace ---font-serif: ui-serif, Georgia, serif -``` - -**Usage**: -```tsx -
Body text
-const example = true; -``` - -### Type Scale - -Tailwind CSS provides a comprehensive type scale. We use: - -| Size | Class | Use Case | -|------|-------|----------| -| 3xl | `text-3xl` | Page titles | -| 2xl | `text-2xl` | Section headings | -| xl | `text-xl` | Card titles | -| lg | `text-lg` | Subheadings | -| base | `text-base` | Body text (default) | -| sm | `text-sm` | Secondary text, captions | -| xs | `text-xs` | Labels, helper text | - -### Font Weights - -| Weight | Class | Use Case | -|--------|-------|----------| -| 700 | `font-bold` | Headings, emphasis | -| 600 | `font-semibold` | Subheadings, buttons | -| 500 | `font-medium` | Labels, menu items | -| 400 | `font-normal` | Body text (default) | -| 300 | `font-light` | De-emphasized text | - -### Typography Guidelines - -**DO**: -- ✅ Use `text-foreground` for body text -- ✅ Use `text-muted-foreground` for secondary text -- ✅ Maintain consistent heading hierarchy (h1 → h2 → h3) -- ✅ Limit line length to 60-80 characters for readability - -**DON'T**: -- ❌ Use more than 3 font sizes on a single page -- ❌ Use custom colors without checking contrast -- ❌ Skip heading levels (h1 → h3) -- ❌ Use `font-bold` excessively - -**Line Height**: -- Headings: `leading-tight` (1.25) -- Body: `leading-normal` (1.5) - default -- Dense UI: `leading-relaxed` (1.625) - ---- - -## Spacing & Layout - -### Spacing Scale - -Tailwind uses a **0.25rem (4px) base unit**: - -```css ---spacing: 0.25rem; -``` - -| Token | Value | Pixels | Use Case | -|-------|-------|--------|----------| -| `0` | 0 | 0px | No spacing | -| `px` | 1px | 1px | Borders, dividers | -| `0.5` | 0.125rem | 2px | Tight spacing | -| `1` | 0.25rem | 4px | Icon gaps | -| `2` | 0.5rem | 8px | Small gaps | -| `3` | 0.75rem | 12px | Component padding | -| `4` | 1rem | 16px | Standard spacing | -| `6` | 1.5rem | 24px | Section spacing | -| `8` | 2rem | 32px | Large gaps | -| `12` | 3rem | 48px | Section dividers | -| `16` | 4rem | 64px | Page sections | - -### Container & Max Width - -```tsx -
- {/* Responsive container with horizontal padding */} -
- -
- {/* Constrained width for readability */} -
-``` - -**Max Width Scale**: -- `max-w-sm` - 384px - Small cards -- `max-w-md` - 448px - Forms -- `max-w-lg` - 512px - Modals -- `max-w-2xl` - 672px - Article content -- `max-w-4xl` - 896px - Wide layouts -- `max-w-7xl` - 1280px - Full page width - -### Layout Guidelines - -**DO**: -- ✅ Use multiples of 4 for spacing (4, 8, 12, 16, 24, 32...) -- ✅ Use `gap-` utilities for flex/grid spacing -- ✅ Use `space-y-` for vertical stacks -- ✅ Use `container` for page-level constraints - -**DON'T**: -- ❌ Use arbitrary values like `p-[13px]` -- ❌ Mix padding and margin inconsistently -- ❌ Forget responsive spacing (`sm:p-6 lg:p-8`) - ---- - -## Shadows - -Professional shadow system for depth and elevation: - -```css ---shadow-xs: 0 1px 3px 0px hsl(0 0% 0% / 0.05) ---shadow-sm: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10) ---shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10) ---shadow-md: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 2px 4px -1px hsl(0 0% 0% / 0.10) ---shadow-lg: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 4px 6px -1px hsl(0 0% 0% / 0.10) ---shadow-xl: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 8px 10px -1px hsl(0 0% 0% / 0.10) ---shadow-2xl: 0 1px 3px 0px hsl(0 0% 0% / 0.25) -``` - -### Shadow Usage - -| Elevation | Class | Use Case | -|-----------|-------|----------| -| Base | No shadow | Buttons, inline elements | -| Low | `shadow-sm` | Cards, panels | -| Medium | `shadow-md` | Dropdowns, tooltips | -| High | `shadow-lg` | Modals, popovers | -| Highest | `shadow-xl` | Notifications, floating | - -**Usage**: -```tsx -Card content -Menu -Modal -``` - ---- - -## Border Radius - -Consistent rounded corners across the application: - -```css ---radius: 0.375rem; /* 6px - base */ - ---radius-sm: calc(var(--radius) - 4px) /* 2px */ ---radius-md: calc(var(--radius) - 2px) /* 4px */ ---radius-lg: var(--radius) /* 6px */ ---radius-xl: calc(var(--radius) + 4px) /* 10px */ -``` - -### Border Radius Usage - -| Token | Value | Use Case | -|-------|-------|----------| -| `rounded-sm` | 2px | Small elements, tags | -| `rounded-md` | 4px | Inputs, small buttons | -| `rounded-lg` | 6px | Cards, buttons (default) | -| `rounded-xl` | 10px | Large cards, modals | -| `rounded-full` | 9999px | Pills, avatars, icon buttons | - -**Usage**: -```tsx - - -Tag -``` - ---- - -## Components - -### shadcn/ui Component Library - -We use **shadcn/ui** components (New York style) with CSS variables for theming. - -**Installed Components**: -- `alert` - Alerts and notifications -- `avatar` - User avatars -- `badge` - Tags and labels -- `button` - Buttons (primary, secondary, outline, ghost, destructive) -- `card` - Content cards -- `checkbox` - Checkboxes -- `dialog` - Modals and dialogs -- `dropdown-menu` - Context menus, dropdowns -- `input` - Text inputs -- `label` - Form labels -- `popover` - Tooltips, popovers -- `select` - Select dropdowns -- `separator` - Horizontal/vertical dividers -- `sheet` - Side panels -- `skeleton` - Loading skeletons -- `table` - Data tables -- `tabs` - Tabbed interfaces -- `textarea` - Multi-line inputs - -### Component Variants - -#### Button Variants - -```tsx - - - - - - -``` - -#### Button Sizes - -```tsx - - - - -``` - -### Component Guidelines - -**DO**: -- ✅ Use semantic variant names (`destructive`, not `red`) -- ✅ Compose components from shadcn/ui primitives -- ✅ Follow the background/foreground convention -- ✅ Add `aria-label` for icon-only buttons - -**DON'T**: -- ❌ Create custom variants without documenting them -- ❌ Override component styles with arbitrary classes -- ❌ Mix component libraries (stick to shadcn/ui) - ---- - -## Dark Mode - -Dark mode is implemented using CSS classes (`.dark`) with automatic OS preference detection. - -### Dark Mode Strategy - -1. **CSS Variables**: All colors have light and dark variants -2. **Class Toggle**: `.dark` class on `` element -3. **Persistent**: User preference stored in localStorage -4. **Smooth Transition**: Optional transitions between modes - -### Implementation - -```tsx -// Toggle dark mode - - -// Check current mode -const isDark = document.documentElement.classList.contains('dark'); -``` - -### Dark Mode Guidelines - -**DO**: -- ✅ Test all components in both light and dark modes -- ✅ Use semantic color tokens (not hardcoded colors) -- ✅ Maintain WCAG AA contrast in both modes -- ✅ Provide a theme toggle in settings - -**DON'T**: -- ❌ Use absolute colors like `bg-white` or `bg-black` -- ❌ Assume users only use one mode -- ❌ Forget to test shadow visibility in dark mode - ---- - -## Accessibility - -We follow **WCAG 2.1 Level AA** as the minimum standard. - -### Color Contrast - -All text must meet minimum contrast ratios: - -- **Normal text (< 18px)**: 4.5:1 minimum -- **Large text (≥ 18px or ≥ 14px bold)**: 3:1 minimum -- **UI components**: 3:1 minimum - -**Tools**: -- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) -- Chrome DevTools Accessibility panel -- Browser extensions (axe, WAVE) - -### Keyboard Navigation - -**Requirements**: -- ✅ All interactive elements focusable via Tab -- ✅ Visible focus indicators (`:focus-visible`) -- ✅ Logical tab order -- ✅ Escape key closes modals/dropdowns -- ✅ Arrow keys for navigation within components - -### Screen Readers - -**Requirements**: -- ✅ Semantic HTML (headings, lists, nav, main, etc.) -- ✅ `aria-label` for icon-only buttons -- ✅ `aria-describedby` for form errors -- ✅ `role` attributes where needed -- ✅ Live regions for dynamic updates - -### Focus Management - -```tsx -// Proper focus indicator - - -// Skip to main content link - - Skip to main content - -``` - -### Accessibility Checklist - -- [ ] Color contrast meets WCAG AA (4.5:1 for text) -- [ ] All interactive elements keyboard accessible -- [ ] Focus indicators visible -- [ ] Images have `alt` text -- [ ] Forms have labels -- [ ] Error messages associated with inputs -- [ ] ARIA attributes used correctly -- [ ] Tested with screen reader (NVDA, JAWS, VoiceOver) - ---- - -## Best Practices - -### Naming Conventions - -**DO**: -```tsx -// ✅ Descriptive, semantic names - -
Content
-``` - -**DON'T**: -```tsx -// ❌ Generic, non-semantic names - -
Content
-``` - -### Component Structure - -**DO**: -```tsx -// ✅ Compose with shadcn/ui primitives - - - Title - - Content - -``` - -**DON'T**: -```tsx -// ❌ Create custom components for everything -Content -``` - -### Responsive Design - -**DO**: -```tsx -// ✅ Mobile-first responsive utilities -
-

Title

-
-``` - -**DON'T**: -```tsx -// ❌ Desktop-first or no responsive design -
-

Title

-
-``` - -### Performance - -**DO**: -- ✅ Use CSS variables for theming (no runtime JS) -- ✅ Minimize custom CSS (use Tailwind utilities) -- ✅ Lazy load components when appropriate -- ✅ Optimize images with Next.js Image component - -**DON'T**: -- ❌ Inline styles everywhere -- ❌ Large custom CSS files -- ❌ Unoptimized images -- ❌ Excessive animation/transitions - -### Code Organization - -``` -src/components/ -├── ui/ # shadcn/ui components (don't edit) -├── auth/ # Authentication components -├── layout/ # Layout components (Header, Footer) -└── settings/ # Feature-specific components -``` - -### Documentation - -**DO**: -- ✅ Document custom variants in this file -- ✅ Add JSDoc comments to complex components -- ✅ Include usage examples -- ✅ Update this document when making changes - ---- - -## Version History - -| Version | Date | Changes | -|---------|------|---------| -| 1.0 | Nov 2, 2025 | Initial design system with Modern Minimal theme | - ---- - -## Resources - -- [shadcn/ui Documentation](https://ui.shadcn.com) -- [Tailwind CSS 4 Documentation](https://tailwindcss.com/docs) -- [OKLCH Color Space](https://oklch.com) -- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/) -- [Theme Generator](https://tweakcn.com) - ---- - -**For questions or suggestions, refer to this document and the official documentation.** diff --git a/frontend/docs/design-system/00-quick-start.md b/frontend/docs/design-system/00-quick-start.md new file mode 100644 index 0000000..0f64340 --- /dev/null +++ b/frontend/docs/design-system/00-quick-start.md @@ -0,0 +1,456 @@ +# Quick Start Guide + +Get up and running with the FastNext design system immediately. This guide covers the essential patterns you need to build 80% of interfaces. + +--- + +## TL;DR + +```tsx +// 1. Import from @/components/ui/* +import { Button } from '@/components/ui/button'; +import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'; + +// 2. Use semantic color tokens +className="bg-primary text-primary-foreground" +className="text-destructive" + +// 3. Use spacing scale (4, 8, 12, 16, 24, 32...) +className="p-4 space-y-6" + +// 4. Build layouts with these patterns +
+
+ {/* Your content */} +
+
+``` + +--- + +## 1. Essential Components + +### Buttons + +```tsx +import { Button } from '@/components/ui/button'; + +// Primary action + + +// Danger action + + +// Secondary action + + +// Subtle action + + +// Sizes + + + +``` + +**[See all button variants](/dev/components#button)** + +--- + +### Cards + +```tsx +import { + Card, + CardHeader, + CardTitle, + CardDescription, + CardContent, + CardFooter +} from '@/components/ui/card'; + + + + User Profile + Manage your account settings + + +

Card content goes here

+ + + + + +``` + +**[See card examples](/dev/components#card)** + +--- + +### Forms + +```tsx +import { Label } from '@/components/ui/label'; +import { Input } from '@/components/ui/input'; + +
+ + + {errors.email && ( +

+ {errors.email.message} +

+ )} +
+``` + +**[See form patterns](./06-forms.md)** | **[Form examples](/dev/forms)** + +--- + +### Dialogs/Modals + +```tsx +import { + Dialog, + DialogContent, + DialogHeader, + DialogTitle, + DialogDescription, + DialogFooter, + DialogTrigger +} from '@/components/ui/dialog'; + + + + + + + + Confirm Action + + Are you sure you want to proceed? + + + + + + + + +``` + +**[See dialog examples](/dev/components#dialog)** + +--- + +### Alerts + +```tsx +import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'; +import { AlertCircle } from 'lucide-react'; + +// Default alert + + + Heads up! + + This is an informational message. + + + +// Error alert + + + Error + + Something went wrong. Please try again. + + +``` + +**[See all component variants](/dev/components)** + +--- + +## 2. Essential Layouts (1 minute) + +### Page Container + +```tsx +// Standard page layout +
+
+

Page Title

+ {/* Content */} +
+
+``` + +### Dashboard Grid + +```tsx +// Responsive card grid +
+ {items.map(item => ( + + + {item.title} + + {item.content} + + ))} +
+``` + +### Form Layout + +```tsx +// Centered form with max width +
+ + + Login + + +
+ {/* Form fields */} +
+ + +
+``` + +**[See all layout patterns](./03-layouts.md)** | **[Layout examples](/dev/layouts)** + +--- + +## 3. Color System + +**Always use semantic tokens**, never arbitrary colors: + +```tsx +// ✅ GOOD - Semantic tokens +
Primary
+
Error
+
Disabled
+

Body text

+

Secondary text

+ +// ❌ BAD - Arbitrary colors +
Don't do this
+``` + +**Available tokens:** +- `primary` - Main brand color, CTAs +- `destructive` - Errors, delete actions +- `muted` - Disabled states, subtle backgrounds +- `accent` - Hover states, highlights +- `foreground` - Body text +- `muted-foreground` - Secondary text +- `border` - Borders, dividers + +**[See complete color system](./01-foundations.md#color-system-oklch)** + +--- + +## 4. Spacing System + +**Use multiples of 4** (Tailwind's base unit is 0.25rem = 4px): + +```tsx +// ✅ GOOD - Consistent spacing +
+
Content
+
+ +// ❌ BAD - Arbitrary spacing +
+
Content
+
+``` + +**Common spacing values:** +- `2` (8px) - Tight spacing +- `4` (16px) - Standard spacing +- `6` (24px) - Section spacing +- `8` (32px) - Large gaps +- `12` (48px) - Section dividers + +**Pro tip:** Use `gap-` for grids/flex, `space-y-` for vertical stacks: + +```tsx +// Grid spacing +
+ +// Stack spacing +
+``` + +**[Read spacing philosophy](./04-spacing-philosophy.md)** + +--- + +## 5. Responsive Design + +**Mobile-first approach** with Tailwind breakpoints: + +```tsx +
+

+ Responsive Title +

+
+ +// Grid columns +
+``` + +**Breakpoints:** +- `sm:` 640px+ +- `md:` 768px+ +- `lg:` 1024px+ +- `xl:` 1280px+ + +--- + +## 6. Accessibility + +**Always include:** + +```tsx +// Labels for inputs + + + +// ARIA for errors + +{errors.email && ( +

+ {errors.email.message} +

+)} + +// ARIA labels for icon-only buttons + +``` + +**[Complete accessibility guide](./07-accessibility.md)** + +--- + +## 7. Common Patterns Cheat Sheet + +### Loading State + +```tsx +import { Skeleton } from '@/components/ui/skeleton'; + +{isLoading ? ( + +) : ( +
{content}
+)} +``` + +### Dropdown Menu + +```tsx +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuTrigger +} from '@/components/ui/dropdown-menu'; + + + + + + + Edit + Delete + + +``` + +### Badge/Tag + +```tsx +import { Badge } from '@/components/ui/badge'; + +New +Urgent +Draft +``` + +--- + +## 8. Next Steps + +You now know enough to build most interfaces! For deeper knowledge: + +### Learn More +- **Components**: [Complete component guide](./02-components.md) +- **Layouts**: [Layout patterns](./03-layouts.md) +- **Forms**: [Form patterns & validation](./06-forms.md) +- **Custom Components**: [Component creation guide](./05-component-creation.md) + +### Interactive Examples +- **[Component Showcase](/dev/components)** - All components with code +- **[Layout Examples](/dev/layouts)** - Before/after comparisons +- **[Form Examples](/dev/forms)** - Complete form implementations + +### Reference +- **[Quick Reference Tables](./99-reference.md)** - Bookmark this for lookups +- **[Foundations](./01-foundations.md)** - Complete color/spacing/typography guide + +--- + +## 🎯 Golden Rules + +Remember these and you'll be 95% compliant: + +1. ✅ **Import from `@/components/ui/*`** +2. ✅ **Use semantic colors**: `bg-primary`, not `bg-blue-500` +3. ✅ **Use spacing scale**: 4, 8, 12, 16, 24, 32 (multiples of 4) +4. ✅ **Use `cn()` for className merging**: `cn("base", conditional && "extra", className)` +5. ✅ **Add accessibility**: Labels, ARIA, keyboard support +6. ✅ **Test in dark mode**: Toggle with theme switcher + +--- + +## 🚀 Start Building! + +You're ready to build. When you hit edge cases or need advanced patterns, refer back to the [full documentation](./README.md). + +**Bookmark these:** +- [Quick Reference](./99-reference.md) - For quick lookups +- [AI Guidelines](./08-ai-guidelines.md) - If using AI assistants +- [Component Showcase](/dev/components) - For copy-paste examples + +Happy coding! 🎨 diff --git a/frontend/docs/design-system/01-foundations.md b/frontend/docs/design-system/01-foundations.md new file mode 100644 index 0000000..667a314 --- /dev/null +++ b/frontend/docs/design-system/01-foundations.md @@ -0,0 +1,909 @@ +# Foundations + +**The building blocks of our design system**: OKLCH colors, typography scale, spacing tokens, shadows, and border radius. Master these fundamentals to build consistent, accessible interfaces. + +--- + +## Table of Contents + +1. [Technology Stack](#technology-stack) +2. [Color System (OKLCH)](#color-system-oklch) +3. [Typography](#typography) +4. [Spacing Scale](#spacing-scale) +5. [Shadows](#shadows) +6. [Border Radius](#border-radius) +7. [Quick Reference](#quick-reference) + +--- + +## Technology Stack + +### Core Technologies + +- **Framework**: Next.js 15 + React 19 +- **Styling**: Tailwind CSS 4 (CSS-first configuration) +- **Components**: shadcn/ui (New York style) +- **Color Space**: OKLCH (perceptually uniform) +- **Icons**: lucide-react +- **Fonts**: Geist Sans + Geist Mono + +### Design Principles + +1. **🎨 Semantic First** - Use `bg-primary`, not `bg-blue-500` +2. **♿ Accessible by Default** - WCAG AA compliance minimum (4.5:1 contrast) +3. **📐 Consistent Spacing** - Multiples of 4px (0.25rem base unit) +4. **🧩 Compose, Don't Create** - Use shadcn/ui primitives +5. **🌗 Dark Mode Ready** - All components work in light/dark +6. **⚡ Pareto Efficient** - 80% of needs with 20% of patterns + +--- + +## Color System (OKLCH) + +### Why OKLCH? + +We use **OKLCH** (Oklab LCH) color space for: +- ✅ **Perceptual uniformity** - Colors look consistent across light/dark modes +- ✅ **Better accessibility** - Predictable contrast ratios +- ✅ **Vibrant colors** - More saturated without sacrificing legibility +- ✅ **Future-proof** - CSS native support (vs HSL/RGB) + +**Learn more**: [oklch.com](https://oklch.com) + +--- + +### Semantic Color Tokens + +All colors follow the **background/foreground** convention: +- `background` - The background color +- `foreground` - The text color that goes on that background + +**This ensures accessible contrast automatically.** + +--- + +### Primary Colors + +**Purpose**: Main brand color, CTAs, primary actions + +```css +/* Light & Dark Mode */ +--primary: oklch(0.6231 0.1880 259.8145) /* Blue */ +--primary-foreground: oklch(1 0 0) /* White text */ +``` + +**Usage**: +```tsx +// Primary button (most common) + + +// Primary link + + Learn more + + +// Primary badge +New +``` + +**When to use**: +- ✅ Call-to-action buttons +- ✅ Primary links +- ✅ Active states in navigation +- ✅ Important badges/tags + +**When NOT to use**: +- ❌ Large background areas (too intense) +- ❌ Body text (use `text-foreground`) +- ❌ Disabled states (use `muted`) + +--- + +### Secondary Colors + +**Purpose**: Secondary actions, less prominent UI elements + +```css +/* Light Mode */ +--secondary: oklch(0.9670 0.0029 264.5419) /* Light gray-blue */ +--secondary-foreground: oklch(0.1529 0 0) /* Dark text */ + +/* Dark Mode */ +--secondary: oklch(0.2686 0 0) /* Dark gray */ +--secondary-foreground: oklch(0.9823 0 0) /* Light text */ +``` + +**Usage**: +```tsx +// Secondary button + + +// Secondary badge +Draft + +// Muted background area +
+ Less important information +
+``` + +--- + +### Muted Colors + +**Purpose**: Backgrounds for disabled states, subtle UI elements + +```css +/* Light Mode */ +--muted: oklch(0.9846 0.0017 247.8389) +--muted-foreground: oklch(0.4667 0.0043 264.4327) + +/* Dark Mode */ +--muted: oklch(0.2393 0 0) +--muted-foreground: oklch(0.6588 0.0043 264.4327) +``` + +**Usage**: +```tsx +// Disabled button + + +// Secondary/helper text +

+ This action cannot be undone +

+ +// Skeleton loader + + +// TabsList background + + + Tab 1 + + +``` + +**Common use cases**: +- Disabled button backgrounds +- Placeholder/skeleton loaders +- TabsList backgrounds +- Switch backgrounds (unchecked state) +- Helper text, captions, timestamps + +--- + +### Accent Colors + +**Purpose**: Hover states, focus indicators, highlights + +```css +/* Light Mode */ +--accent: oklch(0.9514 0.0250 236.8242) +--accent-foreground: oklch(0.1529 0 0) + +/* Dark Mode */ +--accent: oklch(0.3791 0.1378 265.5222) +--accent-foreground: oklch(0.9823 0 0) +``` + +**Usage**: +```tsx +// Dropdown menu item hover + + + + Edit + + + + +// Highlighted section +
+ Featured content +
+``` + +**Common use cases**: +- Dropdown menu item hover states +- Command palette hover states +- Highlighted sections +- Subtle emphasis backgrounds + +--- + +### Destructive Colors + +**Purpose**: Error states, delete actions, warnings + +```css +/* Light & Dark Mode */ +--destructive: oklch(0.6368 0.2078 25.3313) /* Red */ +--destructive-foreground: oklch(1 0 0) /* White text */ +``` + +**Usage**: +```tsx +// Delete button + + +// Error alert + + + Error + + Something went wrong. Please try again. + + + +// Form error text +

+ {errors.email?.message} +

+ +// Destructive badge +Critical +``` + +**When to use**: +- ✅ Delete/remove actions +- ✅ Error messages +- ✅ Validation errors +- ✅ Critical warnings + +--- + +### Card & Popover Colors + +**Purpose**: Elevated surfaces (cards, popovers, dropdowns) + +```css +/* Light Mode */ +--card: oklch(1.0000 0 0) /* White */ +--card-foreground: oklch(0.1529 0 0) /* Dark text */ +--popover: oklch(1.0000 0 0) /* White */ +--popover-foreground: oklch(0.1529 0 0) /* Dark text */ + +/* Dark Mode */ +--card: oklch(0.2686 0 0) /* Dark gray */ +--card-foreground: oklch(0.9823 0 0) /* Light text */ +--popover: oklch(0.2686 0 0) /* Dark gray */ +--popover-foreground: oklch(0.9823 0 0) /* Light text */ +``` + +**Usage**: +```tsx +// Card (uses card colors by default) + + + Card Title + + Card content + + +// Popover + + Open + Popover content + +``` + +--- + +### Border & Input Colors + +**Purpose**: Borders, input field borders, dividers + +```css +/* Light Mode */ +--border: oklch(0.9276 0.0058 264.5313) +--input: oklch(0.9276 0.0058 264.5313) + +/* Dark Mode */ +--border: oklch(0.3715 0 0) +--input: oklch(0.3715 0 0) +``` + +**Usage**: +```tsx +// Input border + + +// Card with border +Content + +// Separator + + +// Custom border +
+ Content +
+``` + +--- + +### Focus Ring + +**Purpose**: Focus indicators for keyboard navigation + +```css +/* Light & Dark Mode */ +--ring: oklch(0.6231 0.1880 259.8145) /* Primary blue */ +``` + +**Usage**: +```tsx +// Button with focus ring (automatic) + + +// Custom focusable element +
+ Focusable content +
+``` + +**Accessibility note**: Focus rings are critical for keyboard navigation. Never remove them with `outline: none` without providing an alternative. + +--- + +### Chart Colors + +**Purpose**: Data visualization with harmonious color palette + +```css +--chart-1: oklch(0.6231 0.1880 259.8145) /* Blue */ +--chart-2: oklch(0.5461 0.2152 262.8809) /* Purple-blue */ +--chart-3: oklch(0.4882 0.2172 264.3763) /* Deep purple */ +--chart-4: oklch(0.4244 0.1809 265.6377) /* Violet */ +--chart-5: oklch(0.3791 0.1378 265.5222) /* Deep violet */ +``` + +**Usage**: +```tsx +// In chart components +const COLORS = [ + 'hsl(var(--chart-1))', + 'hsl(var(--chart-2))', + 'hsl(var(--chart-3))', + 'hsl(var(--chart-4))', + 'hsl(var(--chart-5))', +]; +``` + +--- + +### Color Decision Tree + +``` +What's the purpose? +│ +├─ Main action/CTA? → PRIMARY +├─ Secondary action? → SECONDARY +├─ Error/delete? → DESTRUCTIVE +├─ Hover state? → ACCENT +├─ Disabled/subtle? → MUTED +├─ Card/elevated surface? → CARD +├─ Border/divider? → BORDER +└─ Focus indicator? → RING +``` + +--- + +### Color Usage Guidelines + +#### ✅ DO + +```tsx +// Use semantic tokens +
CTA
+

Error message

+
Subtle background
+ +// Use accent for hover +
+ Hover me +
+ +// Test contrast +// Primary on white: 4.5:1 ✅ +// Destructive on white: 4.5:1 ✅ +``` + +#### ❌ DON'T + +```tsx +// Don't use arbitrary colors +
Bad
+ +// Don't mix color spaces +
Bad
+ +// Don't use primary for large areas +
Too intense
+ +// Don't override foreground without checking contrast +
Low contrast!
+``` + +--- + +## Typography + +### Font Families + +```css +--font-sans: Geist Sans, system-ui, -apple-system, sans-serif +--font-mono: Geist Mono, ui-monospace, monospace +--font-serif: ui-serif, Georgia, serif +``` + +**Usage**: +```tsx +// Sans serif (default) +
Body text
+ +// Monospace (code) +const example = true; + +// Serif (rarely used) +
Quote
+``` + +--- + +### Type Scale + +| Size | Class | rem | px | Use Case | +|------|-------|-----|----|----| +| 9xl | `text-9xl` | 8rem | 128px | Hero text (rare) | +| 8xl | `text-8xl` | 6rem | 96px | Hero text (rare) | +| 7xl | `text-7xl` | 4.5rem | 72px | Hero text (rare) | +| 6xl | `text-6xl` | 3.75rem | 60px | Hero text (rare) | +| 5xl | `text-5xl` | 3rem | 48px | Landing page H1 | +| 4xl | `text-4xl` | 2.25rem | 36px | Page H1 | +| 3xl | `text-3xl` | 1.875rem | 30px | **Page titles** | +| 2xl | `text-2xl` | 1.5rem | 24px | **Section headings** | +| xl | `text-xl` | 1.25rem | 20px | **Card titles** | +| lg | `text-lg` | 1.125rem | 18px | **Subheadings** | +| base | `text-base` | 1rem | 16px | **Body text (default)** | +| sm | `text-sm` | 0.875rem | 14px | **Secondary text, captions** | +| xs | `text-xs` | 0.75rem | 12px | **Labels, helper text** | + +**Bold = most commonly used** + +--- + +### Font Weights + +| Weight | Class | Numeric | Use Case | +|--------|-------|---------|----------| +| Bold | `font-bold` | 700 | **Headings, emphasis** | +| Semibold | `font-semibold` | 600 | **Subheadings, buttons** | +| Medium | `font-medium` | 500 | **Labels, menu items** | +| Normal | `font-normal` | 400 | **Body text (default)** | +| Light | `font-light` | 300 | De-emphasized text | + +**Bold = most commonly used** + +--- + +### Typography Patterns + +#### Page Title +```tsx +

Page Title

+``` + +#### Section Heading +```tsx +

Section Heading

+``` + +#### Card Title +```tsx +Card Title +``` + +#### Body Text +```tsx +

+ Regular paragraph text uses the default text-base size. +

+``` + +#### Secondary Text +```tsx +

+ Helper text, timestamps, captions +

+``` + +#### Label +```tsx + +``` + +--- + +### Line Height + +| Class | Value | Use Case | +|-------|-------|----------| +| `leading-none` | 1 | Headings (rare) | +| `leading-tight` | 1.25 | **Headings** | +| `leading-snug` | 1.375 | Dense text | +| `leading-normal` | 1.5 | **Body text (default)** | +| `leading-relaxed` | 1.625 | Comfortable reading | +| `leading-loose` | 2 | Very relaxed (rare) | + +**Usage**: +```tsx +// Heading +

+ Tight line height for headings +

+ +// Body (default) +

+ Normal line height for readability +

+``` + +--- + +### Typography Guidelines + +#### ✅ DO + +```tsx +// Use semantic foreground colors +

Body text

+

Secondary text

+ +// Maintain heading hierarchy +

Page Title

+

Section

+

Subsection

+ +// Limit line length for readability +
+

60-80 characters per line is optimal

+
+ +// Use responsive type sizes +

+ Responsive Title +

+``` + +#### ❌ DON'T + +```tsx +// Don't use too many sizes on one page +

Too small

+

Still small

+

Base

+

Large

+

Larger

+// ^ Pick 2-3 sizes max + +// Don't skip heading levels +

Page

+

Section

// ❌ Skipped h2 + +// Don't use custom colors without contrast check +

Low contrast

+ +// Don't overuse bold +

+ Every + word + bold +

+``` + +--- + +## Spacing Scale + +Tailwind uses a **0.25rem (4px) base unit**: + +```css +--spacing: 0.25rem; +``` + +**All spacing should be multiples of 4px** for consistency. + +### Spacing Tokens + +| Token | rem | Pixels | Use Case | +|-------|-----|--------|----------| +| `0` | 0 | 0px | No spacing | +| `px` | - | 1px | Borders, dividers | +| `0.5` | 0.125rem | 2px | Very tight | +| `1` | 0.25rem | 4px | Icon gaps | +| `2` | 0.5rem | 8px | **Tight spacing** (label → input) | +| `3` | 0.75rem | 12px | Component padding | +| `4` | 1rem | 16px | **Standard spacing** (form fields) | +| `5` | 1.25rem | 20px | Medium spacing | +| `6` | 1.5rem | 24px | **Section spacing** (cards) | +| `8` | 2rem | 32px | **Large gaps** | +| `10` | 2.5rem | 40px | Very large gaps | +| `12` | 3rem | 48px | **Section dividers** | +| `16` | 4rem | 64px | **Page sections** | +| `20` | 5rem | 80px | Extra large | +| `24` | 6rem | 96px | Huge spacing | + +**Bold = most commonly used** + +--- + +### Container & Max Width + +```tsx +// Responsive container with horizontal padding +
+ Content +
+ +// Constrained width for readability +
+ Article content +
+``` + +### Max Width Scale + +| Class | Pixels | Use Case | +|-------|--------|----------| +| `max-w-xs` | 320px | Tiny cards | +| `max-w-sm` | 384px | Small cards | +| `max-w-md` | 448px | **Forms** | +| `max-w-lg` | 512px | **Modals** | +| `max-w-xl` | 576px | Medium content | +| `max-w-2xl` | 672px | **Article content** | +| `max-w-3xl` | 768px | Documentation | +| `max-w-4xl` | 896px | **Wide layouts** | +| `max-w-5xl` | 1024px | Extra wide | +| `max-w-6xl` | 1152px | Very wide | +| `max-w-7xl` | 1280px | **Full page width** | + +**Bold = most commonly used** + +--- + +### Spacing Guidelines + +#### ✅ DO + +```tsx +// Use multiples of 4 +
Content
+ +// Use gap for flex/grid +
+ + +
+ +// Use space-y for stacks +
+ + +
+ +// Use responsive spacing +
+ Responsive padding +
+``` + +#### ❌ DON'T + +```tsx +// Don't use arbitrary values +
Bad
+ +// Don't mix methods inconsistently +
+
Inconsistent
+
Inconsistent
+
+ +// Don't forget responsive spacing +
Too much padding on mobile
+``` + +**See [Spacing Philosophy](./04-spacing-philosophy.md) for detailed spacing strategy.** + +--- + +## Shadows + +Professional shadow system for depth and elevation: + +```css +--shadow-xs: 0 1px 3px 0px hsl(0 0% 0% / 0.05) +--shadow-sm: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10) +--shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10) +--shadow-md: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 2px 4px -1px hsl(0 0% 0% / 0.10) +--shadow-lg: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 4px 6px -1px hsl(0 0% 0% / 0.10) +--shadow-xl: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 8px 10px -1px hsl(0 0% 0% / 0.10) +--shadow-2xl: 0 1px 3px 0px hsl(0 0% 0% / 0.25) +``` + +### Shadow Usage + +| Elevation | Class | Use Case | +|-----------|-------|----------| +| Base | No shadow | Buttons, inline elements | +| Low | `shadow-sm` | **Cards, panels** | +| Medium | `shadow-md` | **Dropdowns, tooltips** | +| High | `shadow-lg` | **Modals, popovers** | +| Highest | `shadow-xl` | Notifications, floating elements | +| Maximum | `shadow-2xl` | Dialogs (rare) | + +**Usage**: +```tsx +// Card with subtle shadow +Card content + +// Dropdown with medium shadow + + Menu items + + +// Modal with high shadow + + Modal content + + +// Floating notification +
+ Notification +
+``` + +**Dark mode note**: Shadows are less visible in dark mode. Test both modes. + +--- + +## Border Radius + +Consistent rounded corners across the application: + +```css +--radius: 0.375rem; /* 6px - base */ + +--radius-sm: calc(var(--radius) - 4px) /* 2px */ +--radius-md: calc(var(--radius) - 2px) /* 4px */ +--radius-lg: var(--radius) /* 6px */ +--radius-xl: calc(var(--radius) + 4px) /* 10px */ +``` + +### Border Radius Scale + +| Token | Class | Pixels | Use Case | +|-------|-------|--------|----------| +| None | `rounded-none` | 0px | Square elements | +| Small | `rounded-sm` | 2px | **Tags, small badges** | +| Medium | `rounded-md` | 4px | **Inputs, small buttons** | +| Large | `rounded-lg` | 6px | **Cards, buttons (default)** | +| XL | `rounded-xl` | 10px | **Large cards, modals** | +| 2XL | `rounded-2xl` | 16px | Hero sections | +| 3XL | `rounded-3xl` | 24px | Very rounded | +| Full | `rounded-full` | 9999px | **Pills, avatars, icon buttons** | + +**Bold = most commonly used** + +### Usage Examples + +```tsx +// Button (default) + + +// Input field + + +// Card +Large card + +// Avatar + + + + +// Badge/Tag +Small tag + +// Pill button + +``` + +### Directional Radius + +```tsx +// Top corners only +
Top rounded
+ +// Bottom corners only +
Bottom rounded
+ +// Left corners only +
Left rounded
+ +// Right corners only +
Right rounded
+ +// Individual corners +
+ Top-left and bottom-right +
+``` + +--- + +## Quick Reference + +### Most Used Tokens + +**Colors**: +- `bg-primary text-primary-foreground` - CTAs +- `bg-destructive text-destructive-foreground` - Delete/errors +- `bg-muted text-muted-foreground` - Disabled/subtle +- `text-foreground` - Body text +- `text-muted-foreground` - Secondary text +- `border-border` - Borders + +**Typography**: +- `text-3xl font-bold` - Page titles +- `text-2xl font-semibold` - Section headings +- `text-xl font-semibold` - Card titles +- `text-base` - Body text +- `text-sm text-muted-foreground` - Secondary text + +**Spacing**: +- `p-4` - Standard padding (16px) +- `p-6` - Card padding (24px) +- `gap-4` - Standard gap (16px) +- `gap-6` - Section gap (24px) +- `space-y-4` - Form field spacing (16px) +- `space-y-6` - Section spacing (24px) + +**Shadows & Radius**: +- `shadow-sm` - Cards +- `shadow-md` - Dropdowns +- `shadow-lg` - Modals +- `rounded-lg` - Buttons, cards (6px) +- `rounded-full` - Avatars, pills + +--- + +## Next Steps + +- **Quick Start**: [5-minute crash course](./00-quick-start.md) +- **Components**: [shadcn/ui component guide](./02-components.md) +- **Layouts**: [Layout patterns](./03-layouts.md) +- **Spacing**: [Spacing philosophy](./04-spacing-philosophy.md) +- **Reference**: [Quick lookup tables](./99-reference.md) + +--- + +**Related Documentation:** +- [Quick Start](./00-quick-start.md) - Essential patterns +- [Components](./02-components.md) - shadcn/ui library +- [Spacing Philosophy](./04-spacing-philosophy.md) - Margin vs padding strategy +- [Accessibility](./07-accessibility.md) - WCAG compliance + +**External Resources:** +- [OKLCH Color Picker](https://oklch.com) +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) +- [Tailwind CSS Documentation](https://tailwindcss.com/docs) + +**Last Updated**: November 2, 2025 diff --git a/frontend/docs/design-system/02-components.md b/frontend/docs/design-system/02-components.md new file mode 100644 index 0000000..d23e7a7 --- /dev/null +++ b/frontend/docs/design-system/02-components.md @@ -0,0 +1,1228 @@ +# Components + +**Master the shadcn/ui component library**: Learn all variants, composition patterns, and when to use each component. This is your complete reference for building consistent interfaces. + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Core Components](#core-components) +3. [Form Components](#form-components) +4. [Feedback Components](#feedback-components) +5. [Overlay Components](#overlay-components) +6. [Data Display Components](#data-display-components) +7. [Composition Patterns](#composition-patterns) +8. [Quick Reference](#quick-reference) + +--- + +## Overview + +### About shadcn/ui + +We use **[shadcn/ui](https://ui.shadcn.com)**, a collection of accessible, customizable components built on **Radix UI primitives**. + +**Key features:** +- ✅ **Accessible** - WCAG AA compliant, keyboard navigation, screen reader support +- ✅ **Customizable** - Components are copied into your project (not npm dependencies) +- ✅ **Composable** - Build complex UIs from simple primitives +- ✅ **Dark mode** - All components work in light and dark modes +- ✅ **Type-safe** - Full TypeScript support + +### Installation Method + +```bash +# Add new components +npx shadcn@latest add button card input dialog + +# List available components +npx shadcn@latest add +``` + +**Installed components** (in `/src/components/ui/`): +- alert, avatar, badge, button, card, checkbox, dialog +- dropdown-menu, input, label, popover, select, separator +- sheet, skeleton, table, tabs, textarea, toast + +--- + +## Core Components + +### Button + +**Purpose**: Trigger actions, navigate, submit forms + +```tsx +import { Button } from '@/components/ui/button'; + +// Variants + + + + + + + +// Sizes + + + + + +// States + + + +// As Link (Next.js) + +``` + +**When to use each variant:** + +| Variant | Use Case | Example | +|---------|----------|---------| +| `default` | Primary actions, CTAs | Save, Submit, Create | +| `secondary` | Secondary actions | Cancel, Back | +| `outline` | Alternative actions | View Details, Edit | +| `ghost` | Subtle actions in lists | Icon buttons in table rows | +| `link` | In-text actions | Read more, Learn more | +| `destructive` | Delete, remove actions | Delete Account, Remove | + +**Accessibility**: +- Always add `aria-label` for icon-only buttons +- Use `disabled` for unavailable actions (not hidden) +- Loading state prevents double-submission + +**[See live examples](/dev/components#button)** + +--- + +### Badge + +**Purpose**: Labels, tags, status indicators + +```tsx +import { Badge } from '@/components/ui/badge'; + +// Variants +New +Draft +Pending +Critical + +// Custom colors (use sparingly) +Active +Warning +``` + +**Common patterns:** + +```tsx +// Status badge +{user.is_active ? ( + Active +) : ( + Inactive +)} + +// Count badge +{itemCount} + +// Role badge +{user.role} +``` + +--- + +### Avatar + +**Purpose**: User profile pictures, placeholders + +```tsx +import { Avatar, AvatarImage, AvatarFallback } from '@/components/ui/avatar'; + +// With image + + + JD + + +// Fallback only (initials) + + AB + + +// Sizes (custom classes) +... +... +... +``` + +**Pattern: User menu**: +```tsx + + + + + {user.initials} + + + + Profile + Settings + Logout + + +``` + +--- + +### Card + +**Purpose**: Container for related content, groups information + +```tsx +import { + Card, + CardHeader, + CardTitle, + CardDescription, + CardContent, + CardFooter +} from '@/components/ui/card'; + +// Basic card + + + Users + Manage system users + + +

Card content goes here

+ + + + + + +// Minimal card (content only) + +

Quick Stats

+

1,234

+ +``` + +**Common patterns:** + +```tsx +// Card with action button in header + + +
+
+ Recent Activity + Last 7 days +
+ +
+ + {/* content */} + + +// Dashboard metric card + + + + Total Revenue + + + + +
$45,231.89
+

+ +20.1% from last month +

+ + +``` + +--- + +### Separator + +**Purpose**: Visual divider between content sections + +```tsx +import { Separator } from '@/components/ui/separator'; + +// Horizontal (default) +
+
Section 1
+ +
Section 2
+
+ +// Vertical +
+
Left
+ +
Right
+
+ +// Decorative (for screen readers) + +``` + +--- + +## Form Components + +### Input + +**Purpose**: Text input, email, password, etc. + +```tsx +import { Input } from '@/components/ui/input'; +import { Label } from '@/components/ui/label'; + +// Basic input +
+ + +
+ +// With error state +
+ + + {errors.password && ( +

+ {errors.password.message} +

+ )} +
+ +// Disabled + + +// Read-only + +``` + +**Input types:** +- `text` - Default text input +- `email` - Email address +- `password` - Password field +- `number` - Numeric input +- `tel` - Telephone number +- `url` - URL input +- `search` - Search field + +**See [Forms Guide](./06-forms.md) for complete form patterns** + +--- + +### Textarea + +**Purpose**: Multi-line text input + +```tsx +import { Textarea } from '@/components/ui/textarea'; + +
+ +