组件契约

版本 2.0 - 对齐 v3 原型，覆盖全部新增组件与交互模式。

1. 组件策略

MOSS 使用 shadcn/ui + Radix UI + Lucide，但视觉系统由本 design system 定义。

• shadcn/ui：Button、Dialog、Sheet、Tabs、Tooltip、DropdownMenu、Select、Table 等基础实现。
• Radix UI：焦点管理、Esc 关闭、键盘导航、Popover/Modal 层级。
• Lucide：唯一图标集。
• Tailwind CSS：样式实现工具，映射 MOSS semantic token，不启用默认 palette。

组件代码在 components/ui/，业务组合组件在 feature 目录。不得在业务页面复制基础组件状态样式。

2. 核心组件清单

组件	基础	必须状态
Button	shadcn Button	default、hover、focus、disabled、loading、destructive、primary。
IconButton	Button + Lucide + Tooltip	default、hover、focus、disabled。
NavigationItem	本地组合	default、hover、active、disabled。
FilterBar	ToggleGroup / Tabs	default、hover、active、keyboard focus。
FeedbackControl	ToggleGroup	neutral、selected-positive、selected-negative、disabled。
Tag	Badge	neutral、accent、info、warning、danger、domain-colored。
Chip	本地组合	default（带 dot-live 或纯文本）。
CountChip	本地组合	accent（默认）、plain（中性）。
ContentRow	本地组合	default、hover、selected、read、muted。
FocusItem	本地组合	default、hover、selected、warn、danger + domain-colored icon。
SignalCard	本地组合	default、hover、tinted、warm + 内嵌 viz。
CoverageMeter	本地组合	5 段，逐段 on/off，域色填充。
DayPanel	本地组合	含 stat-num countUp 动画。
ContextPanel / Inspector	aside（宽屏）/ Sheet（窄屏）	open、closed、loading、empty + primary section。
DetailDrawer	本地组合	open、closed + focus trap。
Skeleton	本地组合	shimmer 动画。
EmptyState	本地组合	icon + title + description。
Toast	本地组合	visible（spring 弹入）→ auto-dismiss 3.4s。
CommandPalette	本地组合	open、results filtered。
CaptureDialog	本地组合	open、textarea focus、save → toast。
ConfirmDialog	shadcn Dialog	open、busy。
DecisionPanel	本地组合	3 options + result flash。

3. 新增组件详细契约

3.1 FocusItem

优先处理卡片。左侧 rail + icon + 文案 + meta 四列 grid。

• data-dom 属性驱动 icon 背景色：color-mix(in srgb, var(--color-dom-x) 14%, var(--color-bg-surface))。
• --rail 自定义属性控制左侧指示条颜色：默认 accent，.warn 用 warning，.danger 用 danger。
• 选中态：border-color: accent + box-shadow: 0 0 0 3px accent-glow。
• 决策更新后触发 .flash 动画（accent-soft → raised 600ms）。
• 支持 role="option" + aria-selected + ArrowUp/Down 键盘导航。

3.2 SignalCard

跨域信号卡片。min-height 186px，含 label + metric/title + description + viz。

• .tinted：accent-soft 渐变背景。
• .warm：warning-soft 渐变背景。
• 内嵌 viz 类型：sparkline（SVG path + circle nodes）、progress ring（SVG circle）、bar chart（CSS bars）。
• 每个 viz 必须有 .viz-note 注释行，说明坐标轴含义或图例。
• Hover：translateY(-2px) + elevation-2 + border-color accent。

3.3 CoverageMeter

六域覆盖度仪表。5 段 bar，每段 4px 高，gap 3px。

• .seg.on 在 .reveal.in 时从灰过渡到域色，逐段 delay 80ms。
• 域色通过父元素 --dc 自定义属性传入。

3.4 Inspector（ContextPanel）

右侧上下文面板。四个 section 用 border-bottom 分隔。

