74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
# NEX Design System — Agent Development Rules (0.1.7)
|
||
|
||
NEX 的目标是统一设计规范并约束 Agent 开发行为。NEX 不负责测试体系、测试覆盖率、自动化测试、质量闸门或测试报告。
|
||
|
||
> **本仓库的实际安装路径**:NEX 0.1.7 随仓库置于 `nex_design_system/`,
|
||
> 因此下文的 `docs/…` 均相对该目录(如 `nex_design_system/docs/01-design-principles.md`)。
|
||
> 本文件即项目根 `AGENTS.md`,§1 第 3、4 项指向的项目规则与项目 UI/UX 规范为:
|
||
> `frontend/src/styles/design-tokens.css`(Token 权威来源)、
|
||
> `frontend/src/theme/antdTheme.ts`(antd 主题映射)、
|
||
> `docs/sdd/architecture/standards/nex-conformance-matrix.md`(符合性与例外,按 0.1.6 章节号登记)、
|
||
> `docs/sdd/architecture/standards/responsive-breakpoint-registry.md`(断点登记)、
|
||
> `docs/quickstart.md` §6(前端约定)。本项目没有独立的「项目设计规范」文档,以上即权威来源。
|
||
|
||
## 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. 汇报要求
|
||
|
||
用简洁对话汇报:完成内容、主要文件、关键设计选择、尚未解决的阻塞。除用户明确要求外,不生成长篇报告,不列出与本任务无关的测试证据。
|