aurora-admin
5ee5d829a4
Regression / regression (push) Canceled after 0s
本提交含两条并行工作线，因互相咬合（package.json scripts、regression.yml、 npm run build 链）无法按文件干净拆分，故合并为一次自洽提交。 ## 详情页减重（本轮主任务：修复「AI 干太重」） - 导航收敛：宽屏只用右侧目录、≤1200px 只用页内 sticky 导航，纯 CSS 媒体查询 实现（不引入 JS 宽度监听）。此前两套导航同时可见，active 状态互相打架。 - 入口去重：标题区由「查看示例/在线测试/契约 JSON」三个减为「在线测试」一个； 契约 JSON 归入实现资源；删除示例底部重复的「在线测试」。 - 示例工具栏：删除与目录锚点重复的示例下拉选择器；「全部展开代码」只在 示例数 >1 时出现（103 个组件里 49 个仅 1 个示例，此前恒显示）。 - 重复文案：示例区两句同义导语合并为一句。 - 首页 CTA 由 5 个减为 2 个（浏览组件/快速开始），测试总览入口挂到已有的 通过率统计卡上，不再另占 Hero 按钮。 - 统一详情取数：抽出 fetchDetail/loadDetail 作为 details/*.json 的唯一路径， FAQ 不再自行 fetch 一遍，与组件页共用缓存与失败兜底。 ## i18n - 删除 12 组重复键（含整段 FAQ 说明），字典 604 → 585 唯一键。 - 删除本次改动产生的 6 个死键。 - verify-i18n.mjs 新增 `unique dictionary keys` 断言：重复键在对象字面量里 是静默的后值覆盖，此前无从发现；现由门禁拦住。 ## 文档事实修正（实测为准） - TESTING/CONTRIBUTING：79 → 103 组件；旧断言数改为回指 tests/report.json。 - PLATFORMS：移动端 108 文件/18 端 → 282 文件/47 端；契约 5 → 47； 令牌 17 → 15；uni-app SFC 21 → 50。 - AGENTS：断言 1405/18 页 → 1464/103 页（PC）、807/47 页（移动端）。 - package.json：YOUR-ACCOUNT 占位 → gitea 实址与 kole-ui.mymoyu.top。 ## 品牌标识（并行会话成果，一并入库） - brand-mark.json 收归真源，build:brand 生成 favicon 与单色 SVG； PC 与移动端共用资产，verify:brand 24 条断言。 - regression.yml 增加 verify:brand 步骤。 ## 门禁与验收 新增工具：verify-component-page.mjs（86 条真实浏览器断言，随详情页改造同步 更新为「只允许一套导航可见」）、verify-brand-mark.mjs、lib/i18n-dead-keys.mjs （只读诊断）。 回归：PC 100%（1464/1464，103 页，N/A 50）· 移动端 100%（807/807，47 页）。 门禁：component-page 86 · i18n 17 · brand 24 · routes all · smoke all · theme OK · isolation 31 · nav all · examples 9 · api-docs 10 · mobile-docs 12。 已知未做：i18n 另有约 44 条历史死键（非本次产生），已记为 ROADMAP S8-P6； 顶栏与悬浮区的两个主题入口为刻意设计（verify-theme 断言其互斥），未删。
115 lines
5.6 KiB
Markdown
115 lines
5.6 KiB
Markdown
# 贡献指南
|
||
|
||
欢迎为 Kole UI 组件库添砖加瓦。本仓库以「设计规范 → 实现 → 文档站」三段式维护，所有改动请遵循以下流程。
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
组件规范第一套/
|
||
├─ 组件<N>.txt # 设计规范原文（按批次）
|
||
├─ frameworks/ # 103 组件 × 5 端实现（515 文件）
|
||
│ ├─ <Name>.html # H5 演示页
|
||
│ ├─ <Name>.css
|
||
│ ├─ <Name>.jsx
|
||
│ ├─ <Name>.vue2.vue
|
||
│ └─ <Name>.vue3.vue
|
||
├─ .design_library/kole-ui/
|
||
│ ├─ README.md # 品牌叙事
|
||
│ ├─ SKILL.md # Agent 入口
|
||
│ ├─ colors_and_type.css # 设计令牌（--kole-*）
|
||
│ ├─ 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>`
|
||
- 命名约定（v2.0.0 起统一，见 `AGENTS.md` §七）：类名前缀 `kole-`（如 `kole-btn`）、令牌 `--kole-*`、导出名 `Kole*`（如 `KoleButton`）。Vue 组件的 `name` 选项也要用 `KoleXxx`，否则三端入口导出的名字会不一致
|
||
3. **在 `.design_library/kole-ui/components/index.json` 登记**
|
||
```json
|
||
{ "slug": "yourslug", "name": "中文名 YourName", "tier": "extension",
|
||
"confidence": "high", "specBatch": 7, "specFile": "组件7.txt",
|
||
"frameworksPrefix": "YourName" }
|
||
```
|
||
4. **（核心组件）写契约 JSON**：`.design_library/kole-ui/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 同步追加条目
|
||
|
||
## 设计约束（不要发明）
|
||
|
||
- 颜色：必须用 `--kole-color-*` 变量；不要硬编码 hex
|
||
- 间距：必须用 `--kole-space-*`；不要写 `margin: 13px`
|
||
- 圆角：`--kole-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 包（保持零依赖）
|
||
|
||
## 版本发布流程（S4-P12 · SemVer）
|
||
|
||
1. 在 `CHANGELOG.md` 的 `[Unreleased]` 下写清本次变更条目（有内容才允许提升版本）。
|
||
2. 检查是否可发布：`node tools/release.mjs`（校验 package.json 与 CHANGELOG 最新版本一致）。
|
||
3. 提升版本：`node tools/release.mjs --bump <major|minor|patch> --date YYYY-MM-DD`（自动改 CHANGELOG 与 package.json，复核后提交）。
|
||
4. 人工执行：`git tag v<x.y.z>` → `git push origin main v<x.y.z>` → `npm run build && npm publish`（公开发布需先做 Q1 决策）。
|
||
5. 版本号规则：破坏 `data.json` 全量承诺或删接口 → major；加组件/加页面 → minor；修 bug/改文案 → patch。
|
||
|
||
## 行为准则
|
||
|
||
- 中文优先；技术名词保留英文（如 avatar / tooltip）
|
||
- 注释用「为什么」而非「是什么」
|
||
- 测试断言不写"差不多"，要写「实际值 === 期望值」
|