sb-health

sb-health — 设计系统健康度门禁

浏览器无法调用 Shell，因此脚本会运行检查，并写入由包装器渲染的 JSON。 design-system-health.json 是渲染后的输出（Health Docs + DesignSystemHealth/TokenMatrix），因此 refresh-usage.sh 会与其他渲染提取器一起重新运行此检查——参见 CONTEXT.md §STORAGE MAP。

运行

SKILL=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
CORE=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
"$SKILL/scripts/validate-design-system.sh"       # → .storybook/design-system-health.json
# --emit-prompt  also outputs an LLM sub-agent prompt for semantic checks
#                (naming drift, semantic-vs-presentational, scale clarity)
"$CORE/scripts/scaffold-wrapper.sh" DesignSystemHealth   # → .storybook/wrappers/ (+ icons.tsx)

# Opt-in property→token-family check (off until a designer authors the rules file):
"$SKILL/scripts/check-property-tokens.py" --init   # scaffold design-system/lint/colors.json (+ schema)

检查内容

• raw-color — 组件中的十六进制/rgba/hsl 字面值（应使用令牌）。如果字面值的值等于现有令牌解析后的值（例如，某个磁贴上使用了 #005596，而相邻磁贴使用 bg-secondary → --secondary 解析为 #005596），正确的修复方式是采用该确切令牌，而不是另造一个令牌——如果能够解析出匹配的令牌，发现项会注明该令牌，因此修复方式是“替换为 --x”，而不是“添加令牌”。
• undefined-token — 组件引用了未声明的 --foo
• scale-gap — 间距/字体比例出现意外跳跃
• unused-token — 已声明但从未引用（var、Tailwind 工具类或自定义 @utility）。 从 sb-inventory 的单一来源读取（.storybook/project-inventory.json → tokens.map）， 此处不会重新扫描，因此健康度、清单和令牌视图不会出现不一致。请先运行 sb-inventory； 如果文件不存在，则跳过此检查。
• design-md — DESIGN.md（Google Labs 的 YAML 令牌加 Markdown 格式，是一种日益常见的视觉识别说明方式，用于向 Agent 介绍视觉识别）是声明，而非事实依据——和 AGENTS.md 一样，它会随着代码变化而过时，也可能从一开始就有误。脚本会查找该文件，并将其声明的颜色与代码 CSS 令牌实际声明的颜色进行交叉核对；对于代码中未定义的每种声明颜色，都会生成 design-md-drift。在核对一致之前，请将现有的 DESIGN.md 视为不可信内容。
• property-token-family（可选启用）— 将有效且已声明的令牌用于错误的属性类别（例如，color: var(--color-container)——将容器令牌用作文本颜色）。raw-color 检查“完全没有令牌”的情况；undefined-token 检查“令牌不存在”的情况；此项检查“令牌真实存在，但用于了错误的位置”。默认关闭，只有设计师创建 design-system/lint/colors.json 后才会启用（见下文），以保留零配置默认行为。发现项仅为 warning/info——启用此项不会让绿色的 CI 构建变红。
• 如果已配置，则运行 stylelint

报告 summary（错误/警告/信息计数）和主要发现项。DesignSystemHealth 包装器使用共享图标集渲染严重性（不使用 emoji）。

脚本写入的 JSON（结构——读取这些字段，不要重新推导）。每条发现项的格式为 {kind, severity, message, file?, line?, fix?}；summary 汇总各项计数：

{
  "findings": [
    { "kind": "raw-color",       "severity": "error",   "file": "Button.tsx", "line": 42, "message": "#3b82f6 literal", "fix": "use --color-primary" },
    { "kind": "undefined-token", "severity": "error",   "file": "Card.tsx",   "line": 11, "message": "--surface-2 not declared" },
    { "kind": "design-md-drift", "severity": "warning", "message": "DESIGN.md claims #1e90ff; no token declares it" },
    { "kind": "unused-token",    "severity": "info",    "message": "--legacy-accent declared, never referenced" },
    { "kind": "scale-gap",       "severity": "info",    "message": "spacing jumps 16px → 48px" },
    { "kind": "property-token-family", "severity": "warning", "file": "Card.css", "line": 3, "message": "background uses --color-content — not allowed for 'background*' (expects --color-container / --color-canvas)", "fix": "Use one of --color-container, --color-canvas, or remap with /* color-lint-alias: … */" }
  ],
  "summary": { "total": 6, "errors": 2, "warnings": 2, "info": 2, "checksRun": ["raw-color", "undefined-token", "..."] }
}

