Tools in this repository
The scripts in the tools folder: what each one does and the command that runs it.
You need Python 3 and a copy of the repository. Run every command from the repository's own folder.
Build the gallery and boards: build.py
Turns each .src.html file into the page people open. It replaces {{i:name}} with an icon and <!--ICONS--> with the icon file. Change the .src.html file, never the page it makes.
python3 tools/build.pyThe pages in resources are made from resources/content. After you change one, run this before build.py:
python3 resources/make.pyCheck contrast: contrast.py
Measures every text and control colour pair against WCAG 2.2 AA (Web Content Accessibility Guidelines): in all four themes, and in Light and Dark for every palette. Text needs 4.5:1, and control borders and the focus ring need 3:1. The report must end with "0 failures".
python3 tools/contrast.py > contrast-report.txtCheck every accent: check_accents.py
Measures every token pair the components draw, for every accent colour, in Light, Dark, High contrast and High contrast dark, including the menu hover fill and its edge worked out over each surface. Text needs 4.5:1; control edges, card edges and rules, the hover edge, the current-item bar and the focus ring need 3:1. It fails on any pair that falls short of the rule.
python3 tools/check_accents.py --report accent-report.txtMark up a help screenshot: annotate.js
Draws the outline, curved arrow and step-number badge that Screenshots in help sets out, anchored to the page's own elements, then checks that each outline still wraps its control, nothing is off the screen or covered, and the badges match the article's steps. Paste it into the browser's console on a preview with made-up data, mark, check, then take the screenshot.
Annotate.mark("Add an app", { step: 2 }); Annotate.verify({ steps: [2] })Make the palettes: palettes.py
Writes the six accent colours in palettes/ and the gallery's Accent colours section. A palette changes only the accent, in every theme. Surfaces, status colours and chart series stay the same, so their meanings never change. Run check_accents.py after it.
python3 tools/palettes.pyAdd an icon: icons.py
Rebuilds icons.svg from Lucide. Add the icon's Lucide name to tools/icons.txt, then run:
python3 tools/icons.py "$(tr '\n' ' ' < tools/icons.txt)"Copy the library into the apps: sync.py
Copies tokens.css, components.css, components.js and the icons into Storyarr and Starboard, so both apps use the same components. It does not commit. Add --check to list what would change without writing anything.
python3 tools/sync.py --checkpython3 tools/sync.pyBy default it uses ../starboard and ../storyarr beside this repository. To use other folders, set STARBOARD_WEB and STORYARR_SHARED, or put them in tools/paths.local.json, which git ignores:
{
"STARBOARD_WEB": "~/src/starboard/web",
"STORYARR_SHARED": "~/src/storyarr/apps/web/src/shared"
}Keep banned words out: check_words.py
Checks the guides, the gallery, the Boards and resources pages, and the strings in components.js and the terminal frame for the words the content design guide bans, such as "see", "look", "click", "type" for entering, "above", "below" and "please". It leaves out code and a word quoted on its own. A genuine exception goes in tools/words-allowed.txt, with its reason. It ends with a list of lines to fix, or "none".
python3 tools/check_words.pyUse only real tokens: check_tokens.py
Lists every name a style sheet uses that tokens.css does not have, and the token to use instead. With no files it checks components.css; an app gives its own.
python3 tools/check_tokens.py ../starboard/web/css/*.cssKeep private details out: check-private.sh and install-hooks.sh
check-private.sh stops a commit that would publish home network addresses, email addresses, keys, or the words in your own .private-words file (one word a line; git ignores it). install-hooks.sh runs this check and the banned words check before every commit in your copy. Run it once.
tools/install-hooks.shtools/check-private.sh