# Next_Edu Design System Specs

**Version**: 1.4.0 (Updated)
**Status**: ACTIVE
**Role**: Chief Creative Director
**Philosophy**: "Data as Art" - Clean, Minimalist, Information-Dense.

---

## 1. 核心理念 (Core Philosophy)

Next_Edu 旨在对抗教育系统常见的信息过载。我们的设计风格深受 **International Typographic Style (国际主义设计风格)** 影响。

*   **Precision (精准)**: 每一个像素的留白都有其目的。
*   **Clarity (清晰)**: 通过排版和对比度区分层级，而非装饰性的色块。
*   **Efficiency (效率)**: 专为高密度数据操作优化，减少视觉噪音。

---

## 2. 视觉基础 (Visual Foundation)

### 2.1 色彩系统 (Color System)

我们放弃 Hex 直选，全面采用 **HSL 语义化变量** 以支持完美的多主题适配。

#### **Base (基调)**
*   **Neutral**: Zinc (锌色). 冷峻、纯净，无偏色。
*   **Brand**: Deep Indigo (深靛蓝).
    *   `Primary`: 专业、权威，避免幼稚的高饱和蓝。
    *   语义: `hsl(var(--primary))`

#### **Functional (功能色)**
| 语义 | 色系 | 用途 |
| :--- | :--- | :--- |
| **Destructive** | Red | 删除、危险操作、系统错误 |
| **Warning** | Amber | 需注意的状态、非阻断性警告 |
| **Success** | Emerald | 操作成功、状态正常 |
| **Info** | Blue | 一般性提示、帮助信息 |

#### **Surface Hierarchy (层级)**
1.  **Background**: 应用底层背景。
2.  **Card**: 内容承载容器，轻微提升层级。
3.  **Popover**: 悬浮层、下拉菜单，最高层级。
4.  **Muted**: 用于次级信息或禁用状态背景。

### 2.2 排版 (Typography)

*   **Font Family**: `Geist Sans` > `Inter` > `System UI`.
    *   *Requirement*: 必须开启 `tabular-nums` (等宽数字) 特性，确保表格数据对齐。
*   **Scale**:
    *   **Base Body**: 14px (0.875rem) - 提升信息密度。
    *   **H1 (Page Title)**: 24px, Tracking -0.02em, Weight 600.
    *   **H2 (Section Title)**: 20px, Tracking -0.01em, Weight 600.
    *   **H3 (Card Title)**: 16px, Weight 600.
    *   **Tiny/Caption**: 12px, Text-Muted-Foreground.

### 2.3 质感 (Look & Feel)

*   **Borders**: `1px solid var(--border)`. 界面骨架，以此分割区域而非背景色块。
*   **Radius**:
    *   `sm` (4px): Badges, Checkboxes.
    *   `md` (8px): **Default**. Buttons, Inputs, Cards.
    *   `lg` (12px): Modals, Dialogs.
*   **Shadows**:
    *   Default: None (Flat).
    *   Hover: `shadow-sm` (仅用于可交互元素).
    *   Dropdown/Popover: `shadow-md`.
    *   *Ban*: 禁止使用大面积弥散阴影。

---

## 3. 核心布局 (App Shell)

### 3.1 架构 (Architecture)
我们采用了 `SidebarProvider` + `AppSidebar` 的组合模式，确保了布局的灵活性和移动端的完美适配。

*   **Provider**: `SidebarProvider` (src/modules/layout/components/sidebar-provider.tsx)
    *   管理侧边栏状态 (`expanded`, `isMobile`).
    *   负责在移动端渲染 Sheet (Drawer)。
    *   负责在桌面端渲染 Sticky Sidebar。
    *   **Key Prop**: `sidebar` (显式传递侧边栏组件)。

### 3.2 布局结构
```
+-------------------------------------------------------+
|  Sidebar  |  Header (Sticky)                          |
|           |-------------------------------------------|
| (Collap-  |  Main Content                             |
|  sible)   |                                           |
|           |  +-------------------------------------+  |
|           |  | Card                                |  |
|           |  | +---------------------------------+ |  |
|           |  | | Data Table                      | |  |
|           |  | +---------------------------------+ |  |
|           |  +-------------------------------------+  |
|           |                                           |
+-------------------------------------------------------+
```

