iter(g262): 对比度门禁增加非文本配对
This commit is contained in:
HIsheR
+3
-3
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"$schema": "ui-arch-registry-index/0.1",
|
"$schema": "ui-arch-registry-index/0.1",
|
||||||
"generatedAt": "2026-10-26T14:23:08.179Z",
|
"generatedAt": "2026-10-26T14:23:51.644Z",
|
||||||
"repoRoot": ".",
|
"repoRoot": ".",
|
||||||
"packages": [
|
"packages": [
|
||||||
{
|
{
|
||||||
@@ -4135,7 +4135,7 @@
|
|||||||
"ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）",
|
"ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）",
|
||||||
"ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1",
|
"ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1",
|
||||||
"ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）",
|
"ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）",
|
||||||
"ua audit:contrast [--json|--list]：对比度门禁，把令牌里 16 组「文字色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6）退出码 1；--json 出逐对明细，--list 只列配对表",
|
"ua audit:contrast [--json|--list]：对比度门禁，把令牌里 18 组「前景色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）退出码 1；--json 出逐对明细，--list 只列配对表",
|
||||||
"ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）",
|
"ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）",
|
||||||
"ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段"
|
"ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段"
|
||||||
],
|
],
|
||||||
@@ -4160,7 +4160,7 @@
|
|||||||
"收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们",
|
"收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们",
|
||||||
"改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）",
|
"改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）",
|
||||||
"改完样式跑 npm run audit:visual：各类硬编码计数不得高于 .ua/visual-baseline.json（棘轮只减不增）；字面量可用 npm run visual:migrate 幂等改写成令牌",
|
"改完样式跑 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，人眼看不出但门禁看得出",
|
"改完颜色令牌跑 npm run audit:contrast：18 组前景/底色配对在亮/暗 × 常规/高对比四套主题下都必须达标（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3），跌破即退出码 1——调一个色值就能让全站辅助文字掉到 4.4 或让焦点环糊进背景，人眼看不出但门禁看得出",
|
||||||
"改完动效跑 npm run audit:motion：带 infinite 的动画必须在 prefers-reduced-motion 块里被关掉，悬停 / 按压的位移（translate）必须归零，缺一条即退出码 1——循环动画漏兜底会把「减少动效」用户整页交给抖动，位移漏兜底则每次悬停都在推搡前庭",
|
"改完动效跑 npm run audit:motion：带 infinite 的动画必须在 prefers-reduced-motion 块里被关掉，悬停 / 按压的位移（translate）必须归零，缺一条即退出码 1——循环动画漏兜底会把「减少动效」用户整页交给抖动，位移漏兜底则每次悬停都在推搡前庭",
|
||||||
"在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 传 format: md 拿到与 ua info --md 同款的 Markdown 片段"
|
"在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 传 format: md 拿到与 ua info --md 同款的 Markdown 片段"
|
||||||
],
|
],
|
||||||
|
|||||||
@@ -27,7 +27,7 @@
|
|||||||
- `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html
|
- `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html
|
||||||
- `apps/docs`：文档站，纯产物（ua docs 生成）
|
- `apps/docs`：文档站，纯产物（ua docs 生成）
|
||||||
|
|
||||||
**门禁一条龙**：`npm run check` = build + demo + style + typecheck + smoke + index + verify + lint-iterations + audit:visual + audit:contrast + audit:motion，提交前必过。其中 `smoke` 是两段内核断言：`@ui-arch/frame` 14 条（信号读写与同值短路、effect 注销与条件分支重追踪、computed 链式派生、多订阅者扇出）+ `@ui-arch/table-core` 31 条（排序 / 筛选 / 分页 / 选择的派生管线 + setRows 换源与失效行剔除 + 越界页码回写）；改内核语义前先跑它，别靠组件 demo 肉眼验。`ua audit:visual` 统计皮肤包里十四类硬编码视觉字面量（字号 / 动效时长 / 阴影 / 圆角 / 焦点环 / 内距 / 控件高度 / 字重 / 行高 / 层级 / 边框色 / 混色浓度 / transform 位移 / 焦点描边）并与 `.ua/visual-baseline.json` 做棘轮：任一类超过基线即退出码 1 并指出疑似引入的提交；迁移脚本 `npm run visual:migrate` 可把字面量幂等改写成令牌。`ua audit:contrast` 走另一条线：把令牌里 16 组「文字色 × 底色」配对（正文/次级/辅助文字 × 页面底/表面/凹陷底、强调色与其反白、语义三色、禁用态豁免档）按 WCAG 公式算成对比度（支持 `color-mix` 与 `var()` 求值，半透明底先压到页面底色上），亮 / 暗 × 常规 / 高对比四套主题各算一遍，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6）即退出码 1；`--json` 出逐对明细，`--list` 只列配对表。改任一颜色令牌后它会立刻告诉你「改完谁读不清了」，不必等人工目测暗色。`ua audit:motion` 守的是动效面，两类必查：① 带 `infinite` 的动画是否在 `prefers-reduced-motion: reduce` 块里被 `animation: none` 关掉——循环动画是前庭敏感用户的硬伤，漏一条整页就在抖（它抓出过转圈与不确定态进度两处漏网）；② 悬停 / 按压的位移（`translate`）是否在减少动效下归零——位移最容易诱发前庭不适，且只提供手感、不表达状态（一条 `ua-` 类通配的 `transform: none !important` 兜住全站 14 处，新增组件不用各自补）。`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']` 里有覆盖值且暗色块没有凭空多出的变量名（新增颜色令牌漏写暗色值直接报错）、核对 `tokens.json` 的 `color` 键与 tokens.css 的 `--ua-color-*` 同名同值（名字按 camelCase → kebab 折算，亮色值与暗色值都比，双向查漏——只改一处时文档色板会凭空多/少一个令牌，过去只能靠人眼发现）、核对 `@keyframes` 没有「帧体完全相同但名字不同」的复制粘贴（同一段动效只该有一份声明，改名复制会让方向 / 时长各写各的，翻转态就出现过「朝反方向入场」），核对 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 + audit:contrast + audit:motion，提交前必过。其中 `smoke` 是两段内核断言：`@ui-arch/frame` 14 条（信号读写与同值短路、effect 注销与条件分支重追踪、computed 链式派生、多订阅者扇出）+ `@ui-arch/table-core` 31 条（排序 / 筛选 / 分页 / 选择的派生管线 + setRows 换源与失效行剔除 + 越界页码回写）；改内核语义前先跑它，别靠组件 demo 肉眼验。`ua audit:visual` 统计皮肤包里十四类硬编码视觉字面量（字号 / 动效时长 / 阴影 / 圆角 / 焦点环 / 内距 / 控件高度 / 字重 / 行高 / 层级 / 边框色 / 混色浓度 / transform 位移 / 焦点描边）并与 `.ua/visual-baseline.json` 做棘轮：任一类超过基线即退出码 1 并指出疑似引入的提交；迁移脚本 `npm run visual:migrate` 可把字面量幂等改写成令牌。`ua audit:contrast` 走另一条线：把令牌里 18 组「前景色 × 底色」配对（正文/次级/辅助文字 × 页面底/表面/凹陷底、强调色与其反白、语义三色、禁用态豁免档、焦点描边 × 页面底/表面）按 WCAG 公式算成对比度（支持 `color-mix` 与 `var()` 求值，半透明底先压到页面底色上），亮 / 暗 × 常规 / 高对比四套主题各算一遍，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）即退出码 1；`--json` 出逐对明细，`--list` 只列配对表。改任一颜色令牌后它会立刻告诉你「改完谁读不清了」，不必等人工目测暗色。`ua audit:motion` 守的是动效面，两类必查：① 带 `infinite` 的动画是否在 `prefers-reduced-motion: reduce` 块里被 `animation: none` 关掉——循环动画是前庭敏感用户的硬伤，漏一条整页就在抖（它抓出过转圈与不确定态进度两处漏网）；② 悬停 / 按压的位移（`translate`）是否在减少动效下归零——位移最容易诱发前庭不适，且只提供手感、不表达状态（一条 `ua-` 类通配的 `transform: none !important` 兜住全站 14 处，新增组件不用各自补）。`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']` 里有覆盖值且暗色块没有凭空多出的变量名（新增颜色令牌漏写暗色值直接报错）、核对 `tokens.json` 的 `color` 键与 tokens.css 的 `--ua-color-*` 同名同值（名字按 camelCase → kebab 折算，亮色值与暗色值都比，双向查漏——只改一处时文档色板会凭空多/少一个令牌，过去只能靠人眼发现）、核对 `@keyframes` 没有「帧体完全相同但名字不同」的复制粘贴（同一段动效只该有一份声明，改名复制会让方向 / 时长各写各的，翻转态就出现过「朝反方向入场」），核对 README 的 `<!-- ua:components -->` 区块与「分组：」行都覆盖清单组件集合（漏写/多写/重复都报错），并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应（另外查 backlog id 不重复、g 编号严格递增、同一 id 只有一条 done 留痕，且留痕 ts 带 +08:00、时间线不回退、不落在未来——都是过去手工插条目/手写时间戳踩过的坑）；配方还要求编号连续、每条都有代码块与要点，且代码块里至少认出一个已注册组件 id（拼错组件名时 `ua recipes` 会把它列成空组件表）。
|
||||||
|
|
||||||
`ua verify` 另外校验 `ITERATION.md` 的《视觉回归抽查清单》：button / textField / select / modal / dataTable / toast 六段各 ≥3 条可勾选要点、每条维度标签必须落在边框 / 阴影 / 过渡 / 焦点环 / 暗色五类内、合计 ≥18 条且五维度全覆盖——视觉类条目收尾前照单过一遍，改清单时别把条目删漏。
|
`ua verify` 另外校验 `ITERATION.md` 的《视觉回归抽查清单》：button / textField / select / modal / dataTable / toast 六段各 ≥3 条可勾选要点、每条维度标签必须落在边框 / 阴影 / 过渡 / 焦点环 / 暗色五类内、合计 ≥18 条且五维度全覆盖——视觉类条目收尾前照单过一遍，改清单时别把条目删漏。
|
||||||
|
|
||||||
|
|||||||
@@ -22,7 +22,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup
|
|||||||
|
|
||||||
## 可访问性约定
|
## 可访问性约定
|
||||||
|
|
||||||
- 对比度：令牌层 16 组「文字色 × 底色」在亮 / 暗 × 常规 / 高对比四套主题下都不低于 WCAG 阈值（正文 7、常规 4.5、禁用 2.6），`npm run audit:contrast` 是这条约定的门禁；系统开启「提高对比度」时边框与弱文字自动加深一档
|
- 对比度：令牌层 18 组「前景色 × 底色」在亮 / 暗 × 常规 / 高对比四套主题下都不低于 WCAG 阈值（正文 7、常规 4.5、禁用 2.6、焦点描边等非文本 3），`npm run audit:contrast` 是这条约定的门禁；系统开启「提高对比度」时边框与弱文字自动加深一档
|
||||||
- 键盘焦点：所有库内元素统一 `outline: 2px solid var(--ua-color-accent)`（focus-visible 专属，鼠标点击不出现），组件自绘的 box-shadow 光环与它叠加不冲突。
|
- 键盘焦点：所有库内元素统一 `outline: 2px solid var(--ua-color-accent)`（focus-visible 专属，鼠标点击不出现），组件自绘的 box-shadow 光环与它叠加不冲突。
|
||||||
- 关键交互都有键盘等价：Tab 进焦点、Enter/空格 激活、↑↓/Home/End 在列表类组件内移动、Esc 逐层关闭（内层先关，不连带外层）。
|
- 关键交互都有键盘等价：Tab 进焦点、Enter/空格 激活、↑↓/Home/End 在列表类组件内移动、Esc 逐层关闭（内层先关，不连带外层）。
|
||||||
- 语义与播报：modal/drawer 带 `role="dialog" aria-modal`、toast/notification/empty/result 带 `role="status"/"alert"`，切换类组件用 `aria-selected`/`aria-expanded` 同步状态。
|
- 语义与播报：modal/drawer 带 `role="dialog" aria-modal`、toast/notification/empty/result 带 `role="status"/"alert"`，切换类组件用 `aria-selected`/`aria-expanded` 同步状态。
|
||||||
|
|||||||
+3
-3
@@ -1,6 +1,6 @@
|
|||||||
# @ui-arch 组件库 Agent 文档（无图形版）
|
# @ui-arch 组件库 Agent 文档（无图形版）
|
||||||
|
|
||||||
> 自动生成于 2026-10-26T14:23:08.179Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
|
> 自动生成于 2026-10-26T14:23:51.644Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
|
||||||
> 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
|
> 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
|
||||||
|
|
||||||
## 快速上手
|
## 快速上手
|
||||||
@@ -47,7 +47,7 @@
|
|||||||
5. 收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们
|
5. 收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们
|
||||||
6. 改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）
|
6. 改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）
|
||||||
7. 改完样式跑 npm run audit:visual：各类硬编码计数不得高于 .ua/visual-baseline.json（棘轮只减不增）；字面量可用 npm run visual:migrate 幂等改写成令牌
|
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，人眼看不出但门禁看得出
|
8. 改完颜色令牌跑 npm run audit:contrast：18 组前景/底色配对在亮/暗 × 常规/高对比四套主题下都必须达标（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3），跌破即退出码 1——调一个色值就能让全站辅助文字掉到 4.4 或让焦点环糊进背景，人眼看不出但门禁看得出
|
||||||
9. 改完动效跑 npm run audit:motion：带 infinite 的动画必须在 prefers-reduced-motion 块里被关掉，悬停 / 按压的位移（translate）必须归零，缺一条即退出码 1——循环动画漏兜底会把「减少动效」用户整页交给抖动，位移漏兜底则每次悬停都在推搡前庭
|
9. 改完动效跑 npm run audit:motion：带 infinite 的动画必须在 prefers-reduced-motion 块里被关掉，悬停 / 按压的位移（translate）必须归零，缺一条即退出码 1——循环动画漏兜底会把「减少动效」用户整页交给抖动，位移漏兜底则每次悬停都在推搡前庭
|
||||||
10. 在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 传 format: md 拿到与 ua info --md 同款的 Markdown 片段
|
10. 在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 传 format: md 拿到与 ua info --md 同款的 Markdown 片段
|
||||||
|
|
||||||
@@ -2358,7 +2358,7 @@ API 速览：
|
|||||||
- ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）
|
- ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）
|
||||||
- ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
|
- ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
|
||||||
- ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）
|
- ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）
|
||||||
- ua audit:contrast [--json|--list]：对比度门禁，把令牌里 16 组「文字色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6）退出码 1；--json 出逐对明细，--list 只列配对表
|
- ua audit:contrast [--json|--list]：对比度门禁，把令牌里 18 组「前景色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）退出码 1；--json 出逐对明细，--list 只列配对表
|
||||||
- ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）
|
- ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）
|
||||||
- ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段
|
- ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段
|
||||||
|
|
||||||
|
|||||||
@@ -146,7 +146,7 @@
|
|||||||
- ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）
|
- ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）
|
||||||
- ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
|
- ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
|
||||||
- ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）
|
- ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）
|
||||||
- ua audit:contrast [--json|--list]：对比度门禁，把令牌里 16 组「文字色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6）退出码 1；--json 出逐对明细，--list 只列配对表
|
- ua audit:contrast [--json|--list]：对比度门禁，把令牌里 18 组「前景色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）退出码 1；--json 出逐对明细，--list 只列配对表
|
||||||
- ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）
|
- ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）
|
||||||
- ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段
|
- ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段
|
||||||
- 用法: `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 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`
|
||||||
|
|||||||
@@ -4,7 +4,8 @@
|
|||||||
* 改一个 --ua-color-text-muted 就能让全站辅助文字跌到 4.4，人眼在亮底上未必察觉，暗色下更看不出来。
|
* 改一个 --ua-color-text-muted 就能让全站辅助文字跌到 4.4，人眼在亮底上未必察觉，暗色下更看不出来。
|
||||||
* 这里只做四步：解析令牌 → 求值（含 color-mix 混色）→ 按固定配对表算比值 → 与阈值比对。
|
* 这里只做四步：解析令牌 → 求值（含 color-mix 混色）→ 按固定配对表算比值 → 与阈值比对。
|
||||||
* 配对表写死在代码里（而不是外置配置）：它是「设计契约」，加一条配对等于承认一种新的文字/底色组合，
|
* 配对表写死在代码里（而不是外置配置）：它是「设计契约」，加一条配对等于承认一种新的文字/底色组合，
|
||||||
* 必须在评审里看见；阈值分三档（正文 7 / 常规文字 4.5 / 禁用态 2.6）对应 WCAG AA/AAA 与豁免口径。
|
* 必须在评审里看见；阈值分三档（正文 7 / 常规文字 4.5 / 禁用态 2.6）对应 WCAG AA/AAA 与豁免口径，
|
||||||
|
* 另有一档 3 给非文本元素（焦点描边）：WCAG 1.4.11 对「关键图形与界面部件」只要求 3:1。
|
||||||
*/
|
*/
|
||||||
import fs from 'node:fs';
|
import fs from 'node:fs';
|
||||||
import path from 'node:path';
|
import path from 'node:path';
|
||||||
@@ -30,6 +31,9 @@ export const PAIRS = [
|
|||||||
{ label: '成功色 / 页面底', fg: 'success', bg: 'bg', min: 4.5 },
|
{ label: '成功色 / 页面底', fg: 'success', bg: 'bg', min: 4.5 },
|
||||||
{ label: '警告色 / 页面底', fg: 'warning', bg: 'bg', min: 4.5 },
|
{ label: '警告色 / 页面底', fg: 'warning', bg: 'bg', min: 4.5 },
|
||||||
{ label: '三级文字（禁用）/ 页面底', fg: 'text-faint', bg: 'bg', min: 2.6 },
|
{ label: '三级文字（禁用）/ 页面底', fg: 'text-faint', bg: 'bg', min: 2.6 },
|
||||||
|
// 非文本对比（WCAG 1.4.11）：焦点描边是键盘用户唯一的「我在哪」线索，阈值 3:1 而不是文字档
|
||||||
|
{ label: '焦点描边 / 页面底', fg: 'accent', bg: 'bg', min: 3 },
|
||||||
|
{ label: '焦点描边 / 表面', fg: 'accent', bg: 'surface', min: 3 },
|
||||||
];
|
];
|
||||||
|
|
||||||
/*** 作用：读文件并归一换行，保证解析稳定 ***/
|
/*** 作用：读文件并归一换行，保证解析稳定 ***/
|
||||||
|
|||||||
@@ -22,7 +22,7 @@
|
|||||||
"ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）",
|
"ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）",
|
||||||
"ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1",
|
"ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1",
|
||||||
"ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）",
|
"ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）",
|
||||||
"ua audit:contrast [--json|--list]：对比度门禁，把令牌里 16 组「文字色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6）退出码 1；--json 出逐对明细，--list 只列配对表",
|
"ua audit:contrast [--json|--list]：对比度门禁，把令牌里 18 组「前景色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）退出码 1；--json 出逐对明细，--list 只列配对表",
|
||||||
"ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）",
|
"ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）",
|
||||||
"ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段"
|
"ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段"
|
||||||
],
|
],
|
||||||
@@ -47,7 +47,7 @@
|
|||||||
"收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们",
|
"收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们",
|
||||||
"改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）",
|
"改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）",
|
||||||
"改完样式跑 npm run audit:visual：各类硬编码计数不得高于 .ua/visual-baseline.json（棘轮只减不增）；字面量可用 npm run visual:migrate 幂等改写成令牌",
|
"改完样式跑 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，人眼看不出但门禁看得出",
|
"改完颜色令牌跑 npm run audit:contrast：18 组前景/底色配对在亮/暗 × 常规/高对比四套主题下都必须达标（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3），跌破即退出码 1——调一个色值就能让全站辅助文字掉到 4.4 或让焦点环糊进背景，人眼看不出但门禁看得出",
|
||||||
"改完动效跑 npm run audit:motion：带 infinite 的动画必须在 prefers-reduced-motion 块里被关掉，悬停 / 按压的位移（translate）必须归零，缺一条即退出码 1——循环动画漏兜底会把「减少动效」用户整页交给抖动，位移漏兜底则每次悬停都在推搡前庭",
|
"改完动效跑 npm run audit:motion：带 infinite 的动画必须在 prefers-reduced-motion 块里被关掉，悬停 / 按压的位移（translate）必须归零，缺一条即退出码 1——循环动画漏兜底会把「减少动效」用户整页交给抖动，位移漏兜底则每次悬停都在推搡前庭",
|
||||||
"在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 传 format: md 拿到与 ua info --md 同款的 Markdown 片段"
|
"在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 传 format: md 拿到与 ua info --md 同款的 Markdown 片段"
|
||||||
],
|
],
|
||||||
|
|||||||
Reference in New Issue
Block a user