xiner/CICD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
13e91e628d2e8ee51b83f62bdf0148d3523cee41
CICD/docs/design/design_system.md
SpecialX e7c902e8e1
Some checks failed
CI / build-and-test (push) Failing after 1m31s
Details
CI / deploy (push) Has been skipped
Details
Module Update
2025-12-30 14:42:30 +08:00

11 KiB
Raw Blame History

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)