Merge branch 'main' of github.com:styleframe-dev/styleframe

Author: alexgrozav

.changeset/add-figma-plugin.md

@@ -20,8 +20,7 @@
 		"@styleframe/testing-integration",
 		"@styleframe/docs",
 		"@styleframe/app",
-		"@styleframe/storybook",
-		"@styleframe/figma"
+		"@styleframe/storybook"
 	],
 	"___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
 		"onlyUpdatePeerDependentsWhenOutOfRange": true

.changeset/config.json

@@ -157,6 +157,7 @@ import { useFluidViewport, useFluidFontSize, useFluidClamp } from '@styleframe/p
 5. **NEVER use arbitrary CSS values without `css` template literal for complex expressions**
 6. **NEVER forget to export the Styleframe instance as default**
 7. **NEVER use appearance-based names** - Use semantic names (e.g., `color.primary` not `color.blue`)
+8. **NEVER use named exports in index files** - Use `export *` for all re-exports in index files
 
 ---
 

.claude/CLAUDE.md

@@ -139,6 +139,34 @@ createPadding({ sm: ref(spacingSm) }, [hover, focus]);
 
 **IMPORTANT:** Always invoke the creator function. Defining the utility without calling it produces no CSS.
 
+### Spacing Utility Composables
+
+Spacing utilities (`useMarginUtility`, `usePaddingUtility`, `useGapUtility`, `useSpaceUtility`) support **multiplier values** that generate `calc()` expressions:
+
+```ts
+import { useMarginUtility, usePaddingUtility, useGapUtility } from '@styleframe/theme';
+
+// Create utility with named values
+const createMargin = useMarginUtility(s, {
+    sm: ref(spacingSm),
+    md: ref(spacingMd),
+});
+
+// Add multiplier values using array syntax (with @ prefix)
+createMargin(["@1.5", "@2", "@0.5", "@-1"]);
+
+// Generates:
+// ._margin:1.5 { margin: calc(var(--spacing) * 1.5); }
+// ._margin:2 { margin: calc(var(--spacing) * 2); }
+// ._margin:0.5 { margin: calc(var(--spacing) * 0.5); }
+// ._margin:-1 { margin: calc(var(--spacing) * -1); }
+```
+
+**Supported multiplier formats (with @ prefix):**
+- Integers: `@1`, `@2`, `@3`
+- Decimals: `@0.5`, `@1.5`, `@2.25`
+- Negative: `@-1`, `@-0.5` (for negative margins)
+
 ### modifier(name, factory)
 
 Creates reusable utility modifiers.

.claude/styleframe-api.md

@@ -94,6 +94,41 @@ export function useSpacingUtilities(s: Styleframe) {
 }
 ```
 
+### Spacing Utilities with Multipliers
+
+Use theme composables for spacing utilities with multiplier support:
+
+```ts
+import type { Styleframe } from 'styleframe';
+import { useSpacing } from '@styleframe/theme';
+import { useMarginUtility, usePaddingUtility, useGapUtility } from '@styleframe/theme';
+
+export function useSpacingUtilities(s: Styleframe) {
+    const { ref } = s;
+    const { spacing, spacingSm, spacingMd, spacingLg } = useSpacing(s, {
+        default: '1rem',
+        sm: '0.5rem',
+        md: '1rem',
+        lg: '1.5rem',
+    } as const);
+
+    // Create utilities with named values
+    const createMargin = useMarginUtility(s, {
+        sm: ref(spacingSm),
+        md: ref(spacingMd),
+        lg: ref(spacingLg),
+    });
+
+    // Add multiplier values for flexible spacing (with @ prefix)
+    createMargin(["@1.5", "@2", "@0.5", "@-1"]);
+
+    // Generates: _margin:sm, _margin:md, _margin:lg (named)
+    //            _margin:1.5, _margin:2, etc. (multipliers with calc())
+
+    return { createMargin };
+}
+```
+
 ---
 
 ## Complete Design System Setup

.claude/styleframe-patterns.md

@@ -147,8 +147,36 @@ button({ disabled: true })
 |--------------|----------------|-----------------|
 | `ref(variable)` | Token path | `_property:token.path` |
 | `"@token.path"` | Token path | `_property:token.path` |
+| `"@1.5"` (auto-generated) | Multiplier value | `_property:1.5` |
 | `"literal"` | Wrapped value | `_property:[literal]` |
 
+### Auto-generated Values in Recipes
+
+Spacing properties (`padding`, `margin`, `gap`) support numeric multiplier values with the `@` prefix:
+
+```ts
+recipe({
+    name: 'card',
+    base: {
+        padding: '@1.5',    // → _padding:1.5 → calc(var(--spacing) * 1.5)
+        margin: '@2',       // → _margin:2 → calc(var(--spacing) * 2)
+        gap: '@0.5',        // → _gap:0.5 → calc(var(--spacing) * 0.5)
+    },
+    variants: {
+        spacing: {
+            compact: { padding: '@0.5' },
+            normal: { padding: '@1' },
+            relaxed: { padding: '@2' },
+        },
+    },
+});
+```
+
+**Supported formats:**
+- Integers: `@1`, `@2`, `@3`
+- Decimals: `@0.5`, `@1.5`, `@2.25`
+- Negative: `@-1`, `@-0.5` (useful for negative margins)
+
 ---
 
 ## Variants

.claude/styleframe-recipes.md

@@ -93,6 +93,28 @@ const { spacingXs, spacingSm, spacingMd, spacingLg, spacingXl } =
     });
 ```
 
