Skip to content
前端设计系统

前端设计系统

本文属于“当前架构”文档,描述已经生效的前端基础设施。 尚在推进中的页面改造与阶段计划见 前端重写计划。

1. 定位

前端正在从 Ant Design 后台风格迁移到自有设计系统。当前状态是双轨并行:

  • 新页面与新组件使用 src/components/ui(shadcn/ui 风格 + Radix + Tailwind)。
  • 存量页面继续使用 Ant Design,按业务流程顺序逐页替换,不做一次性重写。

两套体系共存在同一张页面里是允许的,但不允许新代码再引入 antd。

2. 技术选型(已安装)

能力选型用途
设计系统底座shadcn/ui 风格组件 + Radix UI可访问性由 Radix 保证,样式完全可控
样式Tailwind CSS 3 + CSS variables主题切换、低层样式复用
服务端状态TanStack Query 5缓存、失效、乐观更新
客户端状态Zustand主题、布局等本地偏好
动效Framer Motion页面切换、面板、看板拖拽
拖拽@dnd-kit镜头看板列间拖拽(替代已废弃的 react-beautiful-dnd)
表单React Hook Form + Zod校验与提交状态
图标lucide-react新组件图标源
单测Vitest + Testing Library组件与纯函数
E2EPlaywright关键链路

3. 目录职责

front/src/
  app/                  页面级装配:Providers、dev-only 预览页
  components/ui/        无业务语义的设计系统组件
  features/             按业务域组织(后续页面迁移落点)
  lib/                  工具函数、QueryClient、query key
  store/                Zustand stores(沿用存量目录名)
  test/                 单测全局 setup
front/e2e/              Playwright 用例

