- TypeScript 75.2%
- MDX 13.9%
- SCSS 6.4%
- JavaScript 3.5%
- CSS 0.8%
- Other 0.2%
6596b00fd7## Links - Follows #2815, which did the same for page templates. - [Test stories](https://github.com/Amsterdam/design-system/blob/chore/DES-1801-chromatic-css-utilities/documentation/storybook.md#test-stories) in the Storybook documentation. ## What Adds Chromatic coverage for the seven CSS utilities, which had none. `onlyStoryNames` matched `Components` and `Pages` only, so nothing under `Utilities/` was ever snapshotted. Each utility now has a Test story, matched by a new `Utilities/**/**/Test` pattern. Also renames `storybook/src/utils/` to `storybook/src/utilities/`, so the directory matches the section its stories appear in. ## Why These utilities are pure styling — `ams-prose`, `ams-visually-hidden`, and the gap and margin helpers — so a visual diff is the only test that catches a regression in them. `ams-prose` in particular leans on `:has()`-based pairwise spacing between headings, tables and paragraphs, which nothing else guards. ## How With test stories, rather than by widening the glob to `Utilities/**`. Widening it looks like the cheaper option, but it isn’t: a page story is the whole artefact, whereas a utility story is one arg permutation of a parameterised demo, and Chromatic only ever renders the default arg. Snapshotting the presentation stories would have captured one of five gaps, one of six margins, one of six aspect ratios, and the container query never firing. A Test story holds the whole scale in one image, so it costs the same seven stories while covering roughly 25 states. `renderComponentVariants` can’t help here. The component next to each utility is a mock that renders a bare element, and the utility class comes from the story’s `render`, so a generated matrix would show elements without the class on them. The matrices are built by hand instead, taking their scales from the CSS rather than from the mock components’ props — which is why Margin covers a `2xl` that its own control doesn’t offer. Body, Prose and Visually Hidden have no variants. Their `render` moved onto the meta and the Test story inherits it, so the snapshot can’t drift away from the story we document. ## Checklist - [x] Add or update unit tests - [x] Add or update documentation - [x] Add or update stories - [x] Add or update exports in index.\* files - [x] Comment `/chromatic test` and verify visual regression tests pass - [x] Start the PR title with a Conventional Commit prefix, [as explained here](https://github.com/Amsterdam/design-system/blob/main/documentation/publishing.md?plain=1#L11) ## Additional notes I checked the glob against the built `index.json` with picomatch before committing: the seven Test stories match, the seven presentation stories don’t — so nothing gets snapshotted twice — and the existing patterns still return 78 components and 22 pages. Two things worth a look while reviewing. `margin.scss` ships a `2xl` size that both the mock type and `shortSize.ts` omit, so it is undocumented and unreachable from the controls. I left it alone here, since `shortSize` is exported from `packages/react` and changing it is a bigger call, but it deserves a follow-up. `ams-visually-hidden` is built on the same `:not(:active, :focus)` shape that the Chromatic pseudo-state addon is documented to break for the Skip Link. It renders correctly locally, but its first baseline is worth looking at rather than accepting straight away. |
||
|---|---|---|
| .github | ||
| .husky | ||
| documentation | ||
| packages | ||
| packages-proprietary | ||
| plop-templates | ||
| storybook | ||
| stylelint | ||
| .editorconfig | ||
| .gitattributes | ||
| .gitignore | ||
| .nano-staged.json | ||
| .npmpackagejsonlintrc.json | ||
| .nvmrc | ||
| .prettierignore | ||
| .prettierrc.json | ||
| .release-please-manifest.json | ||
| .stylelintignore | ||
| .stylelintrc.json | ||
| AGENTS.md | ||
| CONTRIBUTING.md | ||
| eslint.config.mjs | ||
| eslint.rules.mjs | ||
| LICENSE.md | ||
| LICENSE.txt | ||
| NOTICE.md | ||
| package.json | ||
| plopfile.mjs | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| publiccode.yml | ||
| README.md | ||
| release-please-config.json | ||
| tsconfig.json | ||
Amsterdam Design System
This is the guide for the user interfaces of all digital products and services provided by the City of Amsterdam.
We offer reusable components, patterns and guides for teams that work on our websites. This helps everyone work faster and better, with more time to create value. To our citizens and businesses, all our channels look the same and work similarly; they are broadly accessible and evoke trust.
We aim to create libraries for, or support otherwise, Figma, CSS, React, React Native, and Mendix.
Related resources
A Storybook portal demonstrates our components and documentation.
Our Figma Library contains the design of our components and patterns.
Getting started
See the getting started documentation for developers on how to use our React components.
AI assistance
If you build with an AI coding assistant, connect it to our Model Context Protocol (MCP) server. Your assistant then works with real Amsterdam Design System components and their correct properties, instead of inventing markup. See connecting AI assistants to set it up.
Contributing
See the documentation for contributors.
Code of conduct
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. Read our Code of Conduct if you haven’t already.
NL Design System
This project is part of a community initiative to use NL Design System components for websites that comply with the Amsterdam Design System.
Join the #nl-design-system Slack via praatmee.codefor.nl for more information and to learn about things happening in our open-source community.
Thanks
Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions.
Licence
This project is free and open-source software licenced under the European Union Public License (EUPL) v1.2 or higher.
Documentation is licenced as Creative Commons Zero 1.0 Universal (CC0-1.0).
The open-source licences do not cover the assets in the packages-proprietary directory.
Each directory in the packages-proprietary directory specifies the applicable licence for that directory.
Please read the notice for more information about proprietary assets.