@oardi/css-utils 0.94.1 → 0.95.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oardi/css-utils",
-	"version": "0.94.1",
+	"version": "0.95.0",
 	"author": "Ardian Shala",
 	"homepage": "https://css-utils.oardi.com",
 	"description": "Powerful set of semantic css classes with support for breakpoints, directions and spacings",

package/readme.md

@@ -68,6 +68,26 @@ Responsive utilities are mobile-first. Classes without a breakpoint apply at eve
 </div>
 ```
 
+## Browser support
+
+The minimum supported versions for the compiled library CSS are:
+
+| Browser                             | Minimum version |
+| ----------------------------------- | --------------- |
+| Chrome / Edge (desktop and Android) | 122             |
+| Firefox (desktop and Android)       | 128             |
+| Safari (macOS and iOS/iPadOS)       | 18              |
+
+This feature baseline includes cascade layers, `:has()`, `color-mix()` and relative `rgb()` colors used by component states and backdrops. Older browsers and Internet Explorer are outside the support policy. Modal entry animations using `@starting-style` are a progressive enhancement; the dialog remains usable without that animation.
+
+All solid `.bg-*` utilities provide authored text colors and matching SVG fills. Theme colors use `--on-*`, surfaces use `--text-color` or `--text-inverse`, and fixed colors use black/white fallbacks selected from the Sass palette.
+
+`@supports (color: contrast-color(white))` enables automatic black/white foreground selection. Without it, `.bg-opacity-*` theme backgrounds remain **opaque** so their authored foreground stays readable, including nested backgrounds. With it, opacity and contrast against the composited backdrop are enabled. According to [MDN browser compatibility data](https://github.com/mdn/browser-compat-data/blob/main/css/types/color.json), `contrast-color()` starts at Chrome/Edge 147, Firefox 146 and Safari/iOS 26; relative RGB support establishes the lower baseline above. Feature detection determines which path runs.
+
+When overriding theme colors, keep their `--on-*` tokens in sync. When changing surfaces, update their matching text tokens. Gray fallbacks are calculated at Sass compilation time; runtime gray or black/white token overrides require checking foreground contrast and, where needed, an explicit `.text-*` utility. Explicit text utilities continue to override the automatic foreground.
+
+These versions define the support target, not a claim that every browser release is exercised in CI. Regression tests cover the compiled fallback and enhancement branches and default light/dark contrast; application integrations should also be checked in their target browsers. The SCSS package supplies no JavaScript: interactive behavior belongs to the consuming application.
+
 ## Customize the design
 
 Define overrides after the library import to adapt the global design tokens:

package/scss/components/form.scss

@@ -2,7 +2,7 @@
 	.form-control {
 		--form-control-bg-color: var(--bg-surface);
 		--form-control-border-width: var(--border-width);
-		--form-control-border-color: var(--border-color);
+		--form-control-border-color: var(--control-border-color);
 		--form-control-border-radius: var(--border-radius);
 
 		--form-control-padding-y: var(--spacer-1);
@@ -95,7 +95,7 @@
 	.form-select {
 		--form-select-bg-color: var(--bg-surface);
 		--form-select-border-width: var(--border-width);
-		--form-select-border-color: var(--border-color);
+		--form-select-border-color: var(--control-border-color);
 		--form-select-border-radius: var(--border-radius);
 
 		--form-select-padding-y: var(--spacer-1);
@@ -198,7 +198,7 @@
 
 		--form-check-input-bg-color: var(--bg-surface);
 		--form-check-input-border-width: var(--border-width);
-		--form-check-input-border-color: var(--border-color);
+		--form-check-input-border-color: var(--control-border-color);
 
 		--form-check-input-checked-bg-color: var(--primary);
 		--form-check-input-checked-border-color: var(--primary);
@@ -345,7 +345,7 @@
 
 		--form-switch-input-bg-color: var(--bg-highlight);
 		--form-switch-input-border-width: var(--border-width);
-		--form-switch-input-border-color: var(--border-color);
+		--form-switch-input-border-color: var(--control-border-color);
 		--form-switch-input-border-radius: 9999px;
 
 		--form-switch-input-checked-bg-color: var(--primary);

package/scss/utilities.scss

@@ -1,3 +1,4 @@
+@use 'sass:color';
 @use 'sass:map';
 @use './display.scss';
 @use './theme.scss' as theme;
@@ -15,6 +16,17 @@ $-widths: (
 
 $-overflow-wrap-values: normal, break-word, anywhere;
 
+// Guard the dynamic value: a var() declaration can otherwise become invalid only
+// at computed-value time, when an earlier color declaration cannot rescue it.
+@mixin -background-foreground($background, $fallback) {
+	color: $fallback;
+	fill: currentcolor;
+
+	@supports (color: contrast-color(white)) {
+		color: contrast-color($background);
+	}
+}
+
 @layer utilities {
 	// positions
 	@each $value in map.get(theme.$theme, positions) {
@@ -37,34 +49,39 @@ $-overflow-wrap-values: normal, break-word, anywhere;
 			--bg-opacity: 1;
 			--bg-opacity-backdrop: var(--#{$name});
 
-			color: contrast-color(var(--#{$name}));
-			fill: currentcolor;
-			background-color: rgb(from var(--#{$name}) r g b / var(--bg-opacity));
-
-			&:where(.bg-opacity-10, .bg-opacity-25, .bg-opacity-50, .bg-opacity-75) {
-				--bg-opacity-backdrop: inherit;
-				--bg-opacity-composite: color-mix(
-					in srgb,
-					var(--#{$name}) var(--bg-opacity-percentage),
-					var(--bg-opacity-backdrop)
-				);
-				--bg-opacity-rendered: var(--bg-opacity-composite);
-
-				color: contrast-color(var(--bg-opacity-composite));
-				fill: currentcolor;
-			}
+			background-color: var(--#{$name});
+			@include -background-foreground(var(--#{$name}), var(--on-#{$name}));
+
+			// Keep the authored foreground paired with an opaque background unless
+			// the browser can choose text against the actual translucent composite.
+			@supports (color: contrast-color(white)) {
+				background-color: rgb(from var(--#{$name}) r g b / var(--bg-opacity));
+
+				&:where(.bg-opacity-10, .bg-opacity-25, .bg-opacity-50, .bg-opacity-75) {
+					--bg-opacity-backdrop: inherit;
+					--bg-opacity-composite: color-mix(
+						in srgb,
+						var(--#{$name}) var(--bg-opacity-percentage),
+						var(--bg-opacity-backdrop)
+					);
+					--bg-opacity-rendered: var(--bg-opacity-composite);
+
+					color: contrast-color(var(--bg-opacity-composite));
+					fill: currentcolor;
+				}
 
-			:where(.bg-opacity-10, .bg-opacity-25, .bg-opacity-50, .bg-opacity-75)
-				> &:where(.bg-opacity-10, .bg-opacity-25, .bg-opacity-50, .bg-opacity-75) {
-				--bg-opacity-rendered: inherit;
-				--bg-opacity-composite: color-mix(
-					in srgb,
-					var(--#{$name}) var(--bg-opacity-percentage),
-					var(--bg-opacity-rendered)
-				);
-
-				color: contrast-color(var(--bg-opacity-composite));
-				fill: currentcolor;
+				:where(.bg-opacity-10, .bg-opacity-25, .bg-opacity-50, .bg-opacity-75)
+					> &:where(.bg-opacity-10, .bg-opacity-25, .bg-opacity-50, .bg-opacity-75) {
+					--bg-opacity-rendered: inherit;
+					--bg-opacity-composite: color-mix(
+						in srgb,
+						var(--#{$name}) var(--bg-opacity-percentage),
+						var(--bg-opacity-rendered)
+					);
+
+					color: contrast-color(var(--bg-opacity-composite));
+					fill: currentcolor;
+				}
 			}
 		}
 	}
@@ -73,18 +90,16 @@ $-overflow-wrap-values: normal, break-word, anywhere;
 		--bg-opacity: 1;
 		--bg-opacity-backdrop: var(--white);
 
-		color: contrast-color(var(--white));
-		fill: currentcolor;
 		background-color: var(--white);
+		@include -background-foreground(var(--white), var(--black));
 	}
 
 	.bg-black {
 		--bg-opacity: 1;
 		--bg-opacity-backdrop: var(--black);
 
-		color: contrast-color(var(--black));
-		fill: currentcolor;
 		background-color: var(--black);
+		@include -background-foreground(var(--black), var(--white));
 	}
 
 	@each $name, $value in map.get(theme.$theme, grays) {
@@ -92,9 +107,15 @@ $-overflow-wrap-values: normal, break-word, anywhere;
 			--bg-opacity: 1;
 			--bg-opacity-backdrop: var(--gray-#{$name});
 
-			color: contrast-color(var(--gray-#{$name}));
-			fill: currentcolor;
+			// XYZ Y is relative luminance; this threshold selects the higher
+			// black/white contrast ratio, including Sass palette overrides.
+			$fallback: var(--white);
+			@if color.channel($value, 'y', $space: xyz) > 0.1791287847 {
+				$fallback: var(--black);
+			}
+
 			background-color: var(--gray-#{$name});
+			@include -background-foreground(var(--gray-#{$name}), $fallback);
 		}
 	}
 
@@ -102,54 +123,48 @@ $-overflow-wrap-values: normal, break-word, anywhere;
 		--bg-opacity: 1;
 		--bg-opacity-backdrop: var(--bg-body);
 
-		color: contrast-color(var(--bg-body));
-		fill: currentcolor;
 		background-color: var(--bg-body);
+		@include -background-foreground(var(--bg-body), var(--text-color));
 	}
 
 	.bg-surface {
 		--bg-opacity: 1;
 		--bg-opacity-backdrop: var(--bg-surface);
 
-		color: contrast-color(var(--bg-surface));
-		fill: currentcolor;
 		background-color: var(--bg-surface);
+		@include -background-foreground(var(--bg-surface), var(--text-color));
 	}
 
 	.bg-inverse {
 		--bg-opacity: 1;
 		--bg-opacity-backdrop: var(--bg-inverse);
 
-		color: contrast-color(var(--bg-inverse));
-		fill: currentcolor;
 		background-color: var(--bg-inverse);
+		@include -background-foreground(var(--bg-inverse), var(--text-inverse));
 	}
 
 	.bg-surface-hover {
 		--bg-opacity: 1;
 		--bg-opacity-backdrop: var(--bg-surface-hover);
 
-		color: contrast-color(var(--bg-surface-hover));
-		fill: currentcolor;
 		background-color: var(--bg-surface-hover);
+		@include -background-foreground(var(--bg-surface-hover), var(--text-color));
 	}
 
 	.bg-highlight {
 		--bg-opacity: 1;
 		--bg-opacity-backdrop: var(--bg-highlight);
 
-		color: contrast-color(var(--bg-highlight));
-		fill: currentcolor;
 		background-color: var(--bg-highlight);
+		@include -background-foreground(var(--bg-highlight), var(--text-color));
 	}
 
 	.bg-active {
 		--bg-opacity: 1;
 		--bg-opacity-backdrop: var(--bg-active);
 
-		color: contrast-color(var(--bg-active));
-		fill: currentcolor;
 		background-color: var(--bg-active);
+		@include -background-foreground(var(--bg-active), var(--text-color));
 	}
 
 	.bg-opacity-10 {

package/scss/variables.scss

@@ -59,6 +59,7 @@
 
 		--border-width: 1px;
 		--border-color: var(--gray-100);
+		--control-border-color: var(--gray-550);
 
 		--border-radius-sm: 0.25rem;
 		--border-radius: 0.5rem;
@@ -68,7 +69,7 @@
 		--disabled-bg-color: var(--gray-300);
 		--disabled-border-color: var(--gray-50);
 
-		--shadow-sm: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.1);
+		--shadow-sm: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.125);
 		--shadow: 0 0.25rem 1rem rgba(0, 0, 0, 0.15);
 		--shadow-lg: 0 1rem 2rem rgba(0, 0, 0, 0.2);
 
@@ -120,6 +121,7 @@
 		--text-inverse: var(--gray-900);
 
 		--border-color: var(--gray-650);
+		--control-border-color: var(--gray-350);
 
 		--disabled-text-color: var(--gray-550);
 		--disabled-bg-color: var(--gray-750);