css-utility-functions 1.0.1

package/dist/index.min.css

@@ -0,0 +1,28 @@
+@function --alpha(--color <color>, --opacity <number>: 0.5) returns <color>{result:oklch(from var(--color) l c h/var(--opacity))}@function --lighten(--color <color>, --amount <number>: 0.1) returns <color>{result:oklch(from var(--color) calc(l + var(--amount)) c h)}@function --darken(--color <color>, --amount <number>: 0.1) returns <color>{result:oklch(from var(--color) calc(l - var(--amount)) c h)}@function --saturate(
+  --color <color>,
+  --amount <number>: 0.2
+) returns <color>{result:oklch(from var(--color) l calc(c + c * var(--amount)) h)}@function --desaturate(
+  --color <color>,
+  --amount <number>: 0.2
+) returns <color>{result:oklch(from var(--color) l calc(c - c * var(--amount)) h)}@function --mix(
+  --color1 <color>,
+  --color2 <color>,
+  --weight <percentage>: 50%
+) returns <color>{result:color-mix(in oklch,var(--color1) var(--weight),var(--color2))}@function --contrast-text(--bg <color>) returns <color>{result:oklch(from var(--bg) calc((.6 - l) * infinity) 0 0)}@function --space(--multiplier <number>, --base <length>: var(--space-base, 0.25rem)) returns <length>{result:calc(var(--base) * var(--multiplier))}@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))}@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))}@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))}@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) * .5) calc(var(--blur) * .5) calc(var(--spread) * .5) var(--color)}@function --z(--layer <number>) returns <integer>{result:calc(var(--layer) * 100)}@function --neg(--value <length>) returns <length>{result:calc(var(--value) * -1)}@function --to-rem(--px <number>, --base <number>: var(--rem-base, 16)) returns <length>{result:calc(var(--px) * 1rem / var(--base))}@function --to-px(--rem <number>) returns <length>{result:calc(var(--rem) * 16 * 1px)}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "css-utility-functions",
+  "version": "1.0.1",
+  "description": "A collection of reusable CSS custom native functions using the @function syntax",
+  "main": "dist/index.css",
+  "style": "dist/index.css",
+  "files": [
+    "dist/**/*.css",
+    "src/**/*.css",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "postcss src/index.css -o dist/index.css",
+    "build:min": "postcss src/index.css -o dist/index.min.css --env production",
+    "build:html": "node build-html.js",
+    "build:all": "npm run build:html && npm run build && npm run build:min",
+    "watch": "nodemon --watch src --ext css --exec \"npm run build\"",
+    "watch:html": "node build-html.js --watch",
+    "dev": "concurrently \"npm run watch:html\" \"npm run watch\"",
+    "prebuild": "npm run build:html"
+  },
+  "keywords": [
+    "css",
+    "css-functions",
+    "utility",
+    "design-system",
+    "css-custom-functions",
+    "@function"
+  ],
+  "author": "Yair Even-Or <vsync.design@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yairEO/css-utility-functions.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yaireo/css-utility-functions/issues"
+  },
+  "devDependencies": {
+    "postcss-cli": "^11.0.0",
+    "postcss-import": "^16.1.0",
+    "cssnano": "^7.1.2",
+    "concurrently": "^9.2.1",
+    "nodemon": "^3.1.0"
+  }
+}

package/src/colors/alpha.css

@@ -0,0 +1,27 @@
+/**
+ * --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));
+}
+

package/src/colors/complement.css

@@ -0,0 +1,23 @@
+/**
+ * --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));
+}
+

package/src/colors/contrast-text.css

@@ -0,0 +1,20 @@
+/**
+ * --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);
+}
+

package/src/colors/darken.css

@@ -0,0 +1,20 @@
+/**
+ * --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);
+}
+

package/src/colors/desaturate.css

@@ -0,0 +1,22 @@
+/**
+ * --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);
+}
+

package/src/colors/grayscale.css

@@ -0,0 +1,22 @@
+/**
+ * --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);
+}
+

package/src/colors/invert.css

@@ -0,0 +1,22 @@
+/**
+ * --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);
+}
+

package/src/colors/lighten.css

@@ -0,0 +1,20 @@
+/**
+ * --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);
+}
+

package/src/colors/mix.css

@@ -0,0 +1,27 @@
+/**
+ * --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));
+}
+

package/src/colors/saturate.css

@@ -0,0 +1,22 @@
+/**
+ * --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);
+}
+

package/src/effects/diagonal-lines.css

@@ -0,0 +1,58 @@
+/**
+ * --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))
+  );
+}
+
+

package/src/effects/shadow.css

@@ -0,0 +1,30 @@
+/**
+ * --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);
+}
+

package/src/index.css

@@ -0,0 +1,55 @@
+/**
+ * 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 */
+@import './colors/alpha.css';
+@import './colors/lighten.css';
+@import './colors/darken.css';
+@import './colors/saturate.css';
+@import './colors/desaturate.css';
+@import './colors/mix.css';
+@import './colors/contrast-text.css';
+@import './colors/grayscale.css';
+@import './colors/invert.css';
+@import './colors/complement.css';
+
+/* Spacing & Sizing */
+@import './spacing/space.css';
+@import './spacing/fluid.css';
+@import './spacing/ratio-height.css';
+
+/* Visual Effects */
+@import './effects/shadow.css';
+@import './effects/diagonal-lines.css';
+
+/* Layout Utilities */
+@import './layout/z-index.css';
+@import './layout/neg.css';
+
+/* Math Utilities */
+@import './math/lerp.css';
+@import './math/circle.css';
+@import './math/modular.css';
+@import './math/poly-angle.css';
+
+/* Unit Conversion */
+@import './units/to-rem.css';
+@import './units/to-px.css';
+
+/* Logic Operations */
+@import './logic/not.css';
+@import './logic/and.css';
+@import './logic/or.css';
+@import './logic/xor.css';
+@import './logic/nand.css';
+@import './logic/nor.css';
+@import './logic/xnor.css';
+

package/src/layout/neg.css

@@ -0,0 +1,21 @@
+/**
+ * --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);
+}
+

package/src/layout/z-index.css

@@ -0,0 +1,24 @@
+/**
+ * --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);
+}
+

package/src/logic/and.css

@@ -0,0 +1,30 @@
+/**
+ * --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));
+}
+

package/src/logic/nand.css

@@ -0,0 +1,30 @@
+/**
+ * --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));
+}
+

package/src/logic/nor.css

@@ -0,0 +1,30 @@
+/**
+ * --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)));
+}
+

package/src/logic/not.css

@@ -0,0 +1,23 @@
+/**
+ * --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));
+}
+

package/src/logic/or.css

@@ -0,0 +1,30 @@
+/**
+ * --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)));
+}
+