postcss-ruler 1.1.0 → 1.3.0

package/README.md

@@ -9,12 +9,14 @@ A PostCSS plugin that generates fluid CSS scales and values using the `clamp()`
 Working with design teams often means dealing with sizes that don't follow perfect mathematical ratios. A designer might spec `16px → 24px` for one size and `32px → 56px` for another based on visual harmony rather than a type scale.
 
 postcss-ruler embraces this reality. You get:
+
 - **Fine-tuned control**: Set exact min and max values per size
 - **Design tool compatibility**: Match your Figma specs precisely
 - **Fluid behavior**: Smooth scaling between breakpoints via `clamp()`
 - **Cross pairs**: Generate spacing between any two sizes (explained below)
 
 ## Installation
+
 ```bash
 npm install postcss-ruler
 ```
@@ -22,17 +24,18 @@ npm install postcss-ruler
 ## Usage
 
 Add the plugin to your PostCSS configuration:
+
 ```javascript
 // postcss.config.js
 module.exports = {
   plugins: {
-    'postcss-ruler': {
-      minWidth: 320,    // Default minimum viewport width
-      maxWidth: 1760,   // Default maximum viewport width
-      generateAllCrossPairs: false
-    }
-  }
-}
+    "postcss-ruler": {
+      minWidth: 320, // Default minimum viewport width
+      maxWidth: 1760, // Default maximum viewport width
+      generateAllCrossPairs: false,
+    },
+  },
+};
 ```
 
 ## Features
@@ -40,6 +43,7 @@ module.exports = {
 ### 1. Scale Generation: Create Fluid Scales
 
 Create multiple CSS custom properties from named size pairs:
+
 ```css
 @ruler scale({
   minWidth: 320,
@@ -57,6 +61,7 @@ Create multiple CSS custom properties from named size pairs:
 ```
 
 **Generates:**
+
 ```css
 --space-xs: clamp(0.5rem, 0.4545vw + 0.3636rem, 1rem);
 --space-sm: clamp(1rem, 0.4545vw + 0.8636rem, 1.5rem);
@@ -74,6 +79,7 @@ For example, if you have `xs: [8, 16]` and `lg: [32, 48]`, a cross pair `xs-lg`
 **Without cross pairs**, you only get the sizes you explicitly define.
 
 **With `generateAllCrossPairs: true`**, you get every possible combination:
+
 ```css
 @ruler scale({
   prefix: 'space',
@@ -87,6 +93,7 @@ For example, if you have `xs: [8, 16]` and `lg: [32, 48]`, a cross pair `xs-lg`
 ```
 
 **Generates:**
+
 ```css
 /* Your defined pairs */
 --space-xs: clamp(0.5rem, ...);
@@ -94,12 +101,13 @@ For example, if you have `xs: [8, 16]` and `lg: [32, 48]`, a cross pair `xs-lg`
 --space-lg: clamp(2rem, ...);
 
 /* All cross combinations */
---space-xs-md: clamp(0.5rem, 1.3636vw + 0.3636rem, 2rem);    /* 8px → 32px */
---space-xs-lg: clamp(0.5rem, 2.2727vw + 0.3636rem, 3rem);    /* 8px → 48px */
---space-md-lg: clamp(1.5rem, 0.9091vw + 1.3636rem, 3rem);    /* 24px → 48px */
+--space-xs-md: clamp(0.5rem, 1.3636vw + 0.3636rem, 2rem); /* 8px → 32px */
+--space-xs-lg: clamp(0.5rem, 2.2727vw + 0.3636rem, 3rem); /* 8px → 48px */
+--space-md-lg: clamp(1.5rem, 0.9091vw + 1.3636rem, 3rem); /* 24px → 48px */
 ```
 
 **Use case**: Section padding that needs more dramatic scaling than your base sizes allow.
+
 ```css
 .hero {
   padding-block: var(--space-md-xl); /* Scales across a wider range */
@@ -143,27 +151,41 @@ Generate utility classes from your defined scales with complete selector flexibi
 ```
 
 **Generates:**
+
 ```css
 --space-xs: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem);
 --space-sm: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem);
 --space-md: clamp(1.5rem, 0.5556vw + 1.3889rem, 2rem);
 
-.gap-xs { gap: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem) }
-.gap-sm { gap: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem) }
-.gap-md { gap: clamp(1.5rem, 0.5556vw + 1.3889rem, 2rem) }
+.gap-xs {
+  gap: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem);
+}
+.gap-sm {
+  gap: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem);
+}
+.gap-md {
+  gap: clamp(1.5rem, 0.5556vw + 1.3889rem, 2rem);
+}
 
-&.active-xs { padding: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem) }
-&.active-sm { padding: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem) }
-&.active-md { padding: clamp(1.5rem, 0.5556vw + 1.3889rem, 2rem) }
+&.active-xs {
+  padding: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem);
+}
+&.active-sm {
+  padding: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem);
+}
+&.active-md {
+  padding: clamp(1.5rem, 0.5556vw + 1.3889rem, 2rem);
+}
 
 .p-block-xs {
   padding-top: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem);