属性→token 系列规则（选择启用，由设计师管理）

哪些 token 系列应当用于哪些属性，这套逻辑属于设计意图，因此应放在设计师可编辑的规则文件中，而不是写进脚本。规则由设计师管理；检查器由开发者管理。只需初始化一次（会同时写入规则文件和 JSON Schema，方便在任何编辑器中查看说明）：

"$SKILL/scripts/check-property-tokens.py" --init    # → design-system/lint/colors.json (+ colors.schema.json)

// design-system/lint/colors.json — owned by the designer
{
  "$schema": "./colors.schema.json",
  "propertyTokens": {
    "color":       ["--color-content"],                                   // exact property
    "background*": ["--color-container", "--color-canvas", "--color-backdrop"], // family (trailing *)
    "box-shadow":  ["--color-border", "--color-shadow"],
    "border*":     ["--color-border"]                                     // values are token PREFIXES
  }
}

仅列出的属性受规则约束（每次选择启用一个属性）。按优先顺序排列的变通方式——两者都从源文件中读取：

/* color-lint-alias: --color-theme --color-container */  /* file-level prefix remap: a token is
                                                            semantically right but lives in the "wrong"
                                                            family — treat this prefix as that one */
color: var(--color-theme-fg); /* color-lint-ignore */    /* per-line suppression — counted, and the
                                                            report nudges a refactor past 10. The number
                                                            growing is the signal: mute fast, fix slowly. */

规则文件本身是一种声明，而非事实依据（与 DESIGN.md 的立场相同）：如果某条规则允许的 token 前缀与任何已声明的 token 都不匹配，脚本就会发出 property-rules-drift，避免过时配置悄无声息地通过检查或误报。

分类处理顺序——严重性才是判定依据，而不是数量：先修复 error（raw-color → 映射到现有 token；undefined-token → 声明该 token 或修正拼写错误），再协调处理 warning（design-md-drift → 交由 design-md 处理；property-token-family → 换用允许的 token，或者如果该 token 确实正确，则添加 color-lint-alias；property-rules-drift → 修正规则文件），并按原样报告 info（unused-token / scale-gap / property-lint-suppressions 都是需要核实的信号，绝不可自动修复——见下文“切勿”）。有 0 个错误和 20 条 info 发现的仓库仍然健康。

切勿（以及容易忽略的原因）

• 切勿一看到 unused-token 就删除——它属于 info，不是 error。静态扫描无法识别 Tailwind 工具类（bg-[--brand]）所使用的 token、通过字符串拼接构造的运行时 var()，或单体仓库中其他应用所使用的 token。“未使用”意味着“我没找到引用”，而不是“可以安全删除”。
• 切勿把 scale-gap 当作必须修复的失败项——它属于 info。实际的比例尺存在有意设置的间隔（例如远高于正文尺寸的展示尺寸）；“平滑”这些间隔会凭空创造没人要求的 token，还会破坏设计师选择的节奏。
• 切勿把 DESIGN.md 当作事实依据——它和 AGENTS.md/CLAUDE.md 一样，只是一种声明，会逐渐偏离实际情况。应先根据 design-md-drift 进行协调；未经协调的 DESIGN.md 会言之凿凿地描述代码中并未定义的颜色。
• 切勿通过发明新 token 来“修复” raw-color——应将其映射到现有 token。每个字面颜色值都新建一个 token，只会把混乱转移到 token 层（下次运行时会出现更多 undefined-token 提示）。
• 切勿通过重新 grep 手动重新计算这份 JSON——浏览器无法调用 shell 命令，因此脚本是唯一数据源；请引用其中的字段。凭目测重新推算只会导致计数与包装器呈现的内容不一致。

何时延后处理

对于提取（将混乱的代码库整理为 token 和组件），此技能只负责测量。 若要实际执行提取，请运行 /ds-runbook → /ds-audit → /ds-token-extract → /ds-component-extract，然后回到这里验证健康状况，并前往 sb-stories 进行捕获。

如果 DESIGN.md 已经偏离实际情况（或需要根据代码中真实的 token 编写或重新生成该文件），请交由 design-md 技能处理——它能够编排、提取并深度审计 Google Labs 的 DESIGN.md 格式。sb-health 只会标记偏差；design-md 会协调差异或重写设计说明。

下一步

如果健康状况较差且项目正处于转型期，请先修复 token（或转交给 ds-* 技能），再编写故事。否则，追加一条发现，然后继续前往 sb-stories。