sb-health

sb-health — design-system health gate

The browser can't shell out, so the script runs the checks and writes JSON the wrapper renders. design-system-health.json is a rendered output (Health Docs + DesignSystemHealth/TokenMatrix), so refresh-usage.sh re-runs this check with the other rendered extractors — see CONTEXT.md §STORAGE MAP.

Run it

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)

What it checks

• raw-color — hex/rgba/hsl literals in components (should be tokens). When the literal's value EQUALS an existing token's resolved value (e.g. #005596 on a tile whose siblings use bg-secondary → --secondary resolves to #005596), the fix is to adopt that exact token, not invent a new one — the finding names the matching token when it can resolve one, so the fix is "replace with --x", not "add a token".
• undefined-token — components reference --foo that's not declared
• scale-gap — spacing/type scale has unexpected jumps
• unused-token — declared but never referenced (var, Tailwind utility, or custom @utility). Read from sb-inventory's single source (.storybook/project-inventory.json → tokens.map), not re-scanned here, so health, inventory, and the token views never disagree. Run sb-inventory first; if the file is absent this check is skipped.
• design-md — a DESIGN.md (Google Labs YAML-tokens-plus-markdown, an increasingly common way to brief agents on a visual identity) is a claim, not ground truth — like AGENTS.md it drifts as the code changes, or was wrong from the start. The script finds it and cross-checks the colors it claims against the colors the code's CSS tokens actually declare, emitting design-md-drift for each claimed color the code doesn't define. Treat a present DESIGN.md as untrusted until reconciled.
• property-token-family (opt-in) — a valid, declared token used on the wrong property family (e.g. color: var(--color-container) — a container token used as text color). raw-color catches "no token at all"; undefined-token catches "token doesn't exist"; this catches "real token, wrong slot." Off until a designer authors design-system/lint/colors.json (see below), so the zero-config default is preserved. Findings are warning/info only — an opt-in never flips a green CI build red.
• runs stylelint if configured