nex_design_system/AGENTS.md

10 KiB
Raw Blame History

NEX Design System — Agent Entry Rules (0.1.6)

本文件是 NEX 的 Agent 入口。先确认 NEX 目录位置,再以本文件所在目录为基准读取 docs/、config/ 和 templates/。如果本文件被合并到项目根 AGENTS.md,必须将文档路径改为项目中的实际安装路径,不得保留失效的相对路径。

1. 开始任务前必须读取

  1. docs/00-governance-and-adaptation.md
  2. docs/02-design-principles.md
  3. docs/03-design-tokens.md
  4. docs/04-layout-system.md
  5. docs/05-component-system.md
  6. docs/06-interaction-system.md
  7. docs/07-page-patterns.md
  8. docs/08-accessibility-responsive.md
  9. docs/09-agent-execution-rules.md
  10. docs/12-responsive-accessibility-quality.md
  11. docs/14-accessibility-platform-matrix.md
  12. 项目根目录 nex.config.yaml(如存在)
  13. 项目级 UI/UX 规范(由 nex.config.yaml 声明;如未声明,先搜索项目现有设计文档)

只在任务涉及 NexDocus 历史实现或明确要求参考时,读取 docs/01-project-audit.md 和 config/reference-nexdocus-profile.example.yaml。它们不是新项目的实施基线。

2. 规范层级

遵循 NEX 三层模型:

  • NEX Core:跨项目质量与设计治理要求。
  • Project Design Specification:本项目视觉、布局、技术和交互的权威具体规范。
  • Project Implementation:当前主题、Token、组件和页面的真实实现。

NexDocus 参数、示例截图和示例组件名不是跨项目默认值。新项目的技术起步默认值以 nex.config.yaml 的 stack 为准;它只适用于新项目初始化,不是 NEX Core 对所有项目的强制技术栈。已有项目由项目级规范和真实实现决定。NEX Core 的通用 MUST 要求不能因项目偏好而取消,但可以采用不同技术方式满足。

3. 默认技术栈与自动发现(0.1.6;沿用 0.1.5 默认栈)

config/project-profile.example.yaml 是带有明确默认技术栈的配置模板。它不是“技术栈自动猜测模板”。

  • 新项目:project.lifecycle 为 new,或 auto 且仓库为空/没有实际应用代码时,必须把 stack 中的默认技术栈作为初始化目标。不得忽略这些选型,也不得再次要求用户填写一份技术栈问卷。
  • 已有项目:project.lifecycle 为 existing,或 auto 且仓库已有应用代码/锁文件/构建配置时,以实际项目为准;默认技术栈仅供参考,不得据此替换、升级或迁移现有技术。
  • project.type 默认是 fullstack。纯前端或纯后端项目只需覆盖该字段。
  • 用户可以只覆盖 stack 中不符合当前项目意图的字段;未覆盖的默认值仍然有效。

新项目默认栈详见 docs/13-project-stack-defaults.md,包括 React、TypeScript、Vite、Ant Design、Tailwind CSS v4、Python、FastAPI、SQLite/PostgreSQL 等。依赖版本采用创建时兼容的稳定版本,并提交 lockfile。

Agent 仍须自动发现已有项目的实际情况,包括:

  • 项目名称、类型和主要界面语言;
  • 前后端框架、语言、依赖版本、构建工具和 UI/样式方案;
  • 项目 UI/UX 规范与设计决策文档;
  • Token 权威来源、主题链路、共享组件目录和布局模式;
  • 路由、断点、响应式规则、质量命令、视觉基线和 CI;
  • 适用的辅助技术验证范围及尚未执行的人工测试。

无法发现的信息应标记 UNKNOWN 并说明证据缺口。不得把 auto 当成待用户填写的占位符,也不得为了补全配置而向用户发送长问卷。只有在信息无法从仓库确认且会影响产品选择、数据安全或高风险改动时,才提出最少量的具体问题。

新项目未覆盖的 stack 字段采用默认技术栈。已有项目不采用默认栈迁移,而是优先保留真实、成熟的现有实现;NEX 的通用设计质量要求仍然适用。

4. 开发前审计要求

修改既有前端前,先检查:

  • 项目技术栈和真实依赖(以锁文件、package.json、构建配置为证据)。
  • 项目级 UI 规范和设计决策记录。
  • Token 的单一事实来源及其派生链路(CSS、主题库、框架变量等)。
  • 已有组件、页面模式、主题机制和布局参数。
  • 现有交互路径、响应式行为、自动化检查与视觉基线。

将发现映射为 COMPLIANT、ADOPTED、ADAPTED、DEFERRED 或 NOT_APPLICABLE。优先使用 templates/project-conformance-matrix.md。如果用户要求只审计,则不得修改业务代码。

