temp/UI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

iter(g251): ua tokens 增加 --unused 反向查闲置令牌

Browse Source
This commit is contained in:
HIsheR
2026-10-26 22:08:58 +08:00
parent 33cb04ff68
commit 4b57f1126c
5 changed files with 37 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ua/index.json
+4 -2
View File
@@ -1,6 +1,6 @@
{
"$schema": "ui-arch-registry-index/0.1",
"generatedAt": "2026-10-26T14:07:27.545Z",
"generatedAt": "2026-10-26T14:08:42.662Z",
"repoRoot": ".",
"packages": [
{
@@ -4116,6 +4116,7 @@
"ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt",
"ua list：列出注册表内所有包与组件数；--json 输出「包 + 组件 id」结构化数组，--components 逐组件展开",
"ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单，--md 直接给可粘贴的 Markdown 片段（标题 + 参数表 + 用法 + 示例）",
"ua tokens [关键词] [--json|--unused]：打印 --ua-* 令牌清单（颜色带暗色值）；--unused 反向列出皮肤包与令牌自身都没引用的令牌，用来收口令牌面",
"ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt",
"ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1",
"ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）",
@@ -4130,7 +4131,7 @@
"MCP tool 入参 schema"
]
},
"usage": "node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor",
"usage": "node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens [--json|--unused]|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor",
"conventions": [
"零依赖：只用 node 标准库，Node >= 18",
"清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生",
@@ -4143,6 +4144,7 @@
"查组件：ua list 看全量，ua search <关键词> 按 id/标题/参数名/参数说明/步骤五层 + 配方三层（标题/配方组件/要点）模糊找（命中非 id 标题会标出命中字段，配方命中行直接给 ua recipes <编号> 指路；拼错会回相近 id），ua info <组件id> 看 props/步骤/示例（ua info <包名> 看单包 api 与约定，加 --json 出原始清单）；要给文档 / issue / 回复贴组件说明时加 --md，直接拿到标题 + 参数表 + 用法 + 示例的 Markdown 片段",
"查配方：ua recipes 列全量（编号 / 标题 / 用到的组件），ua recipes <编号> 看骨架代码与要点（--json 给脚本用；MCP 里对应 list_recipes / get_recipe）",
"查令牌：ua tokens 打印全部 --ua-* 变量（颜色带暗色值），--json 输出结构化数组；写样式前先查，禁止硬编码。令牌分十三组：颜色 / 混色浓度 / 圆角 / 间距 / 字号 / 字重行高 / 边框 / 阴影 / 动效 / 位移 / 焦点环 / 控件高度 / 层级，color-mix 混入浓度用 --ua-alpha-soft/tint/line/mid/strong/heavy，弹层阴影用 --ua-shadow-1..4，过渡用 --ua-duration-* + --ua-ease，transform 位移用 --ua-translate-*（负号 calc(-1 * var(...))），焦点环用 --ua-focus-ring(_inset)",
"收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们",
"改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）",
"改完样式跑 npm run audit:visual：各类硬编码计数不得高于 .ua/visual-baseline.json（棘轮只减不增）；字面量可用 npm run visual:migrate 幂等改写成令牌",
"改完颜色令牌跑 npm run audit:contrast：16 组文字/底色配对在亮/暗 × 常规/高对比四套主题下都必须达标（正文 7 / 常规 4.5 / 禁用 2.6），跌破即退出码 1——调一个色值就能让全站辅助文字掉到 4.4，人眼看不出但门禁看得出",
llms-full.txt
+9 -7
View File
@@ -1,6 +1,6 @@
# @ui-arch 组件库 Agent 文档（无图形版）
> 自动生成于 2026-10-26T14:07:27.545Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
> 自动生成于 2026-10-26T14:08:42.662Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
> 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
## 快速上手
@@ -44,11 +44,12 @@
2. 查组件：ua list 看全量，ua search <关键词> 按 id/标题/参数名/参数说明/步骤五层 + 配方三层（标题/配方组件/要点）模糊找（命中非 id 标题会标出命中字段，配方命中行直接给 ua recipes <编号> 指路；拼错会回相近 id），ua info <组件id> 看 props/步骤/示例（ua info <包名> 看单包 api 与约定，加 --json 出原始清单）；要给文档 / issue / 回复贴组件说明时加 --md，直接拿到标题 + 参数表 + 用法 + 示例的 Markdown 片段
3. 查配方：ua recipes 列全量（编号 / 标题 / 用到的组件），ua recipes <编号> 看骨架代码与要点（--json 给脚本用；MCP 里对应 list_recipes / get_recipe）
4. 查令牌：ua tokens 打印全部 --ua-* 变量（颜色带暗色值），--json 输出结构化数组；写样式前先查，禁止硬编码。令牌分十三组：颜色 / 混色浓度 / 圆角 / 间距 / 字号 / 字重行高 / 边框 / 阴影 / 动效 / 位移 / 焦点环 / 控件高度 / 层级，color-mix 混入浓度用 --ua-alpha-soft/tint/line/mid/strong/heavy，弹层阴影用 --ua-shadow-1..4，过渡用 --ua-duration-* + --ua-ease，transform 位移用 --ua-translate-*（负号 calc(-1 * var(...))），焦点环用 --ua-focus-ring(_inset)
5. 改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）
6. 改完样式跑 npm run audit:visual：各类硬编码计数不得高于 .ua/visual-baseline.json（棘轮只减不增）；字面量可用 npm run visual:migrate 幂等改写成令牌
7. 改完颜色令牌跑 npm run audit:contrast：16 组文字/底色配对在亮/暗 × 常规/高对比四套主题下都必须达标（正文 7 / 常规 4.5 / 禁用 2.6），跌破即退出码 1——调一个色值就能让全站辅助文字掉到 4.4，人眼看不出但门禁看得出
8. 改完动效跑 npm run audit:motion：带 infinite 的动画必须在 prefers-reduced-motion 块里被关掉，缺一条即退出码 1——循环动画漏兜底会把「减少动效」用户整页交给抖动
9. 在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe
5. 收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们
6. 改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）
7. 改完样式跑 npm run audit:visual：各类硬编码计数不得高于 .ua/visual-baseline.json（棘轮只减不增）；字面量可用 npm run visual:migrate 幂等改写成令牌
8. 改完颜色令牌跑 npm run audit:contrast：16 组文字/底色配对在亮/暗 × 常规/高对比四套主题下都必须达标（正文 7 / 常规 4.5 / 禁用 2.6），跌破即退出码 1——调一个色值就能让全站辅助文字掉到 4.4，人眼看不出但门禁看得出
9. 改完动效跑 npm run audit:motion：带 infinite 的动画必须在 prefers-reduced-motion 块里被关掉，缺一条即退出码 1——循环动画漏兜底会把「减少动效」用户整页交给抖动
10. 在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe
## @ui-arch/ui（skin-dom）v0.1.0
@@ -2347,6 +2348,7 @@ API 速览：
- ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt
- ua list：列出注册表内所有包与组件数；--json 输出「包 + 组件 id」结构化数组，--components 逐组件展开
- ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单，--md 直接给可粘贴的 Markdown 片段（标题 + 参数表 + 用法 + 示例）
- ua tokens [关键词] [--json|--unused]：打印 --ua-* 令牌清单（颜色带暗色值）；--unused 反向列出皮肤包与令牌自身都没引用的令牌，用来收口令牌面
- ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
- ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
- ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）
@@ -2359,7 +2361,7 @@ API 速览：
一行用法：
```
node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor
node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens [--json|--unused]|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor
```
约定：
llms.txt
+2 -1
View File
@@ -140,6 +140,7 @@
- ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt
- ua list：列出注册表内所有包与组件数；--json 输出「包 + 组件 id」结构化数组，--components 逐组件展开
- ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单，--md 直接给可粘贴的 Markdown 片段（标题 + 参数表 + 用法 + 示例）
- ua tokens [关键词] [--json|--unused]：打印 --ua-* 令牌清单（颜色带暗色值）；--unused 反向列出皮肤包与令牌自身都没引用的令牌，用来收口令牌面
- ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
- ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
- ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）
@@ -148,7 +149,7 @@
- ua audit:contrast [--json|--list]：对比度门禁，把令牌里 16 组「文字色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6）退出码 1；--json 出逐对明细，--list 只列配对表
- ua audit:motion [--json]：动效兜底门禁，扫描皮肤样式表里带 infinite 的动画，逐个核对是否在 prefers-reduced-motion 块里 animation: none，缺兜底退出码 1（--json 出逐条明细）
- ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe
- 用法: `node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor`
- 用法: `node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens [--json|--unused]|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor`
- 约定: 零依赖：只用 node 标准库，Node >= 18
- 约定: 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生
- 约定: 门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段
packages/tools/cli/bin/ua.js
+19 -1
View File
@@ -688,6 +688,24 @@ function cmdTokens(args) {
console.error(`no token match: ${keyword}（共 ${list.length} 个令牌，ua tokens 看全表）`);
process.exit(1);
}
if (args.includes('--unused')) {
// 反向视图：令牌定义了但没有任何组件 / 样式引用它 —— 令牌面越铺越大时靠这个收口，
// 阈值口径只看皮肤样式表（ui.css 自身定义的自设变量也算消费），演示页与文档站不属于组件消费面。
// 消费面 = 皮肤样式表 + 令牌自身的派生引用（--ua-shadow-highlight 引用 --ua-color-highlight 也算消费）
const sources = [path.join(ROOT, 'packages', 'skin', 'ui', 'ui.css'), path.join(ROOT, 'packages', 'design', 'tokens', 'tokens.css')];
const used = new Set(sources
.filter((file) => fs.existsSync(file))
.flatMap((file) => fs.readFileSync(file, 'utf8').match(/var\(\s*(--[\w-]+)/g) ?? [])
.map((m) => m.replace(/var\(\s*/, '')));
const dead = list.filter((t) => !used.has(t.cssVar));
if (args.includes('--json')) {
console.log(JSON.stringify({ total: list.length, unused: dead.map((t) => t.cssVar) }, null, 2));
} else {
for (const t of dead) console.log(`${t.cssVar} ${t.value}`);
console.log(`共 ${list.length} 个令牌，其中 ${dead.length} 个没被皮肤包引用${dead.length ? '（确认是否还需要，删的时候亮暗与 tokens.json 一起改）' : ''}`);
}
return;
}
if (args.includes('--json')) {
console.log(JSON.stringify(picked, null, 2));
return;
@@ -1825,6 +1843,6 @@ switch (cmd) {
cmdMcp();
break;
default:
console.log('usage: ua <index|list|search <kw>|info <name> [--json|--md]|recipes [编号] [--json]|docs|tokens [--json]|style|sync-counts|verify|doctor|commit-lint|lint-iterations|audit:visual [--json|--baseline]|audit:contrast [--json|--list]|audit:motion [--json]|changelog|mcp>');
console.log('usage: ua <index|list|search <kw>|info <name> [--json|--md]|recipes [编号] [--json]|docs|tokens [--json|--unused]|style|sync-counts|verify|doctor|commit-lint|lint-iterations|audit:visual [--json|--baseline]|audit:contrast [--json|--list]|audit:motion [--json]|changelog|mcp>');
process.exit(cmd ? 1 : 0);
}
packages/tools/cli/ua.manifest.json
+3 -1
View File
@@ -16,6 +16,7 @@
"ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt",
"ua list：列出注册表内所有包与组件数；--json 输出「包 + 组件 id」结构化数组，--components 逐组件展开",
"ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单，--md 直接给可粘贴的 Markdown 片段（标题 + 参数表 + 用法 + 示例）",
"ua tokens [关键词] [--json|--unused]：打印 --ua-* 令牌清单（颜色带暗色值）；--unused 反向列出皮肤包与令牌自身都没引用的令牌，用来收口令牌面",
"ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt",
"ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1",
"ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）",
@@ -30,7 +31,7 @@
"MCP tool 入参 schema"
]
},
"usage": "node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor",
"usage": "node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens [--json|--unused]|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor",
"conventions": [
"零依赖：只用 node 标准库，Node >= 18",
"清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生",
@@ -43,6 +44,7 @@
"查组件：ua list 看全量，ua search <关键词> 按 id/标题/参数名/参数说明/步骤五层 + 配方三层（标题/配方组件/要点）模糊找（命中非 id 标题会标出命中字段，配方命中行直接给 ua recipes <编号> 指路；拼错会回相近 id），ua info <组件id> 看 props/步骤/示例（ua info <包名> 看单包 api 与约定，加 --json 出原始清单）；要给文档 / issue / 回复贴组件说明时加 --md，直接拿到标题 + 参数表 + 用法 + 示例的 Markdown 片段",
"查配方：ua recipes 列全量（编号 / 标题 / 用到的组件），ua recipes <编号> 看骨架代码与要点（--json 给脚本用；MCP 里对应 list_recipes / get_recipe）",
"查令牌：ua tokens 打印全部 --ua-* 变量（颜色带暗色值），--json 输出结构化数组；写样式前先查，禁止硬编码。令牌分十三组：颜色 / 混色浓度 / 圆角 / 间距 / 字号 / 字重行高 / 边框 / 阴影 / 动效 / 位移 / 焦点环 / 控件高度 / 层级，color-mix 混入浓度用 --ua-alpha-soft/tint/line/mid/strong/heavy，弹层阴影用 --ua-shadow-1..4，过渡用 --ua-duration-* + --ua-ease，transform 位移用 --ua-translate-*（负号 calc(-1 * var(...))），焦点环用 --ua-focus-ring(_inset)",
"收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们",
"改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）",
"改完样式跑 npm run audit:visual：各类硬编码计数不得高于 .ua/visual-baseline.json（棘轮只减不增）；字面量可用 npm run visual:migrate 幂等改写成令牌",
"改完颜色令牌跑 npm run audit:contrast：16 组文字/底色配对在亮/暗 × 常规/高对比四套主题下都必须达标（正文 7 / 常规 4.5 / 禁用 2.6），跌破即退出码 1——调一个色值就能让全站辅助文字掉到 4.4，人眼看不出但门禁看得出",