chore(docs): Document spacing between components by VincentSmedinga · Pull Request #2455 · Amsterdam/design-system

VincentSmedinga · 2026-03-12T08:40:35Z

Document spacing between components

What

Adds a page advising about space between components to our docs.
a. Includes a little form tool to get the advised spacing between the two selected components; but note that values haven’t been updated since the earlier iteration in March.
Adds 8 temporary, AI-generated example pages to test the new spacing values.
a. The ‘real’ pages haven’t been updated yet.
Values have all been reviewed by @Bondt007 and updated where necessary.
Introduces two patterns: Content Header (mainly because Breadcrumb, Heading 1 and Lead Paragraph should all be unique so didn’t have a real place in the docs) and Link Section.

Why

People were asking about it, and we ourselves aren’t always as sure about what value to choose.

How

n/a

Additional notes

In the stories, toggle the ‘Show size markers’ switch to show and hide indicators of the bottom margin on components that set one.

Copilot

Pull request overview

Adds a new Designer Guide documentation page describing recommended spacing between components, and adjusts Storybook docs styling so table headers use the design system’s bold body-text weight.

Changes:

Add a new “Space between” Designer Guide page with spacing matrices and a code example.
Update Storybook docs CSS overrides to render table header cells (th) in bold.
Tweak the Space design-token doc copy by removing two explanatory sentences.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
`storybook/src/styles/overrides.css`	Ensures Storybook docs tables render header cells with the DS bold font-weight for clearer matrices.
`storybook/src/docs/designer-guide/space-between.docs.mdx`	Introduces the new spacing guidance page and reference tables.
`storybook/src/brand/design-tokens/space.docs.mdx`	Removes a couple of lines from the Spacious spacing intro text.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

RubenSibon

General comments: this documentation is aimed at the designers, but it is also important for developers to follow these guidelines when they implement components with or without a dedicated designer to guide them.

It's quite a responsibility that developers have, and I am not sure that these guidelines will always be followed or even known about.

Apply that size in Figma. Developers can then apply it using the corresponding margin class name on each component.

In practice, many development teams (and possibly content editors?) in the City work without designers to guide them. They might expect to drop these components into a container like Column, set a general spacing with gap and be done.

I don't see an easy way to avoid bad implementations without enforcing spacing by adding outside spacing to components (whether they have them themselves, or parent containers are setting them on children).

How can we make it as easy as possible for developers to do it correctly? Maybe a start would be to add a little bit about spacing to each of the components mentioned in this Space between documentation.

For example, in the Heading docs, there is no mention of vertical space whatsoever. I'd suggest we a line about vertical spacing and maybe a link to these Space between docs. Then do the same to all other components mentioned in the tables.

Bondt007 · 2026-03-26T10:20:12Z

A way to avoid unwanted combinations of components on pages, is to start making more patterns. Patterns are fixed combinations of components. These patterns contain the correct amount of spacing.

Bondt007 · 2026-03-26T10:23:23Z

we're not yet done checking all the values in the cells of these space between matrixes.

Bondt007

still need to check all exact values.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

# Conflicts: # storybook/src/pages/public/ArticlePage/ArticlePage.stories.tsx

Rewrites the prose-spacing mixin so the margins between children of .ams-prose match the pairwise matrix in SpaceBetweenFinder/config.ts. Introduces Sass variables for the recurring component families (heavy body, minor heading, list-or-paragraph, button-or-cta, plain paragraph) so they surface once at the top of the file without changing the compiled output.

Adds a README for the .ams-prose utility class and a matching Storybook entry under Utilities/CSS/Prose. The story renders a Dutch example page about werkzaamheden aan de Oranjeloper that exercises most of the spacing pairings handled by the prose-spacing mixin.

dlnr

I would need more time to check if all compiled selectors do what they are supposed to do, they get kind of long after Sass does it's thing:

