# 前端设计系统 ## 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 使用标准焦点管理。 - 桌面优先的治理页面在移动端应明确限制，不压缩成不可操作布局。 - 时间使用 `