docs(iteration): 选题规则增加域轮换与视觉欠账优先
- backlog 条目新增可选字段 domain(new/tune/visual/tooling),存量 225 条 按标题关键词回填(new 53 / tooling 38 / tune 134) - 每轮选题改为先取 open 且 domain=visual 的条目,无视觉欠账再按数组顺序 - 新增《域轮换与视觉欠账优先》三条:连续 3 轮至少 1 轮 visual、视觉欠账 优先于新增组件、新增组件必须声明只消费 --ua-* 令牌 - AGENTS 落点清单第 4 条补禁止新增硬编码阴影/时长/字号;门禁链描述补 lint-iterations 与 audit:visual - 灌入 8 条 domain=visual 欠账(g179…g186),验收标准均可枚举或可机检
This commit is contained in:
@@ -7,7 +7,7 @@
|
||||
1. **包管理器必须用 pnpm**:包间依赖用 `workspace:*` 协议,npm 不支持。安装依赖:`pnpm install`。
|
||||
2. **构建工具**:TypeScript 5(`tsc`)。若环境未全局安装,可使用托管工作区的副本:`C:/Users/shawn/.workbuddy/binaries/node/workspace/node_modules/typescript`(本仓库历史即如此构建)。
|
||||
3. **Node**:>= 18,ESM(`"type": "module"`)。
|
||||
4. **验证自检**:装好后先跑 `npm run check`(build → demo → style → typecheck → smoke → index → verify)确认基线全绿,再开始改代码。
|
||||
4. **验证自检**:装好后先跑 `npm run check`(build → demo → style → typecheck → smoke → index → verify → lint-iterations → audit:visual)确认基线全绿,再开始改代码。
|
||||
|
||||
## 编码规范(强制)
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
- `apps/demo`(@ui-arch/demo):交互演示,产物 apps/demo/dist/demo.html
|
||||
- `apps/docs`:文档站,纯产物(ua docs 生成)
|
||||
|
||||
**门禁一条龙**:`npm run check` = build + demo + style + typecheck + smoke + index + verify,提交前必过。`ua verify` 校验清单 ↔ 文档 ↔ 演示一致(docs.components 的 id 必须在 api.exports 有对应条目、props 必须带 n/t/d、每个文档字段名必须在组件实现源码里真实出现(改名后忘改文档会直接报错)、反向也校验 `src/types.ts` 里 `<组件>Props`(可用清单的 `propsType` 覆盖接口名,`false` 表示无入参)每个字段都在文档 props 表登记(新加字段忘了写文档会报错)、demo 锚点必须在 `apps/demo/main.ts` 中存在,且该组件必须被 demo 真实调用 `id(` / `id.`),检查皮肤包样式表无硬编码颜色(`#hex` 一律禁止,必须走 `--ua-*` 令牌)与令牌引用有效(`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量)、核对每个 `--ua-color-*` 都在 `[data-theme='dark']` 里有覆盖值且暗色块没有凭空多出的变量名(新增颜色令牌漏写暗色值直接报错),核对 README 的 `<!-- ua:components -->` 区块与「分组:」行都覆盖清单组件集合(漏写/多写/重复都报错),并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应(另外查 backlog id 不重复、g 编号严格递增、同一 id 只有一条 done 留痕,且留痕 ts 带 +08:00、时间线不回退、不落在未来——都是过去手工插条目/手写时间戳踩过的坑);配方还要求编号连续、每条都有代码块与要点,且代码块里至少认出一个已注册组件 id(拼错组件名时 `ua recipes` 会把它列成空组件表)。
|
||||
**门禁一条龙**:`npm run check` = build + demo + style + typecheck + smoke + index + verify + lint-iterations + audit:visual,提交前必过。`ua audit:visual` 统计皮肤包里五类硬编码视觉字面量(字号 / 动效时长 / 阴影 / 圆角 / 焦点环)并与 `.ua/visual-baseline.json` 做棘轮:任一类超过基线即退出码 1 并指出疑似引入的提交;迁移脚本 `npm run visual:migrate` 可把字面量幂等改写成令牌。`ua verify` 校验清单 ↔ 文档 ↔ 演示一致(docs.components 的 id 必须在 api.exports 有对应条目、props 必须带 n/t/d、每个文档字段名必须在组件实现源码里真实出现(改名后忘改文档会直接报错)、反向也校验 `src/types.ts` 里 `<组件>Props`(可用清单的 `propsType` 覆盖接口名,`false` 表示无入参)每个字段都在文档 props 表登记(新加字段忘了写文档会报错)、demo 锚点必须在 `apps/demo/main.ts` 中存在,且该组件必须被 demo 真实调用 `id(` / `id.`),检查皮肤包样式表无硬编码颜色(`#hex` 一律禁止,必须走 `--ua-*` 令牌)与令牌引用有效(`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量)、核对每个 `--ua-color-*` 都在 `[data-theme='dark']` 里有覆盖值且暗色块没有凭空多出的变量名(新增颜色令牌漏写暗色值直接报错),核对 README 的 `<!-- ua:components -->` 区块与「分组:」行都覆盖清单组件集合(漏写/多写/重复都报错),并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应(另外查 backlog id 不重复、g 编号严格递增、同一 id 只有一条 done 留痕,且留痕 ts 带 +08:00、时间线不回退、不落在未来——都是过去手工插条目/手写时间戳踩过的坑);配方还要求编号连续、每条都有代码块与要点,且代码块里至少认出一个已注册组件 id(拼错组件名时 `ua recipes` 会把它列成空组件表)。
|
||||
|
||||
**变更日志**:`CHANGELOG.md` 由 git 提交史生成(`npm run changelog`),**不进 `npm run check`**——它包含每个提交自身,提交后必然与历史差一条,只能作为「发版前刷新」步骤;`npm run changelog:check` 用于确认是否漂移。
|
||||
|
||||
@@ -72,7 +72,7 @@
|
||||
| 1 | `packages/skin/ui/src/<id>.ts` | 组件实现(单文件 ≤ 200 行,导出带 `/*** */` 注释) |
|
||||
| 2 | `packages/skin/ui/src/types.ts` | `<组件>Props` 接口 + 逐字段行尾注释;嵌套项类型(如 `TabItem`)也放这里 |
|
||||
| 3 | `packages/skin/ui/src/index.ts` | 末尾追加 `export { xxx } from './xxx.js';` |
|
||||
| 4 | `packages/skin/ui/ui.css` | 样式只消费 `--ua-*`(禁 `#hex`),动效要带 `prefers-reduced-motion` 兜底 |
|
||||
| 4 | `packages/skin/ui/ui.css` | 样式只消费 `--ua-*`(禁 `#hex`),动效要带 `prefers-reduced-motion` 兜底;**禁止新增硬编码 `box-shadow` / 动效时长 / `font-size` 字面值**,一律用 elevation(`--ua-shadow-1..4`)/ motion(`--ua-duration-*` + `--ua-ease`)/ 字号(`--ua-font-size-*`)令牌,焦点环用 `--ua-focus-ring`,`npm run audit:visual` 会让计数上涨的提交直接红 |
|
||||
| 5 | `packages/skin/ui/ua.manifest.json` → `api.exports` | 一行 `xxx(props):一句话说明` |
|
||||
| 6 | 同上 → `docs.components` | `{ id, title, demo, props[], example, steps[] }`:props 里每个字段名必须在实现源码里真实出现,且 `<组件>Props` 的字段一个都不能漏(verify 双向校验) |
|
||||
| 7 | `apps/demo/main.ts` | 新增 `section('<demo 锚点>', ...)` 并**真实调用**该组件(verify 会查) |
|
||||
|
||||
Reference in New Issue
Block a user