refactor!: drop the last backward-compat token alias (pre-1.0)

[jackgranatowski]

Follow-up to #344 (merged). That PR shipped the v0.6.0 token-surface reduction; this is the one change that landed on the branch after the merge.

What

SLASHED is pre-1.0 and keeps no backward-compat aliases. This removes the last one:

• Removed --sf-color-text--on-surface — a pure compat alias (/* compat alias → base */) forwarding to --sf-color-text--on-base, with zero consumers. Use --sf-color-text--on-base.

I audited the full token graph for other naming-compat aliases — this was the only one. (The slashed.legacy layer in optional/legacy.css is browser fallbacks — dvh/scrollbar — not API aliases, so it stays. --sf-color-surface and --sf-color-text--on-base are systematic semantic tokens, kept.)

Changes

• core/tokens.css: remove the alias.
• tests/tokens.spec.js: the on-color WCAG-AA contrast check listed surface; swapped to base (both --sf-color-base and --on-base resolve).
• docs/token-annotations.json, CHANGELOG, docs/migration.md: updated; regenerated snapshot (694 → 693) and all docs/index artifacts.

Validation

• Public token surface: 693
• lint:css ✓ · check-artifacts ✓ · api-index-sync 9/9 ✓
• Playwright (chromium): tokens + token-api green; full suite was 387/387 on the source branch before the cherry-pick
• Rebuild on top of main produced no drift

🤖 Generated with Claude Code

---

Generated by Claude Code

---

Summary by cubic

Removed the pre-1.0 compat alias --sf-color-text--on-surface in favor of --sf-color-text--on-base, and updated tests/docs to reflect the change. Public token count drops from 694 to 693.

• Migration
  • Replace --sf-color-text--on-surface with --sf-color-text--on-base.

^{Written for commit 5b4c201. Summary will update on new commits.}

Summary by CodeRabbit

Breaking Changes

• Removed the deprecated --sf-color-text--on-surface token alias. Migrate to --sf-color-text--on-base.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 81b383a2-dadd-4c54-bc25-765365d545d1

📥 Commits

Reviewing files that changed from the base of the PR and between 2c897c9 and 5b4c201.

📒 Files selected for processing (14)

• CHANGELOG.md
• configurator/src/data/api-index.generated.json
• core/tokens.css
• docs/api-index.json
• docs/api-index.md
• docs/migration.md
• docs/registry.json
• docs/test-coverage-6-token-reference.html
• docs/token-annotations.json
• docs/token-index.json
• docs/token-index.md
• docs/tokens.md
• tests/token-api.snapshot.json
• tests/tokens.spec.js

💤 Files with no reviewable changes (3)

• docs/token-annotations.json
• tests/token-api.snapshot.json
• core/tokens.css

---

📝 Walkthrough

Walkthrough

The --sf-color-text--on-surface CSS token compat alias is removed from core/tokens.css. Contrast tests are updated to reference base instead of surface. All generated JSON indexes, Markdown references, and the configurator artifact are regenerated to reflect one fewer token. The breaking change is recorded in the changelog and migration guide.

Changes

Remove --sf-color-text--on-surface compat alias

Layer / File(s)	Summary
CSS token removal core/tokens.css	Removes the --sf-color-text--on-surface compat alias line; --sf-color-text--on-base remains as var(--sf-color-text).
Test and snapshot updates tests/tokens.spec.js, tests/token-api.snapshot.json	Replaces surface with base in both the contrast-measurement families array and the WCAG AA assertion FAMILIES array; removes --sf-color-text--on-surface from the token-name snapshot.
Regenerated indexes and artifacts docs/api-index.json, docs/api-index.md, docs/token-index.json, docs/token-index.md, docs/tokens.md, docs/registry.json, docs/token-annotations.json, docs/test-coverage-6-token-reference.html, configurator/src/data/api-index.generated.json	Token removed from all generated JSON and Markdown artifacts; all count fields decremented by 1.
Changelog and migration guide CHANGELOG.md, docs/migration.md	Adds a v0.6.0 breaking-change bullet for the alias removal; corrects migration table entries to show --sf-color-text--on-base as the replacement with no compat alias retained.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• codeslash-dev/SLASHED#194: Introduced or used --sf-color-text--on-surface as a rename of --sf-color-text--on-base, which this PR directly reverses by removing that compat alias.
• codeslash-dev/SLASHED#271: Added the docs/api-index.json generator pipeline whose output (docs/api-index.json) is regenerated in this PR to remove the --sf-color-text--on-surface entry.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: removing the last backward-compatibility token alias, which is the core focus of this changeset across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/drop-on-surface-compat-alias

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 14 files

_{Re-trigger cubic}