Refactor palette color-mix percentages into reusable tokens

[jackgranatowski]

Summary

Extracted hardcoded color-mix percentages from palette token definitions into a new set of reusable --sf-palette-mix-* tokens. This enables global ramp shape adjustments without editing individual palette tokens.

Key Changes

• New palette mix tokens (optional/tokens.palette.css):

  • Added 10 new PUBLIC-ADVANCED tokens: --sf-palette-mix-50, --sf-palette-mix-100, --sf-palette-mix-200, --sf-palette-mix-300, --sf-palette-mix-400, --sf-palette-mix-600, --sf-palette-mix-700, --sf-palette-mix-800, --sf-palette-mix-900, --sf-palette-mix-950
  • Each token holds a percentage value (4%, 8%, 20%, 40%, 65%, 82%, 62%, 38%, 18%, 8%)

• Refactored palette definitions:

  • Updated all 6 brand families (primary, action, success, warning, error, base) to use var(--sf-palette-mix-*) instead of hardcoded percentages in color-mix() expressions
  • Affects ~60 palette tokens across tint (50-400) and shade (600-950) steps

• Removed color-fallback bundles:

  • Removed core/tokens.color-fallbacks.css from optimal bundle configuration in bundle.config.json
  • Cleared bundle arrays for fallback tokens in API index

• Documentation updates:

  • Added theming guide section on per-surface color control
  • Updated token counts: 841 tokens (up from 831), 903 PUBLIC tokens (up from 893)
  • Added comments explaining the new palette mix override pattern

Implementation Details

The new tokens enable users to reshape the entire color ramp globally by overriding a single set of percentages:

:root {
  --sf-palette-mix-200: 30%;  /* Spread tints wider */
  --sf-palette-mix-300: 55%;
}

This change propagates across all 6 brand families simultaneously, providing a powerful customization point without requiring per-token overrides. The tokens are marked PUBLIC-ADVANCED to indicate they're powerful but niche.

Token counts increased by 10 (new mix tokens) and palette token category increased from 132 to 142.

https://claude.ai/code/session_01SykDjAVz3XdqzcrL1MzZoc

Summary by CodeRabbit

• New Features

  • Added new palette mix control variables (--sf-palette-mix-*) enabling customization of color ramp intensities.
  • Added focus ring and caret color tokens tied to surface variants.

• Improvements

  • Updated framework to version 0.5.31.
  • Enhanced per-surface theming with automatic background and text color application.
  • Improved responsive layout container query handling.

• Documentation

  • Expanded contrast threshold documentation with usage examples and workarounds.
  • Updated theming guide with per-surface color control and contrast guarantee details.

[coderabbitai]

Warning

Review limit reached

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

More reviews will be available in 44 minutes and 33 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

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.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 09c8a56d-50e0-4dce-ad3e-33f40563bebe

📥 Commits

Reviewing files that changed from the base of the PR and between 88ed94a and bd52e45.

📒 Files selected for processing (12)

• configurator/src/data/api-index.generated.json
• core/tokens.css
• docs/api-index.json
• docs/api-index.md
• docs/theming.md
• docs/token-index.json
• docs/token-index.md
• docs/tokens.md
• optional/tokens.palette.css
• scripts/token-tiers.js
• tests/tier1-p3-ordering.test.js
• tests/tier1-p7-oldengine.test.js

📝 Walkthrough

Walkthrough

This pull request introduces a palette ramp customization system via new --sf-palette-mix-* knob tokens, refactors six color families to use these knobs instead of hardcoded percentages, adds derived focus and caret color properties to all surface variants, improves theme and layout support, and removes legacy color fallbacks from bundle outputs.

Changes

Palette Mix and Surface Enhancement

Layer / File(s)	Summary
Palette mix control tokens optional/tokens.palette.css, configurator/src/data/api-index.generated.json, docs/api-index.json, docs/token-index.json, docs/registry.json, tests/token-api.snapshot.json	Introduces new public --sf-palette-mix-{50,100,200,300,400,600,700,800,900,950} CSS variables that define the blend percentages used by palette ramps, registered across all API indexes and test snapshots.
Palette ramp refactoring optional/tokens.palette.css, configurator/src/data/api-index.generated.json, docs/api-index.json, docs/api-index.md, docs/token-index.json, docs/token-index.md, docs/tokens.md	Refactors color-mix expressions across action, base, neutral, primary, secondary, and tertiary families to use the new var(--sf-palette-mix-*) knobs instead of hardcoded percentages, applied consistently across the CSS source and all generated documentation.
Surface focus and caret color derivations core/macros.css	Adds --sf-focus-ring-color and --sf-caret-color derived custom properties to .sf-surface and all .sf-surface--* variants, computing them from surface-contrast or the on-color text for each variant; fixes --sf-surface-contrast to explicitly enforce full opacity.

