Issue 153

Issue #153：Alune-UI 共享组件库与官网文档

• 类型：功能。
• 状态：已合入，Pages 部署与公开访问验收通过。
• Issue：https://github.com/ShaoClean/Alune/issues/153
• 执行阶段：#154、#155、#156、#157、#158、#159、#160。
• PR：https://github.com/ShaoClean/Alune/pull/163。
• 最近更新：2026-10-02 02:00（北京时间）。
• 实施基线：development / 20a8dd7ffd912411549a1ceff9ec15b01406d41e，起始工作区干净。
• 分支：codex/alune-ui，负责人：Codex。

背景与范围

建立仓库内 private 源码包 @alune/ui，应用和官网共同使用唯一实现；在 /Alune/ui/ 提供中文规范、API、真实示例与贡献指南。基础控件直接转导出 Ant Design，保留属性、类型和泛型。原始 Modal / Popconfirm 不作为推荐公共入口。

首期不包含 npm 发布、多语言、在线编辑器，以及 Diff / 代码阅读器 / 仓库业务页面提取。

方案与接口

AluneUIProvider 接收必填 theme（light | dark）、可选 reduceMotion（默认 false）和 children。系统偏好与持久化由宿主解析。入口 @alune/ui，样式 @alune/ui/styles.css，字体由宿主提供。同一文档一个根 Provider，统一主题、Portal、反馈和确认；多主题预览采用 iframe。

库不依赖应用 store、路由、API、Electron。业务包装保留在应用，旧路径纯转导出同一实例。测试守卫同时扫描应用与包，没有通过迁移路径绕过检查。

覆盖表与样式归属记录每个导出、类型、依赖、文档、示例与检查。类型化注册表驱动导航、搜索、路由与覆盖。API 从真实 TypeScript 定义生成；基础控件选取常用属性，类型来自当前 Ant Design，默认值维护于可审阅映射。TSX 同时作为执行与复制源码，示例同源 iframe 支持主题、宽度、重置和独立预览；消息验证来源、iframe 实例与示例 ID。

基线与关联演进

本机 Node 25.5.0 / npm 11.8.0；CI 兼容复测使用 Node 22.22.0。React / React DOM 19.2.6、Ant Design 6.3.7、Astro 6.4.8；保持原有锁定运行时。React 集成 5.0.7、MDX 集成 5.0.6 与 Astro 6 兼容。

#151 / #152 在实施基线仍 Open，本次保持已合入通知行为，不顺带改变策略，不推荐高频常规成功弹窗。合并前再次核对 development 与相关状态。引用 UI-Guidelines、UI-Dialogs、#94、#139、#146。

验收标准

• 公开能力、类型、资源与样式归属明确，文档与真实示例覆盖完整。
• UI / Web / 官网类型、构建与桌面构建通过。
• 深浅主题迁移截图一致，动态时间文字差异单独记录。
• Electron 反馈交互与状态回归通过。
• 文档搜索、复制、移动目录、iframe 与无 JS 浏览器验收完成。
• 全新官网依赖环境通过，Electron / 服务端依赖未安装。
• PR 已创建，官网 CI 与分支全套 CI 通过。
• PR 完整 CI、合并与公开部署通过。
• Pages 部署与公开深层访问验收完成。

实际验证与截图。实现完成不等同于发布完成，未执行项保持未勾选。

风险与回退

同一文档采用一个根主题，不同主题的嵌套演示使用 iframe。源码宿主提供兼容 React / Ant Design 与字体。Windows / Linux 原生 UI 仍需现场验证，CI 执行构建与既有自动回归。代码回退时需单独核对 Wiki 与已部署页面。

关联资料

总计划 · 文档目标 · 覆盖 · 验收

依赖与交接

graph TD
  UI[packages/ui: 唯一组件与 token] --> Web[apps/web: 业务布局与状态]
  UI --> Docs[apps/website: 静态文档与隔离示例]
  Web --> Desktop[apps/desktop: Electron 宿主]
  Docs --> Pages[GitHub Pages /Alune/ui/]

Loading

依赖方向是宿主消费共享 UI；库无 apps/web、Electron 或后端反向依赖。P0 提供基线与覆盖表，P1/P2 提供唯一入口与类型，P3 提供 UIDocument 注册、slot 与路由，P4 的示例/API 与 P5 规范采用同一接口；P6 的实际证据见验收页。

最终交付

PR #163 已合入 development，提交 bdc2c4f7258727f5b3eb41a4a994f22b2ea26d75。合入提交与验证分支的 Git tree 均为 fd6b004cd074c0b38c5f34aeaea059e01fce4b6e。

Pages 构建与部署 成功；公开文档、组件页、独立预览 实际直访、刷新与交互通过。详见验收页。

官网排版后续修正（2026-10-02）

PR #176 修正侧栏圆角、31 个示例的分组与自适应高度，统一 Alune 品牌并移除截图版本说明。本地实现与验收完成，待审阅；详见验收记录末尾的后续修正。此记录独立于上方已发布的初始组件库交付。