cardosofelipe/fast-next-template
Template
1
0
Fork 1
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Document initial design system guidelines and implementation details

Browse Source 
- Introduce FastNext Design System based on `shadcn/ui` and `Tailwind CSS 4`.
- Detail semantic color tokens using the OKLCH color space for better accessibility.
- Define typography, spacing, shadows, and border radius standards.
- Provide component usage guidelines for consistent and accessible design.
- Outline responsive design, performance, and accessibility best practices.
- Add dark mode implementation strategy and tooling references.
- Include a version history for change tracking and future updates.
This commit is contained in:
Felipe Cardoso
2025-11-02 06:49:43 +01:00
parent 04110cbf1c
commit 30f0ec5a64
1 changed files with 645 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

645
frontend/docs/DESIGN_SYSTEM.md Normal file
View File

@@ -0,0 +1,645 @@
# 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
<Button>Primary Action</Button>
<a href="#" className="text-primary">Link</a>
```
#### 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
<DropdownMenuItem className="focus:bg-accent">Item</DropdownMenuItem>
```
#### 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
<Button variant="destructive">Delete</Button>
<Alert variant="destructive">Error message</Alert>
```
#### 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
<div className="font-sans">Body text</div>
<code className="font-mono">const example = true;</code>
```
### 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
<div className="container mx-auto px-4">
{/* Responsive container with horizontal padding */}
</div>
<div className="max-w-2xl mx-auto">
{/* Constrained width for readability */}
</div>
```
**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 className="shadow-sm">Card content</Card>
<DropdownMenu className="shadow-md">Menu</DropdownMenu>
<Dialog className="shadow-xl">Modal</Dialog>
```
---
## 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
<Button className="rounded-lg">Default Button</Button>
<Avatar className="rounded-full" />
<Badge className="rounded-sm">Tag</Badge>
```
---
## 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 variant="default">Primary Button</Button>
<Button variant="secondary">Secondary Button</Button>
<Button variant="outline">Outline Button</Button>
<Button variant="ghost">Ghost Button</Button>
<Button variant="destructive">Delete</Button>
<Button variant="link">Link Button</Button>
```
#### Button Sizes
```tsx
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon"><Icon /></Button>
```
### 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 `<html>` element
3. **Persistent**: User preference stored in localStorage
4. **Smooth Transition**: Optional transitions between modes
### Implementation
```tsx
// Toggle dark mode
<Button onClick={() => document.documentElement.classList.toggle('dark')}>
Toggle Theme
</Button>
// 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
<Button className="focus-visible:ring-2 focus-visible:ring-ring">
Action
</Button>
// Skip to main content link
<a href="#main" className="sr-only focus:not-sr-only">
Skip to main content
</a>
```
### 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
<Button variant="destructive">Delete</Button>
<div className="bg-card text-card-foreground">Content</div>
```
**DON'T**:
```tsx
// ❌ Generic, non-semantic names
<Button className="bg-red-500">Delete</Button>
<div className="bg-white text-black">Content</div>
```
### Component Structure
**DO**:
```tsx
// ✅ Compose with shadcn/ui primitives
<Card>
<CardHeader>
<CardTitle>Title</CardTitle>
</CardHeader>
<CardContent>Content</CardContent>
</Card>
```
**DON'T**:
```tsx
// ❌ Create custom components for everything
<CustomCard title="Title">Content</CustomCard>
```
### Responsive Design
**DO**:
```tsx
// ✅ Mobile-first responsive utilities
<div className="p-4 sm:p-6 lg:p-8">
<h1 className="text-2xl sm:text-3xl lg:text-4xl">Title</h1>
</div>
```
**DON'T**:
```tsx
// ❌ Desktop-first or no responsive design
<div className="p-8">
<h1 className="text-4xl">Title</h1>
</div>
```
### 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.**