Foundations

Design tokens

Stable

87 tokens across 14 groups. Every sample below resolves its value through the live custom property, so this page cannot show a value that is no longer true.

Updated in v1.0.0

How the axes compose

Foundry separates three concerns that most systems collapse into one theme enum: scheme (light or dark), palette (accent ramp, display typeface, corner treatment) and density (control height and layout rhythm). All three are written to <html> as data attributes and read back by CSS, and all three compose — Corporate plus dark plus compact is a real, authored combination.

Because the selectors are attribute-based rather than :root-only, any subtree can opt into its own theme. That is exactly what the preview frames on every component page do, and what the playground uses.

Change one file, change everything

A full visual rebrand touches only the token declarations. No component reads a colour, a radius or a control height from anywhere else.

Surface colour

Backgrounds, from the warm page canvas up through raised cards and down into sunken wells. Authored separately for light and dark rather than inverted.

--color-canvas
Page background. The warm off-white that defines Foundry.
--color-surface
Default panel and card background.
--color-surface-raised
Popovers, dropdowns, dialogs — anything floating.
--color-surface-sunken
Wells, table headers, inset preview frames.
--color-surface-inverse
Inverted blocks such as dark CTA bands.
--color-code-surface
Code viewer background, constant across schemes.
--color-code-gutter
Code viewer line-number gutter.

Ink colour

Foreground text. Graphite rather than pure black in light mode; warm off-white rather than pure white in dark mode.

--color-ink-strong
Headings and emphasised numerals.
--color-ink
Body copy.
--color-ink-muted
Secondary copy, descriptions, help text.
--color-ink-subtle
Metadata, placeholders, disabled labels.
--color-ink-inverse
Text on inverted surfaces.

Accent colour

One accent ramp drives every primary action. Palettes swap the ramp wholesale, which is why switching palette visibly changes previews.

--color-accent
Primary actions, active navigation, focus ring.
--color-accent-hover
Hover state for accent surfaces.
--color-accent-active
Pressed state for accent surfaces.
--color-accent-ink
Text placed on an accent fill.
--color-accent-soft
Tinted background for badges and selected rows.
--color-accent-soft-ink
Text on a soft accent tint.
--color-accent-line
Border for accent-tinted surfaces.

Status colour

Each status ships a trio — solid, soft surface and line. Status is never communicated by hue alone; an icon and a text label always accompany it.

--color-success
Confirmations, healthy states, positive deltas.
--color-success-soft
Success alert and badge background.
--color-warning
Degraded states and non-blocking problems.
--color-warning-soft
Warning alert and badge background.
--color-danger
Destructive actions, validation failures, outages.
--color-danger-soft
Danger alert and badge background.
--color-info
Neutral informational messaging.
--color-info-soft
Info alert and badge background.

Border colour

Foundry leans on lines rather than shadows. Three weights cover almost every case.

--color-border-subtle
Internal dividers inside a panel.
--color-border
Default component and panel outline.
--color-border-strong
Emphasised outline, hover borders, table rules.

Typography

A 1.2 modular scale anchored at a 15px base. The display family is palette-controlled: Editorial and Warm use a serif, the rest use the grotesque.

--text-2xs
Technical labels, uppercase eyebrows.
--text-xs
Table metadata, badge text.
--text-sm
Dense UI copy, sidebar navigation.
--text-base
Body copy default.
--text-md
Lead paragraphs.
--text-lg
Card titles, section subheads.
--text-xl
Section headings.
--text-2xl
Page headings.
--text-3xl
Small display.
--text-4xl
Display.
--text-5xl
Hero display.
--text-6xl
Editorial hero display.

Spacing

A 4px grid. Density multiplies the derived layout spacings, not this base scale.

--space-1
4px — icon nudges.
--space-2
8px — inline gaps.
--space-3
12px — control padding.
--space-4
16px — stack rhythm.
--space-6
24px — card padding.
--space-8
32px — block separation.
--space-12
48px — sub-section separation.
--space-16
64px — section padding.
--space-24
96px — hero padding.

Radius

Corner treatment is a palette signature. Minimal squares everything off; Modern rounds generously.

--radius-xs
Focus ring rounding, inline code.
--radius-sm
Badges, small inputs.
--radius-md
Buttons, inputs, menu items.
--radius-lg
Cards and panels.
--radius-xl
Dialogs, feature cards.
--radius-full
Avatars, pills, switches.

Elevation

Shadows read as paper lifting off paper. Nothing glows. The Minimal palette flattens them to zero on purpose.

--shadow-xs
Hairline lift on hover.
--shadow-sm
Resting cards.
--shadow-md
Dropdowns and popovers.
--shadow-lg
Sticky headers over content.
--shadow-overlay
Dialogs and drawers.

Border width

Two widths only. The strong width marks focus and selected states.

--border-width
Default 1px hairline.
--border-width-strong
2px, for selection and focus emphasis.

Breakpoints

Five breakpoints, mirrored into the Tailwind theme so `md:` in a component and the documented value can never disagree.

--breakpoint-sm
640px — large phone.
--breakpoint-md
768px — tablet portrait.
--breakpoint-lg
1024px — tablet landscape / small laptop.
--breakpoint-xl
1280px — desktop.
--breakpoint-2xl
1536px — wide desktop.

Motion

Short durations and a single standard easing. Every animation is disabled under `prefers-reduced-motion`.

--duration-instant
80ms — colour and opacity changes.
--duration-fast
140ms — hover and focus transitions.
--duration-normal
220ms — overlay entrances.
--duration-slow
360ms — drawer travel.
--ease-standard
Default easing for state changes.
--ease-entrance
Elements arriving on screen.
--ease-exit
Elements leaving the screen.

Density

Density is a separate axis from theme. It rescales control heights and layout rhythm without touching the type scale.

--density-control-height
Default control height.
--density-control-height-sm
Small control height.
--density-control-height-lg
Large control height.
--density-gap
Gap between adjacent controls.
--density-stack
Vertical rhythm inside forms and stacks.
--density-card-padding
Card interior padding.
--density-section-y
Vertical padding for marketing sections.
--density-row-height
Table and list row height.

Focus

One focus treatment for the entire library, applied through `:focus-visible` so pointer users never see it.

--focus-ring-width
Outline width of the focus ring.
--focus-ring-offset
Gap between element and ring.
--focus-ring-color
Ring colour — tracks the accent ramp.