This project is very much WORK IN PROGRESS and all components are released as alpha version. Always define the exact version you want to use, and test for breaking changes before upgrading to a newer alpha release.
Applying design elements from this project is strictly prohibited for organisations that are not part of the Municipality of Utrecht.
This project is part of a community iniative to use NL Design System components for projects that need to adhere to the Utrecht Design System. Teams from the central Municipality of Utrecht, as well as those who are contracted by them to develop websites and apps, are able to collaborate via this project.
Include the Design Token CSS variables:
<link
rel="stylesheet"
type="text/css"
href="https://unpkg.com/@nl-design-system-unstable/utrecht-design-tokens/dist/index.css"
/>
Combine it with the latest Web Components from the NL Design System community, for example:
<script
src="https://unpkg.com/@utrecht/web-component-library-stencil/dist/utrecht/utrecht.esm.js"
type="module"
></script>
Then you can go ahead and see the result:
<utrecht-html-content>
<h1>Page styled with NL Design System</h1>
</utrecht-html-content>
For all dependencies, see what the version is you use while developing and update the URL without version to include a version number, and ensure your page keeps working even when new versions are released:
For alpha, beta and rc versions:
https://unpkg.com/@nl-design-system-unstable/utrecht-design-tokens/dist/index.css
Above should become:
https://unpkg.com/@nl-design-system-unstable/utrecht-design-tokens@1.0.0-alpha.37/dist/index.css
For stable versions it would become:
https://unpkg.com/@nl-design-system-unstable/utrecht-design-tokens@^1.0.0/dist/index.css
- Open Terminal.
- Install homebrew by copy-pasting the following:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
. You will be prompted for your password for sudo access. - Install GIT by copy-pasting the following into your terminal:
$ brew install git
. - Install VS Code Visual Studio or your own favourite code editor.
- Clone the repository in VS Code GitHub or your own favourite code editor.
- In a terminal go to the repository folder and run
npm install
there. - Check versions.
- In the terminal, run
node -v
. The version should be at least 14.X - In the terminal, run
npm -v
. The version should be at least 6.X - If the versions are not up to date, run 'npm install' again.
- In the terminal, run
- Run storybook.
- In the Terminal run
npm run storybook
- In the Terminal run
- Your main browser opens automatically with your local storybook.
In .storybook/customTheme.js
the theme used by NL Design System can be found. By changing those properties one can style the storybook to match ones brand. Checkout https://storybook.js.org/docs/react/configure/theming to learn more about all the possible configurations to brand this storybook.
- In
src/demo-empty-component
an example story of a documentation first (or documentation only) component can be found. - Copy this folder
- Rename to match your component
- The folder
- The
x.stories.mdx
tocomponent-name.stories.mdx
- The title of the
Meta
component incomponent-name.stories.mdx
- Add the UX guidelines in
README.md
- Optionally add the component specific accessibility or content guidelines in
docs/accessibility-guidelines
ordocs/content-guidelines
. - Optionally add the Figma component in
component-name.stories.mdx
by adding part of the Figma url to the Figma component<Figma title="Link" url="file/..." />
Add global tokens to /brand.css
. Add tags to make them appear in the Storybook Design token addon. For example @tokens Colors
and @presenter Color
. See https://storybook.js.org/addons/@tommyem/storybook-design-token for more details.
In src/demo-link-component
an example story and web-component can be found. All steps below are represented in this demo-link.stories.mdx
example.
To add a component implementation to storybook, we use the <component-name>-stories.mdx
which already contains the documentation pages or create one with placeholder documentation by following step 1-3 from the Adding UX and other documentation without a component implementation
chapter.
- Create a component template function that takes variable arguments. If an argument might contain childnodes, use the
sanatize
package to prevent unsafe content and injections. Place thisTemplate
function above theMeta
component - Declare a story for each component variation and bind the template
- Declare the possible inputs, with types and a description in the
argTypes
property of theMeta
component instories.mdx
. - Add an
Argstable
component in yourstories.mdx
- Optionally add a different
status
to theMeta
parameters. The options and colors can be found in.storybook/preview.js
- Add the code below to the
Meta
parameters to ensure a resolved code example in your story, instead of the Template function:
parameters: {
docs: {
transformSource: (_src, { args }) => Template(args),
},
// ...
}
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.
This project is free and open-source software licensed under the European Union Public License (EUPL) v1.2.
For information about proprietary assets in this repository, please carefully read the NOTICE file.