mondaycom · rivka-ungar · Mar 5, 2026 · Mar 5, 2026 · Mar 5, 2026 · Mar 5, 2026
diff --git a/VIBE4_CHANGELOG.md b/VIBE4_CHANGELOG.md
@@ -505,12 +505,13 @@ Vibe 4 represents a major evolution of the design system, focusing on:
 - **Task**: [Monday.com Task](https://monday.monday.com/boards/10027056258/pulses/9713029198)
 - **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 -->

diff --git a/VIBE4_MIGRATION_GUIDE.md b/VIBE4_MIGRATION_GUIDE.md
@@ -1246,6 +1246,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

diff --git a/packages/base/src/BaseInput/BaseInput.module.scss b/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-xs);
-  padding-inline: var(--spacing-medium) var(--spacing-xs);
+  gap: var(--space-8);
+  padding-block: var(--space-4);
+  padding-inline: var(--space-16) var(--space-4);
 
   @include vibe-text(text1, normal);
   @include smoothing-text;
@@ -33,11 +33,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 {

diff --git a/packages/components/button/src/Button/Button.module.scss b/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;
 }
 

diff --git a/packages/components/dialog/src/DialogContentContainer/DialogContentContainer.module.scss b/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 {

diff --git a/packages/components/layout/src/Box/_utilities.scss b/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: (

diff --git a/packages/components/layout/src/Flex/Flex.tsx b/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(() => {

diff --git a/packages/components/tooltip/src/Tooltip/Tooltip.module.scss b/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);
 }
 

diff --git a/packages/components/typography/src/Text/Text.module.scss b/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;
 }
 
diff --git a/packages/core/src/components/AlertBanner/AlertBanner.module.scss b/packages/core/src/components/AlertBanner/AlertBanner.module.scss
@@ -38,7 +38,7 @@
   min-width: 0;
   align-items: center;
   justify-content: center;
-  padding-inline-start: var(--spacing-medium);
+  padding-inline-start: var(--space-16);
 }
 
 .closeButtonWrapper {

diff --git a/packages/core/src/components/AlertBanner/AlertBannerButton/AlertBannerButton.module.scss b/packages/core/src/components/AlertBanner/AlertBannerButton/AlertBannerButton.module.scss
@@ -9,5 +9,5 @@
 }
 
 .marginLeft {
-  margin-inline-start: var(--spacing-small);
+  margin-inline-start: var(--space-8);
 }
diff --git a/packages/core/src/components/AlertBanner/AlertBannerLink/AlertBannerLink.module.scss b/packages/core/src/components/AlertBanner/AlertBannerLink/AlertBannerLink.module.scss
@@ -13,5 +13,5 @@
 }
 
 .marginLeft {
-  margin-inline-start: var(--spacing-small);
+  margin-inline-start: var(--space-8);
 }
diff --git a/packages/core/src/components/AlertBanner/AlertBannerText/AlertBannerText.module.scss b/packages/core/src/components/AlertBanner/AlertBannerText/AlertBannerText.module.scss
@@ -5,5 +5,5 @@
 }
 
 .marginLeft {
-  margin-inline-start: var(--spacing-small);
+  margin-inline-start: var(--space-8);
 }
diff --git a/packages/core/src/components/AvatarGroup/AvatarGroup.module.scss b/packages/core/src/components/AvatarGroup/AvatarGroup.module.scss
@@ -8,5 +8,5 @@
 }
 
 .avatarContainer {
-  margin-inline-start: calc(-1 * var(--spacing-small));
+  margin-inline-start: calc(-1 * var(--space-8));
 }
diff --git a/packages/core/src/components/AvatarGroup/AvatarGroupCounter.module.scss b/packages/core/src/components/AvatarGroup/AvatarGroupCounter.module.scss
@@ -7,7 +7,7 @@
   display: flex;
   justify-content: center;
   align-items: center;
