spb/ultra-sharp-agent-skills Public

1---2name: designing-responsive-layouts3description: Designs responsive CSS layouts — mobile-first breakpoints, flexbox vs grid decisions, container queries, fluid sizing with clamp(), and intrinsic auto-fit/minmax patterns. Use when the user asks to make a page or component responsive, build a layout or grid, fix overflow or squished content on mobile, choose between flexbox and grid, or add breakpoints or container queries. Do not use for page content composition and conversion structure (creating-landing-pages) or for color/spacing token systems (theming-design-tokens).4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Designing Responsive Layouts1213## When to use / when NOT to use14- **Use for:** layout mechanics — grids, columns, wrapping, breakpoints, container queries, fluid sizing, overflow fixes.15- **Do NOT use for:** what content goes where on a marketing page (→ creating-landing-pages); token scales and theming (→ theming-design-tokens); typography scales (→ choosing-typography).1617## Core rules18191. **Mobile-first: base styles are the narrow layout; media queries only add width.**20   - ✅ `.cards { display: grid; } @media (min-width: 48rem) { .cards { grid-template-columns: 1fr 1fr; } }`21   - ❌ Desktop styles first, then `@media (max-width: …)` overrides undoing them22232. **Flexbox vs grid decision rule: one dimension → flexbox; two dimensions or explicit placement → grid.** Nav bars, button rows, media objects = flex. Card grids, page shells, dashboards = grid.24253. **Prefer intrinsic (no-breakpoint) patterns before adding media queries.**26   - ✅ `grid-template-columns: repeat(auto-fit, minmax(min(16rem, 100%), 1fr));`27   - ❌ Three hand-written breakpoints to go 1→2→3 columns28294. **Breakpoints in `rem`, chosen where the content breaks — not at device names.** Defaults when nothing else is known: 48rem (768px) and 80rem (1280px); always verify at 360px, 768px, 1280px.30315. **Components respond to their container, not the viewport.**32   - ✅ `.sidebar { container-type: inline-size; } @container (min-width: 24rem) { .card { flex-direction: row; } }`33   - ❌ A viewport media query that breaks the card when it's placed in a narrow sidebar34356. **Fluid values with `clamp()`, not stepped jumps:** `padding: clamp(1rem, 3vw, 2.5rem);` for space that scales; reserve breakpoints for structural change.36377. **Never fix heights on text containers; let content size the box.**38   - ✅ `min-height: 20rem;` (or nothing)39   - ❌ `height: 20rem; overflow: hidden;` — clips translated/user content and causes CLS40418. **Kill accidental horizontal scroll at the source:** media `max-width: 100%; height: auto;`, `min-width: 0` on flex/grid children that must shrink, `overflow-wrap: break-word` on long strings.4243## Workflow44451. Identify the layout's dimensionality per rule 2 and pick flex or grid.462. Build the narrow (360px) layout first with intrinsic patterns (rule 3).473. Add `@container` or `@media (min-width)` steps only where the content visibly breaks.484. Replace remaining fixed values with `clamp()`/`minmax()` where they should flex.495. Validate: test at 360px, 768px, 1280px, and one in-between width; check no horizontal scrollbar, no clipped text, images scale, and layout shift stays visually stable (CLS ≤ 0.1 target).5051## Edge cases & failure modes52- **Flex children overflowing:** flex items default to `min-width: auto` — set `min-width: 0` on the shrinking child.53- **`auto-fit` collapsing with one item stretched full width:** use `auto-fill` when empty tracks should be preserved.54- **Container queries need a named/typed container:** without `container-type: inline-size` on an ancestor, `@container` silently never matches.55- **`100vw` causes a scrollbar-width overflow on Windows:** use `100%` or `100dvw`.56- **Legacy browser support required:** container queries and `dvh/dvw` need a media-query fallback — state the assumption before using them.5758## References59Copy-paste layout recipes (shells, card grids, sidebars, holy grail, media objects): see [references/patterns.md](references/patterns.md)60