SUI tokens and typography

Purpose: Every design token SUI defines, what each one means, and which ones people expect to exist but don’t.

All tokens are declared on :root in sui.css. Always reference the variable, never the hex. A colour written as #43CDB6 is a colour that will not follow a theme change and will not read as semantic to the next person.

The complete machine-extracted list (72 tokens) is in generated/sui-inventory.md. This page groups them by what they are for.

Colour

Accents — interactive state

Text

Surfaces

Borders

The two --border-focus-* tokens are the closest thing SUI has to a focus indicator, and nothing in the stylesheet applies them to :focus. If you add keyboard focus styling — and you should, see gotchas — use these rather than inventing a colour.

Icons and gauges

Spacing — a 7-step scale

--spacing-xs: 2px    --spacing-sm: 4px     --spacing-md: 8px    --spacing-lg: 12px
--spacing-xl: 16px   --spacing-xxl: 24px   --spacing-xxxl: 32px

Most component gaps are 8–16px. There is no larger step; if a layout wants 48px of air, it is probably not a Structs layout.

Dimensions

--icon-xs: 8px    --icon-sm: 16px   --icon-md: 24px
--icon-lg: 32px   --icon-xl: 48px   --icon-xxl: 64px
--tile-width: 128px    --tile-height: 128px
--form-input-height-total: 40px
--from-input-height-content: 36px      /* [sic] */

Copy the typo. --from-input-height-content is misspelled in the source (from, not form). That is the real variable name, and .sui-screen-btn uses it for its height. Writing --form-input-height-content silently resolves to nothing.

Z-index — a defined stack, use it

Typography

Three families, six roles. Loaded via @font-face from fonts/sui/; Inter comes from a CDN in the webapp’s base template.

Font weight is 500 for every one of these except .sui-text-ticker, which is 400. That is the whole weight system — see rule 2 in the design language.

8px sounds unreadable. It isn’t, at scale(2). At 1× it is, which is what the scaling decision is about.

Colour-only helpers

.sui-text-primary, -secondary, -destructive, -disabled, -warning, -hint set color and nothing else — no metrics. Combine them with a metric class.

sui-mod-* doubles as a global colour utility. .sui-mod-primary, -secondary, -destructive, -disabled and -warning set color: on any element, not just inside components. <span class="sui-mod-warning"> is amber. This has consequences — see the inline alert trap.

Tokens that do not exist

There is no --accent-positive, --accent-negative, or --accent-warning. If you see those in a codebase, someone invented them. Map intent to real tokens:

SUI also defines font-variant-numeric nowhere. In a console full of changing figures you want tabular-nums on every numeric cell, or columns will jitter on each refresh. That is a sanctioned local addition, not a deviation — see examples/sui-patch.css.

Verified against structs-webapp 6eec7f7 (2026-07-21), src/public/css/sui/sui.css.