CSS Container Queries

Components style themselves based on the space their container gives them, not the viewport width. This is the primitive that makes a design-system component truly portable: the same card adapts whether it sits in a narrow sidebar or a wide main grid. Baseline across all evergreen browsers since mid-2023.

Design Position

Establish a container, then query it

Container queries need an explicit containment context. Without container-type, @container rules match nothing and fail silently.

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

@container card (min-width: 400px) {
  .card { grid-template-columns: 1fr 2fr; }
}

• inline-size: query width only. Cheap, and the right default for almost everything.
• size: query width and height. More expensive and requires an explicit block size on the container, or it collapses.
• normal: opt out of being a size container. Source: llmbestpractices CSS container queries, https://llmbestpractices.com/frontend/css-container-queries, 2026-05-31

Do not set container-type on html or body. It shifts the containing block and breaks sticky positioning and percentage heights. Wrap the main column instead, and a page-level container is enough to drive nested components.

Container query units

Units resolve against the nearest container ancestor, the way vw and vh resolve against the viewport:

• cqi is 1% of inline size (the common one), cqb is 1% of block size, cqw and cqh are width and height, cqmin and cqmax are the smaller and larger axis.
• They are cheap: they resolve at style computation and trigger no extra layout pass. Use them freely for fluid type and spacing scoped to a component: font-size: clamp(1rem, 4cqi, 2rem). This is what clamp(... + vw, ...) only approximated before. Source: web.dev container queries, https://web.dev/learn/css/container-queries, 2026-05-31

Style queries (newer)

@container style(--state: active) evaluates a container's computed custom-property values rather than its size. Any element can be a style container; container-type is not required for style-only queries. Today style queries only read custom properties, and support is Chrome 111+ and Edge while Firefox and Safari are still implementing. Treat them as enhancement and check Baseline before relying on them. Scroll-state queries are on the same maturing track. Source: MDN container size and style queries, https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_size_and_style_queries, 2026-05-31

Browser support (2026-05-31)

Size queries and container units: Chrome 105+, Edge 105+, Firefox 110+, Safari 16+. Over 95% of global usage; no polyfill needed in 2026. Source: devtoolbox 2026 guide, https://devtoolbox.dedyn.io/blog/css-container-queries-guide, 2026-05-31

@container vs @media

Design-system guidance

Container queries are the backbone of a portable token-driven system like Sigil Token Architecture. Author each component to respond to its slot, expose breakpoints as semantic tokens, and pair cqi-based sizing with the page-level scale from Fluid Typographic Scale. Keep the queries in component styles, not globals.css, while honoring the Tailwind-first stance in CSS UI Enforcement (Tailwind v4 ships @container variants).

---

Timeline

• 2026-07-01 | Design category refresh added this page to the CSS and platform primitives family, linked it to Design System Map, and kept it standalone because CSS Container Queries owns a distinct design decision surface in this family. Source: User request, 2026-07-01
• 2026-05-31 | Page created. Captured container-type (inline-size vs size vs normal), the html/body anti-pattern, container query units (cqi, cqb, etc.) for component-scoped fluid type, style queries (custom-property only, Chrome 111+), the Baseline support since mid-2023 (>95% usage), and the @container vs @media split. Source: MDN + web.dev + llmbestpractices + devtoolbox, 2026-05-31