组件规范

本规范约束 Web App 共享 UI 原语的视觉表达、状态规则、交互语义与组合边界。所有业务页面必须优先复用共享组件，而不是在页面层复制按钮、输入框、卡片、标签或面板的视觉实现。

---

1. 组件体系原则

1. 所有核心交互都应优先落在 web/components/ui/ 共享原语层。
2. 页面可以组合组件，但不应重写组件的核心视觉语义。
3. 同一语义只能对应一套主实现，例如主按钮、主输入框、主状态标签不能在不同页面出现不同视觉语言。
4. 分析页面中的密度需求必须通过受控变体解决，而不是通过复制组件并单独压缩样式解决。

2. 通用 Anatomy 与状态模型

2.1 通用 Anatomy

一个共享组件通常由以下结构构成：

1. Label area：标题、字段名、模块名、eyebrow
2. Content area：主体信息、输入内容、数据内容
3. Supporting area：说明文字、meta、辅助信息
4. Action area：按钮、菜单、快捷操作
5. Status affordance：图标、颜色、边框或徽章形式的状态反馈

2.2 通用状态

所有交互组件应统一定义以下状态：

1. default
2. hover
3. focus-visible
4. pressed / active
5. disabled
6. loading
7. selected
8. error
9. success

3. Button

3.1 用途

按钮用于承载明确操作意图，是视觉层级最强的交互控件之一。

3.2 允许变体

变体	语义	使用场景	限制
primary	主动作	表单提交、主要继续动作	每个区域通常仅 1 个
secondary	次级动作	辅助提交、切换、低优先级操作	不与 primary 争抢视觉中心
ghost	低强调动作	toolbar、小型操作	不用于关键确认
destructive	危险操作	删除、断开、不可逆操作	必须有风险语义

3.3 规则

1. 主按钮使用 primary token 与统一 focus ring。
2. 不允许页面内自行定义 bg-[#2855f5] 形式的主按钮。
3. loading 态必须保留尺寸稳定，不得引发布局抖动。
4. icon-only 按钮必须具备可访问名称。

4. Input / Textarea / Select

4.1 用途

用于信息输入与筛选配置，应具备统一的背景、边框、焦点和错误语义。

4.2 规则

1. 默认字段背景使用统一 surface/input token，而不是页面局部浅蓝色 recipe。
2. focus 态统一使用 focus-ring 和 primary 边框语义。
3. 错误态不得仅靠颜色表达，必须同时具备文案或图标提示。
4. label、help、error text 的排版必须使用统一 typography token。

5. Card / Panel / Badge

5.1 Card / Panel

Card 与 Panel 是信息承载层，不同组件只通过密度与语义变体区分，不应拆出多个互不兼容的视觉分支。

规则：

1. 默认 card 使用统一圆角、边框和 shadow token。
2. glass / elevated 仅用于 auth、summary、highlight panel，不作为 dense page 默认表现。
3. panel header 的标题、meta、actions 结构应保持一致。

5.2 Badge / Status Chip

Badge 与状态 chip 用于表达状态、分类与计数。

规则：

1. 统一使用 pill 造型或小圆角 badge，不允许每页单独定义。
2. 状态色语义只允许来自 success / warning / info / destructive / muted 系统。
3. 不允许把品牌蓝误用为成功或默认状态的替代色。

6. Sidebar / Navbar / Tabs

6.1 Sidebar / Navbar

1. shell 组件优先表达结构与导航秩序，而不是装饰性。
2. active state 必须稳定且可预测，不依赖页面局部样式。
3. sidebar 和 navbar 的密度梯度必须统一，避免 admin/chat/sessions 各自定义。

6.2 Tabs

1. tabs 用于同层级视图切换，不用于替代 breadcrumb 或信息架构。
2. selected 状态应通过对比、边框或底色统一表达。

7. Dialog / Sheet / Popover / Dropdown

1. 叠层组件使用统一的 surface-elevated、radius、shadow 和 overlay 语义。
2. dialog 适用于阻断式决策，sheet 适用于上下文展开，popover/dropdown 适用于轻量选择。
3. 不允许同一用途在不同页面中混用完全不同的交互模式。

8. Data Table / Chart Panel

8.1 Data Table

分析类表格是高密度场景，规则如下：

1. 优先保证可读性与扫描效率，不因品牌化而增加视觉噪音。
2. 工具栏、筛选器、分页、批量操作必须共享一致模式。
3. header、cell、meta、sorting 状态使用统一 typography 和 status 语义。

8.2 Chart Panel

图表容器应具备：

1. 一致的标题区和辅助说明区
2. 一致的图表与说明间距
3. 一致的无数据、加载、错误 fallback
4. 图表色仅来自 chart token 体系

9. Empty / Loading / Error State

1. 空状态应包含标题、说明、建议动作，必要时可加入轻量品牌母题。
2. loading 状态应优先选择 skeleton 或稳定占位，而不是频繁 spinner。
3. error 状态必须说明问题、影响和建议动作，不得只显示红字提示。

10. 组件实现约束

10.1 必须遵守

1. 共享组件的主视觉实现放在 web/components/ui/
2. 页面层只允许通过受控 variant 与 layout class 组合这些组件
3. 状态、密度、主题边界必须在组件 API 中可表达，而不是靠页面 hacks

10.2 不允许

1. 在页面里复制一份新的按钮或输入框视觉实现
2. 在页面里用 raw hex 修补组件状态
3. 为单个页面创建不受治理的阴影、圆角、焦点 recipe
4. 在高频业务组件中自由新增非规范 micro typography