feat(core): refine CSS functions for perceptual uniformity

[auswm85]

Summary

Aligned all OKLCH-based CSS functions with perceptual uniformity philosophy. Functions now use modern 2026 CSS features (color-contrast(), round()) for accurate color math and rhythm-aligned spacing.

Changes

Function	Refinement
--s-saturate	Gamut-aware with min(0.4) clamp to prevent overflow
--s-desaturate	max(0) prevents negative chroma values
--s-glow	Boosted chroma (1.3×) in inner layers for light emission effect
--s-text-shadow-glow	3-layer system with crisp 1px edge for legibility
--s-contrast-text	Native color-contrast() for true WCAG 2.2 compliance
--s-readable-on	50/50 mix ratio for stronger contrast while preserving brand hue
--s-space-scale	round() quantizes output to base unit for Bento rhythm

Philosophy Alignment

• Perceptual Uniformity: All color manipulations use OKLCH math so changes look consistent regardless of base color
• Gamut Awareness: Saturation functions clamp to prevent out-of-gamut colors
• WCAG 2.2 Compliance: color-contrast() delegates luminance calculation to browser engine
• Bento Rhythm: Spacing snaps to grid multiples, preventing sub-pixel jitter

Related Issues

N/A

Checklist

• Code follows project style guidelines
• Tests added/updated (if applicable)
• Documentation updated (if applicable)
• bun run lint passes
• bun run build succeeds

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Additional Notes

Added --s-contrast-text-fallback function for browsers without color-contrast() support. The fallback uses the 0.6 OKLCH lightness threshold approximation.

[coderabbitai]

📝 Walkthrough

Walkthrough

Makes gamut-aware adjustments to color and shadow utilities, clamps saturate/desaturate, rebuilds glow and text-shadow layers, updates contrast/readability logic (including --s-readable-on(--bg, --text) signature), and adds quantized spacing snapping. (Lines changed: +44 / -24)

Changes

Cohort / File(s)

Summary

CSS Color & Shadow Utilities packages/core/src/utils/functions.css

Adds gamut-aware clamping to --s-saturate (clamp chroma to min(0.4, c + amount)); prevents negative chroma in --s-desaturate; reworks --s-glow and --s-text-shadow-glow to use scaled/gamut-aware chroma and adjusted alphas; updates --s-contrast-text threshold and guidance for color-contrast() usage; changes --s-readable-on signature to (--bg, --text) with a 50% mixing target and revised clamp range; implements quantized spacing snap (round(nearest, calc(base * factor), base)); updates docstrings and public API signature accordingly.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat(core): add CSS functions and conditional styling utilities #42 — Modifies the same packages/core/src/utils/functions.css utilities (saturation, glow, contrast, readable-on), likely overlapping the signature and gamut-aware edits.
• feat(core): enhance dark-aware component with theming #47 — Adjusts OKLCH-based contrast/readability logic in the same utilities file, overlapping --s-contrast-text and related changes.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(core): refine CSS functions for perceptual uniformity' directly and clearly summarizes the main change—refining CSS utility functions with a focus on perceptual uniformity.
Description check	✅ Passed	The description provides comprehensive details about the CSS function refinements, including specific changes to each function, the underlying philosophy, and alignment with modern CSS features and accessibility standards.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/refine-css-functions

---

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: 1

🤖 Fix all issues with AI agents

In `@packages/core/src/utils/functions.css`:
- Around line 121-137: The fallback function --s-contrast-text-fallback uses a
0.6 OKLCH lightness threshold which is inconsistent with the [s-dark-aware]
component's 0.55 threshold; update the fallback to use 0.55 instead of 0.6 by
changing the clamp/threshold expression inside --s-contrast-text-fallback so
both --s-contrast-text-fallback and [s-dark-aware] use the same 0.55 lightness
threshold for consistent visual results across fallbacks and native
color-contrast().

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/core/src/utils/functions.css`:
- Around line 121-137: The current `@function` --s-contrast-text relies on
color-contrast(), which has no stable browser support and cannot be
feature-detected inside CSS functions (if() is Chromium-only and CSS `@supports`
works only at rule level), so change the implementation to make the fallback
reachable: either make --s-contrast-text use the logic from
--s-contrast-text-fallback as the default implementation and keep
--s-contrast-text-fallback for clarity, or keep the simple fallback in
--s-contrast-text and move any color-contrast()/contrast-color() usage into the
consumer rules using `@supports` (matching the pattern in
surface.css/button.css/badge.css) so you detect support at rule level before
applying the newer API.