-  margin-inline-start: calc(-1 * var(--spacing-small));
+  margin-inline-start: calc(-1 * var(--space-8));
   z-index: 1;
   border: 1px solid var(--primary-background-color);
 
@@ -36,7 +36,7 @@
   }
   &.large {
     @include counterSize($avatar-size-large);
-    padding: 0 var(--spacing-xs);
+    padding: 0 var(--space-4);
   }
 
   &.primary {

diff --git a/packages/core/src/components/AvatarGroup/AvatarGroupCounterTooltipContent.module.scss b/packages/core/src/components/AvatarGroup/AvatarGroupCounterTooltipContent.module.scss
@@ -10,11 +10,11 @@
 
 .tooltipContainer {
   max-height: 300px;
-  padding-inline-end: var(--spacing-medium);
+  padding-inline-end: var(--space-16);
   align-items: flex-start !important;
   overflow-x: visible;
   overflow-y: auto;
-  margin-top: var(--spacing-small);
+  margin-top: var(--space-8);
   &:focus,
   &:focus-visible,
   &.focus-visible { /* stylelint-disable-line selector-class-pattern */

diff --git a/packages/core/src/components/BaseItem/BaseItem.module.scss b/packages/core/src/components/BaseItem/BaseItem.module.scss
@@ -3,7 +3,7 @@
 .wrapper {
   display: flex;
   align-items: center;
-  gap: var(--spacing-xs);
+  gap: var(--space-4);
   border-radius: var(--border-radius-small);
   color: var(--primary-text-color);
   cursor: pointer;
@@ -33,7 +33,7 @@
   }
 
   &.small {
-    padding: 6px var(--spacing-small);
+    padding: 6px var(--space-8);
   }
 
   &.medium {
@@ -54,7 +54,7 @@
   }
 
   .endElement {
-    padding-inline-start: var(--spacing-small);
+    padding-inline-start: var(--space-8);
     margin-inline-start: auto;
     display: flex;
   }

diff --git a/packages/core/src/components/Checkbox/Checkbox.module.scss b/packages/core/src/components/Checkbox/Checkbox.module.scss
@@ -61,7 +61,7 @@ $checkbox-size: 16px;
   @include smoothing-text;
   cursor: pointer;
   user-select: none;
-  margin-inline-start: var(--spacing-small);
+  margin-inline-start: var(--space-8);
 }
 
 /* Since it is not possible to change the design of the checkbox according to the requirements using css, */

diff --git a/packages/core/src/components/Chips/Chips.module.scss b/packages/core/src/components/Chips/Chips.module.scss
@@ -11,7 +11,7 @@
   padding: 0 8px;
   align-items: center;
   justify-content: center;
-  margin: var(--chips-margin, #{0 var(--spacing-xs)});
+  margin: var(--chips-margin, #{0 var(--space-4)});
   user-select: none;
   @include smoothing-text;
   color: var(--primary-text-color);
@@ -40,13 +40,13 @@
   .customRenderer {
     min-width: 18px;
     &.left {
-      margin-inline-end: var(--spacing-xs);
+      margin-inline-end: var(--space-4);
     }
     &.right {
-      margin-inline-start: var(--spacing-xs);
+      margin-inline-start: var(--space-4);
     }
     &.close {
-      margin-inline-start: var(--spacing-xs);
+      margin-inline-start: var(--space-4);
       color: var(--primary-text-color);
     }
   }

diff --git a/...c/components/ColorPicker/components/ColorPickerContent/ColorPickerClearButton.module.scss b/...c/components/ColorPicker/components/ColorPickerContent/ColorPickerClearButton.module.scss
@@ -1,7 +1,7 @@
 .clearColorIcon {
-  margin-inline-end: var(--spacing-small);
+  margin-inline-end: var(--space-8);
 }
 
 .clearColorButton {
-  margin-top: var(--spacing-small);
+  margin-top: var(--space-8);
 }