+### Spacing Utilities with Multiplier Support
+
+Spacing utilities support multiplier values that generate `calc()` expressions:
+
+```ts
+import { useMarginUtility, usePaddingUtility, useGapUtility } from '@styleframe/theme';
+
+// Create utility with named values
+const createMargin = useMarginUtility(s, {
+    sm: ref(spacingSm),
+    md: ref(spacingMd),
+});
+
+// Add multiplier values using array syntax (with @ prefix)
+createMargin(["@1.5", "@2", "@0.5", "@-1"]);
+
+// Generates: _margin:1.5, _margin:2, _margin:0.5, _margin:-1
+// CSS: calc(var(--spacing) * multiplier)
+```
+
+**Note:** Multiplier values require the base `spacing` variable to be defined.
+
 ---
 
 ### Typography

.claude/styleframe-tokens.md

@@ -476,4 +476,26 @@ recipe({
 ```
 :::
 
+:::accordion-item{label="Can I use auto-generated spacing values in recipes?" icon="i-lucide-circle-help"}
+Yes! Spacing properties (`padding`, `margin`, `gap`) support auto-generated values using the `@` prefix with a number. These generate `calc()` expressions based on your `spacing` variable:
+
+```ts [styleframe.config.ts]
+recipe({
+    name: "card",
+    base: {
+        padding: "@1.5",  // → calc(var(--spacing) * 1.5)
+    },
+    variants: {
+        spacing: {
+            compact: { padding: "@0.5" },
+            normal: { padding: "@1" },
+            relaxed: { padding: "@2" },
+        },
+    },
+});
+```
+
+This allows flexible spacing without pre-defining every value, while keeping proportions consistent with your design system.
+:::
+
 ::

apps/docs/content/docs/02.api/10.recipes/00.index.md

@@ -83,7 +83,7 @@ Recipe field names (in camelCase) map directly to your defined utilities:
 
 ### Value Types and Class Suffixes
 
-There are three ways to specify values in recipes, each producing different class suffixes:
+There are four ways to specify values in recipes, each producing different class suffixes:
 
 #### 1. Token References using `ref()`
 
@@ -122,7 +122,38 @@ recipe({
 });
 ```
 
-#### 3. Arbitrary Values
+#### 3. Auto-generated Values
+
+For spacing properties (padding, margin, gap), you can use numeric multiplier values with the `@` prefix. These generate `calc()` expressions based on your `spacing` variable.
+
+```ts [styleframe.config.ts]
+recipe({
+    name: "card",
+    base: {
+        padding: "@1.5",     // _padding:1.5 → calc(var(--spacing) * 1.5)
+        margin: "@2",        // _margin:2 → calc(var(--spacing) * 2)
+        gap: "@0.5",         // _gap:0.5 → calc(var(--spacing) * 0.5)
+    },
+    variants: {
+        spacing: {
+            compact: { padding: "@0.5" },   // _padding:0.5
+            normal: { padding: "@1" },      // _padding:1
+            relaxed: { padding: "@1.5" },   // _padding:1.5
+        },
+    },
+});
+```
+
+Auto-generated values support:
+- **Integers**: `@1`, `@2`, `@3`
+- **Decimals**: `@0.5`, `@1.5`, `@2.25`
+- **Negative values**: `@-1`, `@-0.5` (useful for negative margins)
+
+::tip
+Auto-generated values provide flexibility without pre-defining every spacing value. They're especially useful for one-off adjustments while keeping your spacing proportional to the base `spacing` variable.
+::
+
+#### 4. Arbitrary Values
 
 Any value that isn't a token reference is treated as an arbitrary value and wrapped in brackets.
 
@@ -303,4 +334,24 @@ Examples:
 
 Class generation format can be customized via the instance's utilities selector option. See [Instance - Configuration Options](/docs/api/instance#utilitiesselector) for details.
 :::
+
+:::accordion-item{label="How do auto-generated values work in recipes?" icon="i-lucide-circle-help"}
+Auto-generated values use the `@` prefix with a numeric value (e.g., `@1.5`, `@2`, `@-1`) for spacing properties like `padding`, `margin`, and `gap`. These generate utility classes that use `calc()` expressions:
+
+```ts
+recipe({
+    name: "card",
+    base: {
+        padding: "@1.5",  // → _padding:1.5
+    },
+});
+```
+
+The generated CSS uses your `--spacing` variable:
+```css
+._padding\:1\.5 { padding: calc(var(--spacing) * 1.5); }
+```
+
+This allows flexible spacing that scales with your design system's base spacing value.
+:::
 ::

apps/docs/content/docs/02.api/10.recipes/02.output-format.md

@@ -279,7 +279,7 @@ export default s;
 
 ### `useGapUtility`
 
-Set the gap between flex or grid items.
+Set the gap between flex or grid items. Gap utilities support both named values and multiplier values.
 
 ::tabs
 :::tabs-item{icon="i-lucide-code" label="Code"}
@@ -292,19 +292,23 @@ import { useGapUtility, useGapXUtility, useGapYUtility } from "@styleframe/theme
 const s = styleframe();
 const { ref } = s;
 
-const { spacingSm, spacingMd, spacingLg } = useSpacing(s, {
+const { spacing, spacingSm, spacingMd, spacingLg } = useSpacing(s, {
+    default: '1rem',
     sm: '0.5rem',
     md: '1rem',
     lg: '1.5rem',
 } as const);
 
-useGapUtility(s, {
+const createGap = useGapUtility(s, {
     '0': '0',
     sm: ref(spacingSm),
     md: ref(spacingMd),
     lg: ref(spacingLg),
 });
 
+// Add multiplier values for flexible gap sizing (with @ prefix)
+createGap(["@1.5", "@2", "@0.5"]);
+
 useGapXUtility(s, {
     sm: ref(spacingSm),
     md: ref(spacingMd),
@@ -323,6 +327,7 @@ export default s;
 
 ```css [styleframe/index.css]
 :root {
+    --spacing: 1rem;
     --spacing--sm: 0.5rem;
     --spacing--md: 1rem;
     --spacing--lg: 1.5rem;
@@ -333,6 +338,11 @@ export default s;
 ._gap\:md { gap: var(--spacing--md); }
 ._gap\:lg { gap: var(--spacing--lg); }
 
+/* Multiplier values (with fallback) */
+._gap\:1\.5 { gap: calc(var(--spacing, 1rem) * 1.5); }
+._gap\:2 { gap: calc(var(--spacing, 1rem) * 2); }
+._gap\:0\.5 { gap: calc(var(--spacing, 1rem) * 0.5); }
+
 ._gap-x\:sm { column-gap: var(--spacing--sm); }
 ._gap-x\:md { column-gap: var(--spacing--md); }
 
@@ -346,6 +356,7 @@ export default s;
 ```html
 <div class="_display:flex _gap:md">Equal gap all around</div>
 <div class="_display:grid _gap-x:lg _gap-y:sm">Different horizontal/vertical gaps</div>
+<div class="_display:flex _gap:1.5">1.5x base spacing gap</div>
 ```
 
 :::