SuperAPI AI 工具集

ux-guardrails

设计与创作

查看项目

更新于 10-16 03:14

技能介绍

用途:在落地页项目中安装并运行机械化的 UX 强制检查,覆盖间距是否落在网格上、禁用任意值与原始调色板、设计令牌配对的 WCAG 对比度、焦点可见性,以及套路化设计迹象(紫色渐变、渐变文字、玻璃拟态、transition: all)。不适用于选择调色板/字体/令牌、整体视觉方向、完整 WCAG 2.2 人工审计、动效设计或通用测试/格式化钩子。

主要能力:脚本 scripts/ux_lint.mjs 为单文件、零依赖 Node lint。严重度分两级:critical 客观错误并阻断,包括禁用缩放、<img> 缺 alt、outline-none 无 focus-visible 替代、正 tabindex、令牌配对低于 4.5:1;advisory 仅提示不阻断,包括偏离刻度间距、任意字号、原始调色板类、渐变文字、慢过渡。对比度仅对遵循 shadcn --x / --x-foreground 约定(含 --background/--foreground)且值可解析(hex、rgb、hsl、oklch,不支持 var() 链、color-mix、alpha)的 CSS 自定义属性计算,无法解析的静默跳过。

使用方式:复制脚本并接入两个钩子: mkdir -p .claude/hooks cp "${CLAUDE_SKILL_DIR}/scripts/ux_lint.mjs" .claude/hooks/ux_lint.mjs node .claude/hooks/ux_lint.mjs --self-test 将 PostToolUse(matcher 为 Edit|Write|MultiEdit)与 Stop 钩子合并进 .claude/settings.json,命令为 node "$CLAUDE_PROJECT_DIR/.claude/hooks/ux_lint.mjs"。可选在项目根放 .ux-guardrails.json 配置 spacingStep、contrastMin、maxFontFamilies、transitionMaxMs、ignoreRules、ignoreFiles;WCAG 下限不应通过配置放宽。CI 中可运行 node .claude/hooks/ux_lint.mjs src/ app/ styles/,critical 时退出码 1。

行为与限制:PostToolUse 只检查刚写入的文件,critical 退出 2 并将 stderr 作为修复指令,advisory 作为上下文注入;Stop 检查所有 git 变更的 UI 文件(上限 20),critical 退出 2 阻断一次,并遵守 stop_hook_active 防止循环。跨文件预算(字体族数量)仅在 Stop/CLI 运行。无 git 项目 Stop 不检查任何内容。豁免方式为行上或上方 ux-guardrails-ignore <rule-id> 注释,或配置 ignoreRules/ignoreFiles;不要通过改脚本或钩子配置来消除告警。输出格式为 file:line [SEVERITY] [rule-id] message,按文件分组,末尾给出 N critical, M advisory 预算行。完整规则目录见 references/rules.md。