nl-design-system / rvo

Work in Progress: RVO Design System based on the NL Design System architecture. Rijksdienst voor Ondernemend Nederland / rvo.nl

RVO Design System

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.

The RVO design system is based on the NL Design System architecture.

For more info about the NL Design System and learn about things happening in our open source community, join the #nl-design-system Slack via praatmee.codefor.nl!

Getting started

Include the Design Token CSS variables:

<link rel="stylesheet" type="text/css" href="https://unpkg.com/@nl-rvo/design-tokens/dist/index.css" />

Combine it with the latest CSS Component classes from the NL Design System community, for example:

<link rel="stylesheet" type="text/css" href="https://unpkg.com/@nl-rvo/component-library-css/dist/index.css" />

Then you can go ahead and use the HTML snippets of the components in this Storybook.

Avoid automatic upgrades to a new version with breaking changes

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-rvo/design-tokens/dist/index.css

Above should become:

https://unpkg.com/@nl-rvo/[email protected]/dist/index.css

For stable versions it would become:

https://unpkg.com/@nl-rvo/design-tokens@^1.0.0/dist/index.css

npm packages

name	version
@nl-rvo/component-library-css
@nl-rvo/design-tokens

Contributing

Install prerequisites

You need to have the following tools installed to run Storybook locally:

• Git
• Node.js and npm

Open a terminal and run the following commands to check:

• git --version: a relatively recent version should be installed (Git 2.28 or later)
• node -v: should be at least the version defined in the engines section of package.json
• npm -v: should be at least the version defined in the engines section of package.json

Install code editor

You can use any editor you'd like, but in case you use Visual Studio Code. We recommend the following extensions that are useful for this project:

• EditorConfig
• ESLint
• markdownlint
• MDX
• Prettier - Code formatter
• stylelint
• Svg Preview

Developing locally

1. Open Terminal
2. Select the directory this repository should be cloned into with cd <name-of-directory>
3. Clone this Git repository
4. cd rvo
5. git checkout master to switch to the main master branch, if you previously worked in this repository.
6. git pull to get to the latest version of the master branch
7. npm install to download and install all the dependencies

Run Docusaurus on your computer

1. Open Terminal
2. Ensure your current directory is rvo
3. Run npm install to ensure the latest and greatest of all dependencies
4. Run npm run docs
5. The local version of docusaurus will be running on localhost:3000/rvo
6. Press Control+C in your terminal to stop Docusaurus

Read the standalone/docusaurus/README.md for docusaurus details

Run Storybook on your computer

1. Open Terminal.
2. Ensure your current directory is rvo
3. Run npm install to ensure the latest and greatest of all dependencies
4. Run npm run storybook to start Storybook
5. Your main browser opens automatically with your local storybook on localhost:6006.
6. Press Control+C in your terminal to stop Storybook.

Debugging Storybook

First check the logs in the terminal if any error is displayed, if something doesn't work as expected.

Secondly check the JavaScript logs in your browsers developer tools if there are errors or warnings.

You can run the code checks with npm run lint to see if any code errors can be detected.

You can also check the build logs of the design tokens for errors, if you have changed Style Dictionary JSON files, by building those separately:

1. cd proprietary/design-tokens/
2. npm run build

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.

License

This project is free and open-source software licensed under the European Union Public License (EUPL) v1.2. The documentation is licensed as Creative Commons Zero 1.0 Universal (CC0-1.0).

For information about proprietary assets in this repository, please carefully read the NOTICE file

rvo's Issues

Basiselementen: base set up with buttons

Dit is een basis opzet om veel gebruikte elementen de bestaande styling van Rijkshuisstijl mee te geven en te delen.
De eerste opzet gebruikt een button om de werkwijze te valideren.

PR: Normalize buttons

Paragraphs

Add tokens to 'basiselementen' paragraphs

Basiselementen: Datalist

Datalist works in RVO but should be a base element. (Review with MinBZK designer)
PR: #276

Button group using a11y layout

Buttons under a certain context may not very visible to some users when placed at the end of the reading direction. This means primary buttons come first, not last and subsequent buttons and or links follow directly adjacent to each other.

PR: #313
Related issue: #265

Onderzoek Lint annotations

Fouten in Markdown en MDX bestanden, met name onnodige spaties aan het eind van een regel, moeten nu uit de logs van Actions gevist worden.

Onderzoek of het mogelijk is om deze met annotations terug te laten komen in de PR zelf.

Basiselementen: Breadcrumbs

Add tokens to 'basiselementen' breadcrumbs

The issue also relies on the issue for links: #321

Use existing NL Design System community React components where possible

Rich text:

• Paragraph
  • Lead paragraph
• Heading 1 - Heading 6
• Unordered list
• Ordered list
• Link
• Strong

Forms:

• Form field
• Form label
• Form description
  • invalid
• Data list
• Button group
• Form input
  • Textbox
  • Textarea
  • Button

Tweede fase:

• Radio button (nog niet klaar bij Utrecht)
• Checkbox (nog niet klaar bij Utrecht)
• Strong (nog geen React component)
• Select (als Utrecht niet meer de icon sloopt)

