css-utility-functions 1.0.1

package/dist/index.css

@@ -0,0 +1,897 @@
+/**
+ * CSS Utility Functions
+ *
+ * A collection of reusable CSS custom functions using the @function syntax.
+ * Import this file to use all utility functions in your project.
+ *
+ * ⚠️ Note: CSS @function is experimental. Check browser support before production use.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/@function
+ */
+
+/* Color Utilities */
+
+/**
+ * --alpha() — Color Transparency
+ *
+ * Creates a semi-transparent version of any color.
+ * Works exactly like CSS opacity property:
+ * - 0 = fully transparent (invisible)
+ * - 1 = fully opaque (solid)
+ * - 0.5 = 50% opaque (50% transparent)
+ *
+ * @param {color} --color - The base color
+ * @param {number} --opacity - Opacity level (0-1), default: 0.5
+ *   Higher values = more opaque, lower values = more transparent
+ * @returns {color} - Color with applied opacity
+ *
+ * @example
+ * .overlay {
+ *   background: --alpha(#6366f1, 0.2);  // 20% opaque, 80% transparent
+ * }
+ * .backdrop {
+ *   background: --alpha(var(--brand), 0.85);  // 85% opaque, 15% transparent
+ * }
+ */
+
+@function --alpha(--color <color>, --opacity <number>: 0.5) returns <color> {
+  result: oklch(from var(--color) l c h / var(--opacity));
+}
+
+/**
+ * --lighten() — Color Luminance Increase
+ *
+ * Adjust a color's lightness upward.
+ * Uses OKLCH lightness channel (0-1 range).
+ *
+ * @param {color} --color - The base color
+ * @param {number} --amount - Amount to lighten (0-1, e.g., 0.1 = 10%, 0.2 = 20%), default: 0.1
+ * @returns {color} - Lightened color
+ *
+ * @example
+ * .btn:hover {
+ *   background: --lighten(var(--btn-bg), 0.15);
+ * }
+ */
+
+@function --lighten(--color <color>, --amount <number>: 0.1) returns <color> {
+  result: oklch(from var(--color) calc(l + var(--amount)) c h);
+}
+
+/**
+ * --darken() — Color Luminance Decrease
+ *
+ * Adjust a color's lightness downward.
+ * Uses OKLCH lightness channel (0-1 range).
+ *
+ * @param {color} --color - The base color
+ * @param {number} --amount - Amount to darken (0-1, e.g., 0.1 = 10%, 0.2 = 20%), default: 0.1
+ * @returns {color} - Darkened color
+ *
+ * @example
+ * .btn:active {
+ *   background: --darken(var(--btn-bg), 0.1);
+ * }
+ */
+
+@function --darken(--color <color>, --amount <number>: 0.1) returns <color> {
+  result: oklch(from var(--color) calc(l - var(--amount)) c h);
+}
+
+/**
+ * --saturate() — Color Saturation Increase
+ *
+ * Adjust a color's chroma (saturation) intensity upward.
+ *
+ * @param {color} --color - The base color
+ * @param {number} --amount - Percentage as decimal (e.g., 0.4 = 40%), default: 0.2
+ * @returns {color} - More saturated color
+ *
+ * @example
+ * .vibrant {
+ *   background: --saturate(var(--primary), 0.4);
+ * }
+ */
+
+@function --saturate(
+  --color <color>,
+  --amount <number>: 0.2
+) returns <color> {
+  result: oklch(from var(--color) l calc(c + c * var(--amount)) h);
+}
+
+/**
+ * --desaturate() — Color Saturation Decrease
+ *
+ * Adjust a color's chroma (saturation) intensity downward.
+ *
+ * @param {color} --color - The base color
+ * @param {number} --amount - Percentage as decimal (e.g., 0.5 = 50%), default: 0.2
+ * @returns {color} - Less saturated (more muted) color
+ *
+ * @example
+ * .muted {
+ *   color: --desaturate(var(--text), 0.5);
+ * }
+ */
+
+@function --desaturate(
+  --color <color>,
+  --amount <number>: 0.2
+) returns <color> {
+  result: oklch(from var(--color) l calc(c - c * var(--amount)) h);
+}
+
+/**
+ * --mix() — Color Mixing
+ *
+ * Blend two colors by a given percentage.
+ *
+ * @param {color} --color1 - First color
+ * @param {color} --color2 - Second color
+ * @param {percentage} --weight - Weight of first color, default: 50%
+ * @returns {color} - Mixed color
+ *
+ * @example
+ * .gradient-mid {
+ *   background: --mix(var(--start), var(--end), 50%);
+ * }
+ * .tinted {
+ *   background: --mix(white, var(--brand), 90%);
+ * }
+ */
+
+@function --mix(
+  --color1 <color>,
+  --color2 <color>,
+  --weight <percentage>: 50%
+) returns <color> {
+  result: color-mix(in oklch, var(--color1) var(--weight), var(--color2));
+}
+
+/**
+ * --contrast-text() — Auto Contrast Text Color
+ *
+ * Returns black or white depending on background luminance for optimal readability.
+ * Uses a mathematical approach with OKLCH lightness.
+ *
+ * @param {color} --bg - Background color
+ * @returns {color} - Black or white based on luminance
+ *
+ * @example
+ * .badge {
+ *   background: var(--badge-color);
+ *   color: --contrast-text(var(--badge-color));
+ * }
+ */
+
+@function --contrast-text(--bg <color>) returns <color> {
+  result: oklch(from var(--bg) calc((0.6 - l) * infinity) 0 0);
+}
+
+/**
+ * --grayscale() — Grayscale Conversion
+ *
+ * Convert any color to grayscale by removing chroma (saturation).
+ * Uses OKLCH color space, setting chroma to 0 while preserving lightness.
+ *
+ * @param {color} --color - The base color
+ * @returns {color} - Grayscale version of the color
+ *
+ * @example
+ * .monochrome {
+ *   background: --grayscale(#6366f1);  // Blue becomes gray
+ * }
+ * .desaturated-image {
+ *   filter: --grayscale(var(--image-color));
+ * }
+ */
+
+@function --grayscale(--color <color>) returns <color> {
+  result: oklch(from var(--color) l 0 h);
+}
+
+/**
+ * --invert() — Color Inversion
+ *
+ * Invert a color by flipping its lightness in OKLCH space.
+ * Dark colors become light, light colors become dark.
+ *
+ * @param {color} --color - The base color
+ * @returns {color} - Inverted color
+ *
+ * @example
+ * .inverted {
+ *   background: --invert(#ffffff);  // White becomes black
+ * }
+ * .dark-mode-text {
+ *   color: --invert(var(--light-text));
+ * }
+ */
+
+@function --invert(--color <color>) returns <color> {
+  result: oklch(from var(--color) calc(1 - l) c h);
+}
+
+/**
+ * --complement() — Complementary Color
+ *
+ * Get the complementary color (opposite on color wheel) by rotating hue 180 degrees.
+ * Uses OKLCH color space for accurate hue rotation.
+ * Note: Achromatic colors (grays) have no hue, so their complement is unchanged.
+ *
+ * @param {color} --color - The base color
+ * @returns {color} - Complementary color
+ *
+ * @example
+ * .accent {
+ *   background: --complement(#6366f1);  // Blue's complement (orange)
+ * }
+ * .contrast-border {
+ *   border-color: --complement(var(--primary));
+ * }
+ */
+
+@function --complement(--color <color>) returns <color> {
+    result: oklch(from var(--color) l c calc(h + 180));
+}
+
+/* Spacing & Sizing */
+
+/**
+ * --space() — Spacing Scale
+ *
+ * Returns spacing based on a consistent multiplier scale.
+ * The base unit can be customized via the --space-base CSS custom property.
+ *
+ * @param {number} --multiplier - Scale multiplier
+ * @param {length} --base - Base spacing unit, default: var(--space-base, 0.25rem)
+ * @returns {length} - Calculated spacing
+ *
+ * @example
+ * :root {
+ *   --space-base: 0.25rem;
+ * }
+ *
+ * .card {
+ *   padding: --space(4);
+ *   margin-bottom: --space(6);
+ *   gap: --space(2);
+ * }
+ *
+ * .special {
+ *   padding: --space(4, 0.5rem);
+ * }
+ */
+
+@function --space(--multiplier <number>, --base <length>: var(--space-base, 0.25rem)) returns <length> {
+  result: calc(var(--base) * var(--multiplier));
+}
+
+/**
+ * --fluid() — Fluid Viewport-Based Sizing
+ *
+ * Generates a clamp() value that scales smoothly between viewport widths.
+ * Use this for global, viewport-dependent responsive sizing.
+ *
+ * @param {length} --min - Minimum size
+ * @param {length} --max - Maximum size
+ * @param {length} --min-vw - Minimum viewport width, default: 375px
+ * @param {length} --max-vw - Maximum viewport width, default: 1440px
+ * @returns {length} - Fluid clamp value based on viewport width
+ *
+ * @example
+ * h1 {
+ *   font-size: --fluid(1.5rem, 4rem);
+ * }
+ * .container {
+ *   padding: --fluid(1rem, 3rem, 320px, 1200px);
+ * }
+ *
+ * @see --fluid-container() for container-based fluid sizing
+ */
+
+@function --fluid(
+  --min <length>,
+  --max <length>,
+  --min-vw <length>: 375px,
+  --max-vw <length>: 1440px
+) returns <length> {
+  --slope: calc((var(--max) - var(--min)) / (var(--max-vw) - var(--min-vw)));
+  --intercept: calc(var(--min) - var(--slope) * var(--min-vw));
+  result: clamp(var(--min), calc(var(--intercept) + var(--slope) * 100vw), var(--max));
+}
+
+/**
+ * --fluid-container() — Fluid Container-Based Sizing
+ *
+ * Generates a clamp() value that scales smoothly based on container width.
+ * Requires the parent element to have container-type: inline-size or container: name / inline-size.
+ * Perfect for component-level responsive design independent of viewport size.
+ *
+ * @param {length} --min - Minimum size
+ * @param {length} --max - Maximum size
+ * @param {length} --min-cqw - Minimum container width, default: 20ch
+ * @param {length} --max-cqw - Maximum container width, default: 65ch
+ * @returns {length} - Fluid clamp value based on container width
+ *
+ * @example
+ * .card {
+ *   container-type: inline-size;
+ * }
+ *
+ * .card h2 {
+ *   font-size: --fluid-container(1rem, 2rem);
+ * }
+ *
+ * .card p {
+ *   font-size: --fluid-container(0.875rem, 1.125rem, 30ch, 60ch);
+ * }
+ */
+
+@function --fluid-container(
+  --min <length>,
+  --max <length>,
+  --min-cqw <length>: 20ch,
+  --max-cqw <length>: 65ch
+) returns <length> {
+  --slope: calc((var(--max) - var(--min)) / (var(--max-cqw) - var(--min-cqw)));
+  --intercept: calc(var(--min) - var(--slope) * var(--min-cqw));
+  result: clamp(var(--min), calc(var(--intercept) + var(--slope) * 100cqw), var(--max));
+}
+
+/**
+ * --ratio-height() — Aspect Ratio Height
+ *
+ * Calculate height from width and aspect ratio (useful for images/containers).
+ *
+ * @param {length} --width - Element width
+ * @param {number} --ratio-w - Ratio width part, default: 16
+ * @param {number} --ratio-h - Ratio height part, default: 9
+ * @returns {length} - Calculated height
+ *
+ * @example
+ * .video-thumb {
+ *   width: 320px;
+ *   height: --ratio-height(320px, 16, 9);
+ * }
+ * .square-avatar {
+ *   width: 48px;
+ *   height: --ratio-height(48px, 1, 1);
+ * }
+ */
+
+@function --ratio-height(
+  --width <length>,
+  --ratio-w <number>: 16,
+  --ratio-h <number>: 9
+) returns <length> {
+  result: calc(var(--width) * var(--ratio-h) / var(--ratio-w));
+}
+
+/* Visual Effects */
+
+/**
+ * --shadow() — Elevation Shadows
+ *
+ * Generates layered box-shadows based on elevation level (1-5).
+ *
+ * @param {number} --level - Elevation level (1-5)
+ * @param {color} --color - Shadow color, default: oklch(0% 0 0 / 0.1)
+ * @returns {string} - Layered box-shadow value (comma-separated shadow list)
+ *
+ * @example
+ * .card {
+ *   box-shadow: --shadow(2);
+ * }
+ * .modal {
+ *   box-shadow: --shadow(5, oklch(0% 0 0 / 0.25));
+ * }
+ */
+
+@function --shadow(
+  --level <number>,
+  --color <color>: oklch(0% 0 0 / 0.1)
+) {
+  --y: calc(var(--level) * 2px);
+  --blur: calc(var(--level) * 4px);
+  --spread: calc(var(--level) * -1px);
+  result:
+    0 var(--y) var(--blur) var(--spread) var(--color),
+    0 calc(var(--y) * 0.5) calc(var(--blur) * 0.5) calc(var(--spread) * 0.5) var(--color);
+}
+
+/**
+ * --diagonal-lines() — Diagonal Line Pattern Background
+ *
+ * Generate a repeating diagonal line pattern with configurable angle, colors, and spacing.
+ * Returns a complete repeating-linear-gradient that can be used directly as a background value.
+ *
+ * @param {angle} --angle - Angle of the lines, default: -45deg
+ * @param {color} --line-color - Color of the lines, default: currentColor
+ * @param {length} --line-width - Width of each line, default: 1px
+ * @param {length} --gap-width - Width of the gap between lines, default: 4px
+ * @param {color} --gap-color - Color of the gap (background), default: transparent
+ * @returns {image} - Complete repeating-linear-gradient value
+ *
+ * Related - https://stackoverflow.com/questions/33091401/background-image-linear-gradient-jagged-edged-result-needs-to-be-smooth-edged
+ *
+ * @example
+ * .bg-diagonal {
+ *   background: --diagonal-lines();
+ * }
+ *
+ * @example
+ * .custom-stripes {
+ *   background: --diagonal-lines(
+ *     --angle: 45deg,
+ *     --line-color: #3b82f6,
+ *     --line-width: 2px,
+ *     --gap-width: 8px
+ *   );
+ * }
+ *
+ * @example
+ * .subtle-pattern {
+ *   color: #94a3b8;
+ *   background: --diagonal-lines(
+ *     --line-color: currentColor,
+ *     --line-width: 1px,
+ *     --gap-width: 10px
+ *   );
+ * }
+ */
+
+@function --diagonal-lines(
+  --angle <angle>: -45deg,
+  --line-color <color>: currentColor,
+  --line-width <length>: 1px,
+  --gap-width <length>: 4px,
+  --gap-color <color>: transparent
+) returns <image> {
+  result: repeating-linear-gradient(
+    var(--angle),
+    var(--line-color) 0,
+    var(--line-color) calc(var(--line-width) - 1px),
+    var(--gap-color) calc(var(--line-width) + 1px),
+    var(--gap-color) calc(var(--line-width) + var(--gap-width))
+  );
+}
+
+/* Layout Utilities */
+
+/**
+ * --z() — Z-Index Scale
+ *
+ * Named z-index layers to avoid magic numbers and conflicts.
+ *
+ * Layer reference:
+ * 1: dropdown, 2: sticky, 3: fixed,
+ * 4: drawer, 5: modal, 6: popover,
+ * 7: tooltip, 8: toast, 9: max
+ *
+ * @param {number} --layer - Layer number (1-9)
+ * @returns {integer} - Z-index value (layer × 100)
+ *
+ * @example
+ * .dropdown { z-index: --z(1); }
+ * .header { z-index: --z(3); }
+ * .modal { z-index: --z(5); }
+ * .tooltip { z-index: --z(7); }
+ */
+
+@function --z(--layer <number>) returns <integer> {
+  result: calc(var(--layer) * 100);
+}
+
+/**
+ * --neg() — Negative Value
+ *
+ * Simple negation — useful in calc-heavy layouts.
+ *
+ * @param {length} --value - Value to negate
+ * @returns {length} - Negative value
+ *
+ * @example
+ * .pull-up {
+ *   margin-top: --neg(var(--header-height));
+ * }
+ * .bleed {
+ *   margin-inline: --neg(var(--container-padding));
+ * }
+ */
+
+@function --neg(--value <length>) returns <length> {
+  result: calc(var(--value) * -1);
+}
+
+/* Math Utilities */
+
+/**
+ * --lerp() — Linear Interpolation
+ *
+ * Interpolates between two values using a t parameter (0-1).
+ * When t=0, returns a; when t=1, returns b; when t=0.5, returns midpoint.
+ * Hides the complex calc expression: calc(a + (b - a) * t)
+ *
+ * @param {length-percentage} --a - Start value
+ * @param {length-percentage} --b - End value
+ * @param {number} --t - Interpolation factor (0-1), default: 0.5
+ * @returns {length-percentage} - Interpolated value
+ *
+ * @example
+ * .animated {
+ *   width: --lerp(100px, 500px, 0.3);  // 30% between 100px and 500px
+ * }
+ * .transition {
+ *   width: --lerp(10%, 80%, 0.75);  // 75% between 10% and 80%
+ * }
+ */
+
+@function --lerp(
+  --a <length-percentage>,
+  --b <length-percentage>,
+  --t <number>: 0.5
+) returns <length-percentage> {
+  result: calc(var(--a) * (1 - var(--t)) + var(--b) * var(--t));
+}
+
+/**
+ * --circle-x() — Circle X Position
+ *
+ * Calculate X coordinate on a circle using radius and angle.
+ * Uses cosine: r * cos(deg)
+ *
+ * @param {length} --radius - Circle radius
+ * @param {angle} --angle - Angle in degrees, default: 0deg
+ * @returns {length} - X coordinate offset from center
+ *
+ * @example
+ * .orbit {
+ *   left: calc(50% + --circle-x(100px, 45deg));  // 45° position
+ * }
+ */
+
+@function --circle-x(
+  --radius <length>,
+  --angle <angle>: 0deg
+) returns <length> {
+  result: calc(var(--radius) * cos(var(--angle)));
+}
+
+/**
+ * --circle-y() — Circle Y Position
+ *
+ * Calculate Y coordinate on a circle using radius and angle.
+ * Uses sine: r * sin(deg)
+ *
+ * @param {length} --radius - Circle radius
+ * @param {angle} --angle - Angle in degrees, default: 0deg
+ * @returns {length} - Y coordinate offset from center
+ *
+ * @example
+ * .orbit {
+ *   top: calc(50% + --circle-y(100px, 45deg));  // 45° position
+ * }
+ */
+
+@function --circle-y(
+  --radius <length>,
+  --angle <angle>: 0deg
+) returns <length> {
+  result: calc(var(--radius) * sin(var(--angle)));
+}
+
+/**
+ * --modular() — Modular Scale (Typographic Scale)
+ *
+ * Calculate values using a modular scale (typographic ratio).
+ * Hides the pow calculation: base * pow(ratio, step)
+ *
+ * @param {number} --step - Scale step (can be negative for smaller values)
+ * @param {length|number} --base - Base value, default: 1rem
+ * @param {number} --ratio - Scale ratio, default: 1.25 (major third)
+ * @returns {length|number} - Scaled value
+ *
+ * @example
+ * :root {
+ *   --type-base: 1rem;
+ *   --type-ratio: 1.25;
+ * }
+ * h1 {
+ *   font-size: --modular(4, var(--type-base), var(--type-ratio));  // Large scale
+ * }
+ * small {
+ *   font-size: --modular(-1, var(--type-base), var(--type-ratio));  // Smaller
+ * }
+ */
+
+@function --modular(
+  --step <number>,
+  --base <length|number>: 1rem,
+  --ratio <number>: 1.25
+) returns <length|number> {
+  result: calc(var(--base) * pow(var(--ratio), var(--step)));
+}
+
+/**
+ * --poly-angle() — Polygon Vertex Angle
+ *
+ * Calculate the angle for a vertex in a regular polygon.
+ * Useful for creating polygon shapes with CSS transforms.
+ * Formula: (360deg / sides * index) - 90deg
+ *
+ * @param {number} --sides - Number of sides in polygon
+ * @param {number} --index - Vertex index (0-based), default: 0
+ * @returns {angle} - Angle in degrees
+ *
+ * @example
+ * .hexagon-vertex-0 {
+ *   transform: rotate(--poly-angle(6, 0));  // First vertex of hexagon
+ * }
+ * .pentagon-vertex-2 {
+ *   transform: rotate(--poly-angle(5, 2));  // Third vertex of pentagon
+ * }
+ */
+
+@function --poly-angle(
+  --sides <number>,
+  --index <number>: 0
+) returns <angle> {
+  result: calc(360deg / var(--sides) * var(--index) - 90deg);
+}
+
+/* Unit Conversion */
+
+/**
+ * --to-rem() — Pixel to REM Conversion
+ *
+ * Convert a pixel value to rem units. Base pixel size defaults to --rem-base (or 16px).
+ *
+ * @param {number} --px - Pixel value (unitless)
+ * @param {number} --base - Base pixel size for conversion, defaults to var(--rem-base, 16)
+ * @returns {length} - REM value
+ *
+ * @example
+ * .legacy-compat {
+ *   font-size: --to-rem(18);
+ *   padding: --to-rem(24);
+ * }
+ *
+ * .custom-base {
+ *   font-size: --to-rem(18, 10);
+ * }
+ *
+ * :root {
+ *   --rem-base: 20;
+ * }
+ */
+
+@function --to-rem(--px <number>, --base <number>: var(--rem-base, 16)) returns <length> {
+  result: calc(var(--px) * 1rem / var(--base));
+}
+
+/**
+ * --to-px() — REM to Pixel Conversion
+ *
+ * Convert a rem value to pixels (assumes 16px base).
+ *
+ * @param {number} --rem - REM value (unitless)
+ * @returns {length} - Pixel value
+ *
+ * @example
+ * .legacy-system {
+ *   width: --to-px(10);
+ *   height: --to-px(5);
+ * }
+ */
+
+@function --to-px(--rem <number>) returns <length> {
+  result: calc(var(--rem) * 16 * 1px);
+}
+
+/* Logic Operations */
+
+/**
+ * --not() — Boolean Negation
+ *
+ * Inverts a boolean value (switch variable). Works with values 0 and 1.
+ * Returns 1 if input is 0, returns 0 if input is 1.
+ *
+ * @param {number} --value - Switch variable (0 or 1)
+ * @returns {number} - Inverted value (0 or 1)
+ *
+ * @example
+ * .toggle {
+ *   --is-active: 1;
+ *   --is-inactive: --not(var(--is-active)); // 0
+ *   opacity: --not(var(--is-hidden));
+ * }
+ *
+ * @see https://css-tricks.com/logical-operations-with-css-variables/
+ */
+
+@function --not(--value <number>) returns <number> {
+  result: calc(1 - var(--value));
+}
+
+/**
+ * --and() — Logical AND Operation
+ *
+ * Returns 1 if both operands are 1, otherwise returns 0.
+ * Uses multiplication since any value multiplied by 0 equals 0.
+ *
+ * Truth table:
+ * - 0 AND 0 = 0
+ * - 0 AND 1 = 0
+ * - 1 AND 0 = 0
+ * - 1 AND 1 = 1
+ *
+ * @param {number} --a - First switch variable (0 or 1)
+ * @param {number} --b - Second switch variable (0 or 1)
+ * @returns {number} - Result (0 or 1)
+ *
+ * @example
+ * .visible-on-mobile-and-dark {
+ *   --is-mobile: 1;
+ *   --is-dark-mode: 1;
+ *   display: --and(var(--is-mobile), var(--is-dark-mode));
+ * }
+ *
+ * @see https://css-tricks.com/logical-operations-with-css-variables/
+ */
+
+@function --and(--a <number>, --b <number>) returns <number> {
+  result: calc(var(--a) * var(--b));
+}
+
+/**
+ * --or() — Logical OR Operation
+ *
+ * Returns 1 if at least one operand is 1, otherwise returns 0.
+ * Uses De Morgan's law: NOT (A OR B) = (NOT A) AND (NOT B)
+ *
+ * Truth table:
+ * - 0 OR 0 = 0
+ * - 0 OR 1 = 1
+ * - 1 OR 0 = 1
+ * - 1 OR 1 = 1
+ *
+ * @param {number} --a - First switch variable (0 or 1)
+ * @param {number} --b - Second switch variable (0 or 1)
+ * @returns {number} - Result (0 or 1)
+ *
+ * @example
+ * .show-on-mobile-or-tablet {
+ *   --is-mobile: 0;
+ *   --is-tablet: 1;
+ *   display: --or(var(--is-mobile), var(--is-tablet));
+ * }
+ *
+ * @see https://css-tricks.com/logical-operations-with-css-variables/
+ */
+
+@function --or(--a <number>, --b <number>) returns <number> {
+  result: calc(1 - (1 - var(--a)) * (1 - var(--b)));
+}
+
+/**
+ * --xor() — Exclusive OR Operation
+ *
+ * Returns 1 if exactly one operand is 1, otherwise returns 0.
+ * Uses subtraction squared to get absolute value: (a - b)²
+ *
+ * Truth table:
+ * - 0 XOR 0 = 0 (both same)
+ * - 0 XOR 1 = 1 (different)
+ * - 1 XOR 0 = 1 (different)
+ * - 1 XOR 1 = 0 (both same)
+ *
+ * @param {number} --a - First switch variable (0 or 1)
+ * @param {number} --b - Second switch variable (0 or 1)
+ * @returns {number} - Result (0 or 1)
+ *
+ * @example
+ * .highlight-when-different {
+ *   --user-theme: 1;
+ *   --system-theme: 0;
+ *   opacity: --xor(var(--user-theme), var(--system-theme));
+ * }
+ *
+ * @see https://css-tricks.com/logical-operations-with-css-variables/
+ */
+
+@function --xor(--a <number>, --b <number>) returns <number> {
+  result: calc((var(--a) - var(--b)) * (var(--a) - var(--b)));
+}
+
+/**
+ * --nand() — Logical NAND Operation (NOT AND)
+ *
+ * Returns 0 if both operands are 1, otherwise returns 1.
+ * Combination of NOT and AND operations.
+ *
+ * Truth table:
+ * - 0 NAND 0 = 1
+ * - 0 NAND 1 = 1
+ * - 1 NAND 0 = 1
+ * - 1 NAND 1 = 0
+ *
+ * @param {number} --a - First switch variable (0 or 1)
+ * @param {number} --b - Second switch variable (0 or 1)
+ * @returns {number} - Result (0 or 1)
+ *
+ * @example
+ * .hide-when-both-active {
+ *   --feature-a: 1;
+ *   --feature-b: 1;
+ *   display: --nand(var(--feature-a), var(--feature-b));
+ * }
+ *
+ * @see https://css-tricks.com/logical-operations-with-css-variables/
+ */
+
+@function --nand(--a <number>, --b <number>) returns <number> {
+  result: calc(1 - var(--a) * var(--b));
+}
+
+/**
+ * --nor() — Logical NOR Operation (NOT OR)
+ *
+ * Returns 1 if both operands are 0, otherwise returns 0.
+ * Combination of NOT and OR operations.
+ *
+ * Truth table:
+ * - 0 NOR 0 = 1
+ * - 0 NOR 1 = 0
+ * - 1 NOR 0 = 0
+ * - 1 NOR 1 = 0
+ *
+ * @param {number} --a - First switch variable (0 or 1)
+ * @param {number} --b - Second switch variable (0 or 1)
+ * @returns {number} - Result (0 or 1)
+ *
+ * @example
+ * .show-default-state {
+ *   --has-custom-bg: 0;
+ *   --has-custom-text: 0;
+ *   opacity: --nor(var(--has-custom-bg), var(--has-custom-text));
+ * }
+ *
+ * @see https://css-tricks.com/logical-operations-with-css-variables/
+ */
+
+@function --nor(--a <number>, --b <number>) returns <number> {
+  result: calc((1 - var(--a)) * (1 - var(--b)));
+}
+
+/**
+ * --xnor() — Exclusive NOR Operation (NOT XOR)
+ *
+ * Returns 1 if both operands are the same, otherwise returns 0.
+ * The opposite of XOR - checks for equality.
+ *
+ * Truth table:
+ * - 0 XNOR 0 = 1 (both same)
+ * - 0 XNOR 1 = 0 (different)
+ * - 1 XNOR 0 = 0 (different)
+ * - 1 XNOR 1 = 1 (both same)
+ *
+ * @param {number} --a - First switch variable (0 or 1)
+ * @param {number} --b - Second switch variable (0 or 1)
+ * @returns {number} - Result (0 or 1)
+ *
+ * @example
+ * .sync-indicator {
+ *   --local-state: 1;
+ *   --remote-state: 1;
+ *   opacity: --xnor(var(--local-state), var(--remote-state));
+ * }
+ *
+ * @see https://css-tricks.com/logical-operations-with-css-variables/
+ */
+
+@function --xnor(--a <number>, --b <number>) returns <number> {
+  result: calc(1 - (var(--a) - var(--b)) * (var(--a) - var(--b)));
+}
+