Test CSS Container Queries as a Component Contract

Start with where the component must work

A card may appear in a full-width page, narrow sidebar, dashboard grid, dialog, and embedded panel. Viewport media queries cannot describe all those available spaces. Begin with a placement matrix: host layout, expected inline size, writing mode, content variants, interactive states, and required outcome. Use one example such as a pricing card that changes from horizontal to stacked when its parent becomes narrow, while preserving price, action, comparison text, and reading order.

Name the element intended to be the query container and why it owns layout context. Record whether size, inline-size, style, or scroll-state queries are in scope and which browsers the product supports. Adding containment can affect intrinsic sizing and layout, so the wrapper choice is architecture, not merely a selector. The component owner approves its behavior; the page owner controls available space.

Choose container boundaries without breaking sizing

Inspect the ancestors that determine the component width: grid tracks, flex items, min-content rules, max widths, gaps, padding, and overflow. Apply a container type only where the sizing consequences are understood. A component cannot generally query its own size to style itself; it queries an ancestor container. Creating an extra wrapper may be appropriate, but the wrapper must not alter semantics, focus order, or styling hooks accidentally.

Give named containers to reusable regions when nesting could otherwise select the wrong ancestor. Test the component inside another query container and inside a page that changes containment. A generic nearest-container rule can work until a new wrapper is introduced. Record the selected container for each fixture through computed styles or a test marker, rather than inferring it from the final screenshot.

Derive breakpoints from failure, not device labels

Resize the container with representative content until the existing arrangement first loses readability, overlaps, clips, or creates an unusable control. Record that range and choose a threshold based on the component’s needs. Avoid labels such as tablet or desktop when the same component can occupy very different widths on one screen. Use relative units where they match typography and user scaling, and document the root assumptions.

For every threshold, test a width just below, exactly at, and just above it. Capture layout mode, order, visible content, control dimensions, overflow, focus outline, and computed query result. Fractional pixels, zoom, scrollbars, and device scale can expose oscillation around an equality boundary. The expected condition should follow the CSS comparison precisely rather than a screenshot made at an approximate drag position.

Use hostile but legitimate content

Build fixtures with short and long headings, unbroken identifiers, translated labels, large prices, missing optional media, validation messages, badges, multiple actions, and user-generated text within product limits. Increase text zoom and browser zoom. A layout that works only with English placeholders is not reusable evidence. Let content wrap unless the product explicitly requires truncation and provides access to the full value.

Check left-to-right and right-to-left direction where supported, plus vertical writing only if the product claims it. Prefer logical properties so inline and block behavior follows the writing mode. Container query units can be useful, but clamp typography and spacing to readable bounds. Verify fallback when no eligible container exists; the base style should remain coherent rather than depending on a query that never matches.

Prevent layout feedback and nested surprises

A query changes descendants based on container size, and those descendants can influence surrounding layout. Construct a grid where several instances switch near the same width, then resize slowly through the boundary. Watch for repeated mode changes, horizontal scroll, track expansion, and unstable height. Keep the queried style from changing the container’s own determining dimension in a way that creates feedback.

Place the component in nested containers with different names and widths. Add an unrelated wrapper and confirm named queries still bind to the intended context. Test a container hidden and then revealed, moved between regions, and rendered before fonts load. If JavaScript measures the same component, define which system owns the decision so CSS and script do not fight and produce hydration or resize loops.

Preserve semantics through visual rearrangement

Changing grid areas or flex order can alter visual order without changing DOM and assistive-technology order. Design source order to remain meaningful in every mode. Navigate by keyboard across each arrangement and compare focus sequence with the visual presentation. Do not duplicate content for wide and narrow modes unless duplicate names, IDs, hidden states, form values, and announcements are deliberately handled.

Check target size, focus visibility, error association, headings, list semantics, table meaning, and live status after each layout switch. Resize while an inner control has focus; focus should remain on the same logical element and stay visible. Reduced motion preferences apply if transitions animate the rearrangement. Accessibility review is behavior evidence, not a final automated score.

Automate the component matrix without screenshot-only approval

Create a harness that sets container width directly instead of relying only on viewport size. Assert layout mode using stable attributes or computed properties, then add focused visual snapshots for representative states. Include boundary widths, nested containers, long content, zoom-compatible checks, and keyboard traversal. Reset fonts and animation conditions so differences are meaningful.

Run supported browser engines because query behavior, subpixel layout, fonts, and screenshots can differ. A pixel diff may flag harmless antialiasing while missing a clipped accessible name, so pair it with DOM, overflow, focus, and text assertions. Record browser versions, container dimensions, content fixture, expected mode, observed result, and uncovered combinations.

Hand off reusable evidence

The packet includes placement matrix, selected container and name, containment effects, breakpoint rationale, boundary results, content fixtures, nested-container cases, accessibility sequence, browser matrix, automated assertions, visual evidence, fallback behavior, known limits, and exact source revision. The offshore developer can implement the component and tests; design and product owners approve information priority; accessibility owners review interaction; release owners accept browser coverage.

Acceptance requires stable behavior across declared placements, no content loss or unexplained overflow, meaningful source order, visible focus, and reproducible boundary outcomes. A clean desktop screenshot does not pass the contract. Developer Offshore clients can use one component across three real placements as a bounded frontend assignment with a named design and accessibility reviewer.

Questions about assessing Philippine developers