Getting started with the NL Design System

Purpose

The NL Design System grows bottom-up: developers build components, share them with the community, and together help them mature into Candidate and, eventually, Hall of Fame status. Using a component is often the first step toward contributing one.

This project shows how you can discover and use components from the NL Design System in a Next.js application and doubles as a starting point if you want to build a component of your own.

This page deliberately combines components from multiple implementations: @nl-design-system-candidate, @utrecht/component-library-react, and @amsterdam/design-system-react.

Which component should you use?

The NL Design System groups every component through the estafettemodel (relay model). It ranges from a documented need with no implementation yet, to a production-proven implementation used across organisations:

Help wanted a documented need for a specific implementation. It has a clear description and use-case. Ready to be developed into a component for each organisation that needs it
Community built by the community according to NL Design System guidelines and usable with confidence. It can contain community specific quirks.
Candidate expected to reach Hall of Fame, but needs some hardening by gathering documentation and feedback, so it can still change.
Hall of Fame used in production by at least two organizations, audited for accessibility, and semantically versioned with a changelog.
Discouraged flagged by user research or accessibility guidelines as something to avoid.

Rule of thumb: if a mature (Hall of Fame or Candidate) component already exists for your use case, reach for that first. If it doesn't exist yet, or it doesn't fit your needs, create your own — share it with the community, and help it grow toward Candidate.

Finding components

Before building a component yourself, check whether it already exists:

Search nldesignsystem.nl/componenten/, the central catalog of components across all NL Design System implementations.
If you can't find what you need there, browse the individual implementation repositories on GitHub and their Storybooks — for example Rijkshuisstijl on GitHub and its Storybook, or Utrecht on GitHub and its Storybook.

Installing your first component

Everything you need to start using the NL Design System in a React application:

Choose an implementation. The NL Design System isn't a single library, so pick the one (or combination) that fits your project, such as @nl-design-system-candidate, @utrecht/component-library-react, or @amsterdam/design-system-react.

Install the React component and its CSS package.

pnpm add @nl-design-system-candidate/heading-react @nl-design-system-candidate/heading-css

Import the component's CSS once, wherever you set up your application or with your component implementation.
```
import '@nl-design-system-candidate/heading-css/heading.css';
```
Load a set of design tokens and apply the matching theme class to your root element. This project loads @nl-design-system-unstable/start-design-tokens and applies the start-theme class in app/layout.tsx.
```
import '@nl-design-system-unstable/start-design-tokens/dist/variables.css';

<html lang="en" className="start-theme">
```
Your chosen component might be using design tokens that have not been defined in your theme file. This means you need to assign these yourself. Generally it's best to do this in a single css file to have all the custom variables in a single location.

Import and render the component.

import { Heading } from '@nl-design-system-candidate/heading-react';

const Example = () => <Heading level={1}>Hello world</Heading>;

The React components can also be imported with CSS included but with the caveat that it can only be client side rendered:

import { Link } from '@nl-design-system-candidate/link-react/css';

Repeat for every component you need.

How to use this project

Each component used on this page follows the steps above and is wrapped in its own file under components/, so you can see the install and import steps applied for real. Open a component in that folder to see the pattern.

Next steps

Want to continue? Here's what you can have a look at next: