Container Query Component Contract

Large Theory

Traditional media queries know the viewport, not whether a component is placed in a 320px sidebar or an 840px content region. Component libraries and agent-generated UIs often reuse the same card, table summary, asset tile, or chart module. If these components rely only on global breakpoints, they fail inside nested layouts, split views, dock panels, and responsive dashboards. Container queries let components declare their own layout contract: preserve core information and primary action in narrow containers, then reveal metadata, secondary actions, and richer visual structure in wider containers.

Small Points

1. Set container-type: inline-size on reusable containers and use container-name when the nearest ancestor would be ambiguous.
2. Component breakpoints should come from content needs such as title wrapping, action count, chart legends, and table column width, not copied page breakpoints like 768/1024.
3. In narrow containers, reduce density and hierarchy first: hide secondary metadata, collapse horizontal action rows into menus, and move chart legends below or into table summaries.
4. Container queries do not replace viewport queries. Page shell, navigation, and sidebars still depend on viewport or layout state.
5. Watch how containment affects percentages, positioned elements, descendant queries, and sticky scenarios. Do not turn every page section into a container by habit.
6. RAG and design-system entries should record compact, regular, and expanded container widths with content priority and screenshots.

Design Judgment

A component has a responsive contract when it keeps the same task meaning inside card grids, drawers, detail sidebars, and full-width content regions without shrinking text or squeezing buttons to survive. If it needs to know the page route to lay out correctly, it is not reusable yet.

Implementation Notes

Write a container contract for each reusable module: minimum usable width, recommended width, wide-container enhancement, hide/collapse rules, fields that cannot be hidden, interaction alternatives, and test viewports. In CSS, define the compact base first and progressively enhance with @container (min-width: ...). React components should not use window.innerWidth to infer internal layout. Chart components need data-table or summary fallback in narrow containers.

Counterexamples/Risks

Component rules fight because they depend on both viewport and parent classes, missing container names match the wrong ancestor, narrow containers only reduce font size instead of recomposing layout, important actions hide behind hover, chart legends squeeze plotting area, and screenshot tests only cover full-width pages.

Case Study

MDN defines container queries as applying styles based on container attributes instead of viewport or device characteristics. web.dev's Netflix case study explains that container queries helped reduce JavaScript layout control and improve component flexibility across contexts. The reusable lesson is that responsive design moves from page-size adaptation to a component placement contract.

Source Links

MDN CSS Container Queries: https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_queries MDN @container: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/%40container web.dev Container Queries: https://web.dev/learn/css/container-queries web.dev Netflix Container Query Case Study: https://web.dev/case-studies/netflix-cq