feat(documentation): add story to document spacing

packages/documentation/src/stories/utilities/spacing/spacing.docs.mdx

@@ -1,11 +1,82 @@
-import { Meta } from '@storybook/blocks';
+import { Canvas, Controls, Meta } from '@storybook/blocks';
 import * as SpacingStories from './spacing.stories';
 
 <Meta of={SpacingStories} />
 
 # Spacing
 
-<div className="alert alert-info">
-  <h2 className="alert-heading">TODO:</h2>
-  <p>Document differences to bootstrap and link over for the rest.</p>
+<div className="lead">
+  Spacing values bring a uniform and consistent distance between elements.
+
+By adhering to standardized spacing guidelines, we maintain visual alignment and
+improve the overall user interface.
+
+</div>
+
+<div class="alert alert-warning mb-bigger-big">
+  <h2 class="alert-heading">Sizing variables are deprecated</h2>
+  <p>
+    The current set of the post-specific sizing variables is deprecated in favour of a new naming
+    system that is consistent with the Design. For further information, please read the
+    <a href="https://github.com/swisspost/design-system/discussions/588">
+      discussion on sizing variables on GitHub
+    </a>
+    and have a look at the
+    <a href="https://www.figma.com/file/ojCcgC5Zd12eUSzq6V5m24/Foundations?node-id=3%3A2&t=l8qimsXlxeMLOzs6-0">
+      implementation in Figma.
+    </a>
+  </p>
+  <p>
+    <b>There is a new solution with updated naming system up coming for spacing sizes.</b>
+  </p>
 </div>
