# ImageStudio 桌面端 UI 重构方案 日期:2026-07-21 分支:`codex/ui-redesign-gallery` 原则:保留业务逻辑、路由查询参数、API 与数据结构;先改一个页面,再扩展共享视觉层。 ## 设计方向 ImageStudio 是桌面端创作工具,不采用营销网站的 hero、宣传卡片或装饰性动效。视觉方向为“安静的工作台”:冷中性背景、单一主色作为动作/选中/状态强调,内容区保持高对比和稳定密度;圆角、阴影、渐变只服务层级,不作为装饰。 ## P0:先保证安全边界 本项目当前没有已确认的 P0 UI 阻塞项。P0 阶段只包含保护措施: - 保留现有 URL 参数:`view`、`module`、`materialView`、`profile`。 - 保留 plugin-page bridge、API endpoint、shared types 和现有事件 emit。 - 每批修改前后运行 `npm.cmd run typecheck`、`npm.cmd run build:web`,并运行 `npm.cmd run test:contracts`。 - 不删除当前工作树已有的 `GalleryPage.vue` 未提交修改;本分支在其基础上继续。 ## P1:首批桌面端可用性重构 ### P1-01 只重构 Gallery 页面 目标文件: - `frontend/standalone-web/src/features/gallery/GalleryPage.vue` - 必要时复用而不改逻辑:`frontend/standalone-web/src/components/ImagePreviewDialog.vue`、`frontend/standalone-web/src/components/EmptyState.vue`、`frontend/standalone-web/src/components/StateCard.vue` - 契约测试:`frontend/tests/production-data-boundary.test.mjs` 与图库相关测试 实施内容: - 保持 props、emits、筛选值、批量 action、endpoint 调用和预览行为不变。 - 重排为稳定的桌面工作区:页面标题/主操作 → 搜索筛选 → 结果区 + inspector;减少重复 surface。 - 统一按钮、输入框、筛选 tabs、选中态、禁用态、loading、error、empty 状态。 - 让 grid/list 在 1024px–1440px 桌面宽度下优先保持主要内容可读,inspector 只在有选择时占据空间。 - 为搜索、批量选择、卡片操作和图片预览补齐可见 focus、名称、Escape/关闭路径检查。 - 不新增依赖,不引入营销式动画;保留现有 reduced-motion 规则并覆盖新过渡。 ### P1-02 抽取最小共享视觉 token 候选文件: - 新增 `frontend/standalone-web/src/styles/tokens.css` 或现有入口可接受的等价 token 文件。 - 调整 `frontend/standalone-web/src/App.vue` 的全局工作台变量接入 token。 范围:颜色角色、spacing、radius、border、shadow、focus ring、motion duration、z-index;只抽取已经在现有 UI 中出现的语义,不改变默认主题含义。 ## P2:扩展一致性 - `frontend/standalone-web/src/components/AppNavigationRail.vue`:统一 active/hover/focus/compact rail,不改变导航 key 或 pin 行为。 - `frontend/standalone-web/src/features/profiles/ProfilesPage.vue`、`ProfileMasterPane.vue`、`ProfileDetailPane.vue`、`ProfileWardrobePane.vue`:应用同一 surface、表单和状态矩阵。 - `frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue`:统一导入步骤、loading/error/empty 和内容密度。 - `frontend/standalone-web/src/features/settings/SettingsPage.vue` 与 settings panels:统一 section、保存/校验/回滚状态。 - `frontend/standalone-web/src/features/workflow/*.vue`:只做视觉层和焦点/状态修复,不改变 workflow route、round、branch、review API。 - `frontend/standalone-web/src/features/logs/LogsPage.vue` 与 queue/performance 区块:统一状态色、表格/列表密度和窄桌面布局。 ## P2:技术收口 - 将 `App.vue` 的局部视觉规则迁移到可定位的页面/组件样式,降低后续回归风险;不在第一批做大规模逻辑拆分。 - 评估路由页面的动态导入,但只有在不影响 plugin-page bridge 和首屏加载契约时才实施。 - 将布局属性过渡替换为 transform/opacity 或明确的 grid track 过渡。 - 统一图片 loading/失败/alt 规则,并复核对话框 focus return。 ## 交付顺序与验证门 1. Gallery 页面视觉与交互状态;通过 typecheck、build:web、contract tests。 2. Gallery 桌面窗口验证:1280×800、1440×900、1024×768;检查横向溢出、sticky 区域、键盘焦点和空/错/加载状态。 3. 共享 tokens 接入;再次跑同一验证门,并确认 plugin build 不受影响。 4. 导航、profiles、materials、settings、workflow、logs/queue 分批推进,每批单独验证。 5. 最后一轮执行 Impeccable `polish`:桌面窗口、溢出、状态、可访问性与设计一致性。 ## 明确不做 - 不重写后端、不改 API endpoint、不迁移数据结构。 - 不更换 Vue/Vite/TypeScript 技术栈。 - 不引入新的 UI 框架或图标依赖。 - 不添加不必要的全屏动画、营销式 hero、装饰性玻璃卡片或渐变文字。