docs(web): add ui planning baseline

2026-03-24 19:48:45 +08:00 · 2026-03-24 19:48:45 +08:00 · ed7239feb2
commit ed7239feb2
parent 74bb184ecb
5 changed files with 1042 additions and 0 deletions
--- a/docs/planning/xworkmate-ui-web/01-information-architecture-and-pages.md
+++ b/docs/planning/xworkmate-ui-web/01-information-architecture-and-pages.md
@ -0,0 +1,159 @@
+# 01. Information Architecture 与页面结构
+
+## 1. 顶层信息架构
+
+以当前 macOS APP UI 为基准，XWorkmate 应被理解为一个 AI Workspace / Agent Operating System，而不是一个普通聊天应用。
+
+建议把整体信息架构划分为四层：
+
+### A. Workspace Shell
+
+负责整个应用的结构外壳：
+
+- 顶层导航
+- 页面切换
+- 左侧栏与工作区布局
+- 全局搜索入口
+- 主题、语言、全局反馈
+- Focus / Favorites 入口容器
+
+这一层不承载具体业务逻辑，只负责承载各域页面与全局交互容器。
+
+### B. Execution Plane
+
+这是用户最常驻的工作平面，核心是 Assistant：
+
+- 任务线程
+- 对话上下文
+- Agent 运行状态
+- 渲染结果
+- 会话级执行参数
+- 底部 composer 与运行入口
+
+这一层的核心对象不是单条 message，而是 thread / task session。
+
+### C. Resource Plane
+
+这是任务执行依赖的能力资产层：
+
+- 任务
+- 技能
+- 节点
+- 密钥
+- LLM API
+
+这些对象本质上是资源目录，不应被挤压进 Assistant 页面内部逻辑。
+
+### D. Control Plane
+
+负责系统与环境配置：
+
+- Settings
+- Gateway / External ACP / LLM endpoint 配置
+- 权限级别
+- 主题、语言
+- Diagnostics / About
+
+该层的目标是集中管理系统配置，而不是在多个页面散布零碎设置按钮。
+
+## 2. 关键对象与关系
+
+### A. Thread 是一级工作对象
+
+每个线程都应具备独立的：
+
+- 标题
+- 执行目标（single / local / remote）
+- provider / model / permission / skills
+- 连接状态
+- 归档状态
+- 消息历史与渲染结果
+
+因此，线程列表不是 message history 的附属视图，而是工作台的一级对象目录。
+
+### B. Focus Entry 是聚合入口，不是独立业务域
+
+“关注入口”不应被视为与任务、技能、节点并列的业务模块。
+
+它的职责应该是：
+
+- 收藏某个业务域入口
+- 给出摘要预览
+- 提供快速跳转
+- 在 Assistant 工作区左侧提供上下文补充
+
+它属于导航聚合层，不属于核心资源域。
+
+### C. Settings 是控制中心，不是弹窗集合
+
+连接设置、语言、主题、权限、执行目标默认项等，不应在多个页面各有一份完整编辑面板。
+
+建议规则：
+
+- 页面内只保留会话级快捷调整
+- 系统级配置统一回到 Settings
+- 所有连接相关能力遵循统一的 Test / Save / Apply 语义
+
+## 3. 页面划分
+
+### A. 主页面
+
+建议以稳定业务域来划分主页面，而不是按截图中的单个按钮来划分：
+
+- Assistant Workspace
+- Tasks
+- Skills
+- Nodes
+- Secrets
+- LLM API
+- Settings
+
+### B. 详情页面
+
+资源域应支持详情态，以便长期扩展：
+
+- Task Detail
+- Skill Detail
+- Node Detail
+- Secret Detail
+- LLM Endpoint Detail
+- Assistant Thread Detail
+
+详情页面可以是独立页面，也可以在桌面大屏下表现为右侧 detail panel，但产品语义上仍应视为详情态。
+
+### C. 面板式子视图
+
+以下内容更适合做 side pane / sheet / overlay，而不应都变成独立主页面：
+
+- Focus Entries
+- 会话设置底部弹层
+- 附件选择
+- 错误详情
+- 渲染模式切换
+- 线程搜索结果
+- 快捷摘要卡
+
+## 4. Assistant 页面结构
+
+Assistant 不是单页聊天窗口，而是一个复合工作台：
+
+- 左侧：线程栏
+- 左侧辅助：Focus / Favorites 面板
+- 中间：当前线程主内容
+- 顶部：会话头与状态栏
+- 底部：composer dock
+- 底部弹层：会话级设置
+
+因此，Assistant 的信息架构应被定义为“工作台容器 + 多模块协作”，而不是单个 page widget。
+
+## 5. Settings 页面结构
+
+以桌面基准来看，Settings 应明确是控制平面页面，建议稳定为：
+
+- Top bar（breadcrumb / title / search）
+- Submission bar（Save / Apply）
+- Primary tabs（General / Workspace / Integrations / Appearance / Diagnostics / About）
+- Integrations sub-tabs（OpenClaw Gateway / LLM Endpoints / External ACP）
+- Detail sections / cards
+
+这能保证 Web 与 macOS APP 在信息层级上保持一致，即使具体交互密度有所裁剪。
--- a/docs/planning/xworkmate-ui-web/02-layout-modules-components-and-state.md
+++ b/docs/planning/xworkmate-ui-web/02-layout-modules-components-and-state.md
@ -0,0 +1,171 @@
+# 02. Layout、模块分层与状态边界
+
+## 1. 组件层级原则
+
+为保证长期维护，建议严格区分三层：
+
+- Layout 层：只负责结构和容器
+- Module 层：负责一个业务单元的交互和状态协调
+- Component 层：负责纯展示或轻交互
+
+页面只做组装，不应堆积大量业务逻辑。
+
+## 2. Layout 层
+
+Layout 层应只负责工作区结构，不直接依赖具体业务域。
+
+建议的壳层对象包括：
+
+- WorkspaceShell
+- PrimaryRail
+- SecondaryPane
+- ContentViewport
+- TopChromeBar
+- BottomDock
+- SplitPaneLayout
+- SheetHost
+
+这些对象负责：
+
+- 左右分栏
+- 顶部导航与 breadcrumb 承载
+- 底部 composer 区承载
+- 面板折叠与尺寸分配
+- Web 响应式适配
+
+## 3. Module 层
+
+Module 是长期维护的关键层，承接复合业务交互。
+
+### A. Assistant 模块
+
+- ThreadListModule
+- ThreadGroupsModule
+- SessionHeaderModule
+- ConversationModule
+- RenderModeModule
+- ConnectionStatusModule
+- ComposerModule
+- SessionSettingsSheetModule
+
+### B. Focus / Favorites 模块
+
+- FocusEntriesModule
+- FocusSummaryCardModule
+- FavoriteEntryManagerModule
+
+### C. Settings 模块
+
+- SettingsTopBarModule
+- SettingsSubmissionBarModule
+- SettingsTabsModule
+- GatewayProfilesModule
+- LlmEndpointsModule
+- ExternalAcpModule
+- AppearanceSettingsModule
+- DiagnosticsModule
+
+### D. Resource 模块
+
+- TasksRegistryModule
+- SkillsRegistryModule
+- NodesRegistryModule
+- SecretsRegistryModule
+- LlmApiRegistryModule
+
+一个 module 应该负责“完整业务语义”，而不是只拼几个 UI 组件。
+
+## 4. Component 层
+
+Component 层应尽可能保持纯展示和可复用。
+
+建议沉淀为通用组件的对象包括：
+
+- SurfaceCard
+- SectionTabs
+- SearchField
+- StatusChip
+- ConnectionBadge
+- ActionChip
+- EmptyState
+- ErrorBanner
+- ToolbarButton
+- DropdownField
+- ToggleField
+- SummaryStatChip
+- BottomSheetPanel
+- ResizeHandle
+
+这些组件不应知道线程、设置页、技能列表等具体业务语义。
+
+## 5. 状态边界
+
+虽然这里主要区分“全局状态”和“局部状态”，但在 Flutter Web 中还应单独重视路由状态。
+
+### A. 全局状态
+
+以下状态建议由 app-level controller / store 持有：
+
+- 当前 workspace / 用户上下文
+- 当前主题、语言
+- feature flags
+- 全局导航结构
+- Focus / Favorites 入口列表
+- 资源目录数据（任务、技能、节点、密钥、LLM API）
+- Gateway profile 列表
+- provider / model catalog
+- 线程索引数据
+- 全局通知 / 错误中心
+
+### B. 路由状态
+
+以下状态更适合映射到 URL / 路由层：
+
+- 当前页面
+- 当前线程 id
+- 当前 Settings tab
+- 当前 Integrations sub-tab
+- 当前详情对象 id
+- 左侧 pane 当前模式
+- 可分享的搜索条件
+
+这些状态如果仅放在内存里，会削弱 Flutter Web 的刷新恢复能力和链接可分享能力。
+
+### C. 局部状态
+
+以下状态建议严格留在模块或组件内部：
+
+- side pane 折叠/展开
+- split pane 临时尺寸
+- bottom sheet 是否打开
+- dropdown 是否展开
+- 输入框内容
+- 当前附件选择结果
+- 卡片折叠状态
+- 某个按钮 loading
+- 某个 form 的未提交草稿
+- hover / pressed / focused 视觉状态
+- 局部滚动位置
+
+## 6. 一条可执行的状态规则
+
+建议全团队统一以下判断标准：
+
+- 会影响多个页面或多个模块的，进入全局状态
+- 需要刷新恢复或支持深链的，进入路由状态
+- 只影响单个模块交互的，保持局部状态
+
+## 7. 必须统一复用的状态机
+
+长期维护时，最容易失控的不是 UI 样式，而是行为流。
+
+建议优先统一以下状态机：
+
+- Test / Save / Apply
+- Connect / Connected / Error / Retry
+- Thread Send / Streaming / Cancel / Complete
+- Load / Empty / Error / Refresh
+- Select / Attach / Remove / Oversize
+- Collapse / Expand / Pin / Unpin
+
+这些状态机一旦被各页面各写一套，后续 Assistant、Settings、Focus、资源域的交互会快速分叉。
--- a/docs/planning/xworkmate-ui-web/03-flutter-web-directory-and-reuse-strategy.md
+++ b/docs/planning/xworkmate-ui-web/03-flutter-web-directory-and-reuse-strategy.md
@ -0,0 +1,217 @@
+# 03. Flutter Web 目录设计与复用策略
+
+## 1. 目录设计目标
+
+Flutter Web 目录设计需要同时解决四个问题：
+
+- 让 Workspace Shell、Assistant、Settings、资源域边界清晰
+- 让 Web 平台适配逻辑与业务逻辑分离
+- 让模块和状态机能够跨页面复用
+- 让未来继续补齐桌面能力时，不需要大规模迁移目录
+
+因此，建议采用：
+
+- app：应用壳与全局入口
+- core：通用基础能力
+- platform/web：浏览器平台适配
+- features：按业务域拆分
+- shared：跨 feature 的复合复用模块
+
+## 2. 建议目录结构
+
+### A. app
+
+负责应用级内容：
+
+- bootstrap
+- app shell
+- navigation
+- routing
+- theme
+- localization
+- global app state
+
+### B. core
+
+只放通用、稳定、与具体业务域无关的能力：
+
+- design system
+- primitives
+- async/result models
+- shared service contracts
+- common value objects
+- utility helpers
+
+### C. platform/web
+
+专门承接 Web 平台相关实现：
+
+- browser storage
+- file picker
+- clipboard
+- drag resize
+- window metrics
+- url sync
+- web socket / SSE adapters
+
+这样可以避免在 feature 目录里到处散落浏览器特例逻辑。
+
+### D. features
+
+按业务域拆分，每个域内部再分层：
+
+- presentation
+- application
+- domain
+- data
+
+建议至少建立以下 feature：
+
+- assistant
+- focus_entries
+- tasks
+- skills
+- nodes
+- secrets
+- llm_endpoints
+- settings
+
+### E. shared
+
+用于放跨 feature 的复合件，而不是基础原子组件：
+
+- shell_modules
+- status_widgets
+- form_patterns
+- summary_cards
+- registry_helpers
+
+## 3. 每个 feature 的分层建议
+
+以 feature-first 为原则，每个 feature 保持四层：
+
+### presentation
+
+负责页面、布局组装、模块展示：
+
+- pages
+- layouts
+- modules
+- components
+
+### application
+
+负责交互编排与状态协调：
+
+- controllers / coordinators
+- use cases
+- screen state
+- action handlers
+
+### domain
+
+负责业务模型与规则：
+
+- entities
+- value objects
+- policies
+- domain services
+
+### data
+
+负责数据读写与适配：
+
+- repositories
+- dto
+- mappers
+- remote/local data source
+
+## 4. 组件复用策略
+
+建议把复用拆成四层，而不是只做视觉组件复用。
+
+### A. 视觉原子复用
+
+用于保证视觉和交互基础一致：
+
+- Button
+- Card
+- Tabs
+- Input
+- Badge / Chip
+- Empty / Error / Loading state
+- BottomSheet
+- SplitHandle
+
+### B. Shell 结构复用
+
+用于保证工作台结构一致：
+
+- WorkspaceShell
+- TopChromeBar
+- PrimaryRail
+- SecondaryPane
+- BottomDock
+- ResizablePaneLayout
+
+### C. 业务模块复用
+
+用于复用完整交互语义：
+
+- ThreadListModule
+- FocusSummaryCardModule
+- SettingsSubmissionBarModule
+- ConnectionProfileModule
+- EndpointEditorModule
+- ResourceListDetailModule
+
+### D. 状态机复用
+
+用于复用行为，而不是只复用 UI：
+
+- Save / Apply flow
+- Connection test flow
+- Streaming lifecycle
+- Attachment lifecycle
+- Search / filter / selection flow
+
+## 5. 注册表驱动策略
+
+结合截图中的“关注入口”、左侧导航和资源域，建议采用注册表驱动策略。
+
+每个业务域应向系统注册自己的：
+
+- id
+- label
+- icon
+- page destination
+- summary preview builder
+- favorite capability
+- feature flag 依赖
+- permission / availability 条件
+
+这样可以解决几个长期问题：
+
+- 新增域时不需要修改多个壳层文件
+- Focus Entries 可以自动枚举可收藏域
+- Web / Desktop / Mobile 可以共享同一套产品语义，只做平台级裁剪
+
+## 6. 维护约束建议
+
+为了防止目录逐步失控，建议团队明确以下约束：
+
+- page 只做路由承接和模块组装，不写复杂业务逻辑
+- module 可以依赖 component，但 component 不反向依赖 module
+- feature 不直接依赖其他 feature 的 presentation 层
+- Web 平台适配逻辑不进入 core
+- Save / Apply、线程会话、连接状态等关键状态流统一复用，不允许每页自定义一套
+
+## 7. 结论
+
+如果以当前 macOS APP UI 作为基准，Flutter Web 的目标不应是“单独实现一个简化网页”，而应是：
+
+- 共享同一套 Workspace 产品语义
+- 在 Web 中复用相同的 Shell、页面域、模块边界和状态机
+- 只在平台能力、导航密度和交互载体上做 Web 裁剪
+
+这将使 Web 版本具备持续演进能力，而不是停留在一次性补齐页面的实现方式。
--- a/docs/planning/xworkmate-ui-web/04-design-system-spec.md
+++ b/docs/planning/xworkmate-ui-web/04-design-system-spec.md
@ -0,0 +1,440 @@
+# 04. 设计系统规范（MacOS AI Workspace 基准）
+
+## 1. 设计目标
+
+这套设计系统以当前 XWorkmate macOS APP UI 为主基准，并吸收 Notion 与 Linear 的两类优点：
+
+- Notion 的平静、中性、低打扰信息组织
+- Linear 的紧凑、精准、状态清晰、专业工具感
+
+但本系统不直接复制两者，而是服务于“MacOS 风格 AI 工作台”：
+
+- 更强调线程、Agent、连接、结果渲染等工作流对象
+- 更强调长时间停留的低疲劳阅读体验
+- 更强调分栏、底部 dock、快捷面板、系统设置等桌面工作台语义
+
+因此，这套视觉语言应满足三个目标：
+
+- Calm：低噪音、可持续停留
+- Compact：适合高密度工作区
+- Tactile：按钮、面板、sheet 都要有轻微但明确的可操作反馈
+
+## 2. 视觉基调
+
+### A. 总体风格
+
+建议定义为：
+
+- calm compact workspace
+- border-first 但不过度描边
+- 系统字体优先
+- 低饱和中性色 + 单一品牌蓝强调
+- 光感和层级主要依靠 tonal layering，而不是高对比色块
+
+### B. 气质关键词
+
+- 安静
+- 精准
+- 专业
+- 编辑式
+- 工具化
+- 长时工作友好
+
+### C. 使用规则
+
+- 主色只用于主 CTA、选中态、关键状态，不大面积铺底
+- 层级优先靠 spacing、字号、权重、surface tone 建立
+- 大部分卡片使用 ghost border + soft shadow，而不是强边框
+- Web 与 macOS 使用同一套语言，只调整密度，不切换视觉流派
+
+## 3. 颜色体系
+
+## Light Theme
+
+### A. Background
+
+- App Background: `#F8F9FA`
+- Workspace Chrome Background: `#F4F7FA`
+- Sidebar Background: `#F1F4F8`
+- Inset Background: `#EFF3F7`
+
+### B. Surface
+
+- Primary Surface: `#FFFFFF`
+- Secondary Surface: `#F2F5F8`
+- Tertiary Surface: `#E9EEF4`
+- Pressed Surface: `#F1F5F9`
+- Highlight Surface: `#FFFFFF`
+
+### C. Text
+
+- Text Primary: `#1C1B1F`
+- Text Secondary: `#667085`
+- Text Muted: `#98A1B2`
+- Text Inverse: `#FFFFFF`
+
+### D. Accent
+
+- Accent Primary: `#0058BD`
+- Accent Hover: `#1A6CCE`
+- Accent Soft: `#E8F0FB`
+- Accent Strong Fill: `#0058BD`
+
+### E. Semantic
+
+- Success: `#34A853`
+- Warning: `#8F4A00`
+- Danger: `#C3655C`
+- Idle: `#98A1B2`
+- Info Banner Tint: `#EEF4FB`
+- Warning Banner Tint: `#FFF3CD`
+- Error Banner Tint: `#FBEDEC`
+
+### F. Border
+
+- Default Border: `rgba(166, 180, 200, 0.20)`
+- Soft Border: `rgba(166, 180, 200, 0.15)`
+- Strong Border: `rgba(166, 180, 200, 0.32)`
+
+## Dark Theme
+
+### A. Background
+
+- App Background: `#141422`
+- Workspace Chrome Background: `#161A26`
+- Sidebar Background: `#1A1D2A`
+- Inset Background: `#1A1F2C`
+
+### B. Surface
+
+- Primary Surface: `#171C28`
+- Secondary Surface: `#1E2433`
+- Tertiary Surface: `#262D3F`
+- Pressed Surface: `#23293A`
+- Highlight Surface: `#2A3145`
+
+### C. Text
+
+- Text Primary: `#E6E1E5`
+- Text Secondary: `#B0B8C8`
+- Text Muted: `#8B95A8`
+- Text Inverse: `#0F1117`
+
+### D. Accent
+
+- Accent Primary: `#4B8FE8`
+- Accent Hover: `#78AFFF`
+- Accent Soft: `#1C3355`
+- Accent Strong Fill: `#4B8FE8`
+
+### E. Semantic
+
+- Success: `#5CB978`
+- Warning: `#E0AE5A`
+- Danger: `#EF9A9A`
+- Idle: `#8B95A8`
+- Info Banner Tint: `#1B2940`
+- Warning Banner Tint: `#3A3118`
+- Error Banner Tint: `#3A2527`
+
+### F. Border
+
+- Default Border: `rgba(202, 196, 208, 0.22)`
+- Soft Border: `rgba(202, 196, 208, 0.15)`
+- Strong Border: `rgba(202, 196, 208, 0.30)`
+
+## 4. Spacing / Radius / Shadow
+
+## A. Spacing
+
+建议继续沿用当前家族的紧凑节奏：
+
+- 4: micro gap
+- 6: compact gap
+- 8: standard gap
+- 12: section inner gap
+- 16: card inner padding / block gap
+- 20: pane padding
+- 24: page section gap
+- 32: large layout gap
+
+使用规则：
+
+- 控件之间优先 `6` 或 `8`
+- 卡片内部优先 `12` 或 `16`
+- 大模块之间优先 `24`
+- 页面级横向 padding 建议 `20` 到 `24`
+
+## B. Radius
+
+基于 MacOS 工作台语义，保持柔和但不臃肿：
+
+- Card Radius: `16`
+- Panel Radius: `18`
+- Sidebar Radius: `20`
+- Button Radius: `12`
+- Icon Button Radius: `12`
+- Input Radius: `14`
+- Chip Radius: `12`
+- Bottom Sheet Radius: `18`
+- Badge Radius: `999`
+
+Web 紧凑版本可收紧，但不建议低于：
+
+- card `12`
+- input `10`
+- button `10`
+
+## C. Shadow
+
+阴影必须是“柔和、带轻微蓝灰偏色”的工作台阴影，而不是通用黑灰阴影。
+
+### Light
+
+- Ambient Shadow: `0 12 40 -14 rgba(0, 88, 189, 0.08)`
+- Lift Shadow: `0 10 24 -12 rgba(0, 88, 189, 0.10)`
+
+### Dark
+
+- Ambient Shadow: `0 12 36 -14 rgba(0, 8, 20, 0.30)`
+- Lift Shadow: `0 8 22 -12 rgba(0, 88, 189, 0.28)`
+
+使用规则：
+
+- 卡片默认只用 ambient
+- 可点击卡片 hover 时追加 lift
+- sidebar 与 sheet 使用更柔和、更大范围的阴影，不用锐利投影
+
+## 5. Typography
+
+## A. 字体策略
+
+优先使用系统字体：
+
+- macOS / iOS: SF Pro
+- Web: `system-ui`, `-apple-system`, sans-serif
+- Monospace: 系统等宽字体，仅用于 token、ID、日志、endpoint
+
+不引入自定义 UI 字体。
+
+## B. 字号体系
+
+### Workspace Display
+
+- 28 / 32 / 700
+- 用于少量登录、欢迎、全屏态标题
+
+### Dialog Title
+
+- 20 / 24 / 600
+- 用于弹窗与设置大卡标题
+
+### Section Title
+
+- 13 / 14 / 600
+- 用于工作区 section、侧栏分组、卡片标题
+
+### Body
+
+- 13 / 15 / 400
+- 默认正文
+
+### Emphasized Body
+
+- 13 / 14 / 600
+- 重要标签、按钮文字、关键值
+
+### Caption
+
+- 12 / 16 / 400
+- 辅助文字、meta、时间、helper text
+
+### Caption Strong
+
+- 12 / 16 / 600
+- 状态标签、breadcrumb、chip 文案
+
+## C. 字体使用规则
+
+- 不在工作区内使用大而营销化的 hero heading
+- 大部分文字应保持在 12 到 13 范围
+- 主要层级靠字重与间距，而不是大字号跳跃
+- 线程标题、卡片标题、section 标题允许 600，不建议更重
+- 技术值、endpoint、token key 才使用 monospace
+
+## 6. 核心组件规范
+
+## A. Card
+
+适用：摘要卡、设置卡、Focus 卡、任务卡。
+
+规则：
+
+- 默认使用 primary 或 secondary surface
+- 带 soft border
+- 16 圆角
+- 内边距 16
+- hover 只抬升一点，不做明显放大
+- 选中态优先用 accent soft 背景 + 轻描边，不直接大面积纯蓝铺底
+
+## B. Panel
+
+适用：线程栏、Focus pane、设置大面板、详情面板。
+
+规则：
+
+- 比 card 更强调容器感
+- panel 内允许嵌套 card，但 panel 自身应更克制
+- 通常使用 chrome background 或 secondary surface
+- 应具备清晰的 header / content / footer 区域
+- 在桌面大屏中应优先承担结构层级，而非视觉重点
+
+## C. Sidebar
+
+适用：主导航、Focus 左侧面板、线程导航区域。
+
+规则：
+
+- 使用 sidebar background
+- 分组信息采用 caption strong
+- 导航项高度建议 32 到 36
+- 选中项使用 accent soft + subtle border
+- 收藏/星标属于辅助交互，不要抢主导航焦点
+- collapse 后仍要保留清晰的 icon-only 语义
+
+## D. Button
+
+### Primary Button
+
+- 用于主行动作，如发送、应用、创建
+- 使用 accent fill
+- 白字
+- hover 稍微变亮
+- active 稍微压暗并减小阴影
+
+### Secondary Button
+
+- 用于次级动作，如保存、测试、打开详情
+- 使用 secondary surface 或 ghost border
+- 文字保持 primary text
+
+### Tertiary / Ghost Button
+
+- 用于工具栏、icon action、内嵌操作
+- 背景默认透明
+- hover 出现 secondary surface
+
+### 尺寸建议
+
+- Desktop utility button height: `30`
+- Toolbar / input-affiliated button: `30` 到 `32`
+- 大型单独 CTA 不建议超过 `36`
+
+## E. Input
+
+适用：搜索、配置输入、endpoint 输入、composer 之外的表单输入。
+
+规则：
+
+- 高度默认 40
+- 圆角 14
+- 背景用 primary surface
+- 边框默认 soft border
+- focus 使用 accent border + very soft glow
+- placeholder 使用 muted text
+- helper / error text 使用 caption
+
+### Search Input
+
+- 左侧 icon 固定
+- hover 只提升表面亮度，不改变布局
+- 不做过重投影
+
+### Composer Input
+
+- 作为特殊输入容器，不完全套用普通 input
+- 更像 bottom dock panel
+- 应支持更大高度、附件、模式切换、发送动作
+
+## 7. 交互状态规范
+
+## A. Hover
+
+目标：给出触感，而不是制造噪音。
+
+规则：
+
+- surface 稍微提亮或切到 pressed surface
+- 阴影轻微增强
+- icon 与文字颜色不剧烈变化
+- 不使用明显 scale 动画
+
+## B. Active / Pressed
+
+规则：
+
+- 背景比 hover 更实一点
+- 阴影减弱，模拟按下
+- 主按钮允许稍微压暗
+- 卡片点击态优先表现为“压下”，而不是“发光”
+
+## C. Selected
+
+规则：
+
+- 优先使用 accent soft background
+- 边框轻微增强
+- 文字使用 emphasized body 或 accent text
+- 不建议用纯色大面积填充，除非是 primary CTA
+
+## D. Disabled
+
+规则：
+
+- 背景不应完全消失，应保留轮廓
+- 文字降到 muted
+- border 保持 soft
+- 对可用区域和不可用区域保持几何一致，避免跳版
+
+## E. Focus
+
+规则：
+
+- 键盘 focus 必须有清晰 focus ring
+- focus ring 使用 accent，并保持较低扩散半径
+- sidebar item、button、input、chip 都要支持 focus state
+
+## 8. 组件状态矩阵建议
+
+以下组件必须具备完整状态：
+
+- button: default / hover / active / disabled / focus
+- input: default / hover / focus / error / disabled
+- card: default / hover / selected / disabled
+- sidebar item: default / hover / selected / focus
+- chip: default / hover / selected / disabled
+- panel: default / pinned / collapsed / active
+
+## 9. 与当前产品的对应关系
+
+这套设计系统应直接映射到当前 XWorkmate 家族 token：
+
+- 颜色基于现有 `AppPalette.light` / `AppPalette.dark`
+- spacing / radius / typography 基于现有 `SimpleSpacing`、`SimpleRadius`、`SimpleTypography`
+- Web 版本采用同一家族语言，但在高密度区域可轻微收紧几何
+
+因此，后续实现建议遵循：
+
+- 不重新发明一套 Web token
+- 先让 Web 继承 macOS 家族 token，再在 shell、sidebar、input、tabs、sheet 上做 Web 密度微调
+- 任何 Notion / Linear 风格借鉴，都应服务于现有产品家族，而不是覆盖现有品牌语言
+
+## 10. 一句话结论
+
+这套设计系统的最终目标，不是把 XWorkmate 做成“像某个 SaaS 后台”，而是把它做成：
+
+- 具有 MacOS 原生工作台气质
+- 适合长时间停留
+- 适合高密度 AI 任务调度
+- 视觉克制但交互明确
+- Web 与 macOS 同源而不割裂
--- a/docs/planning/xworkmate-ui-web/README.md
+++ b/docs/planning/xworkmate-ui-web/README.md
@ -0,0 +1,55 @@
+# XWorkmate Web UI 规划索引
+
+更新时间：2026-03-24
+
+## 目标
+
+本文档集以当前已完善的 macOS APP UI 为基准，为 Flutter Web 版本建立长期可维护的前端信息架构与目录组织方案。
+
+目标不是一次性把截图翻译成页面，而是明确：
+
+- Web 端应该对齐哪些桌面基准能力
+- 哪些能力属于壳层、页面层、模块层、组件层
+- 哪些状态应当全局持有，哪些状态应当局部封装
+- Flutter Web 代码目录应当如何组织，才能支撑持续迭代
+- 组件与模块应如何复用，避免 Assistant / Settings / Focus 等区域重复造轮子
+
+## 基准来源
+
+本文档以当前桌面实现的以下结构为基准，而不是以历史 Web 简化版为基准：
+
+- `lib/app/app_shell_desktop.dart`
+- `lib/app/workspace_page_registry.dart`
+- `lib/widgets/sidebar_navigation.dart`
+- `lib/widgets/assistant_focus_panel.dart`
+- `lib/features/settings/settings_page.dart`
+- `lib/widgets/desktop_workspace_scaffold.dart`
+- `lib/widgets/section_tabs.dart`
+
+## 文档列表
+
+- `01-information-architecture-and-pages.md`
+  - 整体信息架构
+  - 页面域划分
+  - Assistant / Settings / Focus 的职责边界
+- `02-layout-modules-components-and-state.md`
+  - Layout / modules / components 分层
+  - 全局状态、路由状态、局部状态划分
+  - 状态边界与维护规则
+- `03-flutter-web-directory-and-reuse-strategy.md`
+  - Flutter Web 目录设计
+  - feature-first 组织方式
+  - 组件、模块、状态机复用策略
+- `04-design-system-spec.md`
+  - light / dark 颜色体系
+  - spacing / radius / shadow / typography
+  - card / panel / sidebar / button / input 规范
+  - hover / active / disabled 等状态规则
+
+## 规划原则
+
+- Web 不是桌面版的缩略图，而是桌面工作台在浏览器中的平台化裁剪。
+- 产品语义先对齐桌面基准，再决定 Web 的能力裁剪。
+- Assistant 是执行平面；Settings 是控制平面；Focus 是快捷聚合层；资源域是能力资产层。
+- 页面文件保持轻，模块承接业务交互，组件尽量保持纯展示。
+- Save / Apply、线程会话、连接状态、Focus 入口等交互语义必须跨页面复用，不能散落重写。