nex_animation/AGENTS.md

4.0 KiB
Raw Permalink Blame History

NEX Design System — Agent Entry Rules

本项目采用 NEX Design System。开始任何前端页面、组件或样式工作前,必须先读取本文件及下列文档:

  • docs/02-design-principles.md
  • docs/03-design-tokens.md
  • docs/04-layout-system.md
  • docs/05-component-system.md
  • docs/06-interaction-system.md
  • docs/07-page-patterns.md
  • docs/08-accessibility-responsive.md
  • 项目根目录的 nex.config.yaml(如存在)

读取 nex.config.yaml 时,必须同时遵守 requirements 与 rules:前者定义项目必须达到的设计/体验结果,后者定义具体实现约束。特别是 maintain_existing_interactions: true,表示不得在视觉改造中擅自改变既有业务操作路径;确需调整时,必须先说明影响并纳入任务验收。

任务涉及既有页面时,还必须先读取该页面现有 JSX、CSS 和所依赖的共享组件,禁止只根据需求描述重新造一套样式。

强制规则

  1. 先复用,后新增。 先搜索已有 NEX 组件、页面模式和设计令牌;禁止创建功能或视觉重复的组件。
  2. 不擅自改技术栈。 项目技术栈以项目配置和 package.json 为准。不得借 UI 任务升级 React、替换 Ant Design、引入 Tailwind 或改变 JS/TS 方案。
  3. 禁止硬编码设计值。 颜色、字体、间距、圆角、阴影、层级和布局尺寸必须使用 NEX token。确实属于内容本身的颜色(如 Markdown 语法高亮、第三方品牌标识)可例外,但必须限定作用域并说明原因。
  4. 禁止私自建立视觉变体。 新增颜色、按钮尺寸、卡片样式、页头样式或交互模式前,先确认是否能映射到既有 token/variant;不能映射时先更新 NEX 规范。
  5. 页面不得绕开共享模式。 列表页、详情页、表单页、Dashboard、设置页必须采用 docs/07-page-patterns.md 对应模板;特殊工作区按 docs/04-layout-system.md 选择专用 Shell。
  6. 交互状态完整。 异步功能必须考虑 loading、success、empty、error、disabled 和权限不足状态;破坏性操作必须二次确认;可点击元素必须键盘可达。
  7. 不破坏工作区滚动结构。 全屏/嵌套 Flex 或 Grid 工作区必须明确滚动容器;必要时设置 min-width: 0、min-height: 0,避免页面整体溢出或滚动穿透。
  8. 主题必须成对实现。 任何表面、文字、边框、选中态、悬停态和状态色变更,都要检查 Light/Dark 两种主题。
  9. 不滥用局部覆盖。 禁止在业务页用高优先级选择器、!important 或深层 Ant Design DOM 覆盖修补本应由 token/组件主题解决的问题。确实需要时应写明原因并尽可能限域。
  10. 先提交计划再改动。 超过单一组件的小任务,先列出将复用/新增的组件、涉及页面、状态和验收点;不要在未梳理依赖时直接批量修改。

标准工作流

  1. 检查现有页面、共用组件和 token。
  2. 明确页面类型、用户任务、关键状态和响应式行为。
  3. 在需要时先更新页面规格(templates/page-spec.md)。
  4. 优先修改共享组件/主题,再修改业务页面。
  5. 执行项目已有 lint/build/test;不得虚构项目中不存在的脚本。
  6. 做 Light/Dark、窄屏、键盘和状态检查。
  7. 汇报改动文件、复用组件、规范偏离、检查命令和未完成事项。

完成定义

任务只有在以下条件均满足时才可报告完成:

  • 视觉层级和布局符合 NEX 对应页面模式。
  • 使用设计 token,而非散落硬编码值。
  • 交互状态完整且行为一致。
  • 不引入重复组件或不必要依赖。
  • 亮暗主题和响应式行为已检查。
  • 可运行的质量检查已执行;无法执行的检查必须明确说明。
  • 文档与实际行为不存在明显冲突。

例外处理

业务需求确实要求偏离 NEX 时,先在页面规格中记录:偏离项目、原因、影响范围、是否可复用。不得把单个业务例外自动推广为全局规范。