astrbot_plugin_imagestudio/docs/ui-redesign-plan-2026-07-21.md

4.8 KiB

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:首批桌面端可用性重构

目标文件:

  • 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、装饰性玻璃卡片或渐变文字。