Design Tokens — Work Better Together

How this works

Engineers and design tools consume tokens/tokens.css — a single CSS variables file. Three tiers organize the values:

Tier 1

Primitives

Raw brand values: hex codes, spacing pixels, font sizes. The truth source. Never reference directly in components.

Tier 2

Semantic

Role-based: surface.canvas, ink.default, border.focus. This is the API.

Tier 3

Component

Per-component overrides: btn.radius, input.padding. Optional layer.

/* In a component, always reference semantic tokens */
.button {
  background: var(--btn-primary-bg);
  color:      var(--btn-primary-ink);
  padding:    var(--btn-padding-y) var(--btn-padding-x);
  border-radius: var(--btn-radius);
  transition: background var(--motion-state);
}
.button:focus-visible {
  outline: var(--state-focus-ring-width) solid var(--state-focus-ring);
  outline-offset: var(--state-focus-ring-offset);
}

Color · Surface

Backgrounds and container fills. Use surface.* wherever a component needs a fill. The page itself sits on surface.canvas; cards on surface.default.

Token	Value	Role
`--surface-canvas`	`#FAF9F7`	Page background — warm off-white
`--surface-default`	`#FFFFFF`	Cards, panels, form fields
`--surface-muted`	`#F2F1EB`	Hover state on light surfaces
`--surface-subtle`	`#E0E8EB`	Callouts, info panels, element-notes
`--surface-inverse`	`#1F1E1E`	Dark sections, navigation chrome
`--surface-inverse-soft`	`#1E4D5C`	Dark-but-warmer dark sections
`--surface-brand-primary`	`#061A49`	Hero, primary brand surface
`--surface-brand-action`	`#2531A5`	CTA fills, action buttons
`--surface-brand-accent`	`#CD9F36`	Emphasis, insight pulls
`--surface-brand-cream`	`#F9F8F2`	Warm neutral surfaces

Color · Ink

Text colors. ink.default is full Grounded Black at 100%. ink.muted only for meta/captions — never body. ink.action is the link / interactive label color.

Token	Value	Role
`--ink-default`	`#1F1E1E`	Body, headings, default text
`--ink-muted`	`#6B6B6B`	Meta, captions, low emphasis (NOT body)
`--ink-subtle`	`#9A9A9A`	Placeholder, very-low emphasis
`--ink-inverse`	`#F9F8F2`	Text on dark surfaces
`--ink-brand`	`#1E4D5C`	Eyebrows, secondary brand ink
`--ink-accent`	`#061A49`	Primary brand text emphasis
`--ink-action`	`#2531A5`	Links, action labels
`--ink-warning`	`#B55312`	Friction, challenge, errors
`--ink-emphasis`	`#CD9F36`	Insight pulls (use sparingly)

Color · Border

Token	Value	Role
`--border-subtle`	`#E4E2DE`	Default rule line, card borders
`--border-default`	`#CFCDC8`	Hover state on inputs
`--border-strong`	`#1F1E1E`	Secondary buttons, attribute-table head
`--border-focus`	`#2531A5`	Focus ring, active inputs
`--border-brand`	`#1E4D5C`	Callout left accent

Color · Status & feedback

Semantic mappings derived from the brand: Slate for affirmative/info, Ochre for warning/critical. Each set comes with a soft surface, a stronger border, and a high-contrast ink for body copy.

Success / Do

Use for affirmative confirmation, "do" guidance, and positive state messaging. Slate-derived.

Info

Use for neutral context, callouts, and informational annotations. Identical visual language to the type-page element-note.

Warning / Don't

Use for caution, "don't" guidance, and friction states. Ochre-derived.

Critical / Error

Use for blocking errors, destructive confirmations, and high-stakes warnings. Stronger ochre treatment.

Spacing

4px base. Use semantic tokens (gap.tight, gap.default, gap.loose, gap.section) in components — primitives only when a specific pixel value is required.

--space-052px

--space-14px

--space-28px

--space-312px

--space-416px

--space-520px

--space-624px

--space-832px

--space-1040px

--space-1248px

--space-1456px

--space-1664px

--space-1872px

--space-2080px

--space-2496px

Semantic gap roles

Token	Resolves to	Use for
`--gap-tight`	`8px`	Within a component (button label ↔ icon)
`--gap-default`	`16px`	Between fields in a form
`--gap-loose`	`32px`	Between content blocks
`--gap-section`	`72px`	Between major page sections

Radius

The brand favors editorial precision over softness. Default to radius.none; use radius.sm for chrome (badges, tags, inputs); use radius.pill only for filter pills and toggles.