-  padding-bottom: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem)
+  padding-bottom: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem);
 }
 /* ... */
 ```
 
 **Supported selector patterns:**
+
 - **Class selectors**: `.gap` → `.gap-xs`, `.gap-sm`, `.gap-md`
 - **Nested with &**: `&.active` → `&.active-xs`, `&.active-sm` (PostCSS nesting)
 - **Multiple classes**: `.container.space` → `.container.space-xs`, etc.
@@ -173,16 +195,17 @@ Generate utility classes from your defined scales with complete selector flexibi
 
 **Utility options:**
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `selector` | string | Yes | Any valid CSS selector pattern (e.g., `.gap`, `&.active`, `#section`) |
-| `property` | string or array | Yes | CSS property name(s) to apply the scale values to |
-| `scale` | string | Yes | Name of a previously defined scale (the `prefix` value) |
-| `generateAllCrossPairs` | boolean | No | Include/exclude cross-pairs (overrides scale default) |
+| Option                  | Type            | Required | Description                                                           |
+| ----------------------- | --------------- | -------- | --------------------------------------------------------------------- |
+| `selector`              | string          | Yes      | Any valid CSS selector pattern (e.g., `.gap`, `&.active`, `#section`) |
+| `property`              | string or array | Yes      | CSS property name(s) to apply the scale values to                     |
+| `scale`                 | string          | Yes      | Name of a previously defined scale (the `prefix` value)               |
+| `generateAllCrossPairs` | boolean         | No       | Include/exclude cross-pairs (overrides scale default)                 |
 
 ### 3. Inline Mode: Fluid Function
 
 Convert individual values directly to `clamp()` functions:
+
 ```css
 .element {
   /* Uses default minWidth/maxWidth from config */
@@ -197,11 +220,13 @@ Convert individual values directly to `clamp()` functions:
 ```
 
 **Generates:**
+
 ```css
 .element {
   font-size: clamp(1rem, 0.4545vw + 0.8636rem, 1.5rem);
   padding: clamp(0.75rem, 0.9091vw + 0.4773rem, 1.25rem);
-  margin: clamp(0.5rem, 0.4545vw + 0.3636rem, 1rem) clamp(1rem, 0.9091vw + 0.7273rem, 2rem);
+  margin: clamp(0.5rem, 0.4545vw + 0.3636rem, 1rem)
+    clamp(1rem, 0.9091vw + 0.7273rem, 2rem);
 }
 ```
 
@@ -209,23 +234,23 @@ Convert individual values directly to `clamp()` functions:
 
 ### Plugin Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `minWidth` | number | `320` | Default minimum viewport width in pixels |
-| `maxWidth` | number | `1760` | Default maximum viewport width in pixels |
+| Option                  | Type    | Default | Description                               |
+| ----------------------- | ------- | ------- | ----------------------------------------- |
+| `minWidth`              | number  | `320`   | Default minimum viewport width in pixels  |
+| `maxWidth`              | number  | `1760`  | Default maximum viewport width in pixels  |
 | `generateAllCrossPairs` | boolean | `false` | Generate cross-combinations in scale mode |
 
 ### At-Rule Options
 
 All options can be overridden per `@ruler scale()` declaration:
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `minWidth` | number | `320` | Minimum viewport width for this scale |
-| `maxWidth` | number | `1760` | Maximum viewport width for this scale |
-| `prefix` | string | `"space"` | Prefix for generated CSS custom properties |
-| `generateAllCrossPairs` | boolean | `false` | Generate cross-combinations for this scale |
-| `pairs` | object | required | Size pairs as `"name": [min, max]` |
+| Option                  | Type    | Default   | Description                                |
+| ----------------------- | ------- | --------- | ------------------------------------------ |
+| `minWidth`              | number  | `320`     | Minimum viewport width for this scale      |
+| `maxWidth`              | number  | `1760`    | Maximum viewport width for this scale      |
+| `prefix`                | string  | `"space"` | Prefix for generated CSS custom properties |
+| `generateAllCrossPairs` | boolean | `false`   | Generate cross-combinations for this scale |
+| `pairs`                 | object  | required  | Size pairs as `"name": [min, max]`         |
 
 ### Inline Function Syntax
 
