Breakpoints

One set of thresholds for responsive decisions.

Breakpoints name the viewport widths where responsive rules begin to apply. The theme JSON defines the thresholds, components use those names for layout changes, and Density uses them to make Spacing responsive. Prefer Density for component spacing; use explicit breakpoint values for layout behavior and deliberate local exceptions.

A name such as md identifies a configured threshold. It does not detect a tablet, orientation or input device. These examples use viewport width, not container width.

1. Define breakpoints in your theme JSON

This excerpt uses the shared engine defaults. Your theme can configure different values:

{
  "breakpoints": {
    "xs": 0,
    "sm": 480,
    "md": 768,
    "lg": 1024,
    "xl": 1280
  }
}

Keep xs at zero for these examples and use ordered, distinct thresholds. Feed the configured map into your build/runtime integration so the generated CSS and active theme use the same definitions.

2. Declare what changes at a threshold

.layout {
  display: flex;
  flex-direction: xs(column) md(row);
}

.layout {
  display: flex;
  flex-direction: column;
}
@media (min-width: 768px) {
  .layout { flex-direction: row; }
}

With these defaults, the layout is a column below 768px and a row at that width and above. The threshold is inclusive. This is a discrete change, not a fluid interpolation.

A declared value continues to apply until a later applicable rule overrides it. At lg, this example still uses md(row) because no lg() override was declared. The active viewport breakpoint and the rule supplying a property’s value are not necessarily the same.

3. Let Density manage shared responsive spacing

{
  "densities": {
    "4": "xs(space(4)) md(space(5)) xl(space(6))"
  }
}

This additional theme excerpt assumes spacing entries 4, 5 and 6 exist.

.layout {
  display: flex;
  flex-direction: xs(column) md(row);
  padding: density(4);
}

The component defines its layout transition; Density defines its spacing progression. Changing md changes when both rules apply after the configuration is compiled or applied. Changing only a Density mapping changes spacing without moving the layout threshold.

Do not repeat a Density progression locally merely because it produces the same result today. Use space() for intentional stable spacing, explicit responsive values for deliberate local exceptions, and standard CSS when finer control is needed.

Explore the current viewport

The playground below reports the actual browser viewport and edits its breakpoint configuration. Moving a threshold does not resize the browser. Move md across the current viewport width to inspect the transition. Editor constraints keep thresholds ordered; browser overrides may persist. These edits do not write your source JSON file.

Live layout example

The cards below switch from column to row at md. This excerpt matches their responsive declarations. Their spacing is a deliberate local progression for this demonstration; prefer Density for shared component spacing.

#DemoBreakpointsCards {
  display: flex;
  flex-direction: xs(column) md(row);
  gap: xs(space(2)) md(space(4));
  padding: xs(space(3)) md(space(6));
}

Runtime configuration

In a browser integration with UXDSL-generated styles loaded, the runtime exposes breakpoint updates:

import { breakpoints } from 'postcss-uxdsl/ds-runtime'

const current = breakpoints.get()
breakpoints.update('md', 800)

const unsubscribe = breakpoints.subscribe((event) => {
  if (event.type === 'breakpoint') {
    console.log(breakpoints.get())
  }
})

// Call during cleanup when the subscriber is no longer needed.
unsubscribe()

The subscription reports configuration updates; it is not a viewport-resize subscription. A runtime change does not edit the JSON file. Verify the resulting media rules in your integration, especially when stylesheets or overrides are loaded separately.