None0

SM2px

MD4px

LG8px

XL16px

Pill999px

Border width

--border-1

1px · subtle

--border-2

2px · strong

--border-3

3px · accent

Type · Roles

Composite tokens — each maps to family + weight + size + line-height + tracking. See Type Scale and Brand Fonts for design rationale.

Display

Leadership.

--type-display
League Spartan 700 · clamp(56–112px) · LH 1.0

H1

Page heading.

--type-h1
League Spartan 700 · clamp(36–56px) · LH 1.1

H2

Section title.

--type-h2
League Spartan 700 · 36px · LH 1.1

H3

Subsection.

--type-h3
League Spartan 700 · 28px · LH 1.1

H4

Block heading.

--type-h4
League Spartan 700 · 20px · LH 1.1

Body lg

Lora 400, the lead paragraph or long-form body. Calm, readable, generous in line-height.

--type-body-lg
Lora 400 · 17px · LH 1.65

Body

Default body text. Most page copy lives here.

--type-body
Lora 400 · 15px · LH 1.65

Body sm

Captions, small body, helper text.

--type-body-sm
Lora 400 · 13px · LH 1.5

Pull quote

Encouraging, steady, insightful.

--type-pull-quote
Lora italic · clamp(22–30px) · LH 1.55

Eyebrow

Brand voice · How we sound

--type-eyebrow
League Spartan 500 · 11px · +0.18em

Attribution / CTA

Schedule a discovery call

--type-cta
Inconsolata 700 · 13px · +0.18em (uppercase)

Inconsolata is reserved. Use only for attributions and CTAs — never for eyebrows, labels, or general meta.

Motion

Four durations, three easings. Default to --motion-state for component state changes. Hover should feel imperceptible-but-confirmed; modal transitions should feel deliberate.

Duration · Quick

120ms

--motion-duration-quick

Hovers, micro state changes.

Duration · Standard

200ms

--motion-duration-standard

Default for most state transitions.

Duration · Deliberate

320ms

--motion-duration-deliberate

Modal entrance, expressive moments.

Duration · Slow

480ms

--motion-duration-slow

Page-level, hero choreography.

Easing curves

Token	Curve	Role
`--motion-easing-standard`	`cubic-bezier(0.2, 0, 0, 1)`	Default — for most transitions
`--motion-easing-entrance`	`cubic-bezier(0, 0, 0.2, 1)`	Elements entering the screen
`--motion-easing-exit`	`cubic-bezier(0.4, 0, 1, 1)`	Elements leaving the screen
`--motion-easing-emphasized`	`cubic-bezier(0.2, 0, 0, 1)`	Drawing attention; key moments

Elevation & focus

The brand is largely flat. Reserve elevation for system moments — focus indication, overlays, modals.

Flat

--elevation-none

Overlay

--elevation-overlay

Modal

--elevation-modal

Focus ring

2px Intentional Blue, 2px offset. Always visible on keyboard focus — never outline:none without a replacement.

↑ Use keyboard to see the focus ring.

Layout · Containers & breakpoints

--container-narrow

640px

--container-prose

720px

--container-default

960px

--container-wide

1200px

Breakpoints

Token	Min width	Surface
`--breakpoint-sm`	`640px`	Large phone / small tablet
`--breakpoint-md`	`900px`	Tablet · most desktop content kicks in
`--breakpoint-lg`	`1200px`	Standard desktop
`--breakpoint-xl`	`1440px`	Large desktop / dashboard

Accessibility floor

Non-negotiable rules baked into the system. Components inherit these — don't override.

Rule	Why
Body text contrast ≥ 4.5:1	WCAG AA for body. See Color → Accessible combinations.
Large text contrast ≥ 3:1	WCAG AA for ≥18pt or ≥14pt bold.
Focus ring always visible	Keyboard users must always see what's focused.
Min touch target 44×44px	iOS HIG / WCAG 2.5.5 minimum.
Motion respects `prefers-reduced-motion`	Components must collapse animation when set.
No color-only signaling	Always pair color with icon, label, or pattern.

What's next

This token layer is the foundation. The remaining design system pieces hang off it:

Layer	Status
Components — Button, Input, Card, Tag, Modal, Tooltip, Nav, Toast, Table	Pending
Iconography — Library, sizes, stroke discipline	Pending
Data viz palette — Categorical + sequential, colorblind-safe	Pending
Microcopy patterns — Errors, empty states, button labels	Pending
Motion library — Named animations beyond duration/easing tokens	Pending