Skip to content

Latest commit

 

History

History
189 lines (133 loc) · 12.7 KB

README.md

File metadata and controls

189 lines (133 loc) · 12.7 KB
Raw

Utrecht 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.

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.

Getting started

Include the Design Token CSS variables:

<link rel="stylesheet" type="text/css" href="https://unpkg.com/@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 class="utrecht-theme">
  <h1>Page styled with NL Design System</h1>
</utrecht-html-content>

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

Above should become:

https://unpkg.com/@utrecht/design-tokens@1.0.0-alpha.10/dist/index.css

For stable versions it would become:

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

npm packages

name version
@utrecht/component-library-css NPM version
@utrecht/component-library-formio NPM version
@utrecht/components NPM version
@utrecht/design-tokens NPM version
@utrecht/icon NPM version
@utrecht/web-component-library-angular NPM version
@utrecht/web-component-library-react NPM version
@utrecht/web-component-library-stencil NPM version

Contributing

Install prerequisites

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

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:

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 utrecht
  5. git checkout main to switch to the main branch, if you previously worked in this repository.
  6. git pull to get to the latest version of the main 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 utrecht
  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/utrecht
  6. Press Control+C in your terminal to stop Docusaurus

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

Run Storybook on your computer

  1. Open Terminal.
  2. Ensure your current directory is utrecht
  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.
  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

npm scripts for development web servers

script description
npm run docusaurus Start development docusaurus at localhost:3000 (without access to Storybook, start npm run nx-storybook in parallel if you need that)
npm run nx-storybook Start development Storybook with composition for each framework at localhost:6006
npm run serve-docusaurus Start production Docusaurus website (without access to Storybook) at localhost:8080
npm run serve-storybook-angular Start production Storybook for Angular Components at localhost:7009
npm run serve-storybook-react Start production Storybook for React Components at localhost:7008
npm run serve-storybook-vue Start production Storybook for Vue.js Components at localhost:7007
npm run serve Start production Docusaurus website with access to each Storybook at localhost:8080
npm run storybook-angular Start development Storybook for Angular Components at localhost:6009
npm run storybook-css Start development Storybook for CSS Components, HTML Components and Web Components at localhost:6006
npm run storybook-react Start development Storybook for React Components at localhost:6008
npm run storybook-vue Start development Storybook for Vue.js Components at localhost:6007

npm scripts for quality assurance

script description
npm run lint-fix Check code formatting and automatically fix some types of issues
npm run lint Check code formatting et cetera
npm run nx-lint-fix Check code formatting and automatically fix some types of issues (but faster, using cache)
npm run nx-lint Check code formatting et cetera (but faster, using cache)
npm run nx-test Run unit test for each package (but faster, using cache)
npm run test Run unit test for each package

npm scripts for the release process

script description
npm run build Build each package
npm run nx-build Build each package (but faster, using cache)
npm run publish Publish each package to the npm registry
npm run release Determine new version number automatically and update each package.json

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.

Special thanks

Chromatic supports us with a free starter plan for open source.