docs: give every token and class a unique, precise description

[jackgranatowski]

Previously 69 tokens/classes fell through to a shared section-banner
description (e.g. all eight --sf-surface-bg-* slots, every sf-exit--*
variant, the -200/-lighter and -900/-superdark colour shades), and two
theme classes had no description at all. Autocomplete hints and the
generated API reference showed identical text for distinct entries.

Add curated per-entry descriptions in docs/token-annotations.json so each
element documents what makes it distinct (its slot, direction, size, or
alias target), mirroring the already-differentiated action colour family.
Regenerate the derived artifacts (api-index, configurator data, VS Code
custom data).

Result: 0 duplicate and 0 empty descriptions across all 1064 elements.

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

Summary by CodeRabbit

• Documentation
  • Improved API and token documentation with clearer, more human-readable descriptions for colors, animations, selection states, theme utilities, layout helpers, and background/surface presets.
  • Added or expanded documentation for several token aliases and newly documented CSS properties/classes, including card, scoop, scroll, shadow, overlap, sticky, and divider-related entries.

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[coderabbitai]

Warning

Review limit reached

@jackgranatowski, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 43 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8be2c7d4-ef5c-42ca-aa0a-0d264968e5d4

📥 Commits

Reviewing files that changed from the base of the PR and between 0242982 and 5b19e54.

⛔ Files ignored due to path filters (1)

• dist/css-custom-data.json is excluded by !**/dist/**

📒 Files selected for processing (8)

• configurator/src/data/api-index.generated.json
• configurator/src/data/classes.generated.json
• demos/full-api-demo-with-overrides.html
• demos/full-api-demo.html
• demos/ultimate-override.css
• docs/api-index.json
• docs/api-index.md
• docs/token-annotations.json

📝 Walkthrough

Walkthrough

This PR regenerates documentation/description text for design tokens and utility/macro classes across generated data files (api-index.generated.json, classes.generated.json) and docs (api-index.json, api-index.md, token-annotations.json). Changes are descriptive text only, plus new token/class entries and an updated tokensHash; no code logic or structural fields change.

Changes

Token and class documentation regeneration

Layer / File(s)	Summary
Sync hash update configurator/src/data/api-index.generated.json	The _sync.tokensHash value is regenerated.
Animation preset descriptions configurator/src/data/api-index.generated.json, configurator/src/data/classes.generated.json, docs/api-index.json, docs/api-index.md	Slide-out and scroll-out exit animation token/class notes and descriptions are expanded or shortened to explicit shorthand wording.
Color palette step and alias token descriptions configurator/src/data/api-index.generated.json, docs/api-index.json, docs/api-index.md, docs/token-annotations.json	Neutral/primary/secondary/tertiary numeric-step and alias tokens (lighter, superdark, tint, etc.) get step-referenced, contrast-oriented descriptions; new variant alias entries are added in token-annotations.json.
Selection alt token descriptions configurator/src/data/api-index.generated.json, docs/api-index.json	Alt selection background/text token notes and descriptions are filled or shortened.
Corner-scoop and surface-bg macro token descriptions configurator/src/data/api-index.generated.json, docs/api-index.json, docs/api-index.md, docs/token-annotations.json	Corner-scoop mask and sf-surface-bg sub-token descriptions/notes are replaced with concise default/behavior wording; new custom properties documented.
Layout, macro, and utility class descriptions configurator/src/data/classes.generated.json, docs/api-index.json, docs/api-index.md, docs/token-annotations.json	Corner-scoop placement, divide, drop-shadow, header padding, marker color, overlap, sticky, and theme class descriptions are shortened; new class documentation entries are added.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• codeslash-dev/SLASHED#293: Prior PR added the sync-api.mjs logic that reads docs/token-annotations.json and emits the per-token notes/descriptions being regenerated here.
• codeslash-dev/SLASHED#310: Configurator API-index generation/CI sync changes produce the same configurator/src/data/api-index.generated.json file being updated.
• codeslash-dev/SLASHED#560: Both touch the sf-surface-bg token ecosystem, with this PR expanding its documented sub-token descriptions.

Suggested labels: codex

🚥 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 clearly and accurately summarizes the docs-only change to make token and class descriptions unique and precise.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/class-token-hints-descriptions-drm68q

---

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.}

[jackgranatowski]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.