### 3.3 详细规范

#### **Sidebar (侧边栏)**
*   **Width**: Expanded `260px` | Collapsed `64px` | Mobile `Sheet (Drawer)`.
*   **Behavior**:
    *   Desktop: 固定左侧，支持折叠。
    *   Mobile: 默认隐藏，点击汉堡菜单从左侧滑出。
*   **Navigation Item**:
    *   Height: `36px` (Compact).
    *   State:
        *   `Inactive`: `text-muted-foreground hover:text-foreground`.
        *   `Active`: `bg-sidebar-accent text-sidebar-accent-foreground font-medium`.

#### **Header (顶栏)**
*   **Height**: `64px` (h-16).
*   **Layout**: `flex items-center justify-between px-6 border-b`.
*   **Components**:
    1.  **Breadcrumb**: 显示当前路径，层级清晰。
    2.  **Global Search**: `Cmd+K` 触发，居中或靠右。
    3.  **User Nav**: 头像 + 下拉菜单。

#### **Main Content (内容区)**
*   **Padding**: `p-6` (Desktop) / `p-4` (Mobile).
*   **Max Width**: `max-w-[1600px]` (默认) 或 `w-full` (针对超宽报表)。

---

## 4. 导航与角色系统 (Navigation & Roles)

Next_Edu 支持多角色（Multi-Tenant / Role-Based）导航系统。

### 4.1 配置文件
导航结构已从 UI 组件中解耦，统一配置在：
`src/modules/layout/config/navigation.ts`

### 4.2 支持的角色 (Roles)
系统内置支持以下角色，每个角色拥有独立的侧边栏菜单结构：
*   **Admin**: 系统管理员，拥有所有管理权限 (School Management, User Management, Finance)。
*   **Teacher**: 教师，关注班级管理 (My Classes)、成绩录入 (Gradebook) 和日程。
*   **Student**: 学生，关注课程学习 (My Learning) 和作业提交。
*   **Parent**: 家长，关注子女动态和学费缴纳。

### 4.3 开发与调试
*   **View As (Dev Mode)**: 在开发环境下，侧边栏顶部提供 "View As" 下拉菜单，允许开发者实时切换角色视角，预览不同角色的导航结构。
*   **Implementation**: `AppSidebar` 组件通过读取 `NAV_CONFIG[currentRole]` 动态渲染菜单项。

---

## 5. 错误处理与边界情况 (Error Handling & Boundaries)

系统必须优雅地处理错误和边缘情况，避免白屏或无反馈。

### 5.1 全局错误边界 (Global Error Boundary)
*   **Scope**: 捕获渲染期间的未处理异常。
*   **UI**: 显示友好的错误页面（非技术堆栈信息），提供 "Try Again" 按钮重置状态。
*   **Implementation**: 使用 React `ErrorBoundary` 或 Next.js `error.tsx`。

### 5.2 404 Not Found
*   **Design**: 必须保留 App Shell (Sidebar + Header)，仅在 Main Content 区域显示 404 提示。
*   **Content**: "Page not found" 文案 + 返回 Dashboard 的主操作按钮。

### 5.3 空状态 (Empty States)
当列表或表格无数据时，**严禁**只显示空白。
*   **Component**: `EmptyState`。
*   **Composition**:
    1.  **Icon**: 线性风格图标 (muted foreground).
    2.  **Title**: 简短说明 (e.g., "No students found").
    3.  **Description**: 解释原因或下一步操作 (e.g., "Add a student to get started").
    4.  **Action**: (可选) "Create New" 按钮。

### 5.4 加载状态 (Loading States)
*   **Initial Load**: 使用 `Skeleton` 骨架屏，模拟内容布局，避免 CLS (Content Layout Shift)。禁止使用全屏 Spinner。
*   **Action Loading**: 按钮点击后进入 `disabled` + `spinner` 状态。
*   **Table Loading**: 表格内容区域显示 3-5 行 Skeleton Rows。

### 5.5 表单验证 (Form Validation)
*   **Style**: 错误信息显示在输入框下方，字号 `text-xs`，颜色 `text-destructive`。
*   **Input**: 边框变红 (`border-destructive`)。

---

## 6. 职责边界与协作 (Responsibility Boundaries)

**[IMPORTANT] 严禁越界修改 (Strict No-Modification Policy)**

