# Developer guide

Currently the project lives in 2 repositories. If you want to add new components to the design system, you need access for both projects.

Design system documentation (opens new window)

Code repo for the documentation you're currently reading. It is built with VuePress and is hosted at https://static.helsinki.fi/ds (opens new window). Each page is a single markdown file.

Design system library (opens new window)

The component library itself is built using Stencil.js and is made available from npm. You can use the library as a module or directly using a script tag

# Usage

# Direct import

If you want to use the library as a direct import, for example in a quick prototype or a vanilla html site, you can use the library from a CDN. You must import the font definitions first and then the library:

<link
   rel="stylesheet"
   type="text/css"
   href="https://cdn.jsdelivr.net/npm/@itcenteratunihelsinki/huds-lib@0.0.2/dist/fonts/fonts.css"
/>
<link
   rel="stylesheet"
   type="text/css"
   href="https://cdn.jsdelivr.net/npm/@itcenteratunihelsinki/huds-lib@0.0.2/dist/huds-lib/huds-lib.css"
/>
<script
   type="module"
   src="https://cdn.jsdelivr.net/npm/@itcenteratunihelsinki/huds-lib@0.0.2/dist/huds-lib/huds-lib.esm.js"
></script>
<script
   nomodule=""
   src="https://cdn.jsdelivr.net/npm/@itcenteratunihelsinki/huds-lib@0.0.2/dist/huds-lib/huds-lib.js"
></script>

# Module import

If you are working in a modern JavaScript environment, you can install the library from npm:

yarn install @itcenteratunihelsinki/huds-lib

Web components should work with all frameworks, but there are limitations. You can find documentation on how to load stencil components here (opens new window)

IMPORTING FONTS AND GLOBAL CSS

Currently for the fonts and global styles to work, you need to import them separately. Add this line before you load the library itself:

import "@itcenteratunihelsinki/huds-lib/dist/fonts/fonts.css" import "@itcenteratunihelsinki/huds-lib/dist/huds-lib/huds-lib.css"

# Development setup

# Installing and local development

For smoothest experience you should have node 12.16.1 (LTS) or newer and yarn installed. Another option is to use the provided docker setup.

  1. Clone the repositories and install dependencies in both folders by: yarn install
  2. Start Vuepress dev server yarn docs:dev
  3. Start Stencil dev server yarn start

# Basic component creation workflow (design-system-lib)

  1. Have discussions with designers, agree on basic functionality
  2. Run yarn generate and start development
  3. Review the design with designer and PO or a colleague
  4. Check with basic accessibility tools (TBD which tools?!?)
  5. Build the library running yarn build, which will autogenerate technical documentation. Add your own instructions to this .md file and copy it to VuePress (see below). It should:
    • Have a short introduction
    • List all states the component can be in.
    • List all variants the component can have
    • Include code examples
  6. Write unit tests where applicable, if you prefer to write tests before developing the component, that's even trendier!
  7. Make a merge request and ask a colleague to review it.

# Adding documentation (design-system)

Best way is to take a look inside /docs folder and see how content is added. These steps should have you covered

  1. Add a new folder inside /docs folder.
  2. If you want the folder to have its own content, add a README.md file.
  3. Copy the .md file documentation you wrote for the component during development . Make sure to use correct Front Matter Notation in the header of each file. Take a look of current file structure for examples.
  4. Finally register the pages inside .vuepress/config.js
  5. Ask for a colleague for review

# Vuepress extensions

There's a few extensions installed for VuePress.

A Live code block that should be used for it's styling and added usefullness to provide option to test code on the fly

Also a custom container plugin is added. It let's us use custom containers in markdown. There's already a few examples. Feel free to implement your own when needed. Use the Button component for reference.

# Making a release

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

NOTE: remember 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 like this: git push origin --tags

# Coding style

No rigorous coding standard has yet been implemented, which can be seen throughout the codebase. We're still trying things out.

← Designers →