4.0 KiB
4.0 KiB
NEX Design System — Agent Entry Rules
本项目采用 NEX Design System。开始任何前端页面、组件或样式工作前,必须先读取本文件及下列文档:
docs/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.md- 项目根目录的
nex.config.yaml(如存在)
读取 nex.config.yaml 时,必须同时遵守 requirements 与 rules:前者定义项目必须达到的设计/体验结果,后者定义具体实现约束。特别是 maintain_existing_interactions: true,表示不得在视觉改造中擅自改变既有业务操作路径;确需调整时,必须先说明影响并纳入任务验收。
任务涉及既有页面时,还必须先读取该页面现有 JSX、CSS 和所依赖的共享组件,禁止只根据需求描述重新造一套样式。
强制规则
- 先复用,后新增。 先搜索已有 NEX 组件、页面模式和设计令牌;禁止创建功能或视觉重复的组件。
- 不擅自改技术栈。 项目技术栈以项目配置和
package.json为准。不得借 UI 任务升级 React、替换 Ant Design、引入 Tailwind 或改变 JS/TS 方案。 - 禁止硬编码设计值。 颜色、字体、间距、圆角、阴影、层级和布局尺寸必须使用 NEX token。确实属于内容本身的颜色(如 Markdown 语法高亮、第三方品牌标识)可例外,但必须限定作用域并说明原因。
- 禁止私自建立视觉变体。 新增颜色、按钮尺寸、卡片样式、页头样式或交互模式前,先确认是否能映射到既有 token/variant;不能映射时先更新 NEX 规范。
- 页面不得绕开共享模式。 列表页、详情页、表单页、Dashboard、设置页必须采用
docs/07-page-patterns.md对应模板;特殊工作区按docs/04-layout-system.md选择专用 Shell。 - 交互状态完整。 异步功能必须考虑 loading、success、empty、error、disabled 和权限不足状态;破坏性操作必须二次确认;可点击元素必须键盘可达。
- 不破坏工作区滚动结构。 全屏/嵌套 Flex 或 Grid 工作区必须明确滚动容器;必要时设置
min-width: 0、min-height: 0,避免页面整体溢出或滚动穿透。 - 主题必须成对实现。 任何表面、文字、边框、选中态、悬停态和状态色变更,都要检查 Light/Dark 两种主题。
- 不滥用局部覆盖。 禁止在业务页用高优先级选择器、
!important或深层 Ant Design DOM 覆盖修补本应由 token/组件主题解决的问题。确实需要时应写明原因并尽可能限域。 - 先提交计划再改动。 超过单一组件的小任务,先列出将复用/新增的组件、涉及页面、状态和验收点;不要在未梳理依赖时直接批量修改。
标准工作流
- 检查现有页面、共用组件和 token。
- 明确页面类型、用户任务、关键状态和响应式行为。
- 在需要时先更新页面规格(
templates/page-spec.md)。 - 优先修改共享组件/主题,再修改业务页面。
- 执行项目已有 lint/build/test;不得虚构项目中不存在的脚本。
- 做 Light/Dark、窄屏、键盘和状态检查。
- 汇报改动文件、复用组件、规范偏离、检查命令和未完成事项。
完成定义
任务只有在以下条件均满足时才可报告完成:
- 视觉层级和布局符合 NEX 对应页面模式。
- 使用设计 token,而非散落硬编码值。
- 交互状态完整且行为一致。
- 不引入重复组件或不必要依赖。
- 亮暗主题和响应式行为已检查。
- 可运行的质量检查已执行;无法执行的检查必须明确说明。
- 文档与实际行为不存在明显冲突。
例外处理
业务需求确实要求偏离 NEX 时,先在页面规格中记录:偏离项目、原因、影响范围、是否可复用。不得把单个业务例外自动推广为全局规范。