补齐共享 UI 组件库与展示页交互

- 新增 shadcn canonical UI 源码、共享样式与组件导出
- 新增 /components 共享组件展示页及路由测试
- 补齐平台组件筛选、排序、上传预览和异步状态交互
- 同步网站与客户端构建别名、依赖和项目文档

docs/technical/【前端架构】共享基础组件库与展示页-2026-08-26.md

@@ -0,0 +1,40 @@
+# 共享基础组件库与展示页
+
+更新时间：`2026-08-26`
+
+## 目标
+
+网站与 Tauri 客户端共享无业务依赖的基础 UI chrome，同时保留各自的页面布局、路由、账号/钱包业务和玩法视觉。共享层只接受 React props、原生 DOM props、短文案、图标节点和回调，不读取请求客户端、store、Tauri API 或业务实体。
+
+## 包边界
+
+组件位于 `packages/shared/src/components`，由 `@genarrative/shared` 根入口和 `@genarrative/shared/components` 子路径稳定导出。新增组件按 shadcn 的 open-code 方式归档在 `components/ui`，源码、变体和组合点归项目所有；`packages/shared/src/lib/utils.ts` 提供统一的 `cn` 工具。当前迁移阶段仍复用 `packages/shared/src/components/styles.css` 的 `.genarrative-ui-*` 选择器和 `packages/shared/src/theme.css` 的 `--platform-*` token，避免破坏既有平台视觉契约。
+
+已有账户 DTO 适配组件单独由 `@genarrative/shared/components/account` 导出；它们不进入本样式库的通用组件 barrel，也不从该入口转出。
+
+当前基础组件：
+
+- `Button`、`IconButton`
+- `TextField`、`SelectField`
+- `Subpanel`、`Modal`
+- `Status`、`EmptyState`、`Badge`
+- `ProgressBar`、`SegmentedTabs`、`Switch`
+- `Spinner`、`Divider`
+
+迁移约定：`Button`、`Modal`、`SegmentedTabs`、`Switch`、`Input`、`Textarea`、`Badge`、`Card` 的 canonical source 位于 `packages/shared/src/components/ui`，旧的 `@genarrative/shared/components` API 作为兼容适配层继续保留。`Button`、`Input`、`Badge` 使用 CVA，Dialog/Tabs/Switch 使用按需 Radix primitive；原生 `SelectField` 暂不迁移，避免破坏现有 `<option>` 与表单事件合同。后续组件按使用面逐个迁移。
+
+同时提供 `Platform*` 别名，便于从现有平台组件命名迁移；别名不携带平台业务语义。
+
+Web 宿主需要显式启用 Tailwind 4，并引入 `@genarrative/shared/styles.css` 和 `@genarrative/shared/theme.css`；Tauri WebView 与网站共用这套源码，移动端 React Native 不消费 DOM/CSS 组件。组件库不导入网站 `src/index.css`，也不提供页面壳或业务流程。`components.json` 只用于 shadcn CLI 定位源码，不允许覆盖现有业务组件。
+
+## 展示页
+
+网站 `/components`（兼容别名 `/design-system`）是共享组件展示页，不经过账号 Gate。页面按“基础组件”“平台通用组件”“Token”“状态”分区，覆盖公共组件的主要变体、交互态、筛选/标签/媒体/上传/异步状态/指标列表等平台 chrome 和移动端布局；展示数据均为本地静态示例，不调用 API。平台组件分区中的筛选按示例素材状态过滤结果，排序按最近使用或名称重排结果，并在筛选按钮、排序按钮和独立筛选面板之间保持同一份本地状态。展示页可用于网站与客户端接入前的视觉回归和人工验收。平台通用组件示例来自 `src/components/common`，只接入不读取请求、store 或业务实体的 chrome，不把账号、发布和编辑器业务流程嵌入展示页。
+
+## 验收
+
+- 组件具备原生语义、键盘焦点、禁用态和可访问名称。
+- 按钮、图标按钮、分段标签和开关具备明确按压态；展示页中的可操作示例在点击后提供可见状态反馈，加载态按钮保持禁用。
+- `Modal` 支持 ESC、遮罩点击、可选 portal 和移动端底部面板布局。
+- 组件样式不依赖网站总 CSS；Tauri 只需共享主题、共享组件样式和自己的壳层样式。
+- 修改后运行 `npm run typecheck`、`npm run check:encoding`、`npm run test -- src/routing/activeAppRoutes.test.ts` 与 `git diff --check`。