README
DSO Toolkit - Design System van het Digitaal Stelsel Omgevingswet (DSO)
De DSO Toolkit bestaat uit documentatie en een stijlgids. Daarnaast worden er twee implementaties geleverd: CSS en Web Components. De Web Components krijgen voor Angular en React wrappers, zie issue #915.
De deliverables van de DSO Toolkit:
- Handleiding: Een handleiding voor elke versie op https://www.dso-toolkit.nl/
- CDN: Een CDN op https://cdn.dso-toolkit.nl/, voor documentatie zie verderop in deze README
- NPM package
@dso-toolkit/sources
: Alle bronbestanden van het DSO Design System. - NPM package
dso-toolkit
: De handleiding en complete CSS implementatie van de DSO stijlset.
We zijn bezig met het verhuizen van de styling van dso-toolkit
naar @dso-toolkit/sources
. Zodra die verhuizing is afgerond zal dso-toolkit
worden deprecated en moeten implementaties overstappen naar @dso-toolkit/core
(eventueel met Framework bindings), @dso-toolkit/css
of @dso-toolkit/sources
. De componenten zoals die worden aangeboden op https://www.dso-toolkit.nl/ blijven functioneren. Voor meer informatie zie #827
Getting started
Stable releases can be found on the GitHub Releases page.
NPM registry
npm install dso-toolkit --save-dev
Compile SCSS
Stylesheets need to be compiled using Dart Sass. libsass (NPM package node-sass
) is unsupported.
- Add
node_modules/dso-toolkit/libs
as load path to your (Dart) Sass compiler/wrapper. - Import
/node_modules/dso-toolkit/src/dso.scss
in your stylesheet or build process.
Bundle CSS
Import or bundle /node_modules/dso-toolkit/dist/toolkit/styles/dso.css
.
CDN
The toolkit and component library are distributed to dso-toolkit.nl. Use the table below to resolve the branch/channel to the base url:
branch | channel | url |
---|---|---|
master | stable | https://cdn.dso-toolkit.nl/master/ |
tags only | releases | https://cdn.dso-toolkit.nl/VERSION/ |
The same goes for the component library:
branch | channel | url |
---|---|---|
master | stable | https://www.dso-toolkit.nl/master/ |
tags only | releases | https://www.dso-toolkit.nl/VERSION/ |
<link rel="stylesheet" href="https://cdn.dso-toolkit.nl/[master|VERSION]/styles/dso.css" />
For Web Components:
<script type="module" src="https://cdn.dso-toolkit.nl/[master|VERSION]/core/dso-toolkit.esm.js"></script>
<script nomodule src="https://cdn.dso-toolkit.nl/[master|VERSION]/core/dso-toolkit.js"></script>
The referenced scripts are very small: Only the actually used Web Components are lazy loaded. For more information: https://stenciljs.com/docs/distribution
Develop or mockups
To work on the DSO Toolkit using components and variants or create mockups of pages, forms or components you need Node 16 and Yarn. See CONTRIBUTING.md on how to contribute.
Either install Yarn with
npm install --global yarn
or use Yarn with npx
:
npx yarn <<<my commands here>>>
git clone git@github.com:dso-toolkit/dso-toolkit.git
cd dso-toolkit
yarn install
Environments
Depending on the work being done, development can be done in several environments:
fractal
The classic environment with Fractal and Stencil. Because this environment needs two packages (@dso-toolkit/core
and dso-toolkit
) running, this command only be started from the root of the repository, :
yarn fractal
Fractal is started at http://localhost:43000/, Stencil is running on http://localhost:53333. See the Fractal guide for more information on Fractal.
development
This environment is used to develop new components in Storybook. Storybook is built around stories and since this project has multiple Storybooks (one for each implementation), the stories are put in a separate package @dso-toolkit/sources
(/packages/sources
). All the implementations have a devDependency on @dso-toolkit/sources
.
The easiest way to start this environment is with one of the following commands:
yarn start:core
yarn start:react
yarn start:css
yarn start:all
This will start @dso-toolkit/sources
in watch mode and run the corresponding Storybook(s). Since these commands contain a colon (:
), these commands can be run from anywhere in the project.
The following processes are started:
- core:
@dso-toolkit/sources
in watch mode, Stencil in development mode for Web Components, and Storybook - react:
@dso-toolkit/sources
in watch mode, Stencil in watch mode for production, and Storybook for React components - css:
@dso-toolkit/sources
in watch mode, Gulp in watch mode for the SVG spritesheet, dart-sass in watch mode for CSS compilation, and Storybook
Alternatively, you can start a specific implementation with:
yarn workspace @dso-toolkit/core start
yarn workspace @dso-toolkit/react start
yarn workspace @dso-toolkit/css start
but then you need to make sure that @dso-toolkit/sources
is running in watch mode or already built:
yarn workspace @dso-toolkit/sources start
yarn workspace @dso-toolkit/sources build
In case of starting a framework binding package you also need to make sure that @dso-toolkit/core
is built:
yarn workspace @dso-toolkit/core build
cypress
To write tests the following processes are started:
- Stencil, in prod mode
- Storybook, in cypress mode
- Cypress GUI
yarn workspace @dso-toolkit/core cypress
This will start Stencil on http://localhost:53333, Storybook on http://localhost:56106 and the Cypress GUI. Since Stencil and Storybook are running it's possible to develop the components, but keep in mind the tests run in a production environment: This means no Stencil development tools like HMR.
leaflet
Like fractal
, development of Leaflet plugins is package transcendent. Run the following command from root:
yarn start:leaflet
yarn start:react-leaflet
This will start Stencil (http://localhost:53333) and Storybook (http://localhost:56106) in production (no live reload / HMR) and the Leaflet plugins development environment on http://localhost:41234 or the React Leaflet development environment on http://localhost:42345.
Requirements
Node 16. For development on the DSO Toolkit you also need Yarn.
Dependencies
The DSO Toolkit and Component Library uses
npm
as the registry for node packagesyarn
for package managementgulp
for build automationsass
to compile SCSS to cssfractal
to document the toolkityaml
to configure fractal components
Further reading
- https://www.npmjs.com/
- http://fractal.build/
- http://keepachangelog.com/en/1.0.0/
- http://semver.org/
- http://handlebarsjs.com/
- http://www.yaml.org/
Ports
Ports used during development:
- 41234 - Leaflet plugins dev app
- 42345 - React Leaflet plugins dev app
- 43000 - Fractal
- 53333 - Stencil
- 56106 - Storybook for Web Components
- 56206 - Storybook for CSS components
- 56406 - Storybook for React components