前端设计系统
本文属于“当前架构”文档,描述已经生效的前端基础设施。 尚在推进中的页面改造与阶段计划见 前端重写计划。
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 | 组件与纯函数 |
| E2E | Playwright | 关键链路 |
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)不引入。
由此产生的两条编码约定:
- 组件必须显式声明边框颜色。 没有 preflight 就不会有默认
border-color, 单独写border会继承currentColor(深色主题下变成白框)。统一用border-border/border-input。 - 原生表单控件不要直接用。 没有 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 切换 darkAlgorithm | src/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_profile | image-generation-options 的 ratio_size_profiles(standard=1K / high=2K) |
| 视频分辨率 | default_video_resolution | video-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. 已迁移页面
| 路由 | 当前实现 | 旧实现 |
|---|---|---|
/projects | src/features/projects/ProjectListPage.tsx | pages/aiStudio/project/ProjectLobby.tsx(已删除) |
/projects/:id/workbench/* | src/features/workbench/WorkbenchPage.tsx | 旧项目/章节/分镜页面(组件已删除,旧深链接重定向) |
/projects/:id/chapters/:cid/board | 重定向到 /workbench/episodes/:cid | 旧镜头看板(组件已删除) |
/files | src/features/files/FileManagerPage.tsx | 新增(原来工作台里的「前往文件管理」指向不存在的路由,点了 404) |
/styles | src/features/styles/StyleManagerPage.tsx | 新增(风格由枚举升级为可维护目录) |
| 全局布局 | src/app/shell/AppShell.tsx | src/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,保证用例不依赖后端与真实账号。