历史档案文档OceanWay 架构品牌与统一设计系统
历史 · 组件选型与行为规范
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
详细组件规范与实现由 Design 固定来源维护。 本页保留既有组件盘点和消费者检查点；规则变化先更新 Design，再更新引用，不在 Docs 维护第二套标准。
复用 Ocean Foundation，不另建一套组件。 基础动作、输入、状态和媒体组件优先沿用
components/ui 与 components/ocean；复杂表格、弹层保留既有 Ant Design 适配，
已有 Radix 控件也不因“统一”被重写。官网保留轻量品牌表达，文档保留 Fumadocs。
统一的是设计变量、状态、外观和交互契约，不是强迫所有控件更换底层库。
共享实现和详细规范的 Owner 是 Design；Studio 和 Infrastructure 固定提交只作为迁移来源。
当前盘点
| 平台 | 当前情况 | 接入方向 |
|---|---|---|
| Design | 已接收共享基础、独立实验室与平台规范；源码移交已合并 | 独立 design-system/ 工作区，许可审核、制品发布与产品接入仍待完成 |
| Infrastructure | 已移交设计源码 | 只负责固定制品发布、环境与工程治理 |
| Studio | 已继承 /components、Ocean/UI 组件、主题和测试 | 作为来源；迁出实验室、改为消费共享包，保留业务组件 |
| Console | 原生 React 控件 + CSS Modules，已有模型目录 | 不继续扩散一套独立控件；确认后逐项接入统一基础 |
| Docs | Fumadocs、Tailwind、next-themes | 保留文档能力，只统一品牌、阅读语义和全局变量 |
| Site | 在途独立 React/Vite 页面 | 品牌与基础变量一致，营销版式无需强行等同业务后台 |
| Admin/Drama/Commerce | 不同阶段，部分尚无真实页面 | 新页面必须先采用已批准基线，不按仓库各选组件库 |
组件目录与验收
| 组件族 | 统一内容 | 必须覆盖的状态/行为 |
|---|---|---|
| Brand/Logo | 原始资源、比例、浅深反白、可访问名称 | 桌面/窄屏、自定义图失败回退、不重绘字标 |
| Button/IconButton | primary/default/text/danger、尺寸、图标间距 | default/hover/focus/disabled/loading；加载不重复提交 |
| Input/Select/Filter | label、说明、错误、清除、选中摘要 | 输入/空/只读/禁用/验证失败/异步加载；下拉真实可达 |
| Form | 字段栅格、验证位置、保存/取消 | 改动未保存提醒、失败不丢输入、成功读后写一致 |
| Card/List/Table | 标题/元信息/正文/操作区 | skeleton/empty/error/ready、分页、长文本、窄屏 |
| StatusBadge | 语义文字、轻背景、细描边 | 运行状态不冒充终态；颜色不是唯一提示 |
| Modal/Drawer/Popover | 焦点、宽度、滚动、关闭语义 | Escape、焦点归还、手机不溢出、Portal 不触发底层画布 |
| Message/Alert/Confirm | 短提示 vs 持续错误 vs 危险确认 | 不泄露内部堆栈/密钥；错误可带公开请求编号 |
| Pagination/Search | 服务端查询、游标、加载反馈 | 条件变化归第一页、取消旧请求、迟到响应不覆盖新结果 |
| Shell/Navigation | 当前产品、工作空间、导航分组 | 当前项、键盘、窄屏折叠；客户/管理员身份边界清楚 |
统一封装的边界
- 真正共享规则才封装：Logo、主题 Provider、错误展示、身份展示视图、媒体预览、危险确认；身份校验与会话仍在产品/Core。
- 已有 Ocean 控件优先复用；新增需求再查 Ant Design 能力，不新增只转发 props 的同名壳组件。
- 既有 Ocean Dialog/Drawer/Table 适配负责材质和状态，焦点/关闭/表格行为仍由原库承担。
- 业务页面私有组件留在页面目录；多个页面实际复用后再升到共享目录。
- 产品全局状态留在产品已有 store/hook；共享 UI 不导入产品 Store/Session，实验室只持有演示状态。
- 通用交互与服务状态分离：按钮自身不能决定重试、扣费、角色授权或任务成功。
- 不用统一 UI 包携带 Core 客户数据、SQL、Token 签发或网关适配。
执行顺序
独立实验室已迁入 Design，继续保持无 AppWorkspaceShell、产品导航、Session 和服务健康依赖。
本轮先对齐各平台需求、设计与原型，复用按钮、表单、筛选、表格、卡片、状态、错误、弹窗和侧栏样板。
用户确认密度、主题和关键状态，再完成接口/文档、许可与固定制品资格，随后选择产品真实页面接入。
不要先重做全部页面，也不要在样板未通过时把候选组件发布成全生态标准。
实验室、基础组件与 Ant Design token 适配已经存在，并非本轮从零开发；
尚缺跨仓统一消费、token 单一来源和完整产品链路验收。built 只表示该清单项已有实现，
部分 Product Kit 仍是纯视觉候选，不能据此宣称目标业务页面已迁移。