@@ -233,21 +258,62 @@ All options can be overridden per `@ruler scale()` declaration:
 ruler.fluid(minSize, maxSize[, minWidth, maxWidth])
 ```
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `minSize` | number | Yes | Minimum size in pixels |
-| `maxSize` | number | Yes | Maximum size in pixels |
-| `minWidth` | number | No | Minimum viewport width (uses config default) |
-| `maxWidth` | number | No | Maximum viewport width (uses config default) |
+| Parameter  | Type   | Required | Description                                  |
+| ---------- | ------ | -------- | -------------------------------------------- |
+| `minSize`  | number | Yes      | Minimum size in pixels                       |
+| `maxSize`  | number | Yes      | Maximum size in pixels                       |
+| `minWidth` | number | No       | Minimum viewport width (uses config default) |
+| `maxWidth` | number | No       | Maximum viewport width (uses config default) |
+
+### Static Values
+
+When min and max values are equal, postcss-ruler outputs a simple rem value instead of a clamp() function. This works in all three modes:
+
+**Inline function:**
+
+```css
+.element {
+  font-size: ruler.fluid(20, 20);
+}
+```
+
+**Generates:**
+
+```css
+.element {
+  font-size: 1.25rem;
+}
+```
+
+**Scale generation:**
+
+```css
+@ruler scale({
+  prefix: 'size',
+  pairs: {
+    "static": [16, 16],
+    "fluid": [16, 24]
+  }
+});
+```
+
+**Generates:**
+
+```css
+--size-static: 1rem;
+--size-fluid: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem);
+```
+
+**Use case:** Mix static and fluid values in the same scale for consistency. Define your base unit as a static value and let other sizes scale fluidly from it.
 
 ### Utility Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `selector` | string | required | Any valid CSS selector pattern (e.g., `.gap`, `&.active`, `#section`) |
-| `property` | string or array | required | CSS property name(s) to apply the scale values to |
-| `scale` | string | required | Name of a previously defined scale (the `prefix` value) |
-| `generateAllCrossPairs` | boolean | No | Include/exclude cross-pairs (overrides scale default) |
+| Option                  | Type            | Default  | Description                                                           |
+| ----------------------- | --------------- | -------- | --------------------------------------------------------------------- |
+| `selector`              | string          | required | Any valid CSS selector pattern (e.g., `.gap`, `&.active`, `#section`) |
+| `property`              | string or array | required | CSS property name(s) to apply the scale values to                     |
+| `scale`                 | string          | required | Name of a previously defined scale (the `prefix` value)               |
+| `generateAllCrossPairs` | boolean         | No       | Include/exclude cross-pairs (overrides scale default)                 |
 
 ## How It Works
 
@@ -319,6 +385,7 @@ Generate a complete set of utility classes from your design system:
 ```
 
 Use in your HTML:
+
 ```html
 <section class="p-lg gap-md">
   <div class="stack gap-sm">
