feat(style): remove deprecated semantic spacing tokens (#3320)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: rivka-ungar

VIBE4_CHANGELOG.md

@@ -525,12 +525,13 @@ Vibe 4 represents a major evolution of the design system, focusing on:
 - **Task**: [Monday.com Task](https://monday.monday.com/boards/10027056258/pulses/9713029006)
 - **PR**: TBD
 
-#### Design Tokens
+#### Design Tokens — Spacing
 
-- **Change**: TBD
-- **Reason**: TBD
-- **Migration**: TBD
-- **Codemod**: ❌ Manual
+- [x] **Status**: Complete
+- **Change**: Removed deprecated semantic spacing CSS custom properties (`--spacing-xs`, `--spacing-small`, `--spacing-medium`, `--spacing-large`, `--spacing-xl`, `--spacing-xxl`, `--spacing-xxxl`) from `@vibe/style`. All internal usages replaced with numeric spacing tokens (`--space-4`, `--space-8`, `--space-16`, `--space-24`, `--space-32`, `--space-48`, `--space-64`).
+- **Reason**: The numeric naming convention is more scalable, unambiguous, and consistent with modern design token practices. The semantic names (`small`, `medium`, `large`) don't scale beyond `xxxl` and create ambiguity about exact values.
+- **Migration**: Replace all usages of old spacing tokens with their numeric equivalents. Run `npx stylelint --fix "**/*.scss"` with `@vibe/style/use-new-spacing-tokens` rule enabled to auto-fix.
+- **Codemod**: ✅ Stylelint auto-fix via `@vibe/style/use-new-spacing-tokens` rule
 - **PR**: TBD
 
 <!-- Add styling changes as they are identified -->

VIBE4_MIGRATION_GUIDE.md

@@ -1314,6 +1314,54 @@ const renderer: (item: VirtualizedGridItemType, index: number, style: CSSPropert
 
 For component-specific migration details, see [VIBE4_CHANGELOG.md](./VIBE4_CHANGELOG.md).
 
+---
+
+## CSS Design Tokens
+
+### Spacing Tokens
+
+The deprecated semantic spacing CSS custom properties have been removed. Replace them with the numeric spacing tokens:
+
+| Removed Token | Replacement |
+|---|---|
+| `--spacing-xs` | `--space-4` |
+| `--spacing-small` | `--space-8` |
+| `--spacing-medium` | `--space-16` |
+| `--spacing-large` | `--space-24` |
+| `--spacing-xl` | `--space-32` |
+| `--spacing-xxl` | `--space-48` |
+| `--spacing-xxxl` | `--space-64` |
+
+**Before (v3)**
+
+```scss
+.my-component {
+  padding: var(--spacing-small) var(--spacing-medium);
+  margin-block-end: var(--spacing-large);
+  gap: var(--spacing-xs);
+}
+```
+
+**After (v4)**
+
+```scss
+.my-component {
+  padding: var(--space-8) var(--space-16);
+  margin-block-end: var(--space-24);
+  gap: var(--space-4);
+}
+```
+
+**Automated fix:** If you have the `@vibe/style` stylelint plugin configured, run:
+
+```bash
+npx stylelint --fix "**/*.scss"
+```
+
+The `@vibe/style/use-new-spacing-tokens` rule will automatically replace all legacy token references.
+
+---
+
 ## Common Migration Patterns
 
 ### Prop Renames

packages/base/src/BaseInput/BaseInput.module.scss

@@ -5,9 +5,9 @@
   position: relative;
   display: flex;
   align-items: center;
-  gap: var(--spacing-small);
-  padding-block: var(--spacing-small);
-  padding-inline: var(--space-12) var(--spacing-xs);
+  gap: var(--space-8);
+  padding-block: var(--space-8);
+  padding-inline: var(--space-12) var(--space-4);
 
   @include vibe-text(text1, normal);
   @include smoothing-text;
@@ -22,8 +22,8 @@
   &.small {
     min-height: 32px;
     height: 32px;
-    padding-inline-start: var(--spacing-small);
-    gap: var(--spacing-xs);
+    padding-inline-start: var(--space-8);
+    gap: var(--space-4);
     @include vibe-text(text2, normal);
   }
 
@@ -35,11 +35,11 @@
   &.large {
     min-height: 48px;
     height: 48px;
-    padding-block: var(--spacing-small);
+    padding-block: var(--space-8);
   }
 
   &.rightThinnerPadding {
-    padding-inline-end: var(--spacing-medium);
+    padding-inline-end: var(--space-16);
   }
 
   &:hover {

packages/components/button/src/Button/Button.module.scss

@@ -56,11 +56,11 @@ $disabled-on-primary-color-opacity: 0.5;
 }
 
 .marginRight {
-  margin-inline-end: var(--spacing-small);
+  margin-inline-end: var(--space-8);
 }
 
 .marginLeft {
-  margin-inline-start: var(--spacing-small);
+  margin-inline-start: var(--space-8);
 }
 
 .rightFlat {
@@ -78,33 +78,33 @@ $disabled-on-primary-color-opacity: 0.5;
 }
 
 .button .leftIcon {
-  margin-inline-end: var(--spacing-small);
+  margin-inline-end: var(--space-8);
 }
 
 .button .rightIcon {
-  margin-inline-start: var(--spacing-small);
+  margin-inline-start: var(--space-8);
 }
 
 .sizeXxs {
   @include smoothing-text;
   @include vibe-text(text2, normal);
-  padding: 2px var(--spacing-xs);
+  padding: 2px var(--space-4);
   height: 16px;
   line-height: 16px;
 }
 
 .sizeXs {
   @include smoothing-text;
   @include vibe-text(text2, normal);
-  padding: var(--spacing-xs) var(--spacing-small);
+  padding: var(--space-4) var(--space-8);
   height: 24px;
   line-height: 21px;
 }
 
 .sizeSmall {
   @include smoothing-text;
   @include vibe-text(text2, normal);
-  padding: var(--spacing-xs) var(--spacing-small);
+  padding: var(--space-4) var(--space-8);
   height: 32px;
   line-height: 24px;
 }
@@ -116,14 +116,14 @@ $disabled-on-primary-color-opacity: 0.5;
 .sizeMedium {
   @include smoothing-text;
   @include vibe-text(text1, normal);
-  padding: var(--spacing-small) var(--spacing-medium);
+  padding: var(--space-8) var(--space-16);
   height: 40px;
 }
 
 .sizeLarge {
   @include smoothing-text;
   @include vibe-text(text1, normal);
-  padding: 12px var(--spacing-large);
+  padding: 12px var(--space-24);
   height: 48px;
 }
 

packages/components/dialog/src/DialogContentContainer/DialogContentContainer.module.scss

@@ -3,15 +3,15 @@
 }
 
 .sizeSmall {
-  padding: var(--spacing-small);
+  padding: var(--space-8);
 }
 
 .sizeMedium {
-  padding: var(--spacing-medium);
+  padding: var(--space-16);
 }
 
 .sizeLarge {
-  padding: var(--spacing-large);
+  padding: var(--space-24);
 }
 
 .typePopover {

packages/components/layout/src/Box/_utilities.scss

@@ -6,13 +6,13 @@
 /*  stylelint-disable scss/at-if-no-null */
 $utility-spacing-vars: (
   0: 0,
-  xs: var(--spacing-xs),
-  small: var(--spacing-small),
-  medium: var(--spacing-medium),
-  large: var(--spacing-large),
-  xl: var(--spacing-xl),
-  xxl: var(--spacing-xxl),
-  xxxl: var(--spacing-xxxl)
+  xs: var(--space-4),
+  small: var(--space-8),
+  medium: var(--space-16),
+  large: var(--space-24),
+  xl: var(--space-32),
+  xxl: var(--space-48),
+  xxxl: var(--space-64)
 );
 
 $utility-border-colors-vars: (

packages/components/layout/src/Flex/Flex.tsx

@@ -98,7 +98,13 @@ const Flex = forwardRef(
       if (typeof gap === "number") {
         return { gap: `${gap}px` };
       }
-      return { gap: `var(--spacing-${gap})` };
+      const gapTokenMap: Record<string, string> = {
+        xs: "var(--space-4)",
+        small: "var(--space-8)",
+        medium: "var(--space-16)",
+        large: "var(--space-24)"
+      };
+      return { gap: gapTokenMap[gap] };
     }, [gap]);
 
     const flexStyle = useMemo(() => {

packages/components/layout/src/Flex/__tests__/__snapshots__/Flex.snapshot.test.tsx.snap

@@ -121,7 +121,7 @@ exports[`Flex renders correctly > Horizontal display > with gap 1`] = `
   className="container directionRow justifyStart alignCenter"
   style={
     {
-      "gap": "var(--spacing-large)",
+      "gap": "var(--space-24)",
     }
   }
 >

packages/components/tooltip/src/Tooltip/Tooltip.module.scss

@@ -33,13 +33,13 @@
   .content {
     word-break: break-word;
     display: inline-block;
-    padding: var(--tooltip-padding, #{var(--spacing-small) var(--spacing-medium)});
+    padding: var(--tooltip-padding, #{var(--space-8) var(--space-16)});
   }
 }
 
 .tooltip.paddingSizeMd {
   border-radius: var(--border-radius-medium);
-  padding: var(--spacing-medium);
+  padding: var(--space-16);
   @include vibe-text(text2, normal);
 }
 

packages/components/typography/src/Text/Text.module.scss

@@ -7,7 +7,7 @@ p:first-of-type.text {
 }
 
 p.text + p {
-  margin-block-start: var(--spacing-large);
+  margin-block-start: var(--space-24);
   margin-block-end: 0;
 }