feat(api-freeze): pre-freeze API cleanup — token renames, grid renames, remove HSL fallbacks - #329
Merged
Merged
Conversation
|
Warning Review limit reached
More reviews will be available in 55 minutes and 20 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the 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 configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (43)
📝 WalkthroughWalkthroughThe PR executes v1.0 API freeze preparation across the SLASHED CSS framework: grid layout classes are renamed ( Changesv1.0 API Freeze Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Token consistency:
- Rename --sf-color-{family}-hover/active → --sf-color-{family}--hover/active
across core/tokens.css and optional/tokens.palette.css (double-dash
convention for state/modifier separators, matching --sf-color-border--focus)
- Update optional/forms.css to reference new --sf-color-action--hover name
Browser support gates:
- Gate light-dark() block on both light-dark() AND oklch(from): prevents
Safari 15.4–16.3 from parsing relative-color tokens with unknown syntax
- Split oklch(from) block: sign()-using tokens (text-on-color, code-text,
sf-surface auto-contrast) moved to combined gate requiring sign() support,
preventing Chrome 119–137 IACVT that made text invisible on surfaces
New public tokens:
- --sf-border-scale: 1 + calc(Npx * var(--sf-border-scale, 1)) for border widths
- --sf-breakpoint-s: 30em / --sf-breakpoint-l: 48em reference tokens
- --sf-field-radius/padding-block/padding-inline + --sf-button-radius/padding-block/padding-inline
- --sf-h1-max-width through --sf-h6-max-width (consumed by h1–h6 in base.css)
Dead token fix:
- Bind --sf-scrollbar-thumb and --sf-scrollbar-track via html { scrollbar-color }
in core/base.css
Class namespace fixes:
- Rename .sf-grid → .sf-grid-auto (+ all --fit/--xs/--s/--m/--l/--xl/--2xl/--dense modifiers)
to eliminate collision with .sf-grid-N fixed-column grids
- Rename .sf-equal → .sf-fixed-cols (+ --2/--3/--4/--6 modifiers)
to eliminate confusion with .sf-equal-height
- Update all docs (demo.html, test-coverage-*.html) and tests accordingly
New heading utility classes:
- Add .sf-h1 through .sf-h6 in optional/utilities.css, mapping to the
same --sf-h{N}-* tokens as the native heading elements
https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
… premature utility classes - Move --sf-field-* and --sf-button-* (radius, padding-block, padding-inline) from core/tokens.css to optional/tokens.components.css where component tokens belong; they remain part of the public API but load with the optional component layer, not the core - Remove .sf-h1–.sf-h6 heading utility classes from optional/utilities.css: utility and component classes are scheduled for v1.0, not v0.6.0 https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
Matches the pattern of optional/tokens.components.css — classes are defined but commented out, signalling the intended v1.0 API without shipping live code in the v0.6 cycle. https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
… borders Three public API classes had WCAG failures in Windows High Contrast Mode: - .sf-text-gradient: background-gradient is suppressed by forced-colors but color:transparent remains, making text completely invisible (IACVT). Reset background-image/clip and restore CanvasText color. - .is-loading::after: spinner active segment uses --sf-color-action which flattens to the system background in forced-colors, producing a static solid circle with no perceivable motion indicator. Override to ButtonText / Highlight so the spinning segment is visible. - button / input[type=submit|reset|button]: token-driven border-color: transparent loses the control boundary in forced-colors, rendering buttons as unbordered text blocks. Re-assert ButtonBorder to restore the visible boundary. https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
optional/tokens.components.css (1)
6-8:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate the file header comment to reflect that FIELD/BUTTON tokens now ship.
Line 6–8 still says all declarations are commented out and the file ships 0 bytes, but Lines 48–59 are active declarations. This is now misleading during maintenance and release audits.
Suggested patch
- This file is not yet complete. All token declarations below are - commented out — minified bundles ship 0 bytes from this file. + This file is not yet complete. Most token declarations below are + commented out; currently FIELD/BUTTON public tokens are active.🤖 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 `@optional/tokens.components.css` around lines 6 - 8, Update the file header comment in tokens.components.css (lines 6-8) to accurately reflect the current state of the file. The existing comment states that all token declarations are commented out and the file ships 0 bytes, but lines 48-59 contain active FIELD/BUTTON token declarations that are now included in minified bundles. Revise the header to note that the `@layer` declaration is in place AND that FIELD/BUTTON token declarations are active and shipping, rather than claiming the file still ships 0 bytes.
🤖 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.
Outside diff comments:
In `@optional/tokens.components.css`:
- Around line 6-8: Update the file header comment in tokens.components.css
(lines 6-8) to accurately reflect the current state of the file. The existing
comment states that all token declarations are commented out and the file ships
0 bytes, but lines 48-59 contain active FIELD/BUTTON token declarations that are
now included in minified bundles. Revise the header to note that the `@layer`
declaration is in place AND that FIELD/BUTTON token declarations are active and
shipping, rather than claiming the file still ships 0 bytes.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 283681e0-ff31-44ff-927c-0b105325fa91
📒 Files selected for processing (17)
core/accessibility.csscore/base.csscore/layout.csscore/macros.csscore/tokens.cssdocs/demo.htmldocs/test-coverage-2-typography.htmldocs/test-coverage-3-layout.htmldocs/test-coverage-5-forms-features.htmloptional/forms.cssoptional/overrides-example.cssoptional/tokens.components.cssoptional/tokens.palette.cssoptional/utilities.csstests/behavior.spec.jstests/demo-visual.spec.jstests/layout.spec.js
- Preview.svelte: fix --sf-color-{c}-hover/active → --hover/--active,
update .sf-grid → .sf-grid-auto and .sf-equal → .sf-fixed-cols labels
- tests/token-api.snapshot.json: update 12 hover/active token names
- docs/test-coverage-1-colors.html + demo.html: fix inline token refs
- docs/test-coverage-6-token-reference.html: update TOKENS array
- docs/token-annotations.json: rename 12 hover/active annotation keys
- docs/architecture.md: update naming-convention examples and palette
description to reflect double-dash hover/active as application slots
- docs/layout.md: .sf-equal → .sf-fixed-cols in quick-reference table
- docs/migration.md: add hover/active and grid/equal rename entries to
0.4.x→current section; add 0.3.x cross-reference note
- Regenerated: api-index.{json,md}, token-index.{json,md}, tokens.md,
classes.md, registry.json, api-index.generated.json (npm run docs)
https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
jackgranatowski
force-pushed
the
claude/issue-327-api-freeze-pp8lip
branch
from
June 14, 2026 23:22
8058ea3 to
8bbdf39
Compare
…ignment The class name now matches its internal tokens (--sf-equal-cols, --sf-equal-gap), eliminating the class/token naming mismatch introduced by the intermediate .sf-fixed-cols rename. Also fixes remaining .sf-grid → .sf-grid-auto references missed in docs/layout.md. https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
Aligns the gap token with the class namespace (.sf-equal-cols). Full set: .sf-equal-cols + --sf-equal-cols + --sf-equal-cols-gap. https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
…l-gap tokens Reverts the intermediate renames (.sf-equal → .sf-fixed-cols → .sf-equal-cols and --sf-equal-gap → --sf-equal-cols-gap). The original .sf-equal name is the clearest and most concise; the disambiguation with .sf-equal-height does not require a rename since both serve distinct roles. https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
jackgranatowski
changed the title
jackgranatowski
changed the title
These read-only reference tokens document hardcoded @container values but have no functional effect — CSS custom properties cannot be used inside @container or @media queries per spec. They added public API surface (SemVer obligation) without giving consumers real control. https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
…css) The file was never included in any bundle (not in bundle.config.json), making it an opt-in-only legacy shim for engines without light-dark() / oklch(from …). Removing it cleans up dead surface area ahead of the token-API freeze. Changes: - Delete core/tokens.color-fallbacks.css - Remove FALLBACK_FILE logic from scripts/gen-api-index.js and scripts/gen-token-index.js (hasFallback, fallbackOnly, fallback_source, buildFallbackOnlyEntries, fallbackNames) - Delete tests/tier1-p1-srgb-validity.test.js (tested HSL-only sRGB validity) - Delete tests/tier1-p3-ordering.test.js (tested fallback load order) - Delete tests/tier1-p11-overrides.test.js (tested HSL channel propagation) - Rewrite tests/tier1-p10-contrast.test.js: keep only the fast-check pure math invariant (dark text on light bg >= 4.5:1); drop HSL channel reads - Rewrite tests/tier1-p2-coverage.test.js: keep @supports-gating checks on tokens.css; drop fallback coverage and uniqueness assertions - Remove deleted tests from package.json pretest command - Remove <link> for color-fallbacks.css from README.md a la carte example - Clean up stale fallback comment from optional/legacy.css - Regenerate all generated docs (api-index, token-index, tokens.md, etc.) https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
… to .sf-grid-cols-N .sf-grid (auto-fill) stays a single-word primitive consistent with .sf-stack, .sf-cluster, .sf-sidebar etc. Modifiers restore to BEM form: .sf-grid--fit, .sf-grid--xs … .sf-grid--2xl, .sf-grid--dense. Fixed-column and ratio grids renamed from .sf-grid-N / .sf-grid-1-2 to .sf-grid-cols-N / .sf-grid-cols-1-2 — making the distinction between auto-fill (variable columns) and fixed-column (always N columns) explicit without breaking the single-word primitive pattern. Updated: core/layout.css, core/macros.css, optional/overrides-example.css, all docs HTML files, layout.md, architecture.md, migration.md, all test specs, configurator Preview.svelte, and regenerated generated docs. https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
… removal api-index-sync.test.js: - Remove fallback_only_tokens from counts assertion (field no longer exists) - Remove hasFallback / fallbackOnly column checks from token row validation tier1-p7-oldengine.test.js: - Remove dependency on core/tokens.color-fallbacks.css - Rewrite as @supports-gating check on the built bundle alone: no light-dark() / oklch(from…) / color-mix() may survive @supports stripping - Drop sRGB-value assertions (framework no longer provides sRGB fallbacks) https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
…cale - token-api.snapshot.json: add --sf-h1-max-width … --sf-h6-max-width - token-semantic.snapshot.json: --sf-border-width-1 now calc(1px * 1) due to --sf-border-scale multiplier https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
jackgranatowski
force-pushed
the
claude/issue-327-api-freeze-pp8lip
branch
from
June 15, 2026 07:23
3a100d8 to
64eb598
Compare
Three tokens added by the merged PR are now included:
- --sf-field-padding-block
- --sf-field-padding-inline
- --sf-field-radius
Sort order also corrected for --sf-color-{secondary,tertiary}--{active,hover}
which sort before -100 in ASCII order.
https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
Essential: 53.8 kB → 15.5 kB gzip Optimal: 64.9 kB → 19.5 kB gzip https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pre-freeze public API changes. All changes are documented in
docs/migration.md(0.4.x → current section).Token renames
--sf-color-{family}-hover→--sf-color-{family}--hover(double-dash BEM state separator)--sf-color-{family}-active→--sf-color-{family}--activeApplies to all 6 brand families:
primary,secondary,tertiary,action,neutral,base. Lives inoptional/tokens.palette.css;optional/forms.cssupdated to reference the new name. No back-compat alias.Tokens removed
--sf-breakpoint-s/--sf-breakpoint-l— CSS custom properties cannot be used inside@containeror@mediaquery conditions (spec limitation), making these tokens non-functional as intended.core/tokens.color-fallbacks.css(HSL fallback system) — opt-in legacy shim for engines withoutlight-dark()/oklch(from …). Was never included in any bundle (bundle.config.json). Removed along with 3 dedicated test files and allhasFallback/fallbackOnlytracking in the generator scripts.New public tokens
--sf-border-scale— border width multiplier--sf-field-radius,--sf-field-padding-block,--sf-field-padding-inline--sf-button-radius,--sf-button-padding-block,--sf-button-padding-inline--sf-h1-max-width…--sf-h6-max-widthDead token fix
Bind
--sf-scrollbar-thumband--sf-scrollbar-trackviahtml { scrollbar-color }incore/base.css(tokens were declared but never consumed).Class changes
.sf-grid— auto-fill primitive restored to single-word form, consistent with.sf-stack,.sf-cluster, etc. Modifiers are BEM:.sf-grid--fit,.sf-grid--xs … --2xl,.sf-grid--dense..sf-grid-1 / -2 / -3 / -4 / -6→.sf-grid-cols-1 / -2 / -3 / -4 / -6— fixed-column grids renamed to make the auto-fill vs fixed distinction explicit..sf-grid-1-2 / -2-1 / -1-3 / -3-1→.sf-grid-cols-1-2 / -2-1 / -1-3 / -3-1— ratio grids follow the same rename..sf-equalunchanged — stays as.sf-equalwith--sf-equal-cols/--sf-equal-gaptokens.New classes
.sf-h1….sf-h6inoptional/utilities.css— heading size utilities consuming the same--sf-h{N}-*tokens as native heading elements.Browser support gate fixes
light-dark()block on bothlight-dark()ANDoklch(from …): prevents Safari 15.4–16.3 from parsing relative-color tokens with unknown syntax.oklch(from …)block:sign()-dependent tokens (text-on-color,sf-surfaceauto-contrast) moved to a combined gate requiringsign(), fixing Chrome 119–137 IACVT that caused invisible text on surfaces.Docs & tests
docs/migration.md,docs/architecture.md,docs/layout.mdupdated.token-annotations.json, andtests/token-api.snapshot.jsonupdated.tier1-p1,tier1-p3,tier1-p11) deleted;tier1-p2andtier1-p10rewritten to only test what remains.api-index,token-index,tokens.md,classes.md,registry.json) regenerated.https://claude.ai/code/session_015fojLoqhLBDfkqFTJuSdL9