Media Queries

toned-styles supports responsive styling through breakpoints defined in your system configuration. Token values can be overridden at specific breakpoints, and the system handles media query generation automatically.

Breakpoints

The base system defines these breakpoints:

// From @toned/systems/base/config.ts
export const breakpoints = defineBreakpoints({
  xs: 0,    // mobile-first default
  sm: 480,  // small phones landscape
  md: 768,  // tablets
  lg: 992,  // small desktops
  xl: 1200, // large desktops
})

Using Breakpoints in Stylesheets

Prefix a breakpoint name with @ to create a responsive override block inside any element definition:

const layoutStyles = stylesheet({
  container: {
    paddingX: 2,
    flexLayout: 'column',

    '@md': {
      paddingX: 4,
      flexLayout: 'row',
    },

    '@lg': {
      paddingX: 6,
    },
  },
})

Breakpoint blocks support the same token properties and style escape hatch as the base element definition. Properties set inside a breakpoint block override the base values when the viewport matches.

Media Modes

The mediaMode option in your config controls how responsive styles are applied:

CSS Mode

When mediaMode: 'css', breakpoint overrides are compiled into real CSS @media rules. This is the recommended mode for web projects as it uses native browser capabilities and avoids JavaScript overhead:

setConfig(
  defineConfig({
    ...reactConfig,
    useClassName: true,
    useMedia: true,
    mediaMode: 'css',
  }),
)

JavaScript Mode

When mediaMode is not set to 'css', breakpoints are evaluated at runtime using JavaScript window.matchMedia. This mode is useful for React Native or environments where CSS media queries are not available.

Root-Level Breakpoints

Breakpoints can be declared at the root level of a stylesheet to apply overrides across multiple elements at once. This is useful when a layout change at a given viewport affects several elements simultaneously:

const cardStyles = stylesheet({
  card: {
    paddingX: 2,
    flexLayout: 'column',
  },
  title: {
    typo: 'heading_3',
  },
  sidebar: {
    display: 'none',
  },

  // At medium viewports, adjust multiple elements together
  '@md': {
    card: { paddingX: 4, flexLayout: 'row' },
    title: { typo: 'heading_2' },
    sidebar: { display: 'flex' },
  },

  '@lg': {
    card: { paddingX: 6 },
  },
})

Root-level and element-level breakpoints can be mixed freely. They produce the same result — root-level is shorthand for applying overrides to several elements under the same breakpoint.

Breakpoints in Variants

Responsive overrides work inside variant blocks too, letting you combine conditional and responsive styling. Breakpoints can be set on individual elements within a variant:

const styles = stylesheet({
  container: { paddingX: 2 },
}).variants<{ layout: 'grid' | 'list' }>(($) => ({
  [$.layout('grid')]: {
    container: {
      style: { display: 'grid', gridTemplateColumns: '1fr' },
      '@md': {
        style: { gridTemplateColumns: '1fr 1fr' },
      },
      '@lg': {
        style: { gridTemplateColumns: '1fr 1fr 1fr' },
      },
    },
  },
}))