Custom to RVO:

• Paragraph
  • Small paragraph

Basiselementen: Lists

Add tokens to 'basiselementen' lists

Basiselementen: Input & fields

Add tokens to 'basiselementen' textboxes

Basiselementen: Responsive typography

Make sure that Basiselementen has font sizes based on given breakpoints.
This requires alignment on scales for spacing and sizing.

Basiselementen: Extend Utrecht tokens with the new Link token properties

We should consider adding the outline offset to allow for certain implementations of focus

Basiselementen: Select

Utilize the select component from Utrecht in the RVO storybook.

README.md is outdated

The README.md instructs to use npm instead of the current pnpm
See also: #422

Basiselementen: Radio input

Todo: Check if this is possible yet.

Headings

Add tokens to 'basiselementen' headings

Documentatie: toegankelijkheid van expandable helper text

• uitleg over hoe het niet moet:
  • niet uitleg in form label plaatsen
• uitleg over welke HTML wel goed is (<details>, of <button aria-expanded="true">, of <button aria-haspopup="...">, of <button popover>?)
• hoe koppel je de uitleg via aria-describedby?
• uitleggen waarom een tooltip een anti-pattern is (obscures content, displays on hover, etc)
• link naar relevante WCAG regels

Documentatie: toegankelijkheid role="group" voor form field