+
+## Padding & Margin
+
+Padding and margin can be set using `p*` and `m*` prefixes.
+
+You can apply the desired margin / padding all around an element using the prefix alone ( `m-*` / `p-*` ), or you can specify a position (ex: `pt-` , `pb-` , `pe-` , `ps-` respectively for a padding at top, bottom, right and left). You can also set a margin/padding along the horizontal axis (i.e. right and left) using `px-` / `mx-` or along the vertical axis (i.e. top and bottom) using `py`- / `my-` .
+
+Bootstrap offers spacing classes with suffixes going from 0 to 5 ( `*-0` , `*-1` , `*-2` , ...) (see [Bootstrap Spacing](https://getbootstrap.com/docs/5.2/utilities/spacing/) for reference).
+
+Post sizes can be used in the same way: by adding the name of the desired size to a prefix (to find out which size name to use, see the "Size name in classes" column in the reference table on the [Sizing page](/?path=/docs/utilities-sizing--docs) or use the demo below).
+
+### Example
+
+<Canvas of={SpacingStories.Default} />
+<div className="hide-col-default">
+  <Controls of={SpacingStories.Default} />
+</div>
+
+### Negative margin
+
+In CSS, margin properties can utilize negative values (padding cannot).
+
+The syntax is nearly the same as the default, positive margin utilities, but with the addition of n before the requested size. For example `mt-n3` would be the opposite of `mt-3`.
+
+## Responsive behavior
+
+By default, the above classes apply to all breakpoints.
+
+If you need to change the size or spacing of an element based on the breakpoint, you should
+mention it in the class name using one of the following infixes: `-sm-`, `-rg-`, `-md-`, `-lg-`, `-xl-`, `-xxl-`.
+When a breakpoint is specified, the size applies to that breakpoint and to all those that are
+larger.
+
+Another way to define a responsive size is to use the `-r` suffix. It allows to obtain a size which updates automatically and consistently depending on the breakpoint, without having to specify anything manually.
+
+### Example
+
+##### Manually specifying breakpoints
+
+The square below has a "big" padding from the large (-lg-) breakpoint and a "regular"
+padding below.
+
+<Canvas of={SpacingStories.responsiveExample} />
+
+##### Using automatic responsive behavior
+
+The square below has a "large" responsive padding, which means the padding size
+automatically changes based on the breakpoint but remains visually consistent.
+
+<Canvas of={SpacingStories.automaticResponsiveExample} />

packages/documentation/src/stories/utilities/spacing/spacing.stories.ts

@@ -1,15 +1,165 @@
-import { Meta, StoryObj } from '@storybook/web-components';
+import type { Args, Meta, StoryObj, StoryContext } from '@storybook/web-components';
 import { BADGE } from '../../../../.storybook/constants';
+import { html } from 'lit/static-html.js';
+
+const sizingOptions = [
+  '0',
+  '1',
+  '2',
+  '3',
+  '4',
+  '5',
+  'auto',
+  'hair',
+  'line',
+  'micro',
+  'mini',
+  'small-regular',
+  'regular',
+  'small-large',
+  'large',
+  'big',
+  'bigger-big',
+  'small-huge',
+  'huge',
+  'giant',
+  'bigger-giant',
+];
+
+const positionOptions = {
+  '': 'All around',
+  'x': 'Along the horizontal axis',
+  'y': 'Along the vertical axis',
+  't': 'At the top',
+  'b': 'At the bottom',
+  'r': 'To the right',
+  'l': 'To the left',
+};
 
 const meta: Meta = {
   title: 'Utilities/Spacing',
   parameters: {
-    badges: [BADGE.TODO],
+    badges: [BADGE.NEEDS_REVISION],
+  },
+  args: {
+    marginSize: 'regular',
+    marginPosition: '',
+    paddingSize: 'regular',
+    paddingPosition: '',
+  },
+  argTypes: {
+    marginSize: {
+      name: 'Margin size',
+      description: 'Sets the size of the Margin.',
+      control: {
+        type: 'select',
+      },
+      options: sizingOptions,
+      table: {
+        category: 'General',
+      },
+    },
+    marginPosition: {
+      name: 'Margin Position',
+      description: 'Sets the position of the Margin.',
+      control: {
+        type: 'select',
+        labels: positionOptions,
+      },
+      options: Object.keys(positionOptions),
+      table: {
+        category: 'General',
+      },
+    },
+    paddingSize: {
+      name: 'Padding size',
+      description: 'Sets the size of the Padding.',
+      control: {
+        type: 'select',
+      },
+      options: sizingOptions,
+      table: {
+        category: 'General',
+      },
+    },
+    paddingPosition: {
+      name: 'Pading Position',
+      description: 'Sets the position of the Padding.',
+      control: {
+        type: 'select',
+        labels: positionOptions,
+      },
+      options: Object.keys(positionOptions),
+      table: {
+        category: 'General',
+      },
+    },
   },
 };
 
 export default meta;
 
 type Story = StoryObj;
 
-export const Default: Story = {};
+export const Default: Story = {
+  render: (args: Args) => {
+    return html`
+      <!-- Demo -->
+      <div class="bg-primary p-regular d-flex align-items-start">
+        <div class="flex-fill d-flex">
+          <div class="bg-petrol">
+            <div
+              class="bg-petrol-bright border border-dark h-bigger-giant m${args.marginPosition}-${args.marginSize} p${args.paddingPosition}-${args.paddingSize} w-bigger-giant"
+            >
+              <div class="bg-light h-100"></div>
+            </div>
+          </div>
+        </div>
+
+        <!-- Legend -->
+        <ul class="ps-regular text-white">
+          <li class="d-flex align-items-center mb-regular">
+            <div class="bg-petrol h-regular w-regular me-mini"></div>
+            <span>margin</span>
+          </li>
+          <li class="d-flex align-items-center mb-regular">
+            <div class="bg-petrol-bright h-regular w-regular me-mini"></div>
+            <span>padding</span>
+          </li>
+          <li class="d-flex align-items-center mb-regular">
+            <div class="bg-light h-regular w-regular me-mini"></div>
+            <span>content</span>
+          </li>
+        </ul>
+      </div>
+    `;
+  },
+};
+
+export const responsiveExample: Story = {
+  render: (args: Args) => {
+    return html`
+      <div class="bg-primary p-regular">
+        <div
+          class="border border-dark bg-petrol-bright h-bigger-giant w-bigger-giant p-regular p-lg-big"
+        >
+          <div class="bg-light h-100"></div>
+        </div>
+        <p class="text-white"><small>Resize the browser window to see changes.</small></p>
+      </div>
+    `;
+  },
+};
+
+export const automaticResponsiveExample: Story = {
+  render: (args: Args) => {
+    return html`
+      <div class="bg-primary p-regular">
+        <div class="border border-dark bg-petrol-bright h-bigger-giant w-bigger-giant p-large-r">
+          <div class="bg-light h-100"></div>
+        </div>
+        <p class="text-white"><small>Resize the browser window to see changes.</small></p>
+      </div>
+    `;
+  },
+};