7.8 KiB
Nex Animation Studio — Agent 工作手册(项目级入口)
本项目引入 NEX Design System 0.1.1 作为跨项目设计标准。NEX 给的是原则, 不是本项目的固定布局模板、技术栈或尺寸表。本项目已经过 20 余轮真实设计与交互 修正,已验证成熟的设计、组件和交互优先保留;不得为了让数字与 NEX 一致而 反向修改本项目。
1. 规范优先级(冲突时从上往下)
| 层 | 文件 | 负责什么 |
|---|---|---|
| 1 | docs/UI规范.md |
项目级 UI/UX 权威:20 条硬规则 R1–R20、§1–§16 全部尺子与口径、13 道常驻探针、十二步改动流程 |
| 2 | docs/工程规范.md |
目录职责、脚本准入、代码风格、部署、删除策略、最低验收 |
| 3 | docs/NEX-对照与例外.md |
NEX 逐条判定(COMPLIANT / ADOPTED / ADAPTED / DEFERRED / NOT APPLICABLE)与项目级例外登记;NEX 与本项目冲突时按此文件执行 |
| 4 | nex.config.yaml |
项目现状声明(真实尺寸、真实技术栈、真实检查命令)。改了布局尺寸必须同步它 |
| 5 | frontend/src/theme/antd.ts → styles/index.css |
数值的唯一实现;文档与它冲突时以实现为准并回头修文档 |
| 6 | nex_design_system/docs/02–08 |
跨项目原则层(设计原则 / token 治理 / 布局体系 / 组件系统 / 交互系统 / 页面模式 / 可访问性与响应式) |
开始任何前端页面、组件或样式工作前,至少读取:本文件、nex.config.yaml、
docs/NEX-对照与例外.md,以及任务涉及的 docs/UI规范.md 章节。
涉及既有页面时,必须先读该页现有 JSX、CSS 与所依赖的共享组件,
禁止只根据需求描述另造一套样式。
nex.config.yaml 的 requirements 与 rules 都是实施约束:前者是必须达到的
结果,后者是具体实现限制。特别是 maintain_existing_interactions: true ——
视觉改造不得改变既有业务操作路径;确需调整时先说明影响并纳入验收。
⚠️ 历史坑:NEX 0.1.1 的
docs/01-project-audit.md与nex.config.yaml样例描述的是 另一个产品 NexDocus。它的Header 64 / Sider 260·80 / Content 16·1280 / 控件 34·40 / 无 Tailwind / 204 处硬编码色均不是本项目现状。 逐条对照见docs/NEX-对照与例外.md。 同理:.trash/与.local/已被 gitignore,是本地杂物,不作为现状依据。
2. 必须保留的资产(改动前先自查)
- 技术栈:React 18 + TypeScript + Vite + antd 5 + Tailwind CSS v4(只做布局)+ zustand。不升级、不换库、不引入第二套 UI 组件包。
- 单向 Token 流程:
theme/antd.ts→applyRootVars()→:root{--ant-*}→styles/index.css @theme→ Tailwind 语义类。禁止反向造第二把尺子,禁止新增--nex-*全局变量命名空间(该前缀已被 9 个组件局部变量占用,见对照文档 §4)。 - 已验证尺寸:Header 56 / Sider 224·折叠 64 / Content 24(窄屏 16·12)/ 最大宽 1680 / 控件 32·24·40 / 圆角 6·8·4 / 断点 576·768·992·1200·1600 / 主色为 antd 出厂蓝(不覆盖
colorPrimary)。 - 主题机制:跟随系统 + 手动 +
localStorage+<html data-theme>+color-scheme+meta theme-color+⌘⇧L。 - 共享组件 kit:
frontend/src/components/{ui,forms}(25 文件 / 163 导出)。NEX 05 §3 要求的第一批标准组件已全部存在,用它们,不要新造。 - Empty 三分类:没数据 / 没匹配 / 引导下一步,文案分开,且能清除筛选恢复默认。
- 反馈四级表面(R19):
ErrorText/LineHint→Notice→notify*吐司 →confirmAction。长任务唯一进度源是顶栏「平台动态」(§13.7),页面内不得再放第二个进度条。 - 专业工作区交互:分镜卡拖拽、时间线、录音、素材灯箱、版本面板的既有操作路径。
- 质量闸门:13 道常驻探针 + §16 十二步流程。这是 NEX 10「阶段 5 质量门禁」的现成实现,复用而非重造。
- 本项目没有文档阅读 / PDF 预览 / AI Chat 工作区,不要为对齐 NEX 引入相应模板、布局或图表依赖。
3. 强制规则
docs/UI规范.md §0 的 R1–R20 是硬规则,违反任意一条 = 返工(先读那 20 行)。在其之上再加:
- 先复用,后新增。 先在 kit 里找;找不到才新增,且不得与已有件功能或视觉重复。
- 不擅自改技术栈。 不得借 UI 任务升级 React / antd / Tailwind,或引入新组件库、图表库。
- 禁止硬编码设计值。 颜色、字体、间距、圆角、阴影、层级、布局尺寸一律走 token / 语义类(R9)。
- 禁止私自建立视觉变体。 新颜色 / 新按钮尺寸 / 新卡片或页头样式 / 新断点前,先确认能否映射到既有 token;不能映射时先登记例外。
- 交互状态完整。 loading / success / empty / error / disabled / 权限不足都要考虑;破坏性操作二次确认;可点击元素键盘可达(用正确的语义元素,不自造
div + onClick)。 - 不破坏工作区滚动结构。 嵌套 Flex/Grid 必须明确滚动容器,必要时
min-width:0/min-height:0。 - 主题成对实现。 任何表面 / 文字 / 边框 / 选中 / 悬停 / 状态色变更都要检查 Light 与 Dark。
- 不滥用局部覆盖。 业务页禁止高优先级选择器、
!important、深层 antd DOM 覆盖;styles/app.css是全站唯一.ant-*出口。 - 浮层层级不写魔法数。 z-index 走
frontend/src/lib/layers.ts的层级表与docs/UI规范.md§10;浮层叠浮层时页面级快捷键先问floatingLayerOpen()。 - 先提交计划再改动。 超过单一组件的任务,先列将复用/新增的组件、涉及页面、状态与验收点。
4. 标准工作流
-
查现有页面、共享组件、token(
components/{ui,forms}、theme/antd.ts、styles/)。 -
明确页面类型、用户任务、关键状态、响应式行为;必要时写
nex_design_system/templates/page-spec.md规格的页面版。 -
先改共享组件 / 主题,再改业务页面。
-
跑项目真实存在的检查(本仓库没有
lint与test,不得虚构):cd frontend && npm run typecheck && npm run build node scripts/ui/classaudit.mjs NEX_BASE=http://127.0.0.1:5199 .venv/bin/python scripts/ui/<按 §15 改动范围选探针>.py -
按
docs/UI规范.md§16 走完十二步;改过尺子(theme/antd.ts、styles/index.css、styles/app.css)必须全量回归,含 430 / 576 窄屏(R12)。 -
做 Light/Dark、窄屏(1440 / 768 / 430)、键盘与状态检查。基线是 14 路由 × 3 视口 × 2 主题 = 84 个状态,新截图必须与之可比。
-
汇报:改动文件、复用组件、规范偏离、检查命令与实际结果、未完成事项。
5. 完成定义
- 视觉层级与布局符合
docs/UI规范.md对应页面模式; - 用 token 而非散落硬编码;
- 交互状态完整且跨页一致;
- 不引入重复组件或不必要依赖;
- Light / Dark / 窄屏 / 键盘均已检查并有截图证据;
- 可运行的质量检查已执行且退出码为 0;跑不了的必须说明原因;
- 文档(含
nex.config.yaml与本文件)与实际行为不冲突;偏离 NEX 的已登记在docs/NEX-对照与例外.md。
6. 例外处理
偏离 NEX 或偏离 docs/UI规范.md 时,在 docs/NEX-对照与例外.md §3 登记:
偏离项 / NEX 条款 / 本项目值 / 证据位置 / 原因 / 影响范围 / 是否可复用 / 状态。
不得把单个业务例外自动推广为全局规范,也不得复制一份与 docs/UI规范.md
大量重复的规范文档。需要修订 NEX 本身的,登记在对照文档 §5 反向清单里。