# Design System Documentation

> **Hệ thống thiết kế toàn diện cho GoodGo Web Client**
>
> Tài liệu này mô tả đầy đủ các design deliverables chuyên nghiệp, từ UX research đến UI implementation, giúp team phát triển và thiết kế làm việc hiệu quả.

## 📚 Mục lục

- [1. UX Foundation - Nền tảng trải nghiệm người dùng](#1-ux-foundation)
- [2. UI Visual Design - Thiết kế giao diện](#2-ui-visual-design)
- [3. Design System - Hệ thống thiết kế](#3-design-system)
- [4. Component Library - Thư viện thành phần](#4-component-library)
- [5. Developer Handoff - Bàn giao cho Dev](#5-developer-handoff)

---

## 1. UX Foundation - Nền tảng trải nghiệm người dùng

### 1.1 Information Architecture

#### Sitemap
**Vị trí**: `src/docs/ux/sitemap.md`

Cấu trúc tổng quan của ứng dụng:

```
GoodGo Web Client
├── Authentication
│   ├── Login (/login)
│   ├── Register (/register)
│   └── Forgot Password (/forgot-password)
├── Dashboard (/)
│   ├── Overview
│   ├── Analytics
│   └── Quick Actions
├── Profile (/profile)
│   ├── Settings
│   └── Preferences
└── [Add more sections...]
```

**Cách sử dụng**:
- Cập nhật file `ux/sitemap.md` khi thêm/bớt trang
- Dùng cho planning và onboarding team mới
- Tham khảo khi thiết kế navigation

---

### 1.2 User Flows

**Vị trí**: `src/docs/ux/flows/`

Các luồng người dùng quan trọng:

#### Authentication Flow
```
[Landing] → [Login Page] → [Email Input] → [Password Input]
    ↓
[Validation] → [Success: Dashboard]
    ↓
[Error: Show Message]

Alternative: Forgot Password
[Login Page] → [Forgot Password Link] → [Email Input]
    → [Send Reset Email] → [Success Message]
```

**Files**:
- `flows/auth-login.md` - Luồng đăng nhập
- `flows/auth-register.md` - Luồng đăng ký
- `flows/auth-password-reset.md` - Luồng reset mật khẩu

**Template cho mỗi flow**:
```markdown
# [Flow Name]

## Mục tiêu
Người dùng cần đạt được điều gì?

## Entry Points
Từ đâu người dùng bắt đầu?

## Steps
1. Step 1: Action → Result
2. Step 2: Action → Result
...

## Success Criteria
Làm thế nào để biết flow thành công?

## Error States
Các lỗi có thể xảy ra và cách xử lý?

## Figma Link
[Link to prototype]
```

---

### 1.3 Wireframes

**Vị trí**: `src/docs/ux/wireframes/`

#### Low-Fidelity (Concept)
- Sketch thủ công hoặc basic blocks
- Focus vào layout và content hierarchy
- Không có color, chỉ grayscale

#### Mid-Fidelity (Structure)
- Chi tiết hơn về components
- Content placeholders rõ ràng
- Grid system được áp dụng
- Chưa có branding/style

**Files**:
- `wireframes/auth-pages-low.md` - Low-fi wireframes
- `wireframes/auth-pages-mid.md` - Mid-fi wireframes

**Lưu wireframes**:
- Export từ Figma/Sketch dạng PNG
- Đặt trong `public/design/wireframes/`
- Link trong markdown files

---

## 2. UI Visual Design - Thiết kế giao diện

### 2.1 Moodboard

**Vị trí**: `src/docs/ui/moodboard.md`

Định hướng phong cách visual cho project:

#### X.ai Minimal Style (Current Direction)
- **Keywords**: Clean, Minimal, Sophisticated, Tech-forward
- **Inspiration**: X.ai, Linear, Vercel
- **Color Direction**: Dark backgrounds, vibrant accents
- **Typography**: Geometric sans-serif (Inter, Geist)
- **Visual Treatment**: Subtle glassmorphism, minimal shadows

**References**:
- X.ai authentication pages
- Linear app interface
- Vercel dashboard

---

### 2.2 High-Fidelity Mockups

**Vị trí**: `src/docs/ui/mockups/`

Thiết kế hoàn chỉnh của tất cả screens:

#### States Required for Each Screen
- ✅ **Default State** - Trạng thái bình thường
- ✅ **Hover State** - Khi di chuột qua interactive elements
- ✅ **Active State** - Khi click/focus
- ✅ **Error State** - Khi có lỗi validation
- ✅ **Success State** - Khi thao tác thành công
- ✅ **Loading State** - Khi đang xử lý
- ✅ **Empty State** - Khi không có data
- ✅ **Disabled State** - Khi element bị vô hiệu hóa

**Files**:
- `mockups/auth-login-states.md` - Tất cả states của login page
- `mockups/auth-register-states.md` - Tất cả states của register page
- `mockups/auth-forgot-password-states.md` - States của forgot password

---

### 2.3 Responsive Design

**Breakpoints** (Tailwind CSS):
- Mobile: `< 640px` (sm)
- Tablet: `640px - 1024px` (md, lg)
- Desktop: `> 1024px` (xl, 2xl)

**Files**:
- `ui/responsive/mobile-specs.md`
- `ui/responsive/tablet-specs.md`
- `ui/responsive/desktop-specs.md`

**Quy tắc responsive**:
- Mobile-first approach
- Stack elements vertically on mobile
- 2-column layout on tablet
- 3+ column layout on desktop
- Touch targets minimum 44x44px on mobile

---

## 3. Design System - Hệ thống thiết kế

### 3.1 Color Palette

**Vị trí**: `src/styles/theme.css` (Source of Truth)

#### X.ai Minimal Color Palette

**Dark Theme (Default)**:
```css
/* Backgrounds */
--bg-primary: #15202b;        /* Warm dark gray (not pure black) */
--bg-secondary: #1a2734;      /* Lighter variant */
--bg-tertiary: #1f2f3d;       /* Even lighter */
--bg-elevated: #243442;       /* Elevated surfaces */

/* Brand/Accent */
--accent-primary: #1D9BF0;    /* X.ai blue */
--accent-primary-hover: #1a8cd8;
--accent-secondary: #657786;

/* Text */
--text-primary: #FFFFFF;      /* Pure white */
--text-secondary: #8899A6;    /* Light gray */
--text-tertiary: #657786;     /* Mid gray */

/* Status Colors */
--accent-success: #10B981;    /* Green */
--accent-error: #EF4444;      /* Red */
--accent-warning: #F59E0B;    /* Amber */
--accent-info: #1D9BF0;       /* Blue */

/* Borders */
--border-primary: #38444d;
--border-secondary: #4a5966;
--border-focus: #1D9BF0;      /* X.ai blue */
```

**Light Theme**:
```css
--bg-primary: #FFFFFF;
--accent-primary: #1D9BF0;
--text-primary: #1D1D1F;
```

**Color Usage Guidelines**:
- Backgrounds: Use `--bg-*` variables
- Interactive elements: Use `--accent-primary` for primary actions
- Text: Use `--text-*` with proper hierarchy
- Never use hardcoded hex values in components

**Accessibility**:
- All color combinations meet WCAG 2.1 AA (4.5:1 contrast ratio)
- Test with WebAIM Contrast Checker

---

### 3.2 Typography

**Font Family**:
```css
--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
```

**Type Scale**:
```css
/* Headings */
--text-xs: 0.75rem;      /* 12px */
--text-sm: 0.875rem;     /* 14px */
--text-base: 1rem;       /* 16px */
--text-lg: 1.125rem;     /* 18px */
--text-xl: 1.25rem;      /* 20px */
--text-2xl: 1.5rem;      /* 24px */
--text-3xl: 1.875rem;    /* 30px */
--text-4xl: 2.25rem;     /* 36px */
--text-5xl: 3rem;        /* 48px */

/* Line Heights */
--leading-tight: 1.25;
--leading-normal: 1.5;
--leading-relaxed: 1.75;

/* Font Weights */
--font-normal: 400;
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;
--font-extrabold: 800;
```

**Typography Usage**:
- H1: `text-4xl font-extrabold` - Page titles
- H2: `text-3xl font-bold` - Section headers
- H3: `text-2xl font-semibold` - Subsection headers
- Body: `text-base font-normal` - Default text
- Small: `text-sm` - Secondary info
- Caption: `text-xs` - Captions, labels

---

### 3.3 Spacing System

**8-Point Grid System**:
```css
--spacing-0: 0;
--spacing-1: 0.25rem;   /* 4px */
--spacing-2: 0.5rem;    /* 8px */
--spacing-3: 0.75rem;   /* 12px */
--spacing-4: 1rem;      /* 16px */
--spacing-5: 1.25rem;   /* 20px */
--spacing-6: 1.5rem;    /* 24px */
--spacing-8: 2rem;      /* 32px */
--spacing-10: 2.5rem;   /* 40px */
--spacing-12: 3rem;     /* 48px */
--spacing-16: 4rem;     /* 64px */
--spacing-20: 5rem;     /* 80px */
```

**Spacing Guidelines**:
- Form fields: `space-y-4` (16px)
- Card padding: `p-8` (32px)
- Section spacing: `space-y-12` (48px)
- Container max-width: `max-w-md` (448px) for auth forms

---

### 3.4 Border Radius

```css
--radius-sm: 0.375rem;   /* 6px */
--radius-md: 0.5rem;     /* 8px */
--radius-lg: 0.75rem;    /* 12px */
--radius-xl: 1rem;       /* 16px */
--radius-2xl: 1.5rem;    /* 24px */
--radius-full: 9999px;   /* Fully rounded */
```

---

### 3.5 Shadows

```css
/* Subtle shadows for minimal design */
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
--shadow-md: 0 2px 8px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 4px 12px rgba(0, 0, 0, 0.15);
--shadow-xl: 0 8px 24px rgba(0, 0, 0, 0.2);

/* Glass shadows */
--shadow-glass-sm: 0 2px 8px rgba(0, 0, 0, 0.3);
--shadow-glass-lg: 0 4px 12px rgba(0, 0, 0, 0.4);
```

---

### 3.6 Animations & Transitions

**Duration**:
```css
--duration-fast: 150ms;
--duration-normal: 300ms;
--duration-slow: 500ms;
```

**Easing**:
```css
--ease-snap: cubic-bezier(0.4, 0.0, 0.2, 1);
--ease-smooth: cubic-bezier(0.4, 0.0, 0.6, 1);
```

**Common Animations**:
- Hover scale: `hover:scale-[1.02] transition-transform duration-150`
- Fade in: `animate-in fade-in duration-300`
- Float: `animate-float` (custom keyframe in theme.css)

---

## 4. Component Library - Thư viện thành phần

### 4.1 Components Catalog

**Vị trí**: Storybook - `npm run storybook`

Tất cả components đã được document trong Storybook với:
- Visual examples
- Props API
- Usage guidelines
- Accessibility notes
- Code snippets

### 4.2 Core Components

#### Button
**Path**: `src/features/shared/components/ui/button/`

**Variants**:
- `brand` - Primary CTA (X.ai blue)
- `secondary` - Secondary actions
- `ghost` - Tertiary actions
- `danger` - Destructive actions

**Sizes**: `sm`, `md`, `lg`

**States**: default, hover, active, loading, disabled

**Usage**:
```tsx
<Button variant="brand" size="lg">
  Sign In
</Button>
```

---

#### Input
**Path**: `src/features/shared/components/ui/input/`

**Features**:
- Label support
- Error messages
- Description text
- Password visibility toggle
- Focus states with X.ai blue

**States**: default, focus, error, disabled

**Usage**:
```tsx
<Input
  label="Email"
  type="email"
  placeholder="you@example.com"
  error="Invalid email"
/>
```

---

#### Card
**Path**: `src/features/shared/components/ui/card/`

**Features**:
- Glass effect variants
- Hover states
- Border options

**Usage**:
```tsx
<Card className="glass-card p-8">
  <CardHeader>
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent>
    Content here
  </CardContent>
</Card>
```

---

### 4.3 Glass Effects

**Path**: `src/styles/glass.css`

**Classes**:
- `.glass-card` - Card containers
- `.glass-input` - Input fields
- `.glass-bg` - Generic glass background

**X.ai Minimal Glass**:
- Ultra-subtle transparency (1-5%)
- Thin borders (3-10% white)
- Minimal blur (4-12px)
- Works on #15202b background

---

## 5. Developer Handoff - Bàn giao cho Dev

### 5.1 Design Specs

**Tools**:
- Figma Dev Mode (recommended)
- Zeplin
- Measure Chrome Extension

**Specs to Include**:
- Exact pixel measurements
- Spacing between elements
- Font sizes and weights
- Color values (reference CSS variables)
- Border radius
- Shadow values

---

### 5.2 Assets Export

**Location**: `public/design/assets/`

**Format Guidelines**:
- **Icons**: SVG (preferred), PNG @2x, @3x
- **Images**: WebP (preferred), PNG, JPEG
- **Illustrations**: SVG for vector graphics
- **Logo**: SVG + PNG variants

**Export Checklist**:
- [ ] Optimize SVGs (remove unnecessary metadata)
- [ ] Export @1x, @2x, @3x for raster images
- [ ] Name files descriptively: `icon-close.svg`, `logo-light.svg`
- [ ] Organize in folders by category

---

### 5.3 Implementation Notes

**Vị trí**: `src/docs/implementation/`

**Files**:
- `implementation/auth-pages-notes.md` - Ghi chú cho auth pages
- `implementation/components-notes.md` - Component implementation details

**Template**:
```markdown
# [Component/Page Name] Implementation Notes

## Design Intent
Mục đích thiết kế là gì?

## Technical Requirements
- Framework: Next.js 14
- Styling: Tailwind CSS
- Animations: Framer Motion (if needed)

## Accessibility Requirements
- ARIA attributes needed
- Keyboard navigation
- Screen reader considerations

## Edge Cases
- What happens when...?
- How to handle...?

## Dependencies
- Required components
- Third-party libraries

## Testing Checklist
- [ ] Visual regression
- [ ] Accessibility (a11y)
- [ ] Responsive on all breakpoints
- [ ] Cross-browser compatibility
```

---

### 5.4 Component API Documentation

Mỗi component cần có:

**Props Table**:
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'brand' \| 'secondary'` | `'brand'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button |
| `disabled` | `boolean` | `false` | Disable interaction |

**Example Usage**:
```tsx
// Basic usage
<Button>Click me</Button>

// With all props
<Button
  variant="brand"
  size="lg"
  disabled={false}
  onClick={handleClick}
>
  Sign In
</Button>
```

---

## 📝 Maintenance & Updates

### When to Update This Documentation

1. **New Feature Added** → Update sitemap, user flows, components
2. **Visual Redesign** → Update moodboard, mockups, color palette
3. **Component Changes** → Update component specs in Storybook
4. **New Page** → Add to sitemap, create wireframes/mockups
5. **Accessibility Improvements** → Update WCAG compliance docs

### Version Control

- Use semantic versioning for design system updates
- Document breaking changes
- Keep changelog in `DESIGN_SYSTEM_CHANGELOG.md`

---

## 🔗 Quick Links

- [Storybook](http://localhost:6006) - Component library
- [WCAG Compliance](./WCAG_COMPLIANCE.md) - Accessibility guidelines
- [Performance](./PERFORMANCE.md) - Performance best practices
- [Figma Design Files](#) - (Add your Figma link here)

---

## 📞 Contact

**Design Team**: design@goodgo.com
**Dev Team**: dev@goodgo.com

---

**Last Updated**: 2026-01-04
**Version**: 2.0.0 (X.ai Minimal Redesign)
