postcss-ruler 1.0.0 → 1.1.0

package/README.md

@@ -2,8 +2,19 @@
 
 A PostCSS plugin that generates fluid CSS scales and values using the `clamp()` function. Create responsive typography and spacing that scales smoothly between viewport sizes.
 
-## Installation
+**Inspired by [Utopia](https://utopia.fyi/)**, but designed for real-world design collaboration. Instead of strict programmatic scales, postcss-ruler lets you define exact min and max pixel values for each size. This gives you the flexibility to match design specs from tools like Figma while still getting fluid scaling behavior.
+
+## Why postcss-ruler?
+
+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
 ```
@@ -11,7 +22,6 @@ npm install postcss-ruler
 ## Usage
 
 Add the plugin to your PostCSS configuration:
-
 ```javascript
 // postcss.config.js
 module.exports = {
@@ -25,26 +35,11 @@ module.exports = {
 }
 ```
 
-Or in `.postcssrc`:
-
-```json
-{
-  "plugins": {
-    "postcss-ruler": {
-      "minWidth": 320,
-      "maxWidth": 1760,
-      "generateAllCrossPairs": false
-    }
-  }
-}
-```
-
 ## Features
 
-### 1. At-Rule Mode: Generate Fluid Scale
+### 1. Scale Generation: Create Fluid Scales
 
 Create multiple CSS custom properties from named size pairs:
-
 ```css
 @ruler scale({
   minWidth: 320,
@@ -62,7 +57,6 @@ 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);
@@ -71,19 +65,15 @@ Create multiple CSS custom properties from named size pairs:
 --space-xl: clamp(3rem, 0.9091vw + 2.7273rem, 4rem);
 ```
 
-**Usage in CSS:**
+### Understanding Cross Pairs
 
-```css
-.container {
-  padding: var(--space-md);
-  gap: var(--space-sm);
-}
-```
+Cross pairs create fluid values between any two sizes in your scale. This is useful for spacing that needs to span multiple steps.
 
-#### Cross Pairs
+For example, if you have `xs: [8, 16]` and `lg: [32, 48]`, a cross pair `xs-lg` would scale from `8px → 48px`. This gives you a larger range of motion than using `xs` or `lg` alone.
 
-Enable `generateAllCrossPairs: true` to create additional combinations between all defined pairs:
+**Without cross pairs**, you only get the sizes you explicitly define.
 
+**With `generateAllCrossPairs: true`**, you get every possible combination:
 ```css
 @ruler scale({
   prefix: 'space',
@@ -96,21 +86,103 @@ Enable `generateAllCrossPairs: true` to create additional combinations between a
 });
 ```
 
-**Generates base pairs plus cross combinations:**
+**Generates:**
+```css
+/* Your defined pairs */
+--space-xs: clamp(0.5rem, ...);
+--space-md: clamp(1.5rem, ...);
+--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 */
+```
 
+**Use case**: Section padding that needs more dramatic scaling than your base sizes allow.
 ```css
---space-xs: clamp(...);
---space-md: clamp(...);
---space-lg: clamp(...);
---space-xs-md: clamp(0.5rem, 1.3636vw + 0.3636rem, 2rem);
---space-xs-lg: clamp(0.5rem, 2.2727vw + 0.3636rem, 3rem);
---space-md-lg: clamp(1.5rem, 0.9091vw + 1.3636rem, 3rem);
+.hero {
+  padding-block: var(--space-md-xl); /* Scales across a wider range */
+}
 ```
 
-### 2. Inline Mode: Fluid Function
+### 2. Utility Class Generation: Auto-Generate Utility Classes
 
-Convert individual values directly to `clamp()` functions:
+Generate utility classes from your defined scales with complete selector flexibility:
+
+```css
+@ruler scale({
+  prefix: 'space',
+  pairs: {
+    "xs": [8, 16],
+    "sm": [16, 24],
+    "md": [24, 32]
+  }
+});
+
+/* Basic class selector */
+@ruler utility({
+  selector: '.gap',
+  property: 'gap',
+  scale: 'space'
+});
+
+/* Nested selector with & (for PostCSS nesting) */
+@ruler utility({
+  selector: '&.active',
+  property: 'padding',
+  scale: 'space'
+});
 
+/* Multiple properties */
+@ruler utility({
+  selector: '.p-block',
+  property: ['padding-top', 'padding-bottom'],
+  scale: 'space'
+});
+```
+
+**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) }
+
+&.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)
+}
+/* ... */
+```
+
+**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.
+- **ID selectors**: `#section` → `#section-xs`, `#section-sm`
+- **Element selectors**: `section` → `section-xs`, `section-sm`
+- **Parent context**: `.container &` → `.container &-xs`, etc.
+
+**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) |
+
+### 3. Inline Mode: Fluid Function
+
+Convert individual values directly to `clamp()` functions:
 ```css
 .element {
   /* Uses default minWidth/maxWidth from config */
@@ -125,7 +197,6 @@ Convert individual values directly to `clamp()` functions:
 ```
 
 **Generates:**
-
 ```css
 .element {
   font-size: clamp(1rem, 0.4545vw + 0.8636rem, 1.5rem);
@@ -169,6 +240,15 @@ ruler.fluid(minSize, maxSize[, minWidth, maxWidth])
 | `minWidth` | number | No | Minimum viewport width (uses config default) |
 | `maxWidth` | number | No | Maximum viewport width (uses config default) |
 
+### 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) |
+
 ## How It Works
 
 The plugin uses linear interpolation to create fluid values that scale smoothly between viewport sizes:
@@ -192,6 +272,62 @@ At 1760px viewport: `1.5rem` (24px)
 
 ## Use Cases
 
+### Utility-First Workflow with Fluid Scales
+
+Generate a complete set of utility classes from your design system:
+
+```css
+@ruler scale({
+  prefix: 'space',
+  generateAllCrossPairs: true,
+  pairs: {
+    "xs": [8, 16],
+    "sm": [12, 20],
+    "md": [16, 28],
+    "lg": [24, 40],
+    "xl": [32, 56]
+  }
+});
+
+/* Gap utilities */
+@ruler utility({
+  selector: '.gap',
+  property: 'gap',
+  scale: 'space'
+});
+
+/* Padding utilities */
+@ruler utility({
+  selector: '.p',
+  property: 'padding',
+  scale: 'space'
+});
+
+/* Margin utilities */
+@ruler utility({
+  selector: '.m',
+  property: 'margin',
+  scale: 'space'
+});
+
+/* Stack spacing (for flow layout) */
+@ruler utility({
+  selector: '.stack > * + *',
+  property: 'margin-top',
+  scale: 'space'
+});
+```
+
+Use in your HTML:
+```html
+<section class="p-lg gap-md">
+  <div class="stack gap-sm">
+    <h2>Heading</h2>
+    <p>Content that scales smoothly</p>
+  </div>
+</section>
+```
+
 ### Responsive Typography
 
 ```css

package/index.js

@@ -11,6 +11,9 @@ module.exports = opts => {
     };
     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
@@ -113,7 +116,6 @@ module.exports = opts => {
             minWidth: config.minWidth,
             maxWidth: config.maxWidth,
             pairs: {},
-            relativeTo: 'viewport',
             prefix: 'space',
             generateAllCrossPairs: config.generateAllCrossPairs,
         };
@@ -132,11 +134,7 @@ module.exports = opts => {
                     i++;
                     break;
                 case 'prefix':
-                    clampsParams.prefix = value.replace(/['\"]/g, '');
-                    i++;
-                    break;
-                case 'relativeTo':
-                    clampsParams.relativeTo = value.replace(/['\"]/g, '');
+                    clampsParams.prefix = value.replace(/['"]/g, '');
                     i++;
                     break;
                 case 'generateAllCrossPairs':
@@ -187,6 +185,61 @@ module.exports = opts => {
         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,
+        };
+
+        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;
+            }
+        }
+
+        return utilityParams;
+    };
+
     /**
      * Processes @fluid at-rule and generates CSS custom properties
      * @param {Object} atRule - PostCSS at-rule node
@@ -217,11 +270,90 @@ module.exports = opts => {
             pairs: clampPairs,
         });
 
-        const response = clampScale
-            .map(step => `--${clampsParams.prefix}-${step.label}: ${step.clamp};`)
-            .join('\n');
+        // 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 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(response);
+        atRule.replaceWith(rules);
     };
 
     /**
@@ -267,6 +399,8 @@ module.exports = opts => {
             ruler: atRule => {
                 if (atRule.params.startsWith('scale(')) {
                     return processFluidAtRule(atRule);
+                } else if (atRule.params.startsWith('utility(')) {
+                    return processUtilityAtRule(atRule);
                 }
             },
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-ruler",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "PostCSS plugin to generate fluid scales and values.",
   "main": "index.js",
   "files": [
@@ -37,7 +37,7 @@
   },
   "eslintConfig": {
     "parserOptions": {
-      "ecmaVersion": 2017
+      "ecmaVersion": 2018
     },
     "env": {
       "node": true,