nex_design_system/AGENTS.md

3.6 KiB
Raw Blame History

NEX Design System — Agent Development Rules (0.1.7)

NEX 的目标是统一设计规范并约束 Agent 开发行为。NEX 不负责测试体系、测试覆盖率、自动化测试、质量闸门或测试报告。

1. 每个任务的最小读取范围

开始任务时读取:

  1. 本文件;
  2. 项目根目录 nex.config.yaml(如存在);
  3. 项目根 AGENTS.md 中的项目规则;
  4. 项目已有的 UI/UX 规范(如存在)。

然后按任务读取 NEX 文档,不得默认全量读取:

  • 视觉风格/页面:docs/01-design-principles.md、docs/08-page-patterns.md;
  • 颜色/主题/Token:docs/02-design-tokens-and-theme.md;
  • 页面布局/导航/移动端:docs/03-layout-and-responsive.md;
  • 公共组件:docs/04-component-system.md;
  • 表单/表格/弹层/反馈:docs/05-interaction-system.md;
  • 语义/键盘/辅助技术支持:docs/06-accessibility-design.md;
  • 体验性能/加载呈现:docs/07-performance-aware-design.md;
  • 新项目技术栈:docs/10-project-stack-defaults.md;
  • 首次接入:docs/11-project-adoption.md。

2. 新项目与已有项目

  • 新项目:nex.config.yaml 的 stack 是明确技术选型。按它初始化,不得自行换栈。
  • 已有项目:以真实代码、依赖和锁文件为准,保留现有技术栈;不得因为 NEX 默认值不同而迁移。
  • 项目具体视觉参数、Token 名称、组件 API、布局尺寸和断点以项目级 UI 规范为准。

3. 开发时必须遵守

  1. 先理解现有页面和组件,再改代码;优先复用,不重复造组件。
  2. 使用项目既有 Token 和主题单一来源,不另建重复变量层。
  3. 保持同类页面、组件和交互的一致性。
  4. 不擅自改变业务流程、交互路径、默认值或数据语义。
  5. 不擅自升级依赖、替换 UI 库、改变语言或重构目录。
  6. 仅修改完成当前任务所需的范围;不顺手重构无关页面。
  7. 响应式、无障碍和体验性能按对应设计规范实现;不把这些要求扩展成 NEX 自建测试流程。
  8. 若项目实现与 NEX 示例不同,先判断是否是合理的项目适配,不强制套用示例尺寸或命名。
  9. 设计要求有冲突时,以安全/适用规范底线、项目级 UI 规范和用户明确要求为依据;无法确定时只提出一个关键问题。

4. 执行方式

默认采用轻量开发:

  • 对当前需求做必要分析;
  • 查找相关现有组件、Token、页面模式;
  • 读取相关 NEX 章节;
  • 直接实施必要修改;
  • 在对话中简要汇报文件和行为变化。

只有涉及全局 Token、应用 Shell、导航体系、共享组件 API 或大范围视觉统一时,才先提交简短影响说明和实施计划。

5. NEX 的文件和工具边界

  • 普通任务不得创建阶段报告、审计报告、reports/ 目录或截图证据目录。
  • 不得为了遵守 NEX 新建 scripts/ui/、自定义检查脚本、自动化测试或质量闸门。
  • 不得自动引入 Playwright、axe、Vitest、Pytest 或其他测试工具;它们由项目自身工程规范决定。
  • 不得启动 VoiceOver、NVDA、Orca 等屏幕阅读器;NEX 不定义其测试流程。
  • 不得把 NEX 规范文档复制成项目中的第二套完整 UI 规范。项目只需保留必要的项目专属设计说明。
  • 只有用户明确要求,或确有长期设计决策需要留档时,才新增/更新文档。

6. 汇报要求

用简洁对话汇报:完成内容、主要文件、关键设计选择、尚未解决的阻塞。除用户明确要求外,不生成长篇报告,不列出与本任务无关的测试证据。