10 KiB
NEX Design System — Agent Entry Rules (0.1.6)
本文件是 NEX 的 Agent 入口。先确认 NEX 目录位置,再以本文件所在目录为基准读取 docs/、config/ 和 templates/。如果本文件被合并到项目根 AGENTS.md,必须将文档路径改为项目中的实际安装路径,不得保留失效的相对路径。
1. 开始任务前必须读取
docs/00-governance-and-adaptation.mddocs/02-design-principles.mddocs/03-design-tokens.mddocs/04-layout-system.mddocs/05-component-system.mddocs/06-interaction-system.mddocs/07-page-patterns.mddocs/08-accessibility-responsive.mddocs/09-agent-execution-rules.mddocs/12-responsive-accessibility-quality.mddocs/14-accessibility-platform-matrix.md- 项目根目录
nex.config.yaml(如存在) - 项目级 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. 强制约束
- 先盘点、后复用、再新增。 先搜索项目现有共享组件和功能等价物。已有组件能满足需求时,不新增重复组件或第二套组件库。
- 项目适配优先。 不将 NEX 参考项目的技术栈、品牌色、Token 名称、Header/Sider 尺寸、断点、控件高度或页面模式套用到其他项目。
- 不强制
--nex-*命名。 优先沿用项目现有语义 Token 和权威主题管线。只有项目没有合理命名体系、且批准采用 NEX 前缀时才可新增命名空间。 - 保持 Token 单一事实来源。 可以由一个源文件/对象/配置单向派生 CSS Variables、组件库主题或框架变量;不得为同一语义值建立彼此独立、人工维护的多份来源。禁止为追求“统一”而破坏已经验证的单向派生链路。
- 保护成熟实现,但不固化缺陷。 保留已验证的视觉和交互模式。若发现可复现的功能缺陷、安全问题或可访问性缺陷,应说明证据并提出最小修复;不得以“保持现状”为由忽略缺陷。
- 不擅自改变业务交互。 视觉改造不得改变用户操作路径、数据语义、默认值或业务流程,除非任务明确授权。修复可访问性时应优先保持原操作意图和鼠标行为。
- 不擅自改技术栈。 不升级框架、替换 UI 库、改变 JS/TS 方案或引入新样式系统,除非用户明确批准。
- 页面模式按需采用。 只为项目真实存在的页面和工作区选择模式。
NOT_APPLICABLE的页面、组件和工作区不应被引入。 - 避免无意义封装。 不机械包装所有第三方基础组件;只封装重复、高价值、需要统一 API/状态/可访问性行为的模式。
- 交互状态完整。 适用时覆盖 loading、success、empty、error、disabled、permission-denied 等状态。状态不能只靠颜色表达。
- 可访问性是质量底线。 自定义交互必须支持键盘、可见焦点和可访问名称;拖拽操作必须提供非拖拽替代路径。
- 滚动和尺寸必须基于实际布局。 对嵌套 Flex/Grid 工作区检查
min-width: 0、min-height: 0、滚动容器归属和溢出,不要机械添加固定尺寸或overflow: hidden。 - 不滥用局部覆盖。 不用大量
!important、高优先级选择器或深层第三方 DOM 覆盖来修补应由 Token/主题/共享组件解决的问题;需要时说明范围和原因。 - 响应式断点必须登记。 新增断点应有语义名称、数值/范围、布局理由、权威来源和边界测试;不得散落增加无法追踪的媒体查询。
- 窄屏数据必须可对账。 隐藏列、卡片化或折叠详情不得导致重要数据无处可见;必须核验字段、记录数、顺序和动作仍可访问。
- 图标不得污染可访问名称。 装饰性图标应从辅助技术名称计算中排除;图标与可见文案组合时避免重复朗读;图标本身不能以内部 glyph 名称充当业务文案。
- 真实 AT 验证按风险触发且跨平台选择。 日常默认 E0–E2;只有复杂自定义控件、拖拽/排序、复合导航、关键数据表格、重要 Live Region 或合同/目标用户要求触发 E3。macOS 使用 VoiceOver,Windows 使用 NVDA(必要时 JAWS/Narrator),Linux 使用 Orca。E3 不适用时记录
E3_NOT_REQUIRED;必要但环境不可用时标记MANUAL_QA_REQUIRED。 - 不得擅自启动屏幕阅读器。 启动、关闭或切换 VoiceOver/NVDA/Orca 等系统 AT 前必须获得用户对本次 E3 的明确授权。记录初始状态,不得关闭用户原本启用的 AT,不得擅改系统级辅助功能设置。日常视觉、浏览器自动化和键盘验收不得启动屏幕阅读器。
- 样式层与性能优化必须有证据。 不为形式一致进行全量 CSS Layer 迁移;不为消除 Bundle 警告盲目调阈值或分包。先提供级联冲突或实际加载数据,再做最小变更。
- 范围受控。 不把审计顺手扩展为全项目重构。超出授权范围、影响已有体验或需改变设计决策时,先提交方案并等待批准。
6. 标准工作流
- 读取 NEX Core、项目配置和项目级设计规范。
- 检查真实实现并建立符合性/差异映射。
- 明确任务范围、复用组件、可能受影响页面和回归面。
- 对跨组件或跨页面改动先提交实施计划;仅在用户已明确授权的范围内执行。
- 先修正 Token/主题/共享模式,再迁移具体页面;避免一次性机械替换。
- 执行项目实际存在的检查命令;不得虚构 lint、test、视觉测试或脚本结果。
- 验证受影响的主题、视口、键盘路径和交互状态;使用项目现有检查矩阵,不强制所有项目采用同一固定路由数或视口数。
- 汇报改动、规范映射、测试证据、视觉对比、未完成事项和风险。
- 对关键交互区分 E0 源码审阅、E1 自动化、E2 浏览器人工交互和 E3 真实辅助技术验证;E3 按风险触发,不适用时记录
E3_NOT_REQUIRED,必要但未执行时标记MANUAL_QA_REQUIRED。
7. 例外记录
偏离 NEX Core 的 SHOULD 或采用不同项目实现时,记录:规则、状态(通常为 ADAPTED / DEFERRED)、原因、证据、影响范围、责任人/批准来源和复审条件。不得把单个项目的例外自动推广为全局规范。
8. 完成定义
只有在以下事项满足后,才能报告任务完成:
- 项目规范与实现之间没有未说明的重大冲突。
- 新增实现优先复用了现有组件、Token 和页面模式。
- 没有未经授权改变技术栈、布局基线或业务交互。
- 适用的主题、响应式、键盘和状态检查已执行。
- 项目真实可用的质量门禁已执行;不可执行项已说明。
- 文档、配置和代码行为保持一致。