Files

T

Regression / regression (push) Canceled after 0s

Details

feat(品牌标识): 几何 K 图标(favicon/顶栏标记/theme-color) + 并行会话成果入库

## 品牌标识（本次会话）

起因：品牌此前没有任何图形标识 —— 唯一 favicon 是内联 data-URI 里的字母「A」，
那是 v2.0.0「Aurora Admin → Kole UI」改名漏掉的一处（PC 顶栏也是「A」，
移动端站已是「K」；移动端文档站则完全没有 favicon）。

- 几何：24 网格三个互不接触的笔画（竖 + 两斜），圆头描边；
  描边 2.25 → 16px 标签页尺寸下正好 1.5px = 规范原文「描边1.5px」
- 取色分两套（刻意）：favicon 硬编码品牌蓝/白（渲染在浏览器标签栏，不继承 kole-dark）；
  顶栏标记走 currentColor（实测暗色下自动转 rgb(20,22,28)）
- 新增 theme-color 双条（light #FFFFFF / dark #1C1F26，取 --kole-color-card-bg）
- 修 site/app.js hero 标语 KOLE ADMIN → KOLE UI（改名变形残留）
- 移动端 7 个模板补 favicon（此前计数 0）

验收：门禁 9 条全 OK（site-routing/site-routes/mobile-docs/mobile-site/isolation/
theme/nav/i18n/icons）；PC 回归 1464/1464 · 移动端 807/807，各连跑 8 次一致；
两端 favicon 405 字节逐字节一致；PC 站控制台错误 1→0。

## 并行会话成果（本次一并入库）

- 图标系统：2576 图标（TDesign/Element Plus，MIT）+ 11 端注入 + 5 个构建门禁工具
  + IconPreview 预览页 + ICON-SPEC.md 冻结规格
- 移动端平台：47 组件 × 6 端 + 文档站 53 页 + 隔离门禁
- PC 组件：103 个大后台组件 / 组件11 批次
- uni-app：PC 端试点 + 移动端端实现 + 真实编译验证

## 工程

- .gitignore 补 .scratch/ 与 .zcode-preexisting-*.txt（会话中间产物，实测 9.1MB，不入库）
- CHANGELOG 补品牌标识条目
- ROADMAP 登 S8-P4（品牌标识任务包 + og:image/apple-touch-icon 未做部分）

2026-09-21 10:05:48 +08:00

5.6 KiB

Raw Blame History

贡献指南

欢迎为 Kole UI 组件库添砖加瓦。本仓库以「设计规范 → 实现 → 文档站」三段式维护，所有改动请遵循以下流程。

仓库结构

组件规范第一套/
├─ 组件<N>.txt                       # 设计规范原文（按批次）
├─ frameworks/                       # 79 组件 × 5 端实现
│  ├─ <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                        # 测试说明

新增一个组件的标准流程

在 组件<N>.txt 写规格（或追加到现有规范）
在 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，否则三端入口导出的名字会不一致

在 .design_library/kole-ui/components/index.json 登记

{ "slug": "yourslug", "name": "中文名 YourName", "tier": "extension",
  "confidence": "high", "specBatch": 7, "specFile": "组件7.txt",
  "frameworksPrefix": "YourName" }

（核心组件）写契约 JSON：.design_library/kole-ui/components/yourslug.json
跑 build-site.ps1 —— 重新生成 site/data.js
跑 run-tests.ps1 —— 自动生成 tests/yourslug.html（可手动微调）
在 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）

在 CHANGELOG.md 的 [Unreleased] 下写清本次变更条目（有内容才允许提升版本）。
检查是否可发布：node tools/release.mjs（校验 package.json 与 CHANGELOG 最新版本一致）。
提升版本：node tools/release.mjs --bump <major|minor|patch> --date YYYY-MM-DD（自动改 CHANGELOG 与 package.json，复核后提交）。
人工执行：git tag v<x.y.z> → git push origin main v<x.y.z> → npm run build && npm publish（公开发布需先做 Q1 决策）。
版本号规则：破坏 data.json 全量承诺或删接口 → major；加组件/加页面 → minor；修 bug/改文案 → patch。

行为准则

中文优先；技术名词保留英文（如 avatar / tooltip）
注释用「为什么」而非「是什么」
测试断言不写"差不多"，要写「实际值 === 期望值」

5.6 KiB Raw Blame History Unescape Escape