HUDS design system

HUDS is a library of reusable design tokens, components, patterns and templates for building web sites and applications using unified look and feel of Helsinki University.

Note: This library is still under heavy development and we are still researching for the best ways to go forward. Please do not consider it to be production ready. We welcome any feedback and ideas on improving both the library and how to document the components.

The library is published in npm and documentation is hosted at https://static.helsinki.fi/ds/

Install

1. yarn install
2. yarn start should start a dev server in port 3333. It displays the content from src/index.html

Stencil

1. Have discussions with designers, agree on basic functionality
2. run yarn generate to generate a blanc component and start developing
3. Review the design with designer and PO or a colleague
4. Check with basic accessibility tools (TBD which tools?!?)
5. Build the library with yarn build. This will generate a .md file with some technical documentation to the components folder. Add your own desicription and instructions. At least it should
   1. Have a short introduction
   2. List all states the component can be in.
   3. List all variants the component can have
   4. Include code examples
6. Write unit tests where it makes sense. We use jest and puppeteer.
7. Make a merge request and ask a colleague for a review

Adding documentation to Vuepress

You should install the documentation project from https://version.helsinki.fi/julkiset-sivut/design-system.

To run it with your version of the design system, follow these steps:

1. Clone the repo and install dependencies with yarn install
2. By default the library uses the latest version from npm. To use newer library version, see linking instructions below
3. Add necessary .md files to VuePress /docs folder and update .vuepress/config.js

In case you want to develop and see the component inside documentation right away, you can adapt the following workflow:

Inside the library folder, make a dynamic link of the library:

yarn link

yarn build.watch (this builds the library on each save, so your changes will be reflected inside VuePress, thanks to the dynamic link)

Inside the Vuepress project

yarn link <library project name>

yarn docs:dev

Currently you need to manually sync .md files between the library and VuePress code bases. Best workflow could be to write documentation inside VuePress and then finally sync with matching file in library.

Running with Docker (WIP)

If you don't want or cannot install node and other dependencies, you can run the development setup locally in a container like this:

docker-compose up

Image can be rebuilt with docker-compose build if needed for example after a node package was added.

Making a release

After review is passed for both the library and documentation, changes can be merged to development branch. Both the library and the VuePress documentation follows similar process.

NOTE: remeber to check that the documentation project has a correct library dependency (version number) before making the merge.

The release process:

1. Merge the development branch into master
2. Run yarn version and bump the version number. This automatically creates a git tag with the new version
3. Push your changes. Then remeber also to update the tags in the remote like this: git push origin --tags