为了维护大型项目的可维护性，UI 工程师和开发人员必须遵守以下边界规则：

### 6.1 模块化原则 (Modularity)
*   **Scope**: 开发者仅应对分配给自己的模块负责。例如，负责 "Dashboard" 的开发者**不应**修改 "Sidebar" 或 "Auth" 模块的代码。
*   **Dependencies**: 如果你的模块依赖于其他模块的变更，**必须**先与该模块的负责人沟通，或在 PR 中明确标注。

### 6.2 共享组件 (Shared Components)
*   **Immutable Core**: `src/shared/components/ui` 下的基础组件（如 Button, Card）视为**核心库**。
*   **Extension**: 如果基础组件不能满足需求，优先考虑组合（Composition）或创建新的业务组件，而不是修改核心组件的源码。
*   **Modification Request**: 只有在发现严重 Bug 或需要全局样式调整时，才允许修改核心组件，且必须经过 Design Lead 审批。

### 6.3 样式一致性 (Consistency)
*   **Global CSS**: `globals.css` 定义了系统的物理法则。严禁在局部组件中随意覆盖全局 CSS 变量。
*   **Tailwind Config**: 禁止随意在组件中添加任意值（Arbitrary Values, e.g., `w-[123px]`），必须使用 Design Token。

---

## 7. 组件设计规范 (Component Specs)

### 7.1 Card (卡片)
卡片是信息组织的基本单元。
*   **Class**: `bg-card text-card-foreground border rounded-lg shadow-none`.
*   **Header**: `p-6 pb-2`. Title (`font-semibold leading-none tracking-tight`).
*   **Content**: `p-6 pt-0`.

### 7.2 Data Table (数据表格)
教务系统的核心组件。
*   **Density**: 
    *   `Default`: Row Height `48px` (h-12).
    *   `Compact`: Row Height `36px` (h-9).
*   **Header**: `bg-muted/50 text-muted-foreground text-xs uppercase font-medium`.
*   **Stripes**: 默认关闭。仅在列数 > 8 时开启 `even:bg-muted/50`。
*   **Actions**: 行操作按钮应默认隐形 (`opacity-0`)，Hover 时显示 (`group-hover:opacity-100`)，减少视觉干扰。

### 7.3 Feedback (反馈与通知)
*   **Toast**: 使用 `Sonner` 组件。
    *   位置: 默认右下角 (Bottom Right).
    *   样式: 极简黑白风格 (跟随主题)，支持撤销操作。
    *   调用: `toast("Event has been created", { description: "Sunday, December 03, 2023 at 9:00 AM" })`.
*   **Skeleton**: 加载状态必须使用 Skeleton 骨架屏，禁止使用全屏 Spinner。
*   **Badge**: 状态指示器。
    *   `default`: 主要状态 (Primary).
    *   `secondary`: 次要状态 (Neutral).
    *   `destructive`: 错误/警告状态 (Error).
    *   `outline`: 描边风格 (Subtle).

---

## 8. 开发指南 (Developer Guide)

### 8.1 CSS Variables
所有颜色和圆角均通过 CSS 变量控制，定义在 `globals.css` 中。禁止在代码中 Hardcode 颜色值 (如 `#FFFFFF`, `rgb(0,0,0)` )。

### 8.2 Tailwind Utility 优先
优先使用 Tailwind Utility Classes。
*   ✅ `text-sm text-muted-foreground`
*   ❌ `.custom-text-class { font-size: 14px; color: #666; }`

### 8.3 Dark Mode
设计系统原生支持深色模式。只要正确使用语义化颜色变量（如 `bg-background`, `text-foreground`），Dark Mode 将自动完美适配，无需额外编写 `dark:` 修饰符（除非为了特殊调整）。

### 8.4 组件库引用
所有 UI 组件位于 `src/shared/components/ui`。
*   `Button`: 基础按钮
*   `Input`: 输入框
*   `Select`: 下拉选择器 (New)
*   `Sheet`: 侧边栏/抽屉
*   `Sonner`: Toast 通知
*   `Badge`: 徽章/标签
*   `Skeleton`: 加载占位符
*   `DropdownMenu`: 下拉菜单
*   `Avatar`: 头像
*   `Label`: 表单标签
*   `EmptyState`: 空状态占位 (New)