Breakpoint Tokens

Breakpoint tokens define the viewport widths where layouts adapt, ensuring consistent responsive behavior across a design system. Without shared breakpoint definitions, teams implement different viewport thresholds, creating inconsistent experiences as users resize browsers or switch devices. Tokenizing breakpoints establishes a shared responsive foundation.

What Are Breakpoint Tokens

Breakpoint tokens are design tokens that define viewport width thresholds where interface layouts change. These tokens capture decisions about when mobile layouts become tablet layouts, when navigation collapses or expands, and when content reflows for different screen sizes.

Unlike most design tokens that resolve to single CSS values, breakpoint tokens typically feed into media queries, requiring consideration of how they integrate with CSS media query syntax.

How Breakpoint Tokens Work

Breakpoint token systems define a scale of viewport widths:

{
  "breakpoint": {
    "sm": { "value": "640px" },
    "md": { "value": "768px" },
    "lg": { "value": "1024px" },
    "xl": { "value": "1280px" },
    "2xl": { "value": "1536px" }
  }
}

CSS integration requires consideration of how tokens become media queries. Direct CSS custom property usage in media queries is not widely supported:

/* This does NOT work in most browsers */
@media (min-width: var(--breakpoint-md)) { }

Common approaches include:

Generated media query mixins (Sass/Less):

// Generated from tokens
$breakpoint-sm: 640px;
$breakpoint-md: 768px;
$breakpoint-lg: 1024px;

@mixin breakpoint-up($name) {
  @if $name == sm { @media (min-width: $breakpoint-sm) { @content; } }
  @if $name == md { @media (min-width: $breakpoint-md) { @content; } }
  @if $name == lg { @media (min-width: $breakpoint-lg) { @content; } }
}

// Usage
.component {
  @include breakpoint-up(md) {
    display: flex;
  }
}

Container queries with custom properties (modern approach):

.container {
  container-type: inline-size;
}

@container (min-width: 768px) {
  .component {
    display: flex;
  }
}

JavaScript-driven responsive behavior:

import { breakpoints } from './tokens';

const isDesktop = window.matchMedia(`(min-width: ${breakpoints.lg})`).matches;

Key Considerations

• Breakpoints should align with actual content needs, not device categories
• Mobile-first versus desktop-first affects media query direction
• Gaps or overlaps between breakpoints cause edge case issues
• JavaScript access to breakpoint values may be needed
• Breakpoint count should be minimal (3-5 usually suffice)
• Token naming should avoid device references that become outdated
• Container queries are changing responsive patterns
• Breakpoints interact with typography, spacing, and layout tokens

Common Questions

Should breakpoints be mobile-first or desktop-first?

Mobile-first uses min-width queries, applying base styles to mobile and progressively enhancing for larger viewports:

.component {
  flex-direction: column; /* Mobile default */
}

@media (min-width: 768px) {
  .component {
    flex-direction: row; /* Tablet and up */
  }
}

Desktop-first uses max-width queries, applying base styles to desktop and progressively reducing for smaller viewports:

.component {
  flex-direction: row; /* Desktop default */
}

@media (max-width: 767px) {
  .component {
    flex-direction: column; /* Below tablet */
  }
}

Mobile-first has become the dominant approach because:

• Mobile constraints force essential content focus
• Progressive enhancement is philosophically sound
• CSS specificity works naturally with additive queries

Token systems typically express breakpoints as min-width values for mobile-first usage. Max-width variants can be derived by subtracting 1px from the next breakpoint.

How should breakpoint tokens be named?

Naming approaches include size-based, device-based, and numeric systems.

Size-based naming (sm, md, lg, xl) describes relative scale without implying specific devices:

{
  "breakpoint": {
    "sm": { "value": "640px" },
    "md": { "value": "768px" },
    "lg": { "value": "1024px" }
  }
}

Device-based naming (mobile, tablet, desktop) is intuitive but becomes outdated as device categories blur:

{
  "breakpoint": {
    "tablet": { "value": "768px" },
    "desktop": { "value": "1024px" }
  }
}

Numeric naming uses indexes or direct values:

{
  "breakpoint": {
    "1": { "value": "640px" },
    "2": { "value": "768px" },
    "3": { "value": "1024px" }
  }
}

Size-based naming balances clarity with longevity. Names like sm/md/lg communicate relative scale without tying to device categories that evolve.

How do container queries affect breakpoint tokens?

Container queries enable component-level responsive behavior based on container size rather than viewport size. This shifts some responsive logic from viewport breakpoints to component context.

Container query thresholds might be tokenized separately:

{
  "container": {
    "sm": { "value": "300px" },
    "md": { "value": "500px" },
    "lg": { "value": "700px" }
  }
}

These values differ from viewport breakpoints because they apply to container widths, which vary based on layout context.

Components can define responsive behavior relative to their container:

.card-container {
  container-type: inline-size;
}

@container (min-width: 500px) {
  .card {
    flex-direction: row;
  }
}

Container queries complement rather than replace viewport breakpoints. Page-level layout decisions still use viewport queries. Component-level adaptations can use container queries for context-aware responsiveness.

Summary

Breakpoint tokens establish shared viewport thresholds for consistent responsive behavior. Integration with CSS requires approaches like preprocessor mixins or JavaScript media queries since CSS custom properties do not work directly in media query conditions. Mobile-first min-width patterns dominate modern development. Size-based naming provides clarity without device-specific assumptions. Container queries introduce component-level responsive tokens that complement viewport breakpoints.