259 lines
11 KiB
Markdown
259 lines
11 KiB
Markdown
# 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)
|