Bundle Configuration and Fallback Cleanup

Layer / File(s)	Summary
Remove color fallbacks from bundles bundle.config.json, configurator/src/data/api-index.generated.json, docs/api-index.json	Removes core/tokens.color-fallbacks.css from eight bundle output configurations and clears the bundles array for all legacy HSL fallback tokens across action, base, danger, error, info, neutral, primary, secondary, success, tertiary, and warning families.

Theming and Layout Documentation

Layer / File(s)	Summary
Theme support and layout container queries core/themes.css, core/layout.css, docs/api-index.json, docs/api-index.md	Adds explicit background and text color resets for [data-theme] elements that are not :root or html, and documents container-query breakpoints (XS/S/L) for .sf-alternate, .sf-grid-*, and .sf-bento layout classes.
Theming and contrast documentation core/tokens.css, docs/api-index.md, docs/theming.md	Expands inline documentation for --sf-contrast-threshold contrast-selection logic and adds new sections on per-surface color control, contrast guarantee limitations in the OKLCH mid-luminance band, and future CSS contrast-color() migration path.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• codeslash-dev/SLASHED#154: Introduces usage of --sf-focus-ring-color in focus outline rules, complementing this PR's derivation of that token in surface macros.
• codeslash-dev/SLASHED#25: Modifies palette tint/shade logic in optional/tokens.palette.css to change mix anchors, directly overlapping with this PR's palette ramp refactoring.
• codeslash-dev/SLASHED#188: Implements section-level [data-theme] handling in core/themes.css for consistent subtree theming, building on the same feature as this PR.

🚥 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 PR title 'Refactor palette color-mix percentages into reusable tokens' clearly and specifically summarizes the main objective—extracting hardcoded percentages into reusable CSS tokens—which aligns with the core changes across all modified files.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/dazzling-davinci-l3qzm4

---

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

[coderabbitai]

Actionable comments posted: 6

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

docs/api-index.json (1)

18348-18447: ⚠️ Potential issue | 🟠 Major

