docs: pre-freeze API audit (audit-b) for v0.3.0

[kiro-agent]

This pull request was created by @kiro-agent on behalf of @jackgranatowski 👻

Comment with /kiro fix to address specific feedback or /kiro all to address everything.
_{Learn about Kiro autonomous agent}

---

Summary

Full public API audit of the SLASHED framework v0.3.0, performed before the API freeze.

The audit covers all 7 categories (A-G) from the audit checklist:

• A. Tokens - declaration vs usage consistency, hardcoded values, alias chains
• B. Naming - size modifier scales, state naming, prefix conventions, keyframe/token parity
• C. Classes - demo coverage, size scale completeness, animation classes, !important usage
• D. Cascade layers - layer declarations vs files, correct layer assignment, override semantics
• E. Bundle - layers.css first-file requirement, export paths, flat bundle correctness
• F. Documentation - tokens.md sync, states.md sync, layout.md/macros.md gaps, dead references
• G. API freeze specifics - PUBLIC/INTERNAL contract, palette dependencies, theme-example alignment

Results

• 0 breaking issues (🔴) - API is consistent and ready for freeze
• 15 API hygiene issues (🟠) - recommended fixes before freeze
• Several minor/docs issues (🟡) - low priority

Top clusters:

1. Hardcoded values (opacity, z-index, aspect-ratio, duration) that should use existing tokens
2. Missing animation tokens for sf-spin / sf-shimmer
3. Undocumented classes: sf-icon--boxed, sf-surface--*, sf-text-gradient, sf-link-external
4. Dead comment references to removed audits/ directory
5. --sf-lumlocker not classified in the PUBLIC/INTERNAL contract