feat(cli): add styling.unused report to specs analyze styling

[nathanacurtis]

What

specs analyze styling now writes a third aggregate report, _analysis/styling.unused.{json|yaml}, listing every token in the fetched foundations data that no generated spec references — variables, color styles, text styles, and effect styles — with a per-category summary of total/used/unused counts.

How it works

• AnalyzeCommand resolves {alias}.variables.json / {alias}.styles.json from config.sources + dataDirectory (same pattern as GenerateCommand) and loads them via the existing loadFoundations utility. When no data files exist, the report is skipped and the other outputs are unaffected.
• Transformer contract: finalize gains an optional third parameter typed as AnalyzerFoundations — a minimal structural type in Types/Transformer.ts, so the CLI's transformer contract does not depend on specs-from-figma types.
• StylingAnalyzer builds the token universe named exactly as specs reference tokens: variables as Collection name/Variable name (mirroring FigmaVariableReference.tokenPath(), including its unresolved-collection placeholder), styles by raw name. Styles categorize FILL → colorStyles, TEXT → textStyles, EFFECT → effectStyles; GRID styles are excluded since specs never reference them. A token counts as used if any scope references its name in any category, guarding against miscategorized references producing false positives.

Docs

site/src/content/docs/cli/analyze/styling.md is restructured around the three outputs as first-class sections, each describing its collection/comparison logic. The byToken example is corrected to the real category-grouped shape (the previous example showed a flat structure that doesn't match the analyzer's output). The analyze overview page lists the new file.

Testing

• 11 new unit tests covering the unused path (naming, categorization, GRID skip, cross-category matching, dedup, summary counts, determinism, YAML variant, skip-when-absent); 409/409 CLI unit tests pass.
• Verified against specs-testing/workspaces/eg: category totals match an independent recount of the raw data (1394 collection-prefixed variables), zero overlap between used and unused sets, plausible results (146/1394 variables used, 52/55 text styles used, all gradient color styles and Thin/Thick background blurs reported unused).

🤖 Generated with Claude Code