migrate-container-queries
Installation
SKILL.md
Container Query Migration Guide
Migrate viewport-based responsive logic (@media + useMedia) to container queries so components respond to their own available space instead of the raw viewport.
Always do a visual check. After every migration, resize the element (not just the window) and confirm the layout is identical and flips at the intended width. A good way to narrow an element without touching the window is to open a resizable panel next to it — e.g. drag out the Seer explorer sidebar, which squeezes the middle content. The token scales differ, so a mechanical swap that compiles can still render wrong.
Approach: refactor first, swap second
Stop at the first rung that fits. Prefer replacing hand-rolled CSS with primitives over a mechanical token swap.
| Rung | When | Do |
|---|---|---|
| 1. Primitive props | The @media only flips layout (flex-direction, display, grid-template, gap, visibility, width) |
Delete the styled component; use Container/Flex/Grid/Stack responsive props (direction={{xs: 'column', md: 'row'}}) |
2. @container swap |
CSS can't be a prop (descendant selectors, pseudo-elements, font-size, complex grid-template-areas) |
Keep the styled component; swap @media → @container, theme.breakpoints.* → theme.container.* |
| 3. Container-scoped JS | Width is read in JS to branch rendering | Replace useMedia(...) with useResponsivePropValue({...}) for a threshold boolean, or useContainerBreakpoint() to branch on the active key |
4. Leave as useMedia |
Genuine media feature, not width | Do nothing — these do not migrate |