Add token cleanup proposal for review

Detailed, editable proposal to reduce the --sf-* token surface (~205
tokens, ~23%) judged by real-world value for marketing/landing/business
sites. Cuts target power-user/vestigial families (fluid-pair bridge
matrix, over-provisioned alpha ramps, blur/stroke/multi-column presets,
numeric opacity scale, fluid custom slots, rare font-weights, unused
state flags). Keeps theming blocks, z-index ladder, scale knobs,
per-level heading max-width, and safe-area insets.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPiT715ntbZQjooc3JdQAH

Author: claude

TOKEN-CLEANUP-PROPOSAL.md

@@ -0,0 +1,227 @@
+# SLASHED Token Cleanup Proposal
+
+> **Purpose:** Reduce the *conceptual surface* of SLASHED's `--sf-*` token API for its real audience —
+> people building **marketing sites, landing pages, and business/corporate websites**. Bytes are not
+> the goal (gzip handles those); the goal is shrinking what an author must understand when they open
+> `core/tokens.css` or an optional bundle.
+>
+> **Decision rule:** keep a family if a landing-page / business-site builder would plausibly reach for
+> it; trim or cut it if it's power-user or vestigial (they'd inline a value or use the base scale).
+>
+> **How to use this doc:** edit the `Decision:` line on each item (`CUT` / `TRIM` / `KEEP`), adjust
+> counts or kept-subsets in the tables, and leave notes inline. Nothing here is implemented yet.
+
+- **Current surface:** ~899 `--sf-*` tokens
+- **Proposed removal:** ~205 tokens (~23%)
+- **Target after cuts:** ~695 tokens
+- **Release:** single breaking change, `0.5.47 → 0.6.0`
+- **Branch:** `claude/confident-maxwell-5dd0pa`
+
+---
+
+## Summary table
+
+| # | Family | Location | Count | Proposal | Audience need |
+|---|---|---|---|---|---|
+| 1 | Fluid-pair "bridge" matrix | `optional/tokens.sizes-extended.css` | ~130 | **TRIM** → keep ~8–10 | Very low |
+| 2 | Alpha color ramps | `optional/tokens.palette.css` | ~66 | **TRIM** → keep 5/family (~30 kept, ~36 cut) | Low–medium |
+| 3 | Blur presets | `core/tokens.css` | 5 | **CUT** | Low |
+| 4 | Stroke presets | `core/tokens.css` | 4 | **CUT** | Very low |
+| 5 | Multi-column presets | `core/tokens.css` | 6 | **CUT** | Very low |
+| 6 | Numeric opacity scale | `core/tokens.css` | 6 | **CUT** (keep `-disabled`) | Low |
+| 7 | `truncate-suffix` | `core/tokens.macros.css` | 1 | **CUT** | Minimal |
+| 8 | Unused state flags | `core/tokens.css` | 2 | **CUT** (keep `-current`/`-active`/`-dark`) | Low |
+| 9 | Rare font-weights | `core/tokens.css` | 4 | **CUT** (keep light/normal/medium/semibold/bold) | Low |
+| 10 | Fluid custom slots | `core/tokens.css` | 9 | **CUT** | Low (advanced) |
+| — | Z-index ladder + aliases | `core/tokens.css` | — | **KEEP ALL** | High |
+| — | Per-level heading max-width | `core/tokens.css` / `core/base.css` | — | **KEEP** | Medium–high |
+| — | 7 scale knobs | `core/tokens.css` | — | **KEEP** | High |
+| — | All `:root` color / theming blocks | `core/tokens.css`, `core/themes.css` | — | **KEEP** | Critical |
+| — | Safe-area insets | `core/tokens.css` | — | **KEEP** | Medium (mobile) |
+
+> Counts marked `~` are approximate and must be confirmed against the live files during
+> implementation (the generated families differ slightly between earlier scans: bridge matrix reported
+> as both ~72 and ~140; alpha as ~66).
+
+---
+
+## CUT / TRIM candidates (detailed)
+
+### 1. Fluid-pair "bridge" matrix — **TRIM**
+
+- **Location:** `optional/tokens.sizes-extended.css` (generated by `scripts/gen-sizes-extended.js`)
+- **Tokens:** the full combinatorial set `--sf-space-{step}-to-{step}` and `--sf-text-{step}-to-{step}`
+  (every pairing of scale steps fluidly interpolated across the viewport).
+- **Count:** ~130 (confirm exact)
+- **Internal consumers:** none — no core component or utility uses a specific pair.
+- **Why cut:** An author building a landing page uses the base `--sf-space-*` / `--sf-text-*` scale,
+  which is *already* fluid via `clamp()`. Nobody hand-picks `--sf-text-2xl-to-s`. An N×N menu is the
+  clearest case of concept bloat in the framework.
+- **Proposal:** keep a small curated set of common adjacent-step pairs (for fluid section spacing and
+  hero type), cut the rest. Update the generator to emit only the kept pairs.
+- **Suggested keep-list (edit freely):**
+  - `--sf-space-m-to-xl`, `--sf-space-l-to-2xl`, `--sf-space-s-to-l` (fluid section padding)
+  - `--sf-text-l-to-2xl`, `--sf-text-xl-to-3xl`, `--sf-text-2xl-to-4xl` (fluid hero/heading)
+- **Migration:** authors needing a custom pair write their own `clamp()` or import a generated extra.
+- **Decision:** `TRIM` ▢ — keep-list: ____________________
+
+### 2. Alpha color ramps — **TRIM**
+
+- **Location:** `optional/tokens.palette.css` (+ its generator)
+- **Tokens:** `--sf-color-{family}-a5 … -a95` for ~6 families (11 steps each).
+- **Count:** ~66 total → keep 5/family (~30), cut ~36.
+- **Internal consumers:** functional aliases (hover/active/subtle/muted/ghost) redirect into these
+  steps, but no rule needs the full ladder.
+- **Why trim:** real sites use ~2–3 alpha levels — a subtle tint (hover/focus ~10%), a moderate scrim
+  (~50%), a strong overlay (~80%). 11 steps is granularity nobody dials in by hand.
+- **Proposal:** keep `a5, a10, a30, a50, a80` per family; drop `a20, a40, a60, a70, a90, a95`.
+  **Re-point any functional alias** that currently targets a dropped step onto a kept step.
+- **Migration:** intermediate steps via `oklch(from var(--sf-color-x) l c h / .NN)`.
+- **Decision:** `TRIM` ▢ — keep-steps: `a5, a10, a30, a50, a80`  (edit) ____________________
+
+### 3. Blur presets — **CUT**
+
+- **Location:** `core/tokens.css:1172-1176`
+- **Tokens:** `--sf-blur-xs`, `--sf-blur-s`, `--sf-blur-m`, `--sf-blur-l`, `--sf-blur-xl` (4px–48px)
+- **Internal consumers:** none.
+- **Why cut:** glassmorphism/backdrop-blur is a trend, not a business-site need; no bundled component
+  uses it. Authors who want a frosted nav inline `backdrop-filter: blur(12px)`.
+- **Counter-argument (kept for your review):** frosted sticky navs *are* fashionable on some landing
+  pages. If you want to keep one knob, retain a single `--sf-blur` default instead of the 5-step scale.
+- **Decision:** `CUT` ▢  /  keep single `--sf-blur` ▢
+
+### 4. Stroke presets — **CUT**
+
+- **Location:** `core/tokens.css:1348-1351`
+- **Tokens:** `--sf-stroke-thin`, `--sf-stroke-regular`, `--sf-stroke-bold`, `--sf-stroke-heavy` (1–3px)
+- **Internal consumers:** none.
+- **Why cut:** SVG `stroke-width` styling is niche; authors set it on the SVG or reuse
+  `--sf-border-width-*`.
+- **Decision:** `CUT` ▢
+
+### 5. Multi-column presets — **CUT**
+
+- **Location:** `core/tokens.css:1366-1371`
+- **Tokens:** `--sf-col-width-s/m/l`, `--sf-col-rule-width-s/m/l`
+- **Internal consumers:** none.
+- **Why cut:** CSS multi-column breaks on mobile and is essentially unused in modern marketing layout
+  (Grid/Flex instead).
+- **Decision:** `CUT` ▢
+
+### 6. Numeric opacity scale — **CUT (keep `-disabled`)**
+
+- **Location:** `core/tokens.css:1178-1183` (scale) and `:482` (`--sf-opacity-disabled`)
+- **Cut:** `--sf-opacity-0/10/25/50/75/100`
+- **KEEP:** `--sf-opacity-disabled` — actively used by `core/states.css:44`, `optional/forms.css`,
+  `core/accessibility.css:107`.
+- **Why cut the scale:** authors know whether they want 0.5 or 0.3; a preset 0–100 ladder is academic.
+- **Decision:** `CUT scale / KEEP disabled` ▢
+
+### 7. `truncate-suffix` — **CUT**
+
+- **Location:** `core/tokens.macros.css:45` (default `"\2026"` = `…`)
+- **Internal consumers:** none — the `.sf-truncate` macro (`core/macros.css:100-104`) hardcodes
+  `text-overflow: ellipsis` and never reads this token.
+- **Why cut:** aspirational ellipsis-override hook nobody discovers or uses.
+- **Decision:** `CUT` ▢
+
+### 8. Unused interaction-state flags — **CUT 2 of 5**
+
+- **Location:** `core/tokens.css:278-281` (+ `--sf-is-dark:273`)
+- **Cut:** `--sf-is-pressed`, `--sf-is-open` — never set or read anywhere.
+- **KEEP:** `--sf-is-current` (drives nav "current page" styling, `core/states.css:144`),
+  `--sf-is-active` (real toggle/dropdown hook, `core/states.css:132`), `--sf-is-dark` (theming flag).
+- **Decision:** `CUT pressed+open` ▢
+
+### 9. Rare font-weights — **CUT 4 of 9 numeric**
+
+- **Location:** `core/tokens.css:924-941`
+- **Full list:** thin(100), extralight(200), light(300), normal(400), medium(500), semibold(600),
+  bold(700), extrabold(800), black(900) + semantic `body→400`, `heading→600`, `display→700`.
+- **Cut:** `thin`, `extralight`, `extrabold`, `black`.
+- **KEEP:** `light, normal, medium, semibold, bold` + the three semantic aliases.
+- **Why this split:** light (elegant hero display) and medium (buttons/labels) are common in real
+  marketing/business type even though no *bundled* component applies them; the four extremes are
+  showroom weights nobody puts on a corporate site.
+- **⚠️ Open question for you:** the author-facing scan found **`light` and `medium` are not used by any
+  bundled component** (only normal/semibold/bold/body/heading are). If you want the leanest possible
+  set, also cut `light` + `medium` (→ cut 6, keep normal/semibold/bold + semantic). Your call.
+- **Decision:** `CUT thin/extralight/extrabold/black` ▢   also cut light+medium? ▢
+
+### 10. Fluid custom slots — **CUT**
+
+- **Location:** `core/tokens.css:328-360` (`@property` regs + `:root` mirrors + 3 `clamp()` outputs)
+- **Tokens:** `--sf-fluid-custom-{1,2,3}` + `--sf-fluid-custom-{1,2,3}-{min,max}` (9 total)
+- **Internal consumers:** none — only `tests/fluid-custom.spec.js` and commented examples.
+- **KEEP the shared engine knobs** `--sf-fluid-min-vw` / `--sf-fluid-max-vw` (power the core scales).
+- **Why cut:** a "bring-your-own fluid value" power-user feature; the target author writes their own
+  `clamp()` or uses the scale. Too advanced to earn 9 tokens of surface.
+- **Side tasks:** delete `tests/fluid-custom.spec.js`; fix `--sf-fluid-custom-1` ref in
+  `configurator/tests/domains.test.js`; remove commented example in `optional/config-example.css`.
+- **Decision:** `CUT` ▢
+
+---
+
+## KEEP — re-judged as genuinely useful (do not cut)
+
+### Z-index ladder + semantic aliases — **KEEP ALL**
+- `core/tokens.css:1233-1246`. Ladder: `below(-1) base(0) raised(1) low(10) mid(100) high(500)
+  top(900) max(9999)`; aliases: `sticky/fixed/dropdown/toast/overlay`.
+- Essential mental model for nav, sticky headers, dropdowns, modals, toasts — the core of any
+  marketing/business site. *(This reverses an earlier proposal to collapse it.)*
+
+### Per-level heading max-width — **KEEP**
+- `--sf-h1-max-width … --sf-h6-max-width`, applied in `core/base.css:35-40`.
+- Controls line length for readability; per-level override is cheap and occasionally wanted.
+  *(Reverses an earlier collapse-to-one proposal.)*
+
+### 7 scale knobs — **KEEP ALL**
+- `--sf-{space,text,text-display,radius,motion,section,border}-scale` (`core/tokens.css`, all default `1`).
+- Global retuning via the configurator + 6 presets is a core value prop. Removing any would require
+  rewiring the configurator, presets, and ~50 tests.
+
+### All `:root` color / theming blocks — **KEEP (theming-critical)**
+- The `light-dark()` block (`core/tokens.css` ~498-519), the no-`light-dark()` fallback chain
+  (~256-268), and `core/themes.css` dark-mode derivations + `[data-theme="dark"]/[data-theme="light"]`
+  reassignments (~167-236) are the **sole** source of light/dark switching and per-element theming.
+  An `@property initial-value` is one static color and can't encode light-vs-dark. Only the 11 static
+  `-light` mirrors (199-209) are true duplicates, and deleting them regresses pre-`@property` browsers
+  — not worth it.
+
+### Safe-area insets — **KEEP**
+- `--sf-safe-top/bottom/left/right` (`env(safe-area-inset-*)`). Real need for sticky headers/footers
+  and bottom CTAs on notched mobile devices.
+
+---
+
+## Implementation pipeline (per cut)
+
+The repo enforces a token contract — every removal must flow through this or CI fails:
+
+1. **Edit token file(s)**; for generated families update the generator
+   (`scripts/gen-sizes-extended.js`, palette generator).
+2. **No core rewiring** for any cut here (all target families with zero internal consumers). Only grep
+   `core/` + `optional/` to confirm trimmed font-weight/opacity/state names aren't referenced first.
+3. **Regenerate:** `npm run build` (10 bundles) + `npm run docs` (rebuilds `docs/tokens.md`,
+   `docs/api-index.json`, `docs/token-index.json`, configurator data).
+4. **Update API lock:** regenerate/accept `tests/token-api.snapshot.json` (the deliberate-breakage gate).
+5. **Update consequential tests:** `tests/color-semantic.spec.js` (alpha), `tests/tokens.spec.js`,
+   delete `tests/fluid-custom.spec.js`, fix `configurator/tests/domains.test.js`.
+6. **CHANGELOG + migration:** `## [0.6.0]` ⚠️ Breaking Changes listing every removed token; upgrade
+   table in `docs/migration.md` with inline-CSS replacements.
+
+## Verification
+1. `npm run lint:css`
+2. `npm run build` (confirm token count drops in size report)
+3. `node --test tests/tier1-*.test.js tests/api-index-sync.test.js`
+4. `npx playwright test` — green in **both light and dark** (dark-mode is the theming guard)
+5. **Author-experience smoke check** — open the configurator + a sample landing page from `docs/`:
+   nav/sticky/modal z-index, headings, buttons (semibold/medium), disabled form opacity, light/dark
+   all render correctly.
+6. **Surface re-count:** `grep -rhoE -- "--sf-[a-z0-9-]+\s*:"` → expect ~899 → ~695.
+
+## Out of scope
+- Collapsing z-index or heading max-width (re-judged useful, kept).
+- The mirror cut (theming-critical, kept).
+- Precomputing the fluid engine to static `clamp()` (removes the runtime-retunable scale the
+  configurator needs; separate decision).