nex_design_system/START-HERE.md

102 lines
4.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# NEX 0.1.6 — 新项目快速开始(带默认技术栈)
## 1. 放置规范包
建议目录:
```text
project-root/
├── AGENTS.md
├── nex.config.yaml
├── standards/
│ └── nex-design-system/
├── docs/
└── frontend/ / backend/ # 由项目类型和默认技术栈初始化
```
将 ZIP 内 `NEX-Design-System-v0.1.6/` 的内容放入 `standards/nex-design-system/`。
## 2. 复制默认配置
将 `standards/nex-design-system/config/project-profile.example.yaml` 复制到项目根目录,命名为 `nex.config.yaml`。
**默认技术栈已经给定,不需要从零填写:**
- 前端:React + TypeScript + Vite + Ant Design + Tailwind CSS v4 + Zustand + React Router + Axios。
- 后端:Python + FastAPI + Pydantic + SQLAlchemy + Alembic。
- 数据库:开发 SQLite,生产 PostgreSQL。
- API:REST + OpenAPI。
- 本地资源:`./data`。
- 质量工具:ESLint、Prettier、Vitest、Playwright、Pytest。
这些是 NEX 新项目的默认起步方案。需要不同技术时,只修改 YAML 中对应字段,不必填写整份技术清单。
### 生命周期如何处理
`project.lifecycle` 默认为 `auto`:
- 空仓库/无应用代码:按新项目处理,使用上述默认技术栈。
- 已有代码、锁文件或构建配置:按已有项目处理,自动识别并保留当前技术栈,不会强行改成默认方案。
如果需要明确指定,可将其改为 `new` 或 `existing`。
### 项目类型
默认 `project.type: fullstack`。纯前端项目只需改为 `frontend-only`;纯后端项目改为 `backend-only`。Agent 不应初始化不适用的部分。
## 3. 合并根 AGENTS.md
不要覆盖项目已有的根 `AGENTS.md`。合并以下规则,并按实际安装路径调整:
```markdown
## NEX Design System
本项目采用 NEX Design System 0.1.6 作为跨项目设计治理标准。
规范位于 `standards/nex-design-system/`。
UI/UX 任务开始前,读取 NEX AGENTS.md、docs/00-governance-and-adaptation.md、
docs/09-agent-execution-rules.md、docs/12-responsive-accessibility-quality.md、
docs/13-project-stack-defaults.md、docs/14-accessibility-platform-matrix.md,以及项目根目录 nex.config.yaml。
新项目按 nex.config.yaml 中的 stack 默认值初始化,不得忽略或自行替换技术选型。
已有项目自动识别实际技术栈并保留,不得因默认值不同而迁移。
先审计、建立符合性矩阵、提交计划;未经授权不得全量重构或自动进入下一阶段。
```
## 4. 首次交给 Agent
将 `templates/new-project-audit-prompt.md` 交给 Agent。
- 新项目:先核对默认技术栈与项目类型,给出目录结构、依赖和初始化计划;本轮只审计,不实际创建业务代码,除非你另行授权。
- 已有项目:从锁文件、源码、构建配置和运行结果识别真实技术栈,形成与 NEX 的差异映射;不得把默认栈当作迁移目标。
## 5. 只修改真正需要覆盖的字段
例如,若希望数据库从“开发 SQLite、生产 PostgreSQL”改为两阶段均 PostgreSQL,只修改:
```yaml
stack:
database:
development: PostgreSQL
production: PostgreSQL
```
如希望纯前端项目,只修改:
```yaml
project:
type: frontend-only
```
其余默认项保持不动。审计报告不是代码修改授权;确认实施范围后再让 Agent 开始开发。
## 6. 无障碍测试怎么执行
- 默认工程目标为 WCAG 2.2 AA;日常验收使用源码审阅、Playwright/axe 等自动化和浏览器键盘交互(E0–E2)。
- 真实屏幕阅读器(E3)仅在复杂自定义交互、关键业务流程、Live Region、复合控件或客户/法规要求等风险条件下触发,不是每次提交的必做步骤。
- 按项目目标平台选择 AT:macOS VoiceOver、Windows NVDA(必要时 JAWS/Narrator)、Linux Orca。项目不承诺的平台不强制加入测试矩阵。
- Agent 不得自动启动或关闭系统屏幕阅读器;启动/关闭前必须取得本次 E3 测试的明确授权。
- 目标环境不可用时,若 E3 已判定必要,标记 `MANUAL_QA_REQUIRED`;若风险评估不需要 E3,记录 `E3_NOT_REQUIRED`。
详见 `docs/08-accessibility-responsive.md`、`docs/12-responsive-accessibility-quality.md` 和 `docs/14-accessibility-platform-matrix.md`。