: is(.ams-prose>:is(.ams-blockquote,.ams-image,.ams-paragraph--large,.ams-table):has(+:not(.ams-heading)),.ams-prose>:not(.ams-heading):has(+:is(.ams-blockquote,.ams-image,.ams-paragraph--large,.ams-table))) {

But here are some first impressions.

dlnr · 2026-04-16T07:42:30Z

+.ams-prose {
+  @include prose-spacing;
+
+  .ams-accordion__panel {


I don't see an example of this in the story and I'm curious to see what happens. I would assume the ams-prose wrapper only has effect on direct children and this exemption is kind of weird specific inheritance. You could just wrap content in the tabs panel in a div with the className. If you have a custom component, or table, or card it should not have effect on this content either.

Yes, it would be nice if this story shows all descendants that can be affected by Prose. Or if another story shows how an Accordion is affected.

If showing all possible permutation in Storybook is a bit too much, you could of course add that full example to Prototypes and/or a Test story for Chromatic.

Actually it might be a good idea to have snapshot tests for this specific utility class, because there are so many parts that could break at some point.

dlnr · 2026-04-16T07:45:00Z

+    <div {...restProps} className={clsx('_ams-space-between-finder sb-docs sb-docs-content', className)}>
+      <div className="_ams-space-between-finder__fields">
+        <div>
+          <label htmlFor="space-between-above">Component on top:</label>


Missed opportunity to use our own components?

dlnr · 2026-04-16T07:46:44Z

+
+## Code example
+
+{/* prettier-ignore */}


This is weird, the prettier config does not include markdown files.

dlnr · 2026-04-16T07:47:43Z

+
+## Templates te maken
+
+- Contentpagina met h1 en h2 achter elkaar (zonder foto en intro) dus eigenlijk Czaar Peter


Is this unfinished?

dlnr · 2026-04-16T07:49:40Z

+
+{/* prettier-ignore */}
+```tsx
+<Grid.Cell>


Not recommending the prose util?

dlnr · 2026-04-16T07:54:08Z

+
+  /* Context-aware spacing for browsers with :has() support */
+  /* stylelint-disable-next-line scss/operator-no-unspaced */
+  @supports selector(:has(+ *)) {


If the has selector is widely available soon this might be overkill, and if a browser doesn't support the selector the rule will not be applied right?

RubenSibon · 2026-04-17T12:17:18Z

+- It sets `margin-block-end` on each direct child based on what follows it, using the `:has()` selector.
+  Browsers without `:has()` support fall back to a uniform spacing.
+- Content inside an Accordion panel nested under `.ams-prose` is spaced the same way, so an accordion and its surroundings share one rhythm.
+- To add a single ad-hoc gap between two elements, prefer the [Margin Bottom](/docs/utilities-css-margin--docs) utility class on the first one.


Let’s add a reference to the Prose docs in the Margin utility docs.

RubenSibon · 2026-04-17T12:17:40Z

+  Browsers without `:has()` support fall back to a uniform spacing.
+- Content inside an Accordion panel nested under `.ams-prose` is spaced the same way, so an accordion and its surroundings share one rhythm.
+- To add a single ad-hoc gap between two elements, prefer the [Margin Bottom](/docs/utilities-css-margin--docs) utility class on the first one.
+- To add even spacing between a set of siblings, prefer the [Gap](/docs/utilities-css-gap--docs) utility class on their parent.


Let’s also add a reference to the Prose docs in the Gap utility docs.

RubenSibon · 2026-04-17T12:21:33Z

I think it would be good to point implementers to vertical spacing early in the Developer Guide. Not sure where exactly.

And would it be helpful or distracting to add a line to every single component (text, media, etc.) affected by Prose?

RubenSibon · 2026-04-17T12:29:10Z

        'Brand',
        'Components',
        ['Buttons', 'Containers', 'Feedback', 'Forms', 'Layout', 'Media', 'Navigation', 'Text'],
        'Utilities',


Having Utilities here feels wrong, because it between incrementally larger concerns: Tokens < Components < Patterns < Pages.

Either:

move the entire Utilities category up so that it’s above Components and below Brand;

remove the Utilities category (which has only one member anyway) and add a ‘CSS utilities’ folder to the Components category.

Option 2 makes the most sense because our CSS utilities are actually CSS components in (almost?) everyway.

RubenSibon · 2026-04-17T12:31:07Z

        'Components',
        ['Buttons', 'Containers', 'Feedback', 'Forms', 'Layout', 'Media', 'Navigation', 'Text'],
        'Utilities',
+        'Patterns',


This could be a good place for other common component compositions such as form fields with inputs, labels, error messages and whatnot.

RubenSibon · 2026-04-17T12:34:25Z

+
+## Guidelines
+
+- Use this utility class on a container that wraps editorial content — an article, a rich-text block, or a section built from multiple components — so its children are spaced according to the [‘Space between’](/docs/docs-designer-guide-space-between--docs) recommendations.


We can consider adding an Article component that has the prose mixin applied by default.

With the as attribute we could even allow for the article element to be swapped with other element types.

VincentSmedinga requested a review from a team as a code owner March 12, 2026 08:40

VincentSmedinga requested review from Bondt007, bas-kroese and Copilot March 12, 2026 08:41

Copilot started reviewing on behalf of VincentSmedinga March 12, 2026 08:41 View session

Copilot AI reviewed Mar 12, 2026

View reviewed changes

Comment thread storybook/src/docs/designer-guide/space-between.docs.mdx Outdated

Comment thread storybook/src/docs/designer-guide/space-between.docs.mdx Outdated

Comment thread storybook/src/docs/designer-guide/space-between.docs.mdx Outdated

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs March 12, 2026 08:46 Destroyed

RubenSibon reviewed Mar 12, 2026

View reviewed changes

VincentSmedinga marked this pull request as draft March 12, 2026 12:41

Bondt007 reviewed Mar 26, 2026

View reviewed changes

VincentSmedinga force-pushed the chore/DES-1503-space-between-docs branch from 94feaae to c8f97ad Compare April 1, 2026 12:46

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 1, 2026 12:46 Destroyed

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 1, 2026 13:42 Destroyed

VincentSmedinga force-pushed the chore/DES-1503-space-between-docs branch from 6505878 to fd9b691 Compare April 1, 2026 13:48

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 1, 2026 13:48 Destroyed

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 1, 2026 13:51 Destroyed

VincentSmedinga force-pushed the chore/DES-1503-space-between-docs branch from e4241ec to 597f6dc Compare April 15, 2026 11:41

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 15, 2026 11:41 Destroyed

VincentSmedinga added 2 commits April 15, 2026 15:33

Document space between components

815acce

Add AI-generated example pages

973d68a

VincentSmedinga force-pushed the chore/DES-1503-space-between-docs branch from 597f6dc to 973d68a Compare April 15, 2026 13:34

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 15, 2026 13:34 Destroyed

VincentSmedinga changed the title ~~chore(docs): Start documenting space between components~~ chore(docs): Document spacing between components Apr 15, 2026

Add reciprocal links

3cf04c3

VincentSmedinga requested a review from Copilot April 15, 2026 13:44

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 15, 2026 13:44 Destroyed

Copilot started reviewing on behalf of VincentSmedinga April 15, 2026 13:44 View session

Copilot AI reviewed Apr 15, 2026

View reviewed changes

Prevent repetition in mock content

589bd76

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 15, 2026 14:17 Destroyed

VincentSmedinga added 7 commits April 15, 2026 23:56

Update space values for Space Between Finder

3946632

Improve copy of spacing advice

d693b07

Recommend xs space between Heading 1 and metadata Paragraph

1bb1214

Introduce component families for docs

9ade47f

Make lists

9a28d17

Add Content Header pattern

f553543

Add Link Section pattern

140a489

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 15, 2026 21:58 Destroyed

Add rationales, move render function

bd02a31

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 15, 2026 22:06 Destroyed

Add example of Link Section with download links

5a519db

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 15, 2026 22:12 Destroyed

VincentSmedinga added 3 commits April 16, 2026 07:18

poc: Set spacing in prose automagically

e31c067

# Conflicts: # storybook/src/pages/public/ArticlePage/ArticlePage.stories.tsx

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 16, 2026 06:14 Destroyed

Add date line, fix name

351fe72

github-actions bot temporarily deployed to demo-DES-1503-space-between-docs April 16, 2026 06:20 Destroyed

Wrap prose in Grid Cell

c5f472b

github-actions bot deployed to demo-DES-1503-space-between-docs April 16, 2026 07:43 View deployment

dlnr reviewed Apr 16, 2026

View reviewed changes

VincentSmedinga mentioned this pull request Apr 17, 2026

poc: Experiment with prose component to automate typographic whitespace #2497

Closed

RubenSibon reviewed Apr 17, 2026

View reviewed changes


		## Templates te maken

		- Contentpagina met h1 en h2 achter elkaar (zonder foto en intro) dus eigenlijk Czaar Peter


		## Guidelines

		- Use this utility class on a container that wraps editorial content — an article, a rich-text block, or a section built from multiple components — so its children are spaced according to the [‘Space between’](/docs/docs-designer-guide-space-between--docs) recommendations.

Conversation

VincentSmedinga commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Document spacing between components

What

Why

How

Additional notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

RubenSibon left a comment

Choose a reason for hiding this comment

Uh oh!

Bondt007 commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Bondt007 commented Mar 26, 2026

Uh oh!

Bondt007 left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dlnr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RubenSibon Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

VincentSmedinga commented Mar 12, 2026 •

edited

Loading

Bondt007 commented Mar 26, 2026 •

edited

Loading

RubenSibon Apr 17, 2026 •

edited

Loading