ai-ticket-platform/docs/frontend/design-system.md

前端设计系统

1. 设计原则

• 使用 shadcn/ui 基础组件和项目自有 App 组件构建业务页面。
• 运营页面保持紧凑、克制，优先服务高频重复操作。
• 工单状态、优先级、审计、AI 和系统反馈使用统一语义色。
• 用户可见文案以中文为主；TypeScript 标识符和 API 字段可保持英文。
• 列表、筛选、详情、状态和优先级不得创建一次性样式。
• 管理端强调清晰层级、有限表面和紧凑操作，不使用营销页式装饰布局。
• 亮色和暗色主题必须同时可用，业务页面不自行硬编码主题颜色。

2. 设计令牌

主题令牌位于 frontend/src/styles/globals.css，通过 frontend/tailwind.config.ts 暴露给 Tailwind。

核心令牌：

• background、foreground、surface、border
• muted、muted-foreground
• primary、success、warning、danger、info、ai
• sidebar、sidebar-foreground、sidebar-primary、sidebar-accent、 sidebar-border

主题行为：

• AppThemeProvider 使用 next-themes，支持亮色、暗色和跟随系统。
• AppThemeToggle 位于顶部栏，用户选项统一为“亮色”“暗色”“跟随系统”。
• 亮色和暗色值都在全局样式中定义，业务页面不要新增零散的 dark: 颜色覆盖。
• 侧边栏必须使用 sidebar* 令牌，保证主题切换一致。

3. 组件层级

shadcn/ui 基础组件

位于 frontend/src/components/ui，尽量保持生成组件的标准 API：

• Button、Badge
• Card、CardHeader、CardContent、CardTitle、CardDescription
• Input、Textarea、Select
• Table
• Dialog、Sheet、DropdownMenu、Tabs
• Tooltip、Skeleton、Sonner

业务页面不要直接修改基础组件实现来满足单页需求，应通过属性、组合或 App 组件扩展。

项目级 App 组件

位于 frontend/src/components/app，是业务页面优先使用的页面 API：

• AppSidebar、AppTopbar
• AppThemeProvider、AppThemeToggle
• AppPage、AppPageHeader
• AppDataTable、AppFilterBar
• AppDetailLayout、AppSection
• AppEmptyState
• AppStatusBadge、AppPriorityBadge
• AppField

使用约定：

• 列表和表格使用 AppDataTable。
• 搜索和筛选使用 AppFilterBar。
• 主内容加侧栏的详情页使用 AppDetailLayout。
• 状态和优先级使用语义 Badge 组件。
• 表单标签、必填态和说明使用 AppField，避免页面直接使用裸 Label。
• Select 统一采用 SelectContent > SelectGroup > SelectItem。

4. 页面与交互规则

工单

• 工单中心第一列组合工单号、标题、提出人和描述，状态与优先级作为独立运营信息。
• 工单详情使用总览、事件时间线和侧栏区域，不在多个面板重复同一字段。
• 状态流转统一使用 TicketTransitionDialog；需要备注或解决结果时由领域规则决定。
• 工单编辑只提交变化字段，避免把未修改的 Agent 字段误标为人工保护字段。
• pending_info 工单必须展示待补全字段、来源证据、原始材料和受理运行。
• 智能受理 SSE 断线后显示重连状态，终态查询失败时保留人工表单。

知识与解决方案

• 知识、方案和治理页面沿用同一页面、表格和表单组件。
• 检索结果必须展示来源类型、标题、综合分数和可引用片段。
• 版本状态、审核人、发布时间和变更摘要应清晰可见。
• 发布、下线、回滚和高风险确认使用明确的确认对话框。

Agent、Tool、渠道与系统治理

• 配置页先展示当前状态，再提供编辑或新建动作。
• 凭据只显示“已配置”或脱敏尾号，不回填明文。
• Agent 运行详情展示步骤、事件、调用尝试和冻结配置，但不在普通列表泄露敏感正文。
• 高风险 Tool 必须显示申请人、审核人、风险级别和当前确认状态。
• 渠道回复必须展示冻结回复版本及目标会话，不能允许任意自由文本绕过回复任务。

5. 状态与反馈

• 加载：使用 Skeleton 或页面级加载态，避免布局跳动。
• 空状态：使用 AppEmptyState，说明下一步可执行动作。
• 成功：使用简短 Toast，不重复页面已经明确显示的结果。
• 失败：错误消息保留在相关区域，并提供重试或人工降级动作。
• 权限不足：隐藏不可用主操作或明确禁用原因，不伪装成数据为空。
• 长任务：展示进度阶段、最近事件和连接状态，终态后刷新权威业务数据。

6. 可访问性与响应式

• 表单控件必须有可关联标签。
• 仅图标按钮必须提供 sr-only 文本或 aria-label。
• 状态不能只依赖颜色，应同时显示文本或图标。
• 焦点顺序与视觉顺序一致，Dialog 和 Sheet 使用标准焦点管理。
• 桌面优先的治理页面在移动端应明确限制，不压缩成不可操作布局。
• 时间使用 <time> 和 ISO dateTime，展示文本按用户时区格式化。

7. 开发检查

新增或修改页面后运行：

cd frontend
pnpm test:run
pnpm typecheck
pnpm lint
pnpm build

预览入口：

frontend/src/features/design-system/DesignSystemPreview.tsx

业务代码结构、注释和提交规则见开发指南。