Foundations
The structural and interaction primitives every component builds on: responsive layout,
icon sizing, motion, elevation, and stacking order. Like Design
Style, every value below is read directly from the @ghds/tokens build
output.
Layout & Grid sys.breakpoint.* sys.grid.* sys.container.*
Breakpoints are mobile-first: each value is a min-width for
@media queries, so mobile styles are the default and larger breakpoints layer
on top. Grid column counts and container max-widths scale together — more columns and a
wider container as the viewport grows.
| Breakpoint | sys.breakpoint.* | Columns | Container max-width | Gutter |
|---|---|---|---|---|
| mobile | 0px | 4 | fluid (100%) | 16px |
| tablet | 768px | 8 | 720px | 24px |
| desktop | 1024px | 12 | 960px | 24px |
| wide | 1440px | 12 | 1280px | 32px |
Stack/Grid layout primitive: no dedicated Stack/Grid
component exists yet in any of the three platform packages. Until one ships (recommended for
a future component milestone), consume these tokens directly: on the web,
@media (min-width: var(--sys-breakpoint-tablet)); in React Native, which has no
native media queries, compare useWindowDimensions() against the same token
values read from @ghds/tokens.
Icons sys.icon.size.*
Icon sizing follows the sys.icon.size.sm/md/lg scale (see the Icon
component across all three platforms). A full icon catalog page doesn't exist yet — this
section will link to one once it's built.
Motion sys.animation.duration.* sys.animation.easing.*
Named transition patterns and which duration/easing pair backs each one:
| Pattern | Duration | Easing | When to use |
|---|---|---|---|
| Enter | 200ms | sys.animation.easing.enter | An element appearing — modal open, dropdown open, toast in. Decelerates into place so arrival feels responsive, not abrupt. |
| Exit | 120ms | sys.animation.easing.exit | An element disappearing — modal close, dropdown close, toast out. Faster than enter and accelerates away, so it never blocks the next action. |
| Emphasis | 320ms | sys.animation.easing.emphasized | Drawing attention without appearing/disappearing — a validation-error nudge, a pulse. Product judgment call on exact duration. |
Raw values — sys.animation.duration.*: fast = 120ms, normal = 200ms, slow = 320ms.
sys.animation.easing.*: standard, emphasized, enter, exit.
Accessibility: when prefers-reduced-motion matches, skip the
transition entirely or substitute an instant/opacity-only crossfade at
ref.duration.instant (0ms). This is an implementation-layer concern
for each component package, not a separate token.
Elevation sys.shadow.*
Elevation is covered on the Design Style page.
Reach for a higher shadow tier as an element's stacking layer rises (dropdown → modal →
toast); sys.sketch.elevation drives the same idea for the hand-drawn drop-shadow
on cards and raised surfaces.
Z-index / Layering sys.zIndex.*
| Layer | Value | When to use |
|---|---|---|
base | 0 | Default stacking context. Most in-flow content never needs to set z-index at all. |
dropdown | 1000 | Select menus, comboboxes, and other inline popovers anchored to a trigger. |
sticky | 1100 | Elements pinned within the normal document flow, e.g. the site header. |
overlay | 1200 | Full-viewport scrims that sit behind a modal or drawer. |
modal | 1300 | Modal and dialog surfaces themselves, above their scrim. |
toast | 1400 | Toast/snackbar notifications, above modals so they stay visible. |
tooltip | 1500 | Tooltips — always on top, since they must never be obscured by anything else. |
Worked example: this site's .site-header is position: sticky, so
it uses var(--sys-zIndex-sticky) rather than a hardcoded number.
Opacity sys.opacity.*: disabled = 0.4, hover = 0.08, scrim = 0.5.