@@ -399,6 +466,7 @@ h2 {
 ## Browser Support
 
 The `clamp()` function is supported in all modern browsers:
+
 - Chrome 79+
 - Firefox 75+
 - Safari 13.1+

package/index.js

@@ -1,413 +1,450 @@
-const CSSValueParser = require('postcss-value-parser');
+const CSSValueParser = require("postcss-value-parser");
 
 /**
  * @type {import('postcss').PluginCreator}
  */
-module.exports = opts => {
-    const DEFAULTS = {
-        minWidth: 320,
-        maxWidth: 1760,
-        generateAllCrossPairs: false,
-    };
-    const config = Object.assign(DEFAULTS, opts);
-
-    // Storage for generated scales
-    const scales = {};
-
-    /**
-     * Converts pixels to r]em units
-     * @param {number} px - Pixel value to convert
-     * @returns {string} Rem value as string
-     */
-    const pxToRem = px => `${parseFloat((px / 16).toFixed(4))}rem`;
-
-    /**
-     * Validates that min value is less than max value
-     * @param {number} min - Minimum value
-     * @param {number} max - Maximum value
-     * @param {string} context - Context for error message
-     * @throws {Error} If min >= max
-     */
-    const validateMinMax = (min, max, context) => {
-        if (min >= max) {
-            throw new Error(
-                `[postcss-ruler] Invalid ${context}: min (${min}) must be less than max (${max})`
-            );
-        }
-    };
-
-    /**
-     * Calculates a fluid clamp() function
-     * @param {Object} params - Calculation parameters
-     * @param {number} params.minSize - Minimum size in pixels
-     * @param {number} params.maxSize - Maximum size in pixels
-     * @param {number} params.minWidth - Minimum viewport width in pixels
-     * @param {number} params.maxWidth - Maximum viewport width in pixels
-     * @returns {string} CSS clamp() function
-     */
-    const calculateClamp = ({ minSize, maxSize, minWidth, maxWidth }) => {
-        validateMinMax(minSize, maxSize, 'size');
-        validateMinMax(minWidth, maxWidth, 'width');
-
-        const slope = (maxSize - minSize) / (maxWidth - minWidth);
-        const intersect = -minWidth * slope + minSize;
-
-        return `clamp(${pxToRem(minSize)}, ${(slope * 100).toFixed(
-            4
-        )}vw + ${pxToRem(intersect)}, ${pxToRem(maxSize)})`;
-    };
-
-    /**
-     * Generates clamp values from pairs
-     * @param {Object} params - Generation parameters
-     * @param {Array<{name: string, values: [number, number]}>} params.pairs - Size pairs
-     * @param {number} params.minWidth - Minimum viewport width
-     * @param {number} params.maxWidth - Maximum viewport width
-     * @param {boolean} params.generateAllCrossPairs - Whether to generate cross pairs
-     * @returns {Array<{label: string, clamp: string}>} Array of clamp values
-     */
-    const generateClamps = ({
-        pairs,
+module.exports = (opts) => {
+  const DEFAULTS = {
+    minWidth: 320,
+    maxWidth: 1760,
+    generateAllCrossPairs: false,
+  };
+  const config = Object.assign(DEFAULTS, opts);
+
+  // Storage for generated scales
+  const scales = {};
+
+  /**
+   * Converts pixels to r]em units
+   * @param {number} px - Pixel value to convert
+   * @returns {string} Rem value as string
+   */
+  const pxToRem = (px) => `${parseFloat((px / 16).toFixed(4))}rem`;
+
+  /**
+   * Validates that min value is less than max value
+   * @param {number} min - Minimum value
+   * @param {number} max - Maximum value
+   * @param {string} context - Context for error message
+   * @throws {Error} If min >= max
+   */
+  const validateMinMax = (min, max, context) => {
+    if (min >= max) {
+      throw new Error(
+        `[postcss-ruler] Invalid ${context}: min (${min}) must be less than max (${max})`,
+      );
+    }
+  };
+
+  /**
+   * Calculates a fluid clamp() function
+   * @param {Object} params - Calculation parameters
+   * @param {number} params.minSize - Minimum size in pixels
+   * @param {number} params.maxSize - Maximum size in pixels
+   * @param {number} params.minWidth - Minimum viewport width in pixels
+   * @param {number} params.maxWidth - Maximum viewport width in pixels
+   * @returns {string} CSS clamp() function
+   */
+  const calculateClamp = ({ minSize, maxSize, minWidth, maxWidth }) => {
+    // New: Allow equal values - just return rem
+    if (minSize === maxSize) {
+      return pxToRem(minSize);
+    }
+
+    validateMinMax(minSize, maxSize, "size");
+    validateMinMax(minWidth, maxWidth, "width");
+
+    const slope = (maxSize - minSize) / (maxWidth - minWidth);
+    const intersect = -minWidth * slope + minSize;
+
+    return `clamp(${pxToRem(minSize)}, ${(slope * 100).toFixed(
+      4,
+    )}vw + ${pxToRem(intersect)}, ${pxToRem(maxSize)})`;
+  };
+
+  /**
+   * Generates clamp values from pairs
+   * @param {Object} params - Generation parameters
+   * @param {Array<{name: string, values: [number, number]}>} params.pairs - Size pairs
+   * @param {number} params.minWidth - Minimum viewport width
+   * @param {number} params.maxWidth - Maximum viewport width
+   * @param {boolean} params.generateAllCrossPairs - Whether to generate cross pairs
+   * @returns {Array<{label: string, clamp: string}>} Array of clamp values
+   */
+  const generateClamps = ({
+    pairs,
+    minWidth,
+    maxWidth,
+    generateAllCrossPairs,
+  }) => {
+    let clampScales = pairs.map(({ name, values: [minSize, maxSize] }) => ({
+      label: name,
+      clamp: calculateClamp({
+        minSize,
+        maxSize,
         minWidth,
         maxWidth,
-        generateAllCrossPairs,
-    }) => {
-        let clampScales = pairs.map(({ name, values: [minSize, maxSize] }) => ({
-            label: name,
+      }),
+    }));
+
+    if (generateAllCrossPairs) {
+      let crossPairs = [];
+      for (let i = 0; i < pairs.length; i++) {
+        for (let j = i + 1; j < pairs.length; j++) {
+          const [smaller, larger] = [pairs[i], pairs[j]].sort(
+            (a, b) => a.values[0] - b.values[0],
+          );
+          crossPairs.push({
+            label: `${smaller.name}-${larger.name}`,
             clamp: calculateClamp({
-                minSize,
-                maxSize,
-                minWidth,
-                maxWidth,
+              minSize: smaller.values[0],
+              maxSize: larger.values[1],
+              minWidth,
+              maxWidth,
             }),
-        }));
-
-        if (generateAllCrossPairs) {
-            let crossPairs = [];
-            for (let i = 0; i < pairs.length; i++) {
-                for (let j = i + 1; j < pairs.length; j++) {
-                    const [smaller, larger] = [pairs[i], pairs[j]].sort(
-                        (a, b) => a.values[0] - b.values[0]
-                    );
-                    crossPairs.push({
-                        label: `${smaller.name}-${larger.name}`,
-                        clamp: calculateClamp({
-                            minSize: smaller.values[0],
-                            maxSize: larger.values[1],
-                            minWidth,
-                            maxWidth,
-                        }),
-                    });
-                }
-            }
-            clampScales = [...clampScales, ...crossPairs];
+          });
         }
-
-        return clampScales;
-    };
-
-    /**
-     * Parses parameters from @fluid at-rule
-     * @param {Array} params - Parsed parameter nodes
-     * @returns {Object} Parsed configuration object
-     */
-    const parseAtRuleParams = params => {
-        const clampsParams = {
-            minWidth: config.minWidth,
-            maxWidth: config.maxWidth,
-            pairs: {},
-            prefix: 'space',
-            generateAllCrossPairs: config.generateAllCrossPairs,
-        };
-
-        for (let i = 0; i < params.length; i++) {
-            const param = params[i];
-            const nextParam = params[i + 1];
-            if (!param || !nextParam) continue;
-            const key = param.value;
-            let value = nextParam.value.replace(/[:,]/g, '');
-
-            switch (key) {
-                case 'minWidth':
-                case 'maxWidth':
-                    clampsParams[key] = Number(value);
-                    i++;
-                    break;
-                case 'prefix':
-                    clampsParams.prefix = value.replace(/['"]/g, '');
-                    i++;
-                    break;
-                case 'generateAllCrossPairs':
-                    clampsParams.generateAllCrossPairs = value === 'true';
-                    i++;
-                    break;
-            }
-        }
-
-        return clampsParams;
+      }
+      clampScales = [...clampScales, ...crossPairs];
+    }
+
+    return clampScales;
+  };
+
+  /**
+   * Parses parameters from @fluid at-rule
+   * @param {Array} params - Parsed parameter nodes
+   * @returns {Object} Parsed configuration object
+   */
+  const parseAtRuleParams = (params) => {
+    const clampsParams = {
+      minWidth: config.minWidth,
+      maxWidth: config.maxWidth,
+      pairs: {},
+      prefix: "space",
+      generateAllCrossPairs: config.generateAllCrossPairs,
     };
 
-    /**
-     * Extracts pairs from parsed parameters
-     * @param {Array} params - Parsed parameter nodes
-     * @returns {Object} Pairs object with name: [min, max] entries
-     */
-    const extractPairs = params => {
-        const pairs = {};
-        const pairsStartIndex = params.findIndex(x => x.value === 'pairs');
-
-        if (pairsStartIndex === -1) return pairs;
-
-        let currentName = null;
-        let currentValues = [];
-
-        for (let i = pairsStartIndex + 1; i < params.length; i++) {
-            const param = params[i];
-            const value = param.value.replace('[', '').replace(']', '');
-            if (!value || value === '[' || value === ']') continue;
-
-            if (param.type === 'string') {
-                if (currentName && currentValues.length === 2) {
-                    pairs[currentName] = currentValues;
-                }
-                currentName = value;
-                currentValues = [];
-            } else {
-                const numValue = Number(value);
-                if (!isNaN(numValue)) currentValues.push(numValue);
-            }
-
-            if (currentName && currentValues.length === 2) {
-                pairs[currentName] = currentValues;
-            }
+    for (let i = 0; i < params.length; i++) {
+      const param = params[i];
+      const nextParam = params[i + 1];
+      if (!param || !nextParam) continue;
+      const key = param.value;
+      let value = nextParam.value.replace(/[:,]/g, "");
+
+      switch (key) {
+        case "minWidth":
+        case "maxWidth":
+          clampsParams[key] = Number(value);
+          i++;
+          break;
+        case "prefix":
+          clampsParams.prefix = value.replace(/['"]/g, "");
+          i++;
+          break;
+        case "generateAllCrossPairs":
+          clampsParams.generateAllCrossPairs = value === "true";
+          i++;
+          break;
+      }
+    }
+
+    return clampsParams;
+  };
+
+  /**
+   * Extracts pairs from parsed parameters
+   * @param {Array} params - Parsed parameter nodes
+   * @returns {Object} Pairs object with name: [min, max] entries
+   */
+  const extractPairs = (params) => {
+    const pairs = {};
+    const pairsStartIndex = params.findIndex((x) => x.value === "pairs");
+
+    if (pairsStartIndex === -1) return pairs;
+
+    let currentName = null;
+    let currentValues = [];
+
+    for (let i = pairsStartIndex + 1; i < params.length; i++) {
+      const param = params[i];
+      const value = param.value.replace("[", "").replace("]", "");
+      if (!value || value === "[" || value === "]") continue;
+
+      if (param.type === "string") {
+        if (currentName && currentValues.length === 2) {
+          pairs[currentName] = currentValues;
         }
-
-        return pairs;
+        currentName = value;
+        currentValues = [];
+      } else {
+        const numValue = Number(value);
+        if (!isNaN(numValue)) currentValues.push(numValue);
+      }
+
+      if (currentName && currentValues.length === 2) {
+        pairs[currentName] = currentValues;
+      }
+    }
+
+    return pairs;
+  };
+
+  /**
+   * Parses parameters from @ruler utility() at-rule
+   * @param {Array} params - Parsed parameter nodes
+   * @returns {Object} Parsed configuration object
+   */
+  const parseUtilityParams = (params) => {
+    const utilityParams = {
+      selector: null,
+      property: null,
+      scale: null,
+      generateAllCrossPairs: null,
+      attribute: null,
     };
 
-    /**
-     * Parses parameters from @ruler utility() at-rule
-     * @param {Array} params - Parsed parameter nodes
-     * @returns {Object} Parsed configuration object
-     */
-    const parseUtilityParams = params => {
-        const utilityParams = {
-            selector: null,
-            property: null,
-            scale: null,
-            generateAllCrossPairs: null,
-        };
-
-        for (let i = 0; i < params.length; i++) {
-            const param = params[i];
-            const nextParam = params[i + 1];
-            if (!param || !nextParam) continue;
-            const key = param.value;
-            let value = nextParam.value.replace(/[:,]/g, '');
-
-            switch (key) {
-                case 'selector':
-                case 'scale':
-                    utilityParams[key] = value.replace(/['"]/g, '');
-                    i++;
-                    break;
-                case 'property':
-                    // Check if it's an array (next token is '[')
-                    if (nextParam.value === '[') {
-                        // It's an array - collect values until we hit ']'
-                        const arrayValues = [];
-                        i += 2; // Skip 'property' and '['
-                        while (i < params.length && params[i].value !== ']') {
-                            if (params[i].type === 'string') {
-                                arrayValues.push(params[i].value);
-                            }
-                            i++;
-                        }
-                        utilityParams.property = arrayValues;
-                    } else {
-                        // Single value
-                        utilityParams.property = value.replace(/['"]/g, '');
-                        i++;
-                    }
-                    break;
-                case 'generateAllCrossPairs':
-                    utilityParams.generateAllCrossPairs = value === 'true';
-                    i++;
-                    break;
+    for (let i = 0; i < params.length; i++) {
+      const param = params[i];
+      const nextParam = params[i + 1];
+      if (!param || !nextParam) continue;
+      const key = param.value;
+      let value = nextParam.value.replace(/[:,]/g, "");
+
+      switch (key) {
+        case "selector":
+        case "scale":
+        case "attribute":
+          utilityParams[key] = value.replace(/['"]/g, "");
+          i++;
+          break;
+        case "property":
+          // Check if it's an array (next token is '[')
+          if (nextParam.value === "[") {
+            // It's an array - collect values until we hit ']'
+            const arrayValues = [];
+            i += 2; // Skip 'property' and '['
+            while (i < params.length && params[i].value !== "]") {
+              if (params[i].type === "string") {
+                arrayValues.push(params[i].value);
+              }
+              i++;
             }
-        }
-
-        return utilityParams;
-    };
-
-    /**
-     * Processes @fluid at-rule and generates CSS custom properties
-     * @param {Object} atRule - PostCSS at-rule node
-     */
-    const processFluidAtRule = atRule => {
-        const { nodes } = CSSValueParser(atRule.params);
-        const params = nodes[0].nodes.filter(
-            x =>
-                ['word', 'string'].includes(x.type) &&
-                x.value !== '{' &&
-                x.value !== '}'
+            utilityParams.property = arrayValues;
+          } else {
+            // Single value
+            utilityParams.property = value.replace(/['"]/g, "");
+            i++;
+          }
+          break;
+        case "generateAllCrossPairs":
+          utilityParams.generateAllCrossPairs = value === "true";
+          i++;
+          break;
+      }
+    }
+
+    return utilityParams;
+  };
+
+  /**
+   * Processes @fluid at-rule and generates CSS custom properties
+   * @param {Object} atRule - PostCSS at-rule node
+   */
+  const processFluidAtRule = (atRule) => {
+    const { nodes } = CSSValueParser(atRule.params);
+    const params = nodes[0].nodes.filter(
+      (x) =>
+        ["word", "string"].includes(x.type) &&
+        x.value !== "{" &&
+        x.value !== "}",
+    );
+
+    const clampsParams = parseAtRuleParams(params);
+    clampsParams.pairs = extractPairs(params);
+
+    if (Object.keys(clampsParams.pairs).length === 0) {
+      throw new Error("[postcss-ruler] No pairs defined in @ruler scale()");
+    }
+
+    const clampPairs = Object.entries(clampsParams.pairs).map(
+      ([name, values]) => ({ name, values }),
+    );
+    const clampScale = generateClamps({
+      ...clampsParams,
+      pairs: clampPairs,
+    });
+
+    // Store the scale for later use by utility classes
+    scales[clampsParams.prefix] = clampScale;
+
+    const postcss = require("postcss");
+    const root = postcss.root();
+
+    clampScale.forEach((step) => {
+      root.append(
+        postcss.decl({
+          prop: `--${clampsParams.prefix}-${step.label}`,
+          value: step.clamp,
+        }),
+      );
+    });
+
+    atRule.replaceWith(root.nodes);
+  };
+
+  /**
+   * Processes @ruler utility() at-rule and generates utility classes
+   * @param {Object} atRule - PostCSS at-rule node
+   */
+  const processUtilityAtRule = (atRule) => {
+    const postcss = require("postcss");
+    const { nodes } = CSSValueParser(atRule.params);
+    const params = nodes[0].nodes.filter(
+      (x) =>
+        ["word", "string", "function"].includes(x.type) &&
+        x.value !== "{" &&
+        x.value !== "}",
+    );
+
+    const utilityParams = parseUtilityParams(params);
+
+    // Validate attribute-specific constraints first
+    if (utilityParams.attribute !== null) {
+      if (utilityParams.attribute === "") {
+        throw new Error(
+          '[postcss-ruler] @ruler utility() attribute parameter cannot be empty',
         );
-
-        const clampsParams = parseAtRuleParams(params);
-        clampsParams.pairs = extractPairs(params);
-
-        if (Object.keys(clampsParams.pairs).length === 0) {
-            throw new Error(
-                '[postcss-ruler] No pairs defined in @ruler scale()'
-            );
-        }
-
-        const clampPairs = Object.entries(clampsParams.pairs).map(
-            ([name, values]) => ({ name, values })
+      }
+      if (!/^[a-zA-Z0-9_-]+$/.test(utilityParams.attribute)) {
+        throw new Error(
+          '[postcss-ruler] @ruler utility() attribute parameter must contain only letters, numbers, hyphens, and underscores',
         );
-        const clampScale = generateClamps({
-            ...clampsParams,
-            pairs: clampPairs,
-        });
-
-        // Store the scale for later use by utility classes
-        scales[clampsParams.prefix] = clampScale;
-
-        const postcss = require('postcss');
-        const root = postcss.root();
-
-        clampScale.forEach(step => {
-            root.append(
-                postcss.decl({
-                    prop: `--${clampsParams.prefix}-${step.label}`,
-                    value: step.clamp,
-                })
-            );
-        });
-
-        atRule.replaceWith(root.nodes);
-    };
-
-    /**
-     * Processes @ruler utility() at-rule and generates utility classes
-     * @param {Object} atRule - PostCSS at-rule node
-     */
-    const processUtilityAtRule = atRule => {
-        const postcss = require('postcss');
-        const { nodes } = CSSValueParser(atRule.params);
-        const params = nodes[0].nodes.filter(
-            x =>
-                ['word', 'string', 'function'].includes(x.type) &&
-                x.value !== '{' &&
-                x.value !== '}'
+      }
+    }
+
+    // Validate required parameters
+    if (!utilityParams.selector && !utilityParams.attribute) {
+      throw new Error(
+        '[postcss-ruler] @ruler utility() requires either "selector" or "attribute" parameter',
+      );
+    }
+    if (!utilityParams.property) {
+      throw new Error(
+        '[postcss-ruler] @ruler utility() requires a "property" parameter',
+      );
+    }
+    if (!utilityParams.scale) {
+      throw new Error(
+        '[postcss-ruler] @ruler utility() requires a "scale" parameter',
+      );
+    }
+
+    // Check if scale exists
+    const scale = scales[utilityParams.scale];
+    if (!scale) {
+      throw new Error(
+        `[postcss-ruler] Scale "${utilityParams.scale}" not found. Define it with @ruler scale() first.`,
+      );
+    }
+
+    // Determine which scale items to use
+    let scaleItems = scale;
+    if (utilityParams.generateAllCrossPairs === false) {
+      // Filter out cross-pairs (items with hyphens in label)
+      scaleItems = scale.filter((item) => !item.label.includes("-"));
+    }
+
+    // Normalize property to array
+    const properties = Array.isArray(utilityParams.property)
+      ? utilityParams.property
+      : [utilityParams.property];
+
+    // Generate utility classes as PostCSS nodes
+    const rules = scaleItems.map((item) => {
+      let ruleSelector;
+      let ruleValue;
+
+      if (utilityParams.attribute) {
+        // Attribute mode: [data-attr="value"] or .class[data-attr="value"]
+        const attrSelector = `[${utilityParams.attribute}="${item.label}"]`;
+        ruleSelector = utilityParams.selector
+          ? `${utilityParams.selector}${attrSelector}`
+          : attrSelector;
+        ruleValue = `var(--${utilityParams.scale}-${item.label})`;
+      } else {
+        // Class mode (existing behavior)
+        ruleSelector = `${utilityParams.selector}-${item.label}`;
+        ruleValue = item.clamp;
+      }
+
+      const rule = postcss.rule({ selector: ruleSelector });
+
+      properties.forEach((prop) => {
+        rule.append(postcss.decl({ prop, value: ruleValue }));
+      });
+
+      return rule;
+    });
+
+    atRule.replaceWith(rules);
+  };
+
+  /**
+   * Processes inline fluid functions in declarations
+   * @param {Object} decl - PostCSS declaration node
+   */
+  const processFluidDeclaration = (decl) => {
+    const regex = /ruler\.fluid\(([^)]+)\)/g;
+    let newValue = decl.value;
+    let match;
+
+    while ((match = regex.exec(decl.value)) !== null) {
+      const args = match[1]
+        .split(",")
+        .map((s) => s.trim())
+        .map(Number);
+      let [minSize, maxSize, minWidth, maxWidth] = args;
+
+      minWidth = minWidth || config.minWidth;
+      maxWidth = maxWidth || config.maxWidth;
+
+      if (!minSize || !maxSize) {
+        throw new Error(
+          "[postcss-ruler] ruler.fluid() requires minSize and maxSize",
         );
+      }
 
-        const utilityParams = parseUtilityParams(params);
-
-        // Validate required parameters
-        if (!utilityParams.selector) {
-            throw new Error(
-                '[postcss-ruler] @ruler utility() requires a "selector" parameter'
-            );
-        }
-        if (!utilityParams.property) {
-            throw new Error(
-                '[postcss-ruler] @ruler utility() requires a "property" parameter'
-            );
-        }
-        if (!utilityParams.scale) {
-            throw new Error(
-                '[postcss-ruler] @ruler utility() requires a "scale" parameter'
-            );
-        }
-
-        // Check if scale exists
-        const scale = scales[utilityParams.scale];
-        if (!scale) {
-            throw new Error(
-                `[postcss-ruler] Scale "${utilityParams.scale}" not found. Define it with @ruler scale() first.`
-            );
-        }
-
-        // Determine which scale items to use
-        let scaleItems = scale;
-        if (utilityParams.generateAllCrossPairs === false) {
-            // Filter out cross-pairs (items with hyphens in label)
-            scaleItems = scale.filter(item => !item.label.includes('-'));
-        }
-
-        // Normalize property to array
-        const properties = Array.isArray(utilityParams.property)
-            ? utilityParams.property
-            : [utilityParams.property];
-
-        // Generate utility classes as PostCSS nodes
-        const rules = scaleItems.map(item => {
-            const selector = `${utilityParams.selector}-${item.label}`;
-            const rule = postcss.rule({ selector });
-
-            properties.forEach(prop => {
-                rule.append(postcss.decl({ prop, value: item.clamp }));
-            });
-
-            return rule;
-        });
-
-        atRule.replaceWith(rules);
-    };
-
-    /**
-     * Processes inline fluid functions in declarations
-     * @param {Object} decl - PostCSS declaration node
-     */
-    const processFluidDeclaration = decl => {
-        const regex = /ruler\.fluid\(([^)]+)\)/g;
-        let newValue = decl.value;
-        let match;
-
-        while ((match = regex.exec(decl.value)) !== null) {
-            const args = match[1].split(',').map(s => s.trim()).map(Number);
-            let [minSize, maxSize, minWidth, maxWidth] = args;
-
-            minWidth = minWidth || config.minWidth;
-            maxWidth = maxWidth || config.maxWidth;
-
-            if (!minSize || !maxSize) {
-                throw new Error(
-                    '[postcss-ruler] ruler.fluid() requires minSize and maxSize'
-                );
-            }
-
-            const clampValue = calculateClamp({
-                minSize,
-                maxSize,
-                minWidth,
-                maxWidth,
-            });
-
-            newValue = newValue.replace(match[0], clampValue);
-        }
-
-        if (newValue !== decl.value) {
-            decl.value = newValue;
+      const clampValue = calculateClamp({
+        minSize,
+        maxSize,
+        minWidth,
+        maxWidth,
+      });
+
+      newValue = newValue.replace(match[0], clampValue);
+    }
+
+    if (newValue !== decl.value) {
+      decl.value = newValue;
+    }
+  };
+
+  return {
+    postcssPlugin: "ruler",
+    AtRule: {
+      ruler: (atRule) => {
+        if (atRule.params.startsWith("scale(")) {
+          return processFluidAtRule(atRule);
+        } else if (atRule.params.startsWith("utility(")) {
+          return processUtilityAtRule(atRule);
         }
-    };
-
-    return {
-        postcssPlugin: 'ruler',
-        AtRule: {
-            ruler: atRule => {
-                if (atRule.params.startsWith('scale(')) {
-                    return processFluidAtRule(atRule);
-                } else if (atRule.params.startsWith('utility(')) {
-                    return processUtilityAtRule(atRule);
-                }
-            },
-        },
-        Declaration(decl) {
-            processFluidDeclaration(decl);
-        },
-    };
+      },
+    },
+    Declaration(decl) {
+      processFluidDeclaration(decl);
+    },
+  };
 };
 
 module.exports.postcss = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-ruler",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "PostCSS plugin to generate fluid scales and values.",
   "main": "index.js",
   "files": [