Aurora Admin v1.2.0: 79 components x 5 ends, doc site, contracts batch 1, playground, regression, deploy ready

2026-09-10 19:21:56 +08:00
commit 51ce3a28f7
654 changed files with 49082 additions and 0 deletions
@@ -0,0 +1,105 @@
+# 贡献指南
+
+欢迎为 Aurora Admin 组件库添砖加瓦。本仓库以「设计规范 → 实现 → 文档站」三段式维护，所有改动请遵循以下流程。
+
+## 仓库结构
+
+```
+组件规范第一套/
+├─ 组件<N>.txt                       # 设计规范原文（按批次）
+├─ frameworks/                       # 79 组件 × 5 端实现
+│  ├─ <Name>.html                    # H5 演示页
+│  ├─ <Name>.css
+│  ├─ <Name>.jsx
+│  ├─ <Name>.vue2.vue
+│  └─ <Name>.vue3.vue
+├─ .design_library/aurora-admin/
+│  ├─ README.md                      # 品牌叙事
+│  ├─ SKILL.md                       # Agent 入口
+│  ├─ colors_and_type.css            # 设计令牌（--au-*）
+│  ├─ css.json                       # 结构化令牌
+│  ├─ components.css                 # 聚合组件样式
+│  ├─ components/
+│  │  ├─ index.json                  # 全量组件索引
+│  │  └─ <slug>.json                 # 核心组件契约（变体/代表/结构/解剖/不发明/未明示）
+│  └─ preview/                       # 6 核心组件预览
+├─ tests/                            # 每组件独立测试页（本仓库 1.1+ 新增）
+├─ site/                             # 文档站
+│  ├─ index.html
+│  ├─ style.css
+│  ├─ app.js
+│  ├─ data.js                        # 自动生成，请勿手改
+│  ├─ dev-server.js                  # node site/dev-server.js 起本地
+│  ├─ logger.js                      # 日志模块（1.1+ 新增）
+│  └─ test-logger.js                 # 测试日志（1.1+ 新增）
+├─ build-site.ps1                    # 构建 site/data.js
+├─ run-tests.ps1                     # 批量构建 tests/（1.1+ 新增）
+├─ PLAN.md                           # 路线图（1.1+ 新增）
+├─ CHANGELOG.md                      # 变更日志
+├─ CONTRIBUTING.md                   # 本文档
+└─ TESTING.md                        # 测试说明
+```
+
+## 新增一个组件的标准流程
+
+1. **在 `组件<N>.txt` 写规格**（或追加到现有规范）
+2. **在 `frameworks/` 写 5 端实现**
+   - `<Name>.html` —— H5 演示页（必含主类型、主尺寸、禁用/加载/错误三类状态）
+   - `<Name>.css` —— 仅 H5/React 端需要
+   - `<Name>.jsx` —— React 组件（函数式 + hooks）
+   - `<Name>.vue2.vue` —— Options API
+   - `<Name>.vue3.vue` —— `<script setup>`
+3. **在 `.design_library/aurora-admin/components/index.json` 登记**
+   ```json
+   { "slug": "yourslug", "name": "中文名 YourName", "tier": "extension",
+     "confidence": "high", "specBatch": 7, "specFile": "组件7.txt",
+     "frameworksPrefix": "YourName" }
+   ```
+4. **（核心组件）写契约 JSON**：`.design_library/aurora-admin/components/yourslug.json`
+5. **跑 `build-site.ps1`** —— 重新生成 `site/data.js`
+6. **跑 `run-tests.ps1`** —— 自动生成 `tests/yourslug.html`（可手动微调）
+7. **在 `CHANGELOG.md` 加一行**
+
+## 修改现有组件
+
+- 仅改 `frameworks/<Name>.*`：直接保存，构建一次，CHANGELOG 加「Fixed」条目
+- 改契约 JSON：跑 build → 跑 tests → CHANGELOG 加「Changed」条目
+- 改设计令牌：`colors_and_type.css` 与 `css.json` 必须同步；CHANGELOG 显式列出新增/废弃令牌
+
+## 提交规范（建议）
+
+- 一次提交只做一件事（新增 / 修改 / 删除）
+- 标题 `<类型>(<范围>): <一句话>`，如 `feat(button): 新增 loading 态`
+- 范围可选：button / input / table / site / tests / build / tokens
+- 在 CHANGELOG 同步追加条目
+
+## 设计约束（不要发明）
+
+- 颜色：必须用 `--au-color-*` 变量；不要硬编码 hex
+- 间距：必须用 `--au-space-*`；不要写 `margin: 13px`
+- 圆角：`--au-radius-{small,base,medium,large}` 四档
+- 字号：display/h1/h2/body/caption 五级
+- 控件高度：24/32/40 三档
+
+## 字体
+
+中文 PingFang SC / 思源黑体；英文 Inter / DIN；禁外部字体引入。
+
+## 工具
+
+- 本地预览：`node site/dev-server.js`（端口 3311）
+- 文档站数据重建：`powershell -File build-site.ps1`（重建后浏览器需强制刷新 Ctrl+F5：dev-server 无缓存控制头，可能拿到旧 data.js）
+- 测试页批量生成：`powershell -File run-tests.ps1`
+- DSH 会话内运行：直接打开 `site/index.html` 或 `tests/index.html`
+
+## 安全
+
+- 不上传任何含客户数据的真实截图
+- 不在框架实现里 hard-code API key
+- 不引入未审核的 npm 包（保持零依赖）
+
+## 行为准则
+
+- 中文优先；技术名词保留英文（如 avatar / tooltip）
+- 注释用「为什么」而非「是什么」
+- 测试断言不写"差不多"，要写「实际值 === 期望值」