Make a change

How to change the design system so the change reaches Storyarr and Starboard, checked and in step.

This repository is the one source of the library. Change it here, check it, commit it, and then copy it into both apps. This takes 10 steps.

Before you begin:

You need Python 3, git, and copies of this repository, Storyarr and Starboard. Run tools/install-hooks.sh once, so the privacy check runs before every commit.

Steps

  1. Pull first, so you start from the latest version.
    git pull
  2. Change the library here: tokens.css, components.css, components.js, icons.svg or a guide in docs. Never change the copies inside the apps: the next sync replaces them. To add an icon, read Add an icon.
  3. Build the gallery and boards. If you changed these pages, run python3 resources/make.py first.
    python3 tools/build.py
  4. Check the gallery. Open gallery.html, select Display and check the change in each theme: Light, Dark, High contrast and High contrast dark. Then check it at 175% text and at phone width.
  5. Check contrast. The report must end with "0 failures".
    python3 tools/contrast.py > contrast-report.txt
  6. Check the words against the checklist in the content design guide, and the accessibility floor in the accessibility guide. Then run the banned words check and the token check; each must pass.
    python3 tools/check_words.py
    python3 tools/check_tokens.py
  7. Record the decision. When the change alters how something appears or works, add it to the decisions list in docs/LIBRARY.md.
  8. Run the privacy check, then commit.
    tools/check-private.sh
    git commit -am "Toasts: an action on warning toasts"
  9. Ask before you push. The owner of the repository approves every push. If you do not own it, open a pull request instead.
    git push
  10. Copy the library into both apps, then commit in each app, rebuild it and test it.
    python3 tools/sync.py --check
    python3 tools/sync.py

The first time you sync, tell sync.py where the apps are: read Copy the library into the apps.

How you know it worked

  • The gallery shows the change in all four themes and at 175% text.
  • contrast-report.txt ends with "0 failures".
  • python3 tools/sync.py --check lists no changes, and each app shows the change after its rebuild.

Find out more