feat: Add documention for Gap and Margin utility classes

packages/css/src/common/size.scss

@@ -3,11 +3,12 @@
  * Copyright Gemeente Amsterdam
  */
 
-/** The set of available options for sizing. */
+/** The set of available widths for gaps and margins. */
 $ams-sizes: (
   "no": "none",
   "xs": "extra-small",
   "sm": "small",
+  "md": "medium",
   "lg": "large",
   "xl": "extra-large",
 );

packages/css/src/components/column/column.scss

@@ -12,7 +12,9 @@
 }
 
 @each $size, $label in $ams-sizes {
-  .ams-column--gap-#{$label} {
-    gap: var(--ams-column-gap-#{$size});
+  @if $size != "md" {
+    .ams-column--gap-#{$label} {
+      gap: var(--ams-column-gap-#{$size});
+    }
   }
 }

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

@@ -2,4 +2,25 @@
 
 # Gap
 
-Use these utility classes to add consistent white space between a set of elements.
+Adds white space between a set of elements.
+
+## Class names
+
+The five sizes of [Component Space](/docs/foundation-design-tokens-space--docs) are available for the width or height of the gap.
+
+| Class name    | Preview                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| `ams-gap--xs` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-xs);" /> |
+| `ams-gap--sm` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-sm);" /> |
+| `ams-gap--md` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-md);" /> |
+| `ams-gap--lg` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-lg);" /> |
+| `ams-gap--xl` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-xl);" /> |
+
+## 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;
+    }
   }
 }

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

@@ -2,4 +2,24 @@
 
 # Margin
 
-Use these utility classes to add white space below a single element.
+Adds white space below a single element.
+
+## Class names
+
+The five sizes of [Component Space](/docs/foundation-design-tokens-space--docs) are available for the height of the bottom margin.
+
+| Class name   | Preview                                                                                      |
+| ------------ | -------------------------------------------------------------------------------------------- |
+| `ams-mb--xs` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-xs);" /> |
+| `ams-mb--sm` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-sm);" /> |
+| `ams-mb--md` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-md);" /> |
+| `ams-mb--lg` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-lg);" /> |
+| `ams-mb--xl` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-xl);" /> |
+
+## Guidelines
+
+- Use this utility class to vertically separate one element from the next.
+- It can be used on any element and sets the `margin-block-end` CSS property. This declaration is marked with the `!important` flag to ensure it overrides any other margins.
+- Elements’ top and bottom margins are sometimes collapsed into a single margin. Consult [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) for details.
+- To add equal margins between elements, either use the [Gap](/docs/utilities-css-gap--docs) utility class on their common parent or wrap them in a [Column](/docs/components-layout-column--docs) component.
+  This helps in loops: it prevents having to treat the last element differently.

packages/css/src/components/margin/margin.scss