约定:

  • components/ui 内不出现业务字段名,也不 import 业务 store。
  • 业务状态色在 features 层组装,徽标组件本身不内置状态词典。
  • 新页面放 app/ + features/,存量 pages/aiStudio/* 保持原状直到被替换。

4. Token 体系

颜色全部走 CSS variables(src/index.css),通过 <html class="dark"> 切换深浅主题,不重建 Tailwind 配置。

基础语义色

background / foreground / card / popover / primary / secondary / muted / accent / destructive / border / input / ring

三组状态色(互不替代)

组token对应语义
state-*pending / ready镜头信息提取确认状态(shot.status)
run-*running / success / failed / idle运行时任务状态
ready-*blocked / partial / complete视频生成准备度(video-readiness)

这三组刻意分开:页面上任何徽标只能取其中一组,不允许跨组借用颜色, 否则会重新出现「一个颜色在不同位置表示不同状态」的歧义。

5. 样式隔离策略(重要)

Tailwind 的 preflight 必须保持关闭(tailwind.config.js 的 corePlugins)。

原因是一次真实回归:开启 preflight 后,登录页主按钮变成白底白字。 根因是 preflight 的 button { background-color: transparent } 是元素选择器(权重 0,0,1), 而 antd v5 的组件样式全部包在 :where(...) 里(权重 0,0,0), 元素选择器直接压过 antd 的按钮底色。

替代方案是两条局部规则(src/index.css 的 @layer base):

* , ::before, ::after { border-width: 0; border-style: solid; }
body { @apply bg-background text-foreground antialiased; }

只补 shadcn 组件真正依赖的「边框归一化」,其余 preflight 重置(字号、列表、图片 display)不引入。

由此产生的两条编码约定:

  1. 组件必须显式声明边框颜色。 没有 preflight 就不会有默认 border-color, 单独写 border 会继承 currentColor(深色主题下变成白框)。统一用 border-border / border-input。
  2. 原生表单控件不要直接用。 没有 preflight 时 <button> 保留浏览器 padding 与 buttonface 背景, Switch 的滑块曾因此溢出轨道。新增控件一律用 components/ui 里的封装, 确需原生元素时显式补 p-0 / bg-transparent / appearance-none。

6. 主题

  • 偏好三态:system / light / dark,持久化在 localStorage 的 dyeingtime-theme。
  • system 模式监听 prefers-color-scheme 变化;用户显式选择后不再跟随系统。
  • 切换入口在外壳顶栏,任何页面都可一键切换,不需要回首页。
  • 实现见 src/store/useThemeStore.ts,启动同步与订阅在 src/app/providers.tsx。
  • 覆盖范围见第 9 节——主题对存量 antd 页面同样生效。

7. 全局 Provider

AppProviders(src/app/providers.tsx)统一挂载:TanStack Query、Tooltip、 主题启动同步。新增全局能力只改这一处,避免出现「某个页面漏包 Provider」。

src/lib/queryClient.ts 同时是 query key 的统一出口,避免同一份数据被不同 key 缓存两份。

8. 应用外壳

src/app/shell/AppShell.tsx 取代了原 antd MainLayout,是「先换壳、再逐页换肉」的载体。

导航结构(navConfig.ts):

层级入口路由
一级项目/projects
一级资产/assets
分组「配置」提示词模板 / 模型管理 / 音色管理 / 设置/prompts /models /voices /settings

低频配置收进分组、不进一级导航;任务中心仍是常驻浮窗(TaskCenter), 不做成导航项,避免出现「点进去是空页」。

面包屑由 breadcrumbs.ts 按路径段查表解析:

  • 已收录的路径段显示文案并可点击;
  • 未收录的段一律视为实体 ID(项目 / 章节 / 镜头),不显示也不可点。

这条规则取代了旧实现里「按路径位置特判」的拼接逻辑,新增实体路由通常不需要改面包屑。

9. 主题覆盖边界

深浅主题覆盖整个应用,包括尚未重写的 antd 页面。三件事同时生效才成立:

层做法位置
设计系统CSS variables + <html class="dark">src/index.css
antd 组件跟随 resolvedTheme 切换 darkAlgorithmsrc/main.tsx
存量字面色值构建期批量生成 .dark 覆盖tailwind.config.js 插件
antd 静态弹层ConfigProvider.config({ theme }) 同步全局主题src/main.tsx

细节:

  • 存量页面里有大量按调色板写死的类(bg-amber-50、text-gray-700)。 与其逐个文件改,Tailwind 插件在构建期按调色板生成 .dark 覆盖: 浅色底 → 同色系深色 + 透明度,深色字 → 同色系 300 档,浅色边框 → 700 档。 这样保留了「颜色即语义」(待办仍是琥珀色、失败仍是红色),而不是一律灰掉。
  • antd 静态方法(message / notification / Modal.confirm)走独立渲染根, 读的是全局 config 而不是 React context;不同步会在深色下弹出白色提示条。
  • 新页面禁止再写字面色值,否则深色下会被这层覆盖规则「意外改色」。

验收方式:深色下逐页看一遍列表、表格、弹窗、提示条,确认没有白底残留与低对比文字。

9.1 页面自带样式表也要跟随主题

分镜工作室(chapterStudio.separation.css)原先写死了 20 多个浅色十六进制值, 是深色模式下「外壳变黑、工作区仍是白卡片」的主要来源。现在约定:

  • 页面级样式表只用 --cs-* 变量,不写字面色值;
  • .cs-studio 定义浅色,.dark .cs-studio 只重定义同一批变量;
  • 带透明度的工具类(bg-white/80 等)由 index.css 用属性选择器兜底, 否则会留下一块白斑。

9.3 项目设置

项目级生成配置的唯一入口是树状工作台的「项目配置」面板 (features/workbench/panels/ProjectConfigPanel.tsx),支持模型、比例、分辨率、 镜头时长策略、并发、音频参考开关、检查与确认。

项目级生成参数:

项字段可选项来源
图片清晰度default_image_resolution_profileimage-generation-options 的 ratio_size_profiles(standard=1K / high=2K)
视频分辨率default_video_resolutionvideo-generation-options 的 allowed_resolutions
镜头时长策略shot_duration_preference_enabled + default_shot_duration默认 AI 智能规划;开启偏好时才参考秒数
台词配音作参考音频use_dialog_audio_as_reference布尔开关

约定:

  • 可选项一律来自后端能力接口,不在前端写死,否则换模型后会出现「界面上有、供应商不支持」;
  • 每项改动立即 PATCH,失败回滚本地状态;
  • 视频分辨率的生效链是「请求参数 → 项目默认 → 供应商默认」,由后端 resolve_effective_video_resolution 解析后写入任务输入,前端不参与推断。

9.4 项目资产在 V2 内维护

项目资产列表(角色/场景/道具/服装)现在是 V2 工作台的节点:

  • 列表只展示当前项目关联资产,按稳定资产 ID 去重;
  • 「新增」直接创建资产并写入项目关联,随后进入 V2 资产详情;
  • 详情维护角色圣经、候选图、版本、身份锁定、音色与影响分析;
  • 全局素材库 /assets 仍可独立管理跨项目资产,但不是项目制作必经入口;
  • 旧版项目资产 tab 与编辑跳转已删除,旧深链接重定向到 V2 资产组。

9.5 风格目录

风格(真人都市 / 动漫3D / 水墨画 …)原先写在后端枚举里,加一个风格要改代码发版。 现在落在 project_styles 表:

  • /styles 提供增删改:表现形式 + 名称 + 说明,同组内名称唯一;
  • 新建项目的「剧集风格」下拉直接读取该目录(/studio/projects/style-options);
  • 后端首次访问会用内置枚举种子化,升级后行为与枚举时代一致;
  • 删除只影响以后新建项目,已有项目里的字符串值不受影响;
  • Go 控制面也改为读表(该路径已切流),表为空时回落内置列表。

P2 起风格目录新增结构化描述、参考图、样张与三个内置模板; 项目可在工作台「风格圣经」中分析参考图、人工修订并锁定快照。 详见 项目风格快照与锁定。

10. 已迁移页面

路由当前实现旧实现
/projectssrc/features/projects/ProjectListPage.tsxpages/aiStudio/project/ProjectLobby.tsx(已删除)
/projects/:id/workbench/*src/features/workbench/WorkbenchPage.tsx旧项目/章节/分镜页面(组件已删除,旧深链接重定向)
/projects/:id/chapters/:cid/board重定向到 /workbench/episodes/:cid旧镜头看板(组件已删除)
/filessrc/features/files/FileManagerPage.tsx新增(原来工作台里的「前往文件管理」指向不存在的路由,点了 404)
/stylessrc/features/styles/StyleManagerPage.tsx新增(风格由枚举升级为可维护目录)
全局布局src/app/shell/AppShell.tsxsrc/layouts/MainLayout.tsx(已删除)

树状工作台是新设计系统的第一张「多面板工作台」页面:不使用 antd, 由 components/ui + Tailwind + TanStack Query 组成;工作台路径下 AppShell 不渲染旧侧边栏,避免两套导航同时出现。

项目工作台仪表盘的心智是「一屏只回答三个问题」:现在该做什么、流程走到哪、还剩什么没做。 它删掉了三处重复入口与资产卡片里写死的 80/60/75 假进度条—— 装饰性数字会被误读成真实完成度,宁可只展示真实计数。

项目列表页的设计要点:卡片上的「下一步」来自章节准备态, 主按钮文案与点击后跳转的目标严格一致(显示「提取分镜」就跳到分镜页), 不允许出现「文案说下一步、点进去却是首页」。

数据层拆分为 useProjectList(列表与增删改)与 useProjectSummaries(阶段与镜头流量), 页面只负责展示与路由跳转。摘要接口失败时降级为空摘要,不影响列表浏览。

9.2 旧工作室与镜头看板已退役

  • ChapterStudio、ChapterShotsPage、ChapterShotEditPage、ShotBoardPage 等旧项目制作页面组件已删除;
  • /chapters/:cid/studio、/board、/shots、/shots/:sid/edit 只保留到 V2 工作台的安全重定向;
  • 当前的剧集、镜头、参考素材、生成与审核入口统一在 features/workbench/panels/*;
  • 旧页面使用的 chapterStudio.separation.css 与专用回归用例已随页面删除。

11. 设计系统预览页

开发环境访问 /design:

  • 校验 token、按钮/表单/浮层组件与深浅主题。
  • 生产构建下整条路由与动态 import 会被静态裁掉(import.meta.env.DEV 三元),不产出 chunk。
  • 用途是「组件对照表」,不是给最终用户的功能页。

11.1 不启动后端也能跑

前端内置 MSW 演示数据,设计系统与已迁移页面可以完全脱离后端启动:

cd front
pnpm dev:mock       # 演示数据模式,直接进 /projects
pnpm dev:design     # 演示数据模式并打开 /design(设计系统对照表)
pnpm dev:prototype  # 演示数据模式并打开 /prototype(原型索引)

/prototype 把设计系统、已迁移页面与存量页面集中成一页导航, 标注了哪些入口依赖演示数据,演示和验收时不用记路由。

要点:

  • mock 模式下 API 走同源(src/services/openapi.ts 强制 base 为空),由 Service Worker 拦截;
  • 启动时预置演示会话(src/mocks/demoSession.ts),不需要登录;已有真实 token 时不覆盖;
  • 演示数据覆盖:项目/章节/镜头/关联/候选/看板批量操作、文件列表、项目设置的两个参数选项;
  • 生产构建会把 mocks 与演示会话整段 tree-shake 掉(import.meta.env.DEV 收口)。

12. 验证方式

cd front
pnpm exec tsc --noEmit      # 类型
pnpm run lint              # 存量仍有历史告警,新代码必须零错误
pnpm test                  # Vitest
pnpm test:e2e              # Playwright(自带 dev server,端口 7799)

E2E 当前覆盖两条链路:

  • /design:不依赖登录态与后端,验证构建链路、token 与组件渲染;
  • /projects:用 MSW mock 数据 + 伪造登录态,验证列表渲染、搜索过滤、新建弹窗。

E2E 的 dev server 固定带 VITE_USE_MOCK=true,保证用例不依赖后端与真实账号。