Design Tokens

Overview

Design tokens are named CSS custom properties that encode the brand's visual decisions. Every CAAT component references tokens instead of hard-coded values, ensuring consistency and enabling theming at a single point of change.

All tokens are defined in /assets/css/tokens.css on the :root selector and are available globally. Components should never use raw hex values or pixel measurements — always reference the token.

Token tiers

Tokens are organized in tiers so a brand change happens in one place and cascades everywhere:

Theme: light only (by decision). The semantic tier still earns its keep — a rebrand or future theme only re-points Tier 2. See docs/design-system-recommendations.md §A.

Colour Tokens

The palette is divided into brand blues, greens, neutrals, and semantic colours for feedback states.

Blues

Greens

Neutrals

Semantic / Feedback

Colour Usage Reference

Colour Contrast (AODA / WCAG AA)

CAAT is bound by the AODA, which requires WCAG 2.0 AA today and WCAG 2.2 AA by 2027 — we build to 2.2 AA now. Colour contrast thresholds:

• 4.5:1 — normal text
• 3:1 — large text (≥24px, or ≥18.66px bold)
• 3:1 — UI components, graphical objects & focus indicators (1.4.11)

An audit script computes the ratio for every real pairing. Re-run after any colour change:

node scripts/contrast-audit.js   # exits non-zero if any required pairing fails

Fixes applied

Usage restrictions (colours that fail on light surfaces)

These colours are fine in their intended role but must not be used as described:

Semantic Tokens

Semantic tokens express intent ("primary action", "muted text") rather than a raw value. Components should reference these — they alias the primitive palette, so a brand change happens once, here.

Text

Surfaces & borders

Actions & focus

Feedback

Each status has matching -bg, -border, and (where text sits on the fill) -text tokens: --caat-color-feedback-info-*, -success-*, -warning-*, -danger-*.

Typography

CAAT uses Libre Franklin as its sole typeface across all digital touchpoints. The font is loaded from Google Fonts in weights 300–900.

Font Families

Letter Spacing

Font Weights

Type Scale

The heading scale uses .caat-title classes from the Text / Title component. All headings use weight 800, tight letter-spacing, and --caat-blue-900.

Title & Text CSS Classes

The Text / Title component provides ready-made utility classes for typography.

Long-form prose & vertical rhythm

Running prose (articles, guides, policy) uses a typographic rhythm, not the 4px UI spacing scale. The principle: space belongs to what follows — a heading opens a large gap before it (it begins a new section) and a small gap after it (so it attaches to its first paragraph). The cadence is heading-before > paragraph-flow > heading-after. Use the canonical .caat-rich-text container; other components (e.g. the Article Layout body) compose it.

Eyebrow (overline label)

A short kicker above a heading used for categorization or context only. There is now one canonical class, .caat-eyebrow, driven by the --caat-text-eyebrow-* / --caat-color-eyebrow tokens. The legacy component-scoped aliases (.caat-title__eyebrow, .caat-feature-hero__eyebrow) have been removed; all markup uses the canonical class.

<!-- on light -->
<span class="caat-eyebrow">Pension Solutions</span>
<h2 class="caat-title caat-title--h2">A better pension matters</h2>

<!-- on dark / imagery -->
<span class="caat-eyebrow caat-eyebrow--on-dark">Pension Solutions</span>

Accessibility & rationale: see docs/design-system-recommendations.md §B1.

Spacing & Radius

Spacing Scale

A 4px-based scale. Use these for padding, margins, and gaps instead of arbitrary values — it's what keeps rhythm consistent across components and the page-layout grid.

Radius

Radius Preview

Shadows & Elevation

Elevation maps to a role, not a pixel value — pick by what the surface is, so layering reads as a system.

Shadow Preview

Motion

Consistent timing makes the UI feel like one product. Pair a duration with an easing; default to --caat-duration-base + --caat-ease-standard for most transitions.

Z-index / Layering

A single ordered scale prevents stacking bugs (modal behind a sticky header, toast behind a backdrop). It is deliberately aligned to coexist with Bootstrap's 1000–1090 range — use these instead of inventing z-index values.

Focus Ring

Focus Preview

The focus ring is a solid blue-500 ring — it meets WCAG 1.4.11 (3:1) on both light (3.31:1) and dark navy (3.82:1) surfaces. (An earlier semi-transparent version failed at 1.47:1 and was replaced.) Consume it through the semantic alias and apply as:

.my-component:focus-visible {
  outline: 0;
  box-shadow: var(--caat-color-focus-ring);
}

Bootstrap Overrides

The token file maps CAAT values onto Bootstrap's CSS custom properties so Bootstrap utilities and components inherit brand styling automatically.

Usage Guidelines

Source File

All tokens are defined in a single file that every component and template imports:

/assets/css/tokens.css

The file is organized in three tiers — Primitives (raw values), Semantic (intent aliases that components consume), and Bootstrap overrides. Rather than duplicate it here (which drifts out of date), view the canonical source directly:

Open tokens.css