3.6 KiB
3.6 KiB
NEX Design System — Agent Development Rules (0.1.7)
NEX 的目标是统一设计规范并约束 Agent 开发行为。NEX 不负责测试体系、测试覆盖率、自动化测试、质量闸门或测试报告。
1. 每个任务的最小读取范围
开始任务时读取:
- 本文件;
- 项目根目录
nex.config.yaml(如存在); - 项目根
AGENTS.md中的项目规则; - 项目已有的 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. 开发时必须遵守
- 先理解现有页面和组件,再改代码;优先复用,不重复造组件。
- 使用项目既有 Token 和主题单一来源,不另建重复变量层。
- 保持同类页面、组件和交互的一致性。
- 不擅自改变业务流程、交互路径、默认值或数据语义。
- 不擅自升级依赖、替换 UI 库、改变语言或重构目录。
- 仅修改完成当前任务所需的范围;不顺手重构无关页面。
- 响应式、无障碍和体验性能按对应设计规范实现;不把这些要求扩展成 NEX 自建测试流程。
- 若项目实现与 NEX 示例不同,先判断是否是合理的项目适配,不强制套用示例尺寸或命名。
- 设计要求有冲突时,以安全/适用规范底线、项目级 UI 规范和用户明确要求为依据;无法确定时只提出一个关键问题。
4. 执行方式
默认采用轻量开发:
- 对当前需求做必要分析;
- 查找相关现有组件、Token、页面模式;
- 读取相关 NEX 章节;
- 直接实施必要修改;
- 在对话中简要汇报文件和行为变化。
只有涉及全局 Token、应用 Shell、导航体系、共享组件 API 或大范围视觉统一时,才先提交简短影响说明和实施计划。
5. NEX 的文件和工具边界
- 普通任务不得创建阶段报告、审计报告、
reports/目录或截图证据目录。 - 不得为了遵守 NEX 新建
scripts/ui/、自定义检查脚本、自动化测试或质量闸门。 - 不得自动引入 Playwright、axe、Vitest、Pytest 或其他测试工具;它们由项目自身工程规范决定。
- 不得启动 VoiceOver、NVDA、Orca 等屏幕阅读器;NEX 不定义其测试流程。
- 不得把 NEX 规范文档复制成项目中的第二套完整 UI 规范。项目只需保留必要的项目专属设计说明。
- 只有用户明确要求,或确有长期设计决策需要留档时,才新增/更新文档。
6. 汇报要求
用简洁对话汇报:完成内容、主要文件、关键设计选择、尚未解决的阻塞。除用户明确要求外,不生成长篇报告,不列出与本任务无关的测试证据。