@@ -6,7 +6,9 @@
 @import "../../common/size";
 
 @each $size in map-keys($ams-sizes) {
-  .ams-mb--#{$size} {
-    margin-block-end: var(--ams-margin-#{$size}) !important;
+  @if $size != "no" {
+    .ams-mb--#{$size} {
+      margin-block-end: var(--ams-margin-#{$size}) !important;
+    }
   }
 }

packages/css/src/components/row/row.scss

@@ -12,8 +12,10 @@
 }
 
 @each $size, $label in $ams-sizes {
-  .ams-row--gap-#{$label} {
-    gap: var(--ams-row-gap-#{$size});
+  @if $size != "md" {
+    .ams-row--gap-#{$label} {
+      gap: var(--ams-row-gap-#{$size});
+    }
   }
 }
 

packages/css/src/components/visually-hidden/README.md

@@ -4,7 +4,11 @@
 
 Hides content from sighted users but keeps it accessible to non-visual user agents, such as screen readers.
 
+## Class name
+
+`ams-visually-hidden`
+
 ## Guidelines
 
 - In most cases, visually available content should be accessible to non-visual user agents and vice versa.
-- Elaborate instructions or guidance read only by non-visual user agents can do more harm than good.
+  Elaborate instructions or guidance read only by non-visual user agents can do more harm than good.

storybook/config/manager-head.html

@@ -2,7 +2,7 @@
   // Somewhat hacky way to expand all folders. Storybook does not support that natively.
   var clickCollapsedItemsUntilNoneLeft = () => {
     const collapsedItems = document.querySelectorAll(
-      ':is(button[data-parent-id="components"], button[data-parent-id="pages"])[aria-expanded="false"]',
+      ':is(button[data-parent-id="foundation"], button[data-parent-id="components"], button[data-parent-id="utilities"], button[data-parent-id="pages"])[aria-expanded="false"]',
     );
 
     for (item of collapsedItems) {

storybook/config/preview-body.html

@@ -59,4 +59,17 @@
     margin: -1rem; /* stylelint-disable-line */
     padding: 1rem; /* stylelint-disable-line */
   }
+
+  [class*="ams-docs-token-preview--"] {
+    block-size: 1rem;
+  }
+
+  [class*="ams-docs-token-preview--border"] {
+    border-inline-start-style: solid;
+  }
+
+  [class*="ams-docs-token-preview--space"] {
+    outline: 1px dashed var(--ams-color-neutral-grey2);
+    background-color: var(--ams-color-primary-white);
+  }
 </style>

storybook/src/components/Accordion/Accordion.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Accordion, Paragraph } from '@amsterdam/design-system-react/src'
+import { Paragraph } from '@amsterdam/design-system-react'
+import { Accordion } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 import { exampleAccordionHeading, exampleParagraph } from '../shared/exampleContent'
 

storybook/src/components/Alert/Alert.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Alert, Link, Paragraph, UnorderedList } from '@amsterdam/design-system-react/src'
+import { Link, Paragraph, UnorderedList } from '@amsterdam/design-system-react'
+import { Alert } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/AspectRatio/AspectRatio.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatio, Image } from '@amsterdam/design-system-react/src'
+import { Image } from '@amsterdam/design-system-react'
+import { AspectRatio } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/Avatar/Avatar.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Avatar, Header, PageMenu } from '@amsterdam/design-system-react/src'
+import { Header, PageMenu } from '@amsterdam/design-system-react'
+import { Avatar } from '@amsterdam/design-system-react/src'
 import { SearchIcon } from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
 

storybook/src/components/Button/Button.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Button, Icon } from '@amsterdam/design-system-react/src'
+import { Icon } from '@amsterdam/design-system-react'
+import { Button } from '@amsterdam/design-system-react/src'
 import { ShareIcon } from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
 

storybook/src/components/Card/Card.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatio, Card, Heading, Image, Paragraph } from '@amsterdam/design-system-react/src'
+import { AspectRatio, Heading, Image, Paragraph } from '@amsterdam/design-system-react'
+import { Card } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 import { exampleTopTask } from '../shared/exampleContent'
 

storybook/src/components/Column/Column.docs.mdx

@@ -16,7 +16,7 @@ The five [space](/docs/foundation-design-tokens-space--docs) sizes are available
 
 Wrap a Column around a set of components that need the same amount of white space between them.
 
-To add white space below a single element, you can alternatively use a utility class for bottom margins, e.g. `class="ams-mb--md"`.
+To add white space below a single element, the [Margin Bottom](/docs/utilities-css-margin--docs) utility class can be used as well.
 
 ## Examples
 

storybook/src/components/Column/Column.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Card, Column, Heading, Paragraph } from '@amsterdam/design-system-react/src'
+import { Card, Heading, Paragraph } from '@amsterdam/design-system-react'
+import { Column } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const ThreeBoxes = Array.from(Array(3).keys()).map((i) => (

storybook/src/components/DescriptionList/DescriptionList.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { DescriptionList } from '@amsterdam/design-system-react'
+import { DescriptionList } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 import { inverseColorDecorator } from '../shared/decorators'
 import { exampleParagraph } from '../shared/exampleContent'

storybook/src/components/Dialog/Dialog.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Button, Dialog, Heading, Paragraph } from '@amsterdam/design-system-react/src'
+import { Button, Heading, Paragraph } from '@amsterdam/design-system-react'
+import { Dialog } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 import { MouseEvent } from 'react'
 

storybook/src/components/Field/Field.stories.tsx

@@ -3,8 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { ErrorMessage, Label, TextInput } from '@amsterdam/design-system-react'
-import { Field, Paragraph } from '@amsterdam/design-system-react/src'
+import { ErrorMessage, Label, Paragraph, TextInput } from '@amsterdam/design-system-react'
+import { Field } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/FieldSet/FieldSet.stories.tsx

@@ -8,12 +8,12 @@ import {
   Column,
   ErrorMessage,
   Field,
-  FieldSet,
   Label,
   Paragraph,
   Radio,
   TextInput,
-} from '@amsterdam/design-system-react/src'
+} from '@amsterdam/design-system-react'
+import { FieldSet } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/Footer/Footer.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Footer, Grid, Heading, LinkList, PageMenu, Paragraph } from '@amsterdam/design-system-react/src'
+import { Grid, Heading, LinkList, PageMenu, Paragraph } from '@amsterdam/design-system-react'
+import { Footer } from '@amsterdam/design-system-react/src'
 import {
   CameraIcon,
   ClockIcon,

storybook/src/components/Grid/Grid.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Grid, Screen } from '@amsterdam/design-system-react/src'
+import { Screen } from '@amsterdam/design-system-react'
+import { Grid } from '@amsterdam/design-system-react/src'
 import type { GridCellProps } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 

