Feat(web): Introduce custom Stack spacing #DS-1079

lmc-eu · Dec 4, 2023 · b40d453 · b40d453
1 parent 5bf52c1
commit b40d453
Show file tree

Hide file tree

Showing 5 changed files with 178 additions and 54 deletions.
diff --git a/packages/web/src/scss/components/Stack/README.md b/packages/web/src/scss/components/Stack/README.md
@@ -118,3 +118,87 @@ Usage with combination of spacing and dividers:
   </li>
 </ul>
 ```
+
+## Custom spacing
+
+Use CSS custom properties to define custom spacing between items in `Stack--hasSpacing`. Set the `--stack-spacing`
+property to spacing token value which are defined on the `:root` element. E.g. `--stack-spacing: var(--spirit-space-800)`.
+This will set the spacing to `var(--spirit-space-800)` for all breakpoints.
+
+```html
+<ul class="Stack Stack--hasSpacing" style="--stack-spacing: var(--spirit-space-1200)">
+  <li>
+    <div>Block 1</div>
+  </li>
+  <li>
+    <div>Block 2</div>
+  </li>
+  <li>
+    <div>Block 3</div>
+  </li>
+</ul>
+```
+
+ℹ️ We highly discourage you from using absolute values like `--stack-spacing: 1rem`. It will work, but you will lose
+the consistency between the spacing and the design tokens.
+
+If you need to set custom spacing from a specific breakpoint, use the `--stack-spacing-{breakpoint}` property.
+E.g. `--stack-spacing-tablet: var(--spirit-space-800)`. The breakpoint value must be one of the breakpoint tokens
+and for the `mobile` breakpoint you don't need the suffix at all. The spacing is set to all larger breakpoints
+automatically if you don't set them explicitly. E.g. if you set only `--stack-spacing-tablet: var(--spirit-space-800)`
+the spacing will be set to `var(--spirit-space-800)` for `tablet` and `desktop` breakpoints too and on the `mobile`
+breakpoint the default spacing will be used.
+
+Custom spacing from tablet up:
+
+```html
+<ul class="Stack Stack--hasSpacing" style="--stack-spacing-tablet: var(--spirit-space-1200)">
+  <li>
+    <div>Block 1</div>
+  </li>
+  <li>
+    <div>Block 2</div>
+  </li>
+  <li>
+    <div>Block 3</div>
+  </li>
+</ul>
+```
+
+Custom spacing for each breakpoint:
+
+```html
+<ul
+  class="Stack Stack--hasSpacing"
+  style="--stack-spacing: var(--spirit-space-800); --stack-spacing-tablet: var(--spirit-space-1000); --stack-spacing-desktop: var(--spirit-space-1200)"
+>
+  <li>
+    <div>Block 1</div>
+  </li>
+  <li>
+    <div>Block 2</div>
+  </li>
+  <li>
+    <div>Block 3</div>
+  </li>
+</ul>
+```
+
+The custom spacing works with dividers too.
+
+```html
+<ul
+  class="Stack Stack--hasSpacing Stack--hasIntermediateDividers Stack--hasStartDivider Stack--hasEndDivider"
+  style="--stack-spacing: var(--spirit-space-800)"
+>
+  <li>
+    <div>Block 1</div>
+  </li>
+  <li>
+    <div>Block 2</div>
+  </li>
+  <li>
+    <div>Block 3</div>
+  </li>
+</ul>
+```
diff --git a/packages/web/src/scss/components/Stack/_Stack.scss b/packages/web/src/scss/components/Stack/_Stack.scss
@@ -1,5 +1,6 @@
 @use 'sass:math';
 @use 'theme';
+@use '../../tools/breakpoint';
 
 .Stack {
     display: grid;
@@ -9,7 +10,22 @@
 }
 
 .Stack--hasSpacing {
-    gap: theme.$gap;
+    $property-name: --stack-spacing;
+    $fallback: theme.$gap;
+
+    @each $breakpoint-name, $breakpoint-value in theme.$breakpoints {
+        @if $breakpoint-value > 0 {
+            $property-name: --stack-spacing-#{$breakpoint-name};
+        }
+
+        @include breakpoint.up($breakpoint-value) {
+            --gap: var(#{$property-name}, #{$fallback});
+        }
+
+        $fallback: var(#{$property-name}, #{$fallback});
+    }
+
+    gap: var(--gap);
 }
 
 .Stack--hasSpacing.Stack--hasStartDivider,
@@ -29,11 +45,11 @@
 
 .Stack--hasSpacing.Stack--hasStartDivider > *,
 .Stack--hasSpacing.Stack--hasEndDivider > * {
-    padding-block: math.div(theme.$gap, 2);
+    padding-block: calc(var(--gap) / 2);
 }
 
 .Stack--hasSpacing.Stack--hasIntermediateDividers > * {
-    padding-block: theme.$gap;
+    padding-block: var(--gap);
 }
 // stylelint-enable
 
@@ -62,9 +78,9 @@
 }
 
 .Stack--hasSpacing.Stack--hasStartDivider > :first-child {
-    padding-block-start: theme.$gap;
+    padding-block-start: var(--gap);
 }
 
 .Stack--hasSpacing.Stack--hasEndDivider > :last-child {
-    padding-block-end: theme.$gap;
+    padding-block-end: var(--gap);
 }
diff --git a/packages/web/src/scss/components/Stack/_theme.scss b/packages/web/src/scss/components/Stack/_theme.scss
@@ -1,4 +1,5 @@
 @use '@tokens' as tokens;
 
+$breakpoints: tokens.$breakpoints;
 $border: tokens.$border-width-100 tokens.$border-style-100 tokens.$border-secondary-default;
 $gap: tokens.$space-600;
diff --git a/packages/web/src/scss/components/Stack/index.html b/packages/web/src/scss/components/Stack/index.html
@@ -1,5 +1,4 @@
-{{#> layout/plain }}
-
+{{#> layout/plain }} {{setVar "blocks" "Block 1" "Block 2" "Block 3" }}
 <section class="docs-Section">
 
   <h2 class="docs-Heading">Stacked Form Fields</h2>
@@ -18,7 +17,7 @@ <h2 class="docs-Heading">Stacked Form Fields</h2>
     </div>
 
   </div>
-    
+
 </section>
 
 <section class="docs-Section">
@@ -28,21 +27,13 @@ <h2 class="docs-Heading">Stacked Blocks</h2>
   <div class="docs-Stack docs-Stack--stretch">
 
     <ul class="Stack">
+    {{#each @root.blocks as |block|}}
       <li>
         <div class="docs-Box">
-          Block 1
-        </div>
-      </li>
-      <li>
-        <div class="docs-Box">
-          Block 2
-        </div>
-      </li>
-      <li>
-        <div class="docs-Box">
-          Block 3
+          {{block}}
         </div>
       </li>
+    {{/each}}
     </ul>
 
   </div>
@@ -56,21 +47,13 @@ <h2 class="docs-Heading">Stacked Blocks with Vertical Spacing</h2>
   <div class="docs-Stack docs-Stack--stretch">
 
     <ul class="Stack Stack--hasSpacing">
+      {{#each @root.blocks as |block|}}
       <li>
         <div class="docs-Box">
-          Block 1
-        </div>
-      </li>
-      <li>
-        <div class="docs-Box">
-          Block 2
-        </div>
-      </li>
-      <li>
-        <div class="docs-Box">
-          Block 3
+          {{block}}
         </div>
       </li>
+      {{/each}}
     </ul>
 
   </div>
@@ -84,23 +67,15 @@ <h2 class="docs-Heading">Stacked Blocks with Inner Dividers and Vertical Spacing
   <div class="docs-Stack docs-Stack--stretch">
 
     <ul class="Stack Stack--hasIntermediateDividers Stack--hasSpacing">
+      {{#each @root.blocks as |block|}}
       <li>
         <div class="docs-Box">
-          Block 1
-        </div>
-      </li>
-      <li>
-        <div class="docs-Box">
-          Block 2
-        </div>
-      </li>
-      <li>
-        <div class="docs-Box">
-          Block 3
+          {{block}}
         </div>
       </li>
+      {{/each}}
     </ul>
-    
+
   </div>
 
 </section>
@@ -112,21 +87,33 @@ <h2 class="docs-Heading">Stacked Blocks with Inner and Outer Dividers and Vertic
   <div class="docs-Stack docs-Stack--stretch">
 
     <ul class="Stack Stack--hasIntermediateDividers Stack--hasEndDivider Stack--hasStartDivider Stack--hasSpacing">
+      {{#each @root.blocks as |block|}}
       <li>
         <div class="docs-Box">
-          Block 1
-        </div>
-      </li>
-      <li>
-        <div class="docs-Box">
-          Block 2
+          {{block}}
         </div>
       </li>
+      {{/each}}
+    </ul>
+
+  </div>
+
+</section>
+
+<section class="docs-Section">
+
+  <h2 class="docs-Heading">Stacked Blocks with Inner Dividers without Vertical Spacing</h2>
+
+  <div class="docs-Stack docs-Stack--stretch">
+
+    <ul class="Stack Stack--hasIntermediateDividers">
+      {{#each @root.blocks as |block|}}
       <li>
         <div class="docs-Box">
-          Block 3
+          {{block}}
         </div>
       </li>
+      {{/each}}
     </ul>
 
   </div>
@@ -135,26 +122,58 @@ <h2 class="docs-Heading">Stacked Blocks with Inner and Outer Dividers and Vertic
 
 <section class="docs-Section">
 
-  <h2 class="docs-Heading">Stacked Blocks with Inner Dividers without Vertical Spacing</h2>
+  <h2 class="docs-Heading">Stacked Blocks with Custom Spacing</h2>
 
   <div class="docs-Stack docs-Stack--stretch">
 
-    <ul class="Stack Stack--hasIntermediateDividers">
+    <ul class="Stack Stack--hasSpacing" style="--stack-spacing: var(--spirit-space-1200)">
+      {{#each @root.blocks as |block|}}
       <li>
         <div class="docs-Box">
-          Block 1
+          {{block}}
         </div>
       </li>
+      {{/each}}
+    </ul>
+
+  </div>
+
+</section>
+
+<section class="docs-Section">
+
+  <h2 class="docs-Heading">Stacked Blocks with Custom Spacing from Tablet Breakpoint</h2>
+
+  <div class="docs-Stack docs-Stack--stretch">
+
+    <ul class="Stack Stack--hasSpacing" style="--stack-spacing-tablet: var(--spirit-space-1200)">
+      {{#each @root.blocks as |block|}}
       <li>
         <div class="docs-Box">
-          Block 2
+          {{block}}
         </div>
       </li>
+      {{/each}}
+    </ul>
+
+  </div>
+
+</section>
+
+<section class="docs-Section">
+
+  <h2 class="docs-Heading">Stacked Blocks with Custom Spacing for Each Breakpoint</h2>
+
+  <div class="docs-Stack docs-Stack--stretch">
+
+    <ul class="Stack Stack--hasSpacing" style="--stack-spacing: var(--spirit-space-100);--stack-spacing-tablet: var(--spirit-space-1000);--stack-spacing-desktop: var(--spirit-space-1200)">
+      {{#each @root.blocks as |block|}}
       <li>
         <div class="docs-Box">
-          Block 3
+          {{block}}
         </div>
       </li>
+      {{/each}}
     </ul>
 
   </div>

diff --git a/packages/web/src/scss/foundation/_tokens.scss b/packages/web/src/scss/foundation/_tokens.scss
@@ -4,4 +4,8 @@
     @each $breakpoint-name, $breakpoint-value in tokens.$breakpoints {
         --spirit-breakpoint-#{$breakpoint-name}: #{$breakpoint-value};
     }
+
+    @each $space-name, $space-value in tokens.$spaces {
+        --spirit-space-#{$space-name}: #{$space-value};
+    }
 }