De form field van Utrecht is op dit moment een <div> zonder accessible role en zonder label. De component van RVO voegt daar code aan toe: `role="group" aria-labelledby="...".

Is dit een toegankelijk patroon? Ik ken role="group" alleen voor fieldsets. Als dit niet gewenste aanpak is, dan moet dit in de documentatie van form field worden toegevoegd.

• controleren aanpak role="group" voor form fields
• documentatie schrijven over of dit ongewenste markup is, of dat het alternatieve correcte markup is. Ik zou de documentatie toevoegen bij de form field component van Utrecht.

Patch round 2024-01

Pro-tip: ignore warnings about deprecated packages until you have completed upgrade of major releases. Often major releases will fix deprecated warnings.

Configuration

The following configuration is a prerequisite for this workflow. All of this should have already been installed and configured.

• npm-check-updates is installed in the root, and there are three npm scripts:
  • pnpm run update-patch with .ncurc.patch.cjs as configuration file
  • pnpm run update-patch with .ncurc.minor.cjs as configuration file
  • pnpm run update-major with .ncurc.major.cjs as configuration file
  • pnpm run test-update to run the continuous integration steps as "smoke test".
• npm-package-json-lint with .npmpackagejsonlintrc.json as configuration file
• Require fixed version dependencies for npm:
  • .npmrc has save-prefix= to override the ^ or ~ with an empty string
  • none of the existing package.json files have ^ and ~ dependencies.
  • package-json-lint checks the following rules:
    • "no-caret-version-dependencies": "error"
    • "no-caret-version-devDependencies": "error"
    • "no-tilde-version-dependencies": "error"
    • "no-tilde-version-devDependencies": "error"
• the pnpm-lock.yaml lock file for the package manager has been committed to the git repo (and lock files for other package managers have been added to .gitignore to prevent accidentally committing those)
• "Security advisories" for this repository are enabled, as well as Dependabot alerts.

Preparation

• Check the /.patches/ directory in the root (if present), and see if there are any npm packages that have overrides for their code.
  • When for a patch/minor/major update these package are updated, you must also create a new version of the patch file. Create a task for this in this issue.
  • Sometimes the patch is no longer necessary, because the bug that the patch is for has been fixed in the actual package. Read the commit message for the patch, or read the GitHub PR comments or the related GitHub issue comments to find out what the patch was for.
  • Ideally the patch files have a code comment in .patches/README.md explaining the conditions when the patch is no longer required.

npm dependencies

We use the npm-check-updates package to upgrade to new versions of npm packages, and have consistent versions across all packages in our mono-repository.

There are three configuration files:

• .ncurc.patch.cjs: include packages in this array to prevent upgrading patch versions and higher.

• .ncurc.minor.cjs: prevent upgrading to new minor versions and higher.

• .ncurc.major.cjs: prevent upgrading to new major versions and higher.

• Check the configuration files above, to see if some of the updates no longer need to be blocked. Ideally the entries in these files have a code comment explaining the conditions where the upgrade no longer needs to be prevented.

patch versions

We don't allow ~1.0.0 style dependencies, so patch versions will not be installed automatically (1.0.0 to 1.0.1). That's why it is important to frequently install patches yourself.

• Run pnpm run update-patch to install new patch versions.
• Run npm run test-update and see if the build/lint/test scripts are still OK.
• Check if the logs contain any (new) warnings. You can compare the logs with GitHub Action logs for the main branch.
• If a patch update is problematic, you can temporarily add the package to the "ignore updates" list in .ncurc.patch.js.

Not all package maintainers use semantic versioning, especially 0.x.x versions, and alpha and beta versions. Unfortunately they will be installed as part of update-patch, so update-patch isn't as safe as you might think. You might want to read change logs of patch upgrades below 1.0.0 to see if there are breaking API changes.

• Check if any packages have upgrades like 0.1.2 ➝ 0.1.9, and pay extra attention to these packages.

Create a pull request at this stage already, since minor upgrades and major upgrades might take some effort. Patches sometimes contain security vulnerability fixes.

minor versions

We don't allow ^1.0.0 style dependencies (1.0.0 to 1.0.1)

• ideally install pnpm run update-minor.
• Run npm run test-update and see if the build/lint/test scripts are still OK
• If a minor update is problematic, you can add the package to the "ignore updates" list in .ncurc.minor.js.

major versions

• if there is time, install pnpm run update-major.
• Run npm run test-update and see if the build/lint/test scripts are still OK
• If a major update is problematic, you can add the package to the "ignore updates" list in .ncurc.major.js.

Make an issue for minor/major upgrades that require so much time we better schedule it in a sprint.

deprecations

Run pnpm install. If the log still contains deprecation warnings at this stage, check if they are direct dependencies. Are the dependencies mentioned in our own package.json files? Then it its probably worthwhile to investigate why the package is deprecated. A good information source is often the README on the page about the package on npmjs.com. They will likely mention the reason for deprecating the page (e.g: no time to install security patches, you are on your own!) and they might even suggest alternative packages.

GitHub Action

Dependabot pull requests are a great way to detect outdated dependencies in GitHub Actions.

• Upgrade all GitHub Action dependencies

Node.js

Check the Node.js website to see what the long term support version is ("Node LTS")

• Upgrade to the latest minor Node LTS version (long term support)
  • package.json
  • .nvmrc
  • .github/workflows/*: configure node-version or reference node-version-file: ".nvmrc"
• Vercel: go to project Settings ➝ General ➝ Node.js version and select the new major version

pnpm

• Upgrade to latest pnpm version
  • .github/workflows/*": upgrade pnpm version in GitHub Actions for pnpm
  • package.json under engines. "^version" is usually okay, an exact version dependency is undesirable for developer experience, unless everyone develops in Docker containers. You can install an exact version of pnpm in GitHub Action if you want to.

Vulnerabilities

• Check the "Security" tab of this GitHub repository and consider the Vulnerabilities
• Upgrade all vulnerable dependencies, or dismiss the alerts with a good reason.

Docker images

Currently this repo doesn't have a docker-compose.yml where image needs to be updated, or any Dockerfile where FROM needs to be updated.

Customize template repository

npm packages

• Configure npm organization in .npmpackagejsonlintrc.json (replace @example in valid-values-name-scope), and replace @example in every package.json and package-lock.json with find-and-replace. Use npm run lint:package-json and npm ls to check if you missed anything.
• Replace the @example/ reference in imports in every .js/.jsx/.ts/.tsx file with your scope
• Replace the @example/ reference in the packages/web-components-stencil/stencil.config.ts file with your scope
• Update the "repository" field of every package.json file with the URL of your repository. The SSH URL is preferred over the HTTPS URL.
• Optional: mention the name of your organisation in the "description" field of every package.json file.

CSS prefix

• Configure class name prefix in .stylelintrc.json with selector-class-pattern and replace example with your own prefix.
• Configure CSS keyframe prefix in .stylelintrc.json with keyframes-name-pattern and replace example with your own prefix.
• Configure custom CSS property prefix in .stylelintrc.json with custom-property-pattern and replace example with your own prefix.
• Configure custom SCSS variable prefix in .stylelintrc.json with scss/dollar-variable-pattern and replace example with your own prefix.
• Configure custom SCSS placeholder prefix in .stylelintrc.json with scss/percent-placeholder-pattern and replace example with your own prefix.
• Configure the CSS class name prefix by updating proprietary/design-tokens/style-dictionary.config.json and example in "selector": ".example-theme" with your own prefix.

Design tokens

• Configure the design token property prefix in every *.tokens.json:
  • replace { "example": {} } root property with your own prefix.
  • replace every instance of example in design token references with your own prefix, look for every instance of {example. in *.tokens.json.
• Rename directory example/ in proprietary/design-tokens/src/brand/example/ to your own prefix.

Documentation

• Configure your organisation name in documentation files:
  • Heading of README.md
  • Every instance of {author} in LICENSE.md files (as well as {year} for copyright)

Basiselementen: Icons

Foutmelding lint

Door een lint foutmelding kan de website niet meer gebouwd en gepubliceerd worden.

Zie: https://github.com/nl-design-system/rvo/actions/runs/8467665908/job/23198961105#step:6:482

Basiselementen: Checkbox input

Todo: Check if this is possible yet.

Basiselementen: Links

Add tokens to 'basiselementen' links and use the Utrecht component.
PR: #341

Basiselementen: Demo pages

Belasting dienst.
These new pages should show only the basic elements and no specific RVO content. This will allow for a clean overview of what is available.

PR: #356

Basiselementen: Blockquote

Check if BZK is using this. (Based on the Utrecht blockquote CSS component)

npm install fails

'npm install' gives following error:

npm ERR! code EUNSUPPORTEDPROTOCOL
npm ERR! Unsupported URL Type "workspace:": workspace:*`

Tried on different systems but always with the same result, is this a bug or am I doing something wrong?