• 首个 section 使用 .primary 类：浅 accent 背景 + accent-deep 标题色 + 负 margin 撑满面板宽度。
• 切换内容时 140ms cross-fade（opacity + translateY 6px），带 debounce 防快速点击闪烁。
• 视图切换时自动同步为域级概览上下文（viewInspectorMap）。
• "打开详情"按钮映射到该域最相关的 detail key。

3.5 Skeleton

加载占位。.skeleton 基类 + .sk-line（文本行）/ .sk-block（卡片块）。

• shimmer 动画：translateX(-100%) → translateX(100%)，1.4s infinite。
• 用于 lazy view 首次切换时 280ms 占位。

3.6 EmptyState

空状态容器。dashed border + 居中 icon + title + description。

• 说明"没有什么"和"下一步可做什么"。
• 不写冗长产品教学文案。

3.7 HeroGlow

Hero 区域氛围光。两个绝对定位 div，filter: blur(80px)，opacity 0.55。

• 不同尺寸（520×320 / 360×260）。
• 不同 drift 动画（22s / 18s alternate）。
• 背景色使用 --color-wash-1 / --color-wash-2。
• aria-hidden="true"，纯装饰。

3.8 DecisionPanel

决策面板。3 个 option 按钮 + result 弹层。

• .danger option 用 danger 色标题 + hover border。
• Result 使用 spring 弹入动画。
• 取消操作必须经过 ConfirmDialog 二次确认。
• 决策完成后：更新 detail state + timeline + 卡片文案（带 flash）+ inspector + toast + audit event。

3.9 Toast

底部居中通知。accent 左边框 4px + elevation-3。

• Spring 弹入（translateY 14px → 0）。
• 3.4s 后自动消失。
• role="status" + aria-live="polite"。

4. 交互规则

4.1 Buttons

• primary 每个局部区域最多一个。渐变背景 + inset highlight + glow shadow。
• secondary 有边框 + elevation-1，hover 时 border 变 accent + glow shadow。
• Active：scale(.965) 120ms。
• Loading 保留宽度，禁用重复提交。

4.2 NavigationItem

• Active：accent-soft 背景 + accent-deep 文字 + 700 weight + 左侧 3px 渐变指示线。
• Hover：accent-soft 背景 + ink 文字 + icon 变 accent 色。
• Count badge：active 时变 accent 色 + 600 weight。

4.3 视图切换

• switchView() 同步更新：中间内容区 + sidebar 高亮 + breadcrumb + inspector 上下文。
• 非 Today 视图首次切换时：skeleton 280ms → template clone 注入 → reveal 动画。
• 已注入视图直接显示 + reveal class 添加。

4.4 列表与表格

• 推荐流使用连续行，不嵌套卡片。
• 行点击更新 inspector；行内按钮 stopPropagation。
• 空状态使用 EmptyState 组件。

4.5 Overlay

• Dialog 用于阻断流程和高风险确认。
• Sheet 用于可随时关闭的上下文。
• Escape + 点击遮罩 + 关闭按钮遵循 Radix 默认行为。
• Detail drawer 打开后 trap focus，关闭后焦点回到触发元素。

5. 页面组成约束

所有信息域复用同一工作台骨架：Sidebar + Workspace + Inspector。

信息域	中央工作区	Inspector 默认上下文
Today	Hero + Priority + Signals + Coverage	最高优先级 focus-item。
Inbox	待处理输入 + 建议动作 + 入库规则	收件箱概览。
Knowledge	内容流 + 学习 + 研究 + 模板 + 输出	域概览 + 活跃研究问题。
Action	计划 + 维护 + 问题 + 应急 + 节奏	域概览 + 今日计划。
Context	机会 + 车辆 + 身份 + 声誉 + 文化	域概览 + 最新机会。
Self	事件 + 医疗 + 偏好 + 审美	域概览 + 数据边界。
Asset	理财 + 家庭 + 账号 + 订阅 + 风险	预算偏差信号。
Governance	策略列表 + 审计事件	逾期恢复演练。

新增页面必须先回答：它是否可以作为现有工作区的一种视图？若可以，不能另造 Dashboard 或新导航框架。