storybook/src/components/Header/Header.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Header, PageMenu } from '@amsterdam/design-system-react/src'
+import { PageMenu } from '@amsterdam/design-system-react'
+import { Header } from '@amsterdam/design-system-react/src'
 import { SearchIcon } from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
 

storybook/src/components/Heading/Heading.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Column, Heading } from '@amsterdam/design-system-react/src'
+import { Column } from '@amsterdam/design-system-react'
+import { Heading } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 import { inverseColorDecorator } from '../shared/decorators'
 import { exampleHeading } from '../shared/exampleContent'

storybook/src/components/Icon/Icon.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Heading, Icon } from '@amsterdam/design-system-react/src'
+import { Heading } from '@amsterdam/design-system-react'
+import { Icon } from '@amsterdam/design-system-react/src'
 import * as Icons from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
 

storybook/src/components/Link/Link.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Link, Paragraph } from '@amsterdam/design-system-react/src'
+import { Paragraph } from '@amsterdam/design-system-react'
+import { Link } from '@amsterdam/design-system-react/src'
 import type { Meta, StoryObj } from '@storybook/react'
 
 type Story = StoryObj<typeof Link>

storybook/src/components/Mark/Mark.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Mark, Paragraph } from '@amsterdam/design-system-react/src'
+import { Paragraph } from '@amsterdam/design-system-react'
+import { Mark } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/MegaMenu/MegaMenu.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Grid, Heading, LinkList, MegaMenu, Screen } from '@amsterdam/design-system-react/src'
+import { Grid, Heading, LinkList, Screen } from '@amsterdam/design-system-react'
+import { MegaMenu } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/OrderedList/OrderedList.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Heading, OrderedList, Paragraph } from '@amsterdam/design-system-react/src'
+import { Heading, Paragraph } from '@amsterdam/design-system-react'
+import { OrderedList } from '@amsterdam/design-system-react/src'
 import type { Meta, StoryObj } from '@storybook/react'
 import { inverseColorDecorator } from '../shared/decorators'
 import { exampleOrderedList } from '../shared/exampleContent'

storybook/src/components/Overlap/Overlap.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatio, Grid, Image, Overlap, SearchField } from '@amsterdam/design-system-react/src'
+import { AspectRatio, Grid, Image, SearchField } from '@amsterdam/design-system-react'
+import { Overlap } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/Radio/Radio.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { FieldSet, Radio } from '@amsterdam/design-system-react/src'
+import { FieldSet } from '@amsterdam/design-system-react'
+import { Radio } from '@amsterdam/design-system-react/src'
 import { useArgs } from '@storybook/preview-api'
 import { Meta, StoryObj } from '@storybook/react'
 

storybook/src/components/Row/Row.stories.tsx

@@ -3,7 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Avatar, Button, Heading, Link, Paragraph, Row } from '@amsterdam/design-system-react/src'
+import { Avatar, Button, Heading, Link, Paragraph } from '@amsterdam/design-system-react'
+import { Row } from '@amsterdam/design-system-react/src'
 import { crossAlignOptions, mainAlignOptions } from '@amsterdam/design-system-react/src/common/layout'
 import { Meta, StoryObj } from '@storybook/react'