Skip to content

About

Shared design system for Storyarr and Starboard: tokens, components, icons, a live gallery, and the content design and accessibility guides.

Topics

Resources

Contributing

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

TRex Design System

The design system for Storyarr and Starboard.

One design system for two self-hosted apps, so they share one design, one voice and one behaviour. It holds the shared component library (tokens, components, behaviour and icons), the design rules, the content design guide and the accessibility guide.

The two apps that use it

  • Storyarr: follow authors and series and keep your audiobook library complete. Built with React; it wraps the library's classes in its own components.
  • Starboard: an accessible dashboard for a home media server. Plain HTML and JavaScript; it uses the library as it is.

Each app keeps a copy of the library files, made by tools/sync.py, including the terminal frame and QR encoder. This repository is the source: never change the copies inside the apps.

What is in it

Path What it is
palettes/ Six more accent colours (Teal, Indigo, Forest, Plum, Ember, Graphite) over Mica's greys: load one after tokens.css
tokens.css Every colour, size, space and motion value as role names, for Light, Dark, High contrast and High contrast dark
components.css Every component, in @layer shared, using only the tokens
components.js The behaviour every component must have (menus, slide-outs, dialogs, phone menu, filter chips, copy, help, display settings), in plain JavaScript
icons.svg Lucide icons as an SVG sprite (<use href="#i-book-open">); tools/icons.txt lists them
fonts/ Atkinson Hyperlegible Next, with its licence
gallery.src.html, gallery.html The live gallery of every component (edit the .src file, then build)
areas/ Design boards for each area of both apps, built from the library. index.html is the Boards landing page; index-starboard.html and index-storyarr.html show each app's boards in the page, chosen from the menu, written by areas/make_index.py
docs/LIBRARY.md The component reference: every class, the rule for slide-out, dialog or page, and how each app adopts the library
docs/DESIGN-SYSTEM.md Principles, tokens, shell, page templates and consistency rules
docs/COMPONENTS.md Storyarr's interface before the redesign, and the duplicates to merge
docs/WIZARD.md Every job done in steps, in the browser and the terminal: one question per step, buttons, a job's progress, help in a slide-out, outside services, the Check table, feedback with Snaglist
docs/TERMINAL.md How a wizard appears and behaves in a terminal: the frame, questions, the menu line, help boxes, job bars, plain mode for screen readers, and feedback as a QR code
terminal/ The terminal frame every app's terminal scripts use (terminal-frame.sh) and the QR code encoder for feedback (qr.py); terminal/README.md says how to use them
docs/CONTENT-DESIGN.md How every word is written: voice, rules, words each app uses, status vocabulary, patterns
docs/HELP-WRITING.md How help is written: tiers, kinds of topic, categories, layouts, screenshots
docs/CHANGELOGS.md How every project keeps its changelog, after Keep a Changelog: Unreleased first, the six change types, links, withdrawn releases
docs/ACCESSIBILITY.md The accessibility floor and how to test it
docs/WCAG.md How the design system meets each point of WCAG 2.2 AA, after the GOV.UK Service Manual, and what each app must still do
docs/ALT-TEXT.md How to write text descriptions (alt text) for every kind of image, after the BBC's guidance
docs/SCREENSHOTS.md Screenshots in help: when one earns its place, made-up data only, the outline, arrow and step-number mark-up, and a short version for AI tools; tools/annotate.js draws and checks the mark-up
docs/SECURITY-CHECKS.md The security checks both apps run, how to sort what they find, and how to record the results and release notes
resources/ The Design resources and tools pages: what you can use, the tools, outside tools, how to make a change and how to get feedback
tools/help_centre/ The help centre builder every app's help uses: Markdown and help-centre.json in, the standard help centre out (docs/HELP-WRITING.md section 11)
tools/ Build, contrast, icon, sync and privacy scripts

Help centre components

The help centre standard (owner, 14 November 2026) added these components to components.css and components.js. Each is in the gallery under Help centre, and docs/LIBRARY.md has its classes and rules.

Component What it is
Top links (.top-links) The seven main items of a help centre as quick links in the header
Side tree (.side-tree) A side menu that folds three levels deep (area, group, page), with the current page marked and open; works with no script
Journey (.journey, .stage-card) Stages on a dashed path, each with a column of cards under it
Flow chart (.flow-chart) A decision chart in SVG that follows every theme, with the same paths in words
Answer card (.answer-card) A numbered answer with its number and heading on a grey band
Feature card (.feature-card) The newest thing, with a chip and a small chart or picture
Solver card and solver (.solver-card, .solver) The way into the problem solver, and the solver itself: one question at a time, lists of links with no script
Version badge (.version-badge) The latest version beside a heading, with no date
Plug-in card and band (.plugin-card, .plugin-band) A plug-in in the grey band design, in a list and at the top of its pages

Open the gallery

Open gallery.html in a browser; it needs no server and no build. Display, in the gallery's header, changes the theme (Light, Dark, High contrast), the text size, wider spacing and reduced motion. Menus, slide-outs, the phone menu and the dialog all work. The gallery is also published at https://themightytrex.github.io/design-system/gallery.html.

The boards open the same way: start at areas/index.html, choose an app, then a board in the menu. Each board shows in the page; Open on its own shows it in the whole window.

Design resources and tools

Design resources and tools lists everything here you can use, on five pages:

The pages are in resources/. Change the bodies in resources/content/, then run python3 resources/make.py and python3 tools/build.py.

The site's header, main menu (Components, Boards, Guides, Resources), phone menu and footer come from tools/sitepage.py, used by the resources pages and the Boards pages. The gallery keeps its own copy, because its header also has search: change both when the main menu changes.

Change a component and sync it

In short: pull first, change the library here (never the copies in the apps), build the gallery, check four themes and 175% text, run tools/contrast.py and tools/check_accents.py (0 failures each), tools/check_words.py, tools/check_tokens.py and tools/check-private.sh, commit, ask before you push, then run tools/sync.py and commit in each app. Every step, with its command, is in Make a change.

tools/install-hooks.sh adds a pre-commit check that stops banned words and private details (home network addresses, email addresses, keys and the words in your own .private-words file) from being committed.

Mica, the default design

Since 18 November 2026 (DASH-479) the design system's default is Mica: neutral greys, 6px corners, a light lift on cards and menus and one accent colour, Blue unless another is chosen. The dashboard card is the model for every container. The design before it (teal on blue-grey, square corners) is the Classic style in Starboard's Styles plug-in.

Accessibility floor

Everything here meets WCAG 2.2 level AA in every theme. In practice:

  • 4.5:1 contrast for text and 3:1 for control borders, card edges, the menu hover edge and the focus ring, with every accent colour, measured by tools/contrast.py and tools/check_accents.py.
  • 44px controls and targets, and a visible 3px focus ring.
  • Status in words plus a shape or an icon, never colour alone.
  • Keyboard first: slide-outs and dialogs are named, keep focus inside, close with Escape and return focus.
  • Everything works at 175% text and with wider spacing; nothing moves when Reduce motion is active.

docs/ACCESSIBILITY.md has the full checklist and how to test each item.

Contributing

Read CONTRIBUTING.md. Every word follows the content design guide.

Licences

About

Shared design system for Storyarr and Starboard: tokens, components, icons, a live gallery, and the content design and accessibility guides.

Topics

Resources

Contributing

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages