Principles

Our key UX principles we must abide by for our customers' benefit.

Tone & Personality

Naming

The names we give CSS variables, design tokens, and components have to survive growth, redesigns, and new features. Four priorities drive every naming decision; a single structure pattern keeps tokens predictable; and a small list of preferences resolves the recurring "which word do we use" debates.

Priorities

Structure

Token and class names follow a consistent left-to-right pattern, narrowing from broad to specific.

--{category}-{property}-{variant}-{state}-{size modifier}

Examples

Categories

Rules

• All lower case.
• Keep Figma design tokens and CSS names the same — one source of truth, two surfaces.
• Prefer full words over abbreviations: background not bg; button not btn.

Preferences

When two reasonable words mean the same thing, we pick one and stick with it. The chosen term is in bold.

Theme & Consistency

• Always design in light theme first.
• Allow users to switch between light, dark, or system preference.

Colors

Our target is WCAG 2.x AA contrast across the whole system — accessible, readable, and inclusive interfaces regardless of theme. The ratio you need depends on what the colour is doing.

Product / accent colour

The product (or accent) colour changes per product. It carries the product's visual identity — brand chrome, hero accents, the product glyph — without touching any of the system's interactive states. Two examples shipping today:

Greyscale

Scales are generated from lightness values at 98, 96, 94, 90, 85, 80, 60, 40, 20 and 10. The active color can be used on backgrounds of --gray-1 and --gray-2. Backgrounds of --gray-3 and higher will fail contrast without shading the active color.

Usage notes

The first six steps build surfaces, fills, hovers and borders — the architecture the page is constructed from. The last four steps carry text, stepping from quietest helper copy at --gray-7 to the highest-contrast headings at --gray-10.

Active

The active colour signals interactivity — buttons, links, form-control states (checkboxes, radios, focus rings). Because no single hue holds 4.5 : 1 against every possible background, the active colour is shaded for its specific role: one tone for the resting state, one for hover, one for focus, and a separate tone for active text shown on a selected background.

Usage

--active-primary remains as an alias for --active — it's the token to reach for when you specifically need the contrast-safe variant for white text on an active-coloured background (the Primary button).

Validation — three variants

Pick whichever suits your application best. You can use the validation classes for general text highlighting, but use .warning-text rather than .warning as the warning colour does not pass contrast on light backgrounds.

Validation text colors

You can use the validation classes for general text highlighting, but use .warning-text as opposed to .warning as the warning colour does not pass contrast rules on light backgrounds.

Typography

Headings are sized proportional to the base text size. Line heights are calculated at 1.25× the font size and may be rounded to the nearest pixel if fractional sizes are not supported.

Headings

Font size modifiers

Font weights

Inline text

Use strong or bold to highlight specific words. Use links for navigation. Use inline code or samples in monospace. Subscript H₂O and superscript E = mc².

Date & time formats

Unless specified otherwise, display dates and times in the local format. The standard user-facing format is MMM DD, YYYY, HH:MM AM/PM — identified as the fastest to scan visually.

For tables, lists, and anywhere dates appear stacked, the digits must line up by column even when the dates themselves vary. The cleanest way to do that without breaking out of the page font is font-variant-numeric: tabular-nums: it keeps Inter as the family but engages the font's tabular-figure OpenType feature, so every digit takes the same advance width. The result reads as ordinary body text yet every comma, colon, and AM/PM lands in the same horizontal column down the list.

One caveat: the MMM month abbreviation is still proportional (Jan, Mar, and Sep have different widths in Inter), so the comma after the day number can shift a pixel or two between rows. For columns where perfect start-to-end alignment is non-negotiable — reconciliation tables, audit logs, batched timestamps — use a numeric format like YYYY-MM-DD HH:MM or MM/DD/YYYY HH:MM AM/PM with tabular-nums. Every character then comes from the digit set or fixed punctuation.

Implementation

Apply font-variant-numeric: tabular-nums on the cell, the column's td rule, or use the existing .tabular-nums utility from the product layer. The foundation already wires this on td.num and th.num in the Tables & Grids section, so the «Tonnes» and «Grade» columns there are already tabular without any per-cell styling.

Code

Code snippets and inline formulas use Fira Code — a monospace family with programming ligatures for the arrows, equality signs, and comparison glyphs that engineering input contains. The generic monospace keyword is the fallback, so terminals, embedded views, and offline contexts still render with a fixed-width family when Fira Code isn't available.

Example — formula

Snippet — declaration

code, samp, kbd, pre {
  font-family: 'Fira Code', monospace;
}

Full typography stack — @font-face declarations

The four font families used across the system are loaded locally via @font-face so the visual identity stays consistent regardless of the user's network or device font availability. Inter is the variable body face, Fira Code carries monospace contexts, Noto Serif SC handles Simplified Chinese, and Sandvik Sans is reserved for Sandvik-branded surfaces.

@font-face {
  font-family: 'Inter';
  src: url('Inter-VariableFont_opsz,wght.ttf') format('truetype');
  font-weight: 100 900;
  font-stretch: 50% 100%;
  font-display: swap;
}
@font-face {
  font-family: 'Fira Code';
  src: url('FiraCode-Regular.ttf') format('truetype');
  font-weight: 400;
  font-display: swap;
}
@font-face {
  font-family: 'Noto Serif SC';
  src: url('NotoSerifSC-Regular.ttf') format('truetype');
  font-weight: 400;
  font-display: swap;
}
@font-face {
  font-family: 'Sandvik Sans';
  src: url('SandvikSans-Regular.ttf') format('truetype');
  font-weight: 400;
  font-display: swap;
}

Font-family utility classes

Each face is reachable as a utility class so non-default contexts (a code block in a marketing page, a Chinese-language heading inside an English page, a Sandvik co-branded panel) can opt in without rewiring the whole element tree.

body, .font-body {
  font-family: 'Inter', sans-serif;
}
code, samp, kbd, pre, .font-code {
  font-family: 'Fira Code', monospace;
}
.font-chinese {
  font-family: 'Noto Serif SC', serif;
}
.font-sandvik {
  font-family: 'Sandvik Sans', sans-serif;
}

Special cases

When typography needs to display content in a language whose characters aren't well-served by Inter, switch to a face designed for that script. The default body font handles Latin glyphs cleanly but can't represent ideographic or other non-Latin scripts authentically — using a face designed for the script keeps the strokes, proportions, and visual rhythm that native readers expect.

For Simplified Chinese, the system uses Noto Serif Simplified Chinese (Google Fonts: Noto Serif SC) — a serif designed specifically for the character forms of simplified Chinese. Its stroke contrast and proportions reflect the script's construction in ways a Latin-first family cannot. Mark up the affected content with lang="zh-Hans" and the foundation's :lang(zh-Hans) rule swaps the family in automatically.

Example — Simplified Chinese

Snippet — declaration

:lang(zh-Hans) {
  font-family: 'Noto Serif SC', serif;
}

For Sandvik branding, use Sandvik Sans — Sandvik's own corporate sans-serif. Apply it to surfaces that carry the Sandvik visual identity (co-branded pages, partner widgets, equipment displays). The generic sans-serif keyword is the fallback, so machines or kiosks without the licensed font still render cleanly. Mark the affected element with data-brand="sandvik" and the foundation's [data-brand="sandvik"] rule swaps the family in automatically.

Example — Sandvik branding

Snippet — declaration

[data-brand="sandvik"] {
  font-family: 'Sandvik Sans', sans-serif;
}

Scale

Sizing and spacing are foundational layout primitives, but they describe different things: sizing is the dimensions of an element (icon size, font size, component height), while spacing is the gap between elements (gap, padding, margin). They share a numeric scale so the values feel consistent, and at the call site they appear under two parallel token names — --size-N for the dimension of a thing, --space-N for the breathing room between things.

When a product only ever needs three to five values per role, an optional set of t-shirt aliases (--gap-sm, --padding-md, --margin-lg, etc.) is documented under Add Ons → Spacing Variables.

The scale

Special case — borders. Borders use fixed pixel values (--size-1px, --size-2px) for visual precision. A rem-based 1 px border can blur or vanish at certain zoom levels; a pixel value renders the same hairline on every device.

Sizing — element dimensions

Reach for --size-N when the value describes the element itself — its font size, icon size, height, or border width.

Spacing — between elements

Reach for --space-N when the value is the gap, padding or margin around an element. Same numeric values as --size-N; the parallel name signals layout intent at the call site so a reviewer can tell a gap from a font-size at a glance.

When using these in Figma files, use pixels; in production code, prefer the relative rem values so the layout scales with the user's root font size.

Size modifiers

Size modifiers scale a whole component while preserving its proportions — the height, internal padding, font size and icon size all step together. Apply them to entire components (buttons, inputs, cards), not to individual properties.

Font size modifiers

Where the size modifiers above scale a whole component, font size modifiers scale a single piece of text relative to the element's own base size. They drive the same --font-size-scale variable that the foundation uses internally for headings, so a piece of text inside a heading still scales proportionally rather than jumping to a fixed pixel value.

Reach for --font-size-scale directly only when none of the four modifier classes fits. Otherwise use the named class so the value stays anchored to the t-shirt scale shared with component size modifiers.

Tables and Data Grids

Table — used when space is available, visual display is more important and when data has a complex structure. Data grid — used when high density is needed, with inline editing as a key feature, where Excel would be a substitution.

Table (banded, with row states)

Data grid (high density)

Alignment rules

Clickable cell text

When a cell value navigates to a record's own page, render the text in --text-color by default and only colour it on hover. A row of clickable cells in their default --active state competes with chips, status pills, and the row's own selection state for attention; pulling the colour back to body text keeps the table calm and reserves the active colour for the moment of intent.

Example

Hover any name to see the link colour and underline appear; the cell stays neutral the rest of the time so the chips and selection state read first.

Snippet — declaration

table td a {
  color: var(--text-color);
  text-decoration: none;
}
table td a:hover {
  color: var(--active);
  text-decoration: underline;
}

Buttons

Button contents may include icons and text. As a general rule, contents should not wrap onto multiple lines. Each variant has states for: enabled (default), hover, focus and disabled.

Variants

With icons

Icon inherits the button's text colour, sized at --size-4, with a --size-2 gap from any text — all from the foundation button rule.

States

Usage

Form Inputs

Form inputs are minimally styled — browser defaults control the main appearance. Inputs and buttons share the same height for visual consistency. Inputs should be sized to the content they accept. Labels are inline with fields, right-justified, and linked via for/id.

Navigation

Tabs — horizontal

Tabs — vertical

Cards

Card containers group content. Use .card-1 or .card-2 for tinted backgrounds.

Page Layouts

Two primary page layout variants for product UIs.

Layout templates

Icons

Icons are a visual representation of a function or message that helps reinforce it. They act as accelerators for advanced users who can recognise the symbol without reading the accompanying text.

Purpose and philosophy

Structure

Use <i> tags with Font Awesome classes. Always include .fa-fw so icons share a fixed width and align cleanly when listed, stacked, or paired with text.

<i class="fal fa-fw fa-house"></i>

Vue and React FA packages use the same icon names with a shorthand:

<FontAwesomeIcon :icon="byPrefixAndName.fal['house']" />

<FontAwesomeIcon icon={byPrefixAndName.fal['house']} />

Variants

Each product may use whichever variant or combination of variants it chooses — they need only be consistent within the product.

Stacked icons

Some icons (especially validation icons) contain a cutout that shows the surface colour through. Stack icons to place a solid white or black backplate behind the shape, making the symbol clearer against any background.

Apply .fa-stack to the parent element of the two icons, and add .fa-stack-1x or .fa-stack-2x to the icons themselves to size them within the stack.

<span class="fa-stack">
  <i class="fa-solid fa-triangle fa-stack-2x black"></i>
  <i class="fa-solid fa-triangle-exclamation fa-stack-2x warning"></i>
</span>

<span class="fa-stack">
  <i class="fa-solid fa-circle fa-stack-2x background"></i>
  <i class="fa-solid fa-circle-check fa-stack-2x success"></i>
</span>

States, behaviours, and interactions

App and Model Space Considerations

General app considerations

Modal space considerations