Fix incorrect token descriptions for safe-area inset tokens in docs/api-index.json.
--sf-safe-bottom, --sf-safe-left, --sf-safe-right, and --sf-safe-top (values are env(safe-area-inset-*, 0px)) have the description copied from --sf-contrast-threshold (“Lightness crossover for text-on-color auto-contrast…”), which is unrelated to safe-area insets.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/api-index.json` around lines 18348 - 18447, The four token entries
--sf-safe-bottom, --sf-safe-left, --sf-safe-right, and --sf-safe-top in
docs/api-index.json currently have an incorrect description copied from
--sf-contrast-threshold; locate those token objects and replace the description
text with an accurate one describing safe-area insets (e.g., "Safe area inset
for bottom/left/right/top to account for device notches and UI safe areas;
defaults to env(safe-area-inset-*, 0px)"). Ensure each token's description
matches its name (bottom/left/right/top) and reflects that the value defaults to
env(safe-area-inset-*, 0px).

docs/token-index.json (1)

2024-2032: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Primary ramp still hardcodes mix percentages at Line 2031 and Line 2058.

--sf-color-primary-400 and --sf-color-primary-600 still use 65%/82% literals while the rest of the palette ladder uses --sf-palette-mix-*. This leaves primary partially non-overridable and defeats the new global mix-knob behavior.

Suggested fix

-      "value": "color-mix(in oklab, var(--sf-color-primary) 65%, var(--sf-color-surface))"
+      "value": "color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-400), var(--sf-color-surface))"

-      "value": "color-mix(in oklab, var(--sf-color-primary) 82%, var(--sf-color-text))"
+      "value": "color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-600), var(--sf-color-text))"

Also applies to: 2051-2059

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/token-index.json` around lines 2024 - 2032, The primary ramp entries
--sf-color-primary-400 and --sf-color-primary-600 currently hardcode mix
percentages (65% and 82%); replace those literal percentages in their "value"
expressions with the corresponding palette mix variables (e.g. use
var(--sf-palette-mix-400) for --sf-color-primary-400 and
var(--sf-palette-mix-600) for --sf-color-primary-600) so they follow the same
overridable mix-knob pattern used by the rest of the palette; update both
occurrences mentioned (the 400 and 600 entries) to use the var(...) references
instead of numeric literals.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/api-index.md`:
- Around line 707-710: Replace the hardcoded mix percentages in the primary ramp
so the ramp is fully configurable: in the table entries for
`--sf-color-primary-400` and `--sf-color-primary-600` (currently using `65%` and
`82%`), swap those literal percentages for the corresponding knob variables
`var(--sf-palette-mix-400)` and `var(--sf-palette-mix-600)` so the
`color-mix(...)` expressions use the palette mix variables instead of fixed
values.
- Around line 440-443: The descriptions for the tokens `--sf-safe-bottom`,
`--sf-safe-left`, `--sf-safe-right`, and `--sf-safe-top` are incorrect (they
currently describe contrast thresholds); replace each description with a concise
safe-area inset description (e.g., "Device safe-area inset for
bottom/left/right/top; value uses env(safe-area-inset-*, 0px) and defaults to
0px") and ensure the example value remains `env(safe-area-inset-*, 0px)`; also
fix the docs generator mapping that assigns descriptions so tokens whose names
start with `--sf-safe-` map to a safe-area inset description rather than the
contrast-threshold template.
- Around line 770-779: The table rows for the palette-mix tokens (e.g.,
`--sf-palette-mix-50`, `--sf-palette-mix-100`, `--sf-palette-mix-200`, ...,
`--sf-palette-mix-950`) have mismatched tier data: the Tier column shows
`PUBLIC` but the description begins with `PUBLIC-ADVANCED`; update either the
Tier column to `PUBLIC-ADVANCED` or change the description prefix to `PUBLIC` so
both metadata and description match for each `--sf-palette-mix-*` entry, keeping
the descriptive text otherwise unchanged.

In `@docs/theming.md`:
- Around line 229-233: The example exposes an internal token
(--sf-surface-contrast) that core/macros.css marks as internal; remove or
replace the .my-card.sf-surface snippet so docs do not instruct consumers to
override --sf-surface-contrast. Instead, demonstrate using a supported public
token or macro (for example show overriding --sf-surface-color or using the
public theming API/macro for surface color) and update the example to reference
.sf-surface and the public token (--sf-surface-color) rather than the internal
--sf-surface-contrast.

In `@docs/token-index.md`:
- Around line 389-392: Update the two primary ramp tokens so they consume the
palette mix knob variables instead of hardcoded percentages: replace the
hardcoded `65%` in `--sf-color-primary-400` with `var(--sf-palette-mix-400)` and
replace the hardcoded `82%` in `--sf-color-primary-600` with
`var(--sf-palette-mix-600)` (ensure you update both locations where
`--sf-color-primary-400` and `--sf-color-primary-600` are defined so they match
how other families use `var(--sf-palette-mix-XXX)`).

In `@optional/tokens.palette.css`:
- Around line 72-74: The primary palette entries --sf-color-primary-400 and
--sf-color-primary-600 were left with literal mix percentages (65% and 82%);
change their color-mix calls to use the shared ramp variables
--sf-palette-mix-400 and --sf-palette-mix-600 respectively (keeping the same
color operands var(--sf-color-primary) with var(--sf-color-surface) for 400 and
var(--sf-color-primary) with var(--sf-color-text) for 600) so they follow the
same global ramp-shape override behavior as the other families.

---

Outside diff comments:
In `@docs/api-index.json`:
- Around line 18348-18447: The four token entries --sf-safe-bottom,
--sf-safe-left, --sf-safe-right, and --sf-safe-top in docs/api-index.json
currently have an incorrect description copied from --sf-contrast-threshold;
locate those token objects and replace the description text with an accurate one
describing safe-area insets (e.g., "Safe area inset for bottom/left/right/top to
account for device notches and UI safe areas; defaults to env(safe-area-inset-*,
0px)"). Ensure each token's description matches its name (bottom/left/right/top)
and reflects that the value defaults to env(safe-area-inset-*, 0px).

In `@docs/token-index.json`:
- Around line 2024-2032: The primary ramp entries --sf-color-primary-400 and
--sf-color-primary-600 currently hardcode mix percentages (65% and 82%); replace
those literal percentages in their "value" expressions with the corresponding
palette mix variables (e.g. use var(--sf-palette-mix-400) for
--sf-color-primary-400 and var(--sf-palette-mix-600) for --sf-color-primary-600)
so they follow the same overridable mix-knob pattern used by the rest of the
palette; update both occurrences mentioned (the 400 and 600 entries) to use the
var(...) references instead of numeric literals.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 359ce941-f472-488d-854e-eab2c15f8282

📥 Commits

Reviewing files that changed from the base of the PR and between 99ec385 and 88ed94a.

⛔ Files ignored due to path filters (1)

• dist/badge-essential.json is excluded by !**/dist/**

📒 Files selected for processing (15)

• bundle.config.json
• configurator/src/data/api-index.generated.json
• core/layout.css
• core/macros.css
• core/themes.css
• core/tokens.css
• docs/api-index.json
• docs/api-index.md
• docs/registry.json
• docs/theming.md
• docs/token-index.json
• docs/token-index.md
• docs/tokens.md
• optional/tokens.palette.css
• tests/token-api.snapshot.json

💤 Files with no reviewable changes (1)

• bundle.config.json