Add documentation for the Gap utility class

packages/css/src/components/gap/README.md

@@ -2,4 +2,15 @@
 
 # Gap
 
-Use these utility classes to add consistent white space between a set of elements.
+Adds white space between a set of elements.
+
+The five sizes of [Component Space](/docs/foundation-design-tokens-space--docs) are available for the length of the gap.
+
+## Guidelines
+
+- Use this utility class to vertically separate the children of a parent element from each other.
+- It can be used on any element and sets the `gap` CSS property.
+  It also makes the element a grid container; the gap would be ignored otherwise.
+  These declarations are marked with the `!important` flag to ensure they override any other gaps and display modes.
+- To add a gap between 2 siblings, the first one can be given a [Margin Bottom](/docs/utilities-css-margin--docs) instead.
+  This may be preferable because it doesn’t change the parent’s display mode.

packages/css/src/components/gap/gap.scss

@@ -10,7 +10,9 @@
 }
 
 @each $size in map-keys($ams-sizes) {
-  .ams-gap--#{$size} {
-    gap: var(--ams-gap-#{$size}) !important;
+  @if $size != "no" {
+    .ams-gap--#{$size} {
+      grid-gap: var(--ams-gap-#{$size}) !important;
+    }
   }
 }

storybook/src/utils/Gap/Gap.docs.mdx

@@ -0,0 +1,13 @@
+{/* @license CC0-1.0 */}
+
+import { Controls, Markdown, Meta, Primary } from "@storybook/blocks";
+import * as GapStories from "./Gap.stories.tsx";
+import README from "../../../../packages/css/src/components/gap/README.md?raw";
+
+<Meta of={GapStories} />
+
+<Markdown>{README}</Markdown>
+
+<Primary />
+
+<Controls />

storybook/src/utils/Gap/Gap.stories.tsx

@@ -0,0 +1,46 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import { Meta, StoryObj } from '@storybook/react'
+import type { HTMLAttributes } from 'react'
+
+type GapProps = {
+  length: (typeof lengthOptions)[number]
+} & HTMLAttributes<HTMLElement>
+
+const lengthOptions = ['xs', 'sm', 'md', 'lg', 'xl'] as const
+
+const Gap = ({ children, length }: GapProps) => <span className={`ams-gap--${length}`}>{children}</span>
+
+const render = ({ length }: GapProps) => (
+  <div className={`ams-gap--${length}`}>
+    <p className="ams-paragraph">These paragraphs are separated by a gap.</p>
+    <p className="ams-paragraph">These paragraphs are separated by a gap.</p>
+    <p className="ams-paragraph">These paragraphs are separated by a gap.</p>
+  </div>
+)
+
+const meta = {
+  title: 'Utilities/CSS/Gap',
+  component: Gap,
+  args: {
+    length: 'xs',
+  },
+  argTypes: {
+    length: {
+      control: 'radio',
+      description: 'The amount of white space to add between the children.',
+      options: ['xs', 'sm', 'md', 'lg', 'xl'],
+    },
+  },
+} satisfies Meta<typeof Gap>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render,
+}