5. 强制约束

  1. 先盘点、后复用、再新增。 先搜索项目现有共享组件和功能等价物。已有组件能满足需求时,不新增重复组件或第二套组件库。
  2. 项目适配优先。 不将 NEX 参考项目的技术栈、品牌色、Token 名称、Header/Sider 尺寸、断点、控件高度或页面模式套用到其他项目。
  3. 不强制 --nex-* 命名。 优先沿用项目现有语义 Token 和权威主题管线。只有项目没有合理命名体系、且批准采用 NEX 前缀时才可新增命名空间。
  4. 保持 Token 单一事实来源。 可以由一个源文件/对象/配置单向派生 CSS Variables、组件库主题或框架变量;不得为同一语义值建立彼此独立、人工维护的多份来源。禁止为追求“统一”而破坏已经验证的单向派生链路。
  5. 保护成熟实现,但不固化缺陷。 保留已验证的视觉和交互模式。若发现可复现的功能缺陷、安全问题或可访问性缺陷,应说明证据并提出最小修复;不得以“保持现状”为由忽略缺陷。
  6. 不擅自改变业务交互。 视觉改造不得改变用户操作路径、数据语义、默认值或业务流程,除非任务明确授权。修复可访问性时应优先保持原操作意图和鼠标行为。
  7. 不擅自改技术栈。 不升级框架、替换 UI 库、改变 JS/TS 方案或引入新样式系统,除非用户明确批准。
  8. 页面模式按需采用。 只为项目真实存在的页面和工作区选择模式。NOT_APPLICABLE 的页面、组件和工作区不应被引入。
  9. 避免无意义封装。 不机械包装所有第三方基础组件;只封装重复、高价值、需要统一 API/状态/可访问性行为的模式。
  10. 交互状态完整。 适用时覆盖 loading、success、empty、error、disabled、permission-denied 等状态。状态不能只靠颜色表达。
  11. 可访问性是质量底线。 自定义交互必须支持键盘、可见焦点和可访问名称;拖拽操作必须提供非拖拽替代路径。
  12. 滚动和尺寸必须基于实际布局。 对嵌套 Flex/Grid 工作区检查 min-width: 0、min-height: 0、滚动容器归属和溢出,不要机械添加固定尺寸或 overflow: hidden。
  13. 不滥用局部覆盖。 不用大量 !important、高优先级选择器或深层第三方 DOM 覆盖来修补应由 Token/主题/共享组件解决的问题;需要时说明范围和原因。
  14. 响应式断点必须登记。 新增断点应有语义名称、数值/范围、布局理由、权威来源和边界测试;不得散落增加无法追踪的媒体查询。
  15. 窄屏数据必须可对账。 隐藏列、卡片化或折叠详情不得导致重要数据无处可见;必须核验字段、记录数、顺序和动作仍可访问。
  16. 图标不得污染可访问名称。 装饰性图标应从辅助技术名称计算中排除;图标与可见文案组合时避免重复朗读;图标本身不能以内部 glyph 名称充当业务文案。
  17. 真实 AT 验证按风险触发且跨平台选择。 日常默认 E0–E2;只有复杂自定义控件、拖拽/排序、复合导航、关键数据表格、重要 Live Region 或合同/目标用户要求触发 E3。macOS 使用 VoiceOver,Windows 使用 NVDA(必要时 JAWS/Narrator),Linux 使用 Orca。E3 不适用时记录 E3_NOT_REQUIRED;必要但环境不可用时标记 MANUAL_QA_REQUIRED。
  18. 不得擅自启动屏幕阅读器。 启动、关闭或切换 VoiceOver/NVDA/Orca 等系统 AT 前必须获得用户对本次 E3 的明确授权。记录初始状态,不得关闭用户原本启用的 AT,不得擅改系统级辅助功能设置。日常视觉、浏览器自动化和键盘验收不得启动屏幕阅读器。
  19. 样式层与性能优化必须有证据。 不为形式一致进行全量 CSS Layer 迁移;不为消除 Bundle 警告盲目调阈值或分包。先提供级联冲突或实际加载数据,再做最小变更。
  20. 范围受控。 不把审计顺手扩展为全项目重构。超出授权范围、影响已有体验或需改变设计决策时,先提交方案并等待批准。

6. 标准工作流

  1. 读取 NEX Core、项目配置和项目级设计规范。
  2. 检查真实实现并建立符合性/差异映射。
  3. 明确任务范围、复用组件、可能受影响页面和回归面。
  4. 对跨组件或跨页面改动先提交实施计划;仅在用户已明确授权的范围内执行。
  5. 先修正 Token/主题/共享模式,再迁移具体页面;避免一次性机械替换。
  6. 执行项目实际存在的检查命令;不得虚构 lint、test、视觉测试或脚本结果。
  7. 验证受影响的主题、视口、键盘路径和交互状态;使用项目现有检查矩阵,不强制所有项目采用同一固定路由数或视口数。
  8. 汇报改动、规范映射、测试证据、视觉对比、未完成事项和风险。
  9. 对关键交互区分 E0 源码审阅、E1 自动化、E2 浏览器人工交互和 E3 真实辅助技术验证;E3 按风险触发,不适用时记录 E3_NOT_REQUIRED,必要但未执行时标记 MANUAL_QA_REQUIRED。

7. 例外记录

偏离 NEX Core 的 SHOULD 或采用不同项目实现时,记录:规则、状态(通常为 ADAPTED / DEFERRED)、原因、证据、影响范围、责任人/批准来源和复审条件。不得把单个项目的例外自动推广为全局规范。

8. 完成定义

只有在以下事项满足后,才能报告任务完成:

  • 项目规范与实现之间没有未说明的重大冲突。
  • 新增实现优先复用了现有组件、Token 和页面模式。
  • 没有未经授权改变技术栈、布局基线或业务交互。
  • 适用的主题、响应式、键盘和状态检查已执行。
  • 项目真实可用的质量门禁已执行;不可执行项已说明。
  • 文档、配置和代码行为保持一致。