[Feature]: Detect dead CSS custom properties

[nujovich]

Which surface does this affect?

Audit / token-generation pipeline (prompts, clustering, scales)

What problem are you trying to solve?

Stylesheets accumulate --vars that nothing references anymore — leftovers from feature flags, deleted components, or renames. The audit clusters declared values but treats every --foo: … as relevant input, which inflates the proposed token set and hides the fact that some declarations are pure dead weight.

Proposed solution

Add a dead-token pass:

• Index every --custom-prop declaration in the scanned files.
• Index every var(--custom-prop) usage (including fallback chains).
• Flag declared-but-never-referenced custom properties in the audit report.
• Offer to exclude them from the generated tokens by default (CLI: implicit; playground: a "Drop unused" checkbox per cluster).

Alternatives you considered

• Running a separate tool like purgecss — focused on classes, not custom properties.
• Manual grep for each var — doesn't scale on a real codebase.

Additional context

Edge case to handle: vars that are referenced only via runtime JS (element.style.setProperty('--foo', …)). The audit doesn't see JS today, so a --keep-prefix flag (e.g. --keep-prefix=--theme-) is a reasonable escape hatch.

Sanity checks

• I searched existing issues and didn't find this proposal.
• This isn't something I could solve with existing CLI flags or playground options.