Design system

Stratastax has one design system for every surface: the Flutter apps, this documentation site and the API explorer. It is defined once, in stratastax.tokens.yaml in stratastax-design, and exported for each of them.

Principles

• Calm first. The rest and consistency of shadcn/ui: neutral surfaces, 1px borders, little shadow and compact type. The neutrals have a slight indigo tint, so they feel calm and still our own.
• A few vivid colours, used on purpose. Indigo for actions, teal for secondary actions and positive data, coral and violet as accents. Subtle colour fields carry callouts, cards and bands.
• Accessible by construction. Every text colour passes WCAG AA (4.5:1) on the backgrounds it is used on, in light and dark. The tests of stratastax-design fail otherwise, and the stx compiler warns about any app that breaks it.
• Light is the primary mode, and dark is complete as well.

Tokens

Each swatch shows the light and the dark value, with the contrast of the text that goes on it.

Brand

Aalight #4F46E5 · 6.3:1

Aadark #818CF8 · 5.9:1

primary

Aalight #14B8A6 · 6.1:1

Aadark #2DD4BF · 9.5:1

secondary

Aalight #0F766E · 5.2:1

Aadark #2DD4BF · 9.7:1

secondaryStrong

Aalight #F97360 · 5.6:1

Aadark #FB8A78 · 7.6:1

accent

Aalight #7C3AED · 5.7:1

Aadark #A78BFA · 6.5:1

highlight

light #8B5CF6

dark #A78BFA

focus

Status

Aalight #0F766E · 5.5:1

Aadark #2DD4BF · 9.5:1

success

Aalight #D97706 · 5.6:1

Aadark #FCD34D · 12.3:1

warning

Aalight #DC2626 · 4.8:1

Aadark #F87171 · 6.4:1

danger

Neutral

Aalight #F8F9FF · 14.5:1

Aadark #11142A · 15.2:1

background

Aalight #FFFFFF · 15.3:1

Aadark #171B34 · 14.1:1

surface

Aalight #EEF0FB · 13.5:1

Aadark #272B44 · 11.6:1

subtle

Aalight #565C7E · 6.2:1

Aadark #9AA0BC · 7.0:1

muted

light #E0E3F2

dark #272B44

border

Subtle fields

Aalight #EEF0FF · 13.5:1

Aadark #23274B · 12.0:1

primarySubtle

Aalight #E6FAF7 · 14.1:1

Aadark #153342 · 11.1:1

secondarySubtle

Aalight #FFF0EC · 13.8:1

Aadark #362736 · 11.7:1

accentSubtle

Aalight #F3EEFF · 13.4:1

Aadark #29274B · 11.8:1

highlightSubtle

Aalight #FFF7E6 · 14.3:1

Aadark #373330 · 10.5:1

warningSubtle

Aalight #FEF2F2 · 14.0:1

Aadark #362335 · 12.1:1

dangerSubtle

Gradient, radius and fonts

light

dark

gradient.brand

6px

radius.sm

8px

radius.md

12px

radius.lg

• sans Inter: The quick brown fox records a match
• heading Plus Jakarta Sans: The quick brown fox records a match
• mono JetBrains Mono: The quick brown fox records a match

Rules of use

Do	Don’t
Use primary for the one main action on a screen, secondary or an outline button for the others	Use more than one coral accent or one gradient per screen
Put text on a vivid fill in its on* colour: ink on teal and coral, white on indigo, the strong teal and danger	Use coral for errors: an accent must never read as a failure, errors are danger
Use the subtle fields with ink text for callouts and bands	Put white text on fresh teal, coral or violet glow (2.5, 2.7 and 4.2:1); use the strong variants

The type is Inter for text, Plus Jakarta Sans for headings and JetBrains Mono for code. The radius is 8px for buttons and fields, 12px for cards and round for pills, and the spacing is a multiple of 4px.

Using the tokens

Where	How
Flutter apps	stratastax.tokens.yaml is the brand layer of the stx compiler: stx_style defaults ← the brand ← the app’s own stx.tokens.yaml
Web, shadcn/ui	/design/tokens.css: every token as a --stx-* property and the shadcn/ui variables
Starlight	/design/starlight.css, after tokens.css (this site)
Swagger UI	/design/swagger.css (the API explorer)
Design tools	/design/tokens.json, in the Design Tokens Community Group format