Skip to content

EliasOulkadi/shokunin / .pack/skills/responsive-engine

responsive-engine

Verified

Design multi-device layouts with Container Queries, clamp() fluid typography, :has() selector, subgrid, and modern CSS units (dvh/svh/lvh). Use when user asks to make a layout responsive, handle mobile/tablet/desktop breakpoints, create fluid typography, or use Container Queries. Do NOT use for full-page layouts (use landing-craft), component design (use component-forge), or animation-specific responsive (use motion-craft).

Responsive Engine

Layouts that work at every screen size without breakpoint spaghetti. Inspired by Ahmad Shadeed (Container Queries), Jen Simmons (Intrinsic Web Design), and the CSS Working Group.

Core Principle

Responsive design is about containers, not viewports. Use Container Queries first, media queries only for global layout shifts and form factor detection.


Container Queries (preferred over media queries)

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

@container card-grid (min-width: 600px) {
  .card {
    display: grid;
    grid-template-columns: 200px 1fr;
  }
}

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

Container query length units

.card {
  padding: 10cqw;      /* 10% of container width */
  font-size: 5cqi;     /* 5% of container inline size */
  margin-block: 2cqb;  /* 2% of container block size */
  border-radius: 1cqmin; /* 1% of container smaller side */
}

Form Factor Detection

Detect the device type, not just width.

/* Touch vs mouse */
@media (pointer: coarse) {
  .button { min-height: 48px; }
}

@media (hover: hover) {
  .card:hover { transform: scale(1.02); }
}

@media (hover: none) {
  .card:active { transform: scale(0.98); }
}

/* Portrait vs landscape */
@media (orientation: portrait) {
  .hero-grid { grid-template-columns: 1fr; }
}

Viewport Unit Decision Tree

Use caseUnitWhy
Full-screen heromin-h-[100dvh]Adapts to URL bar on mobile. Never 100vh — iOS Safari viewport jumps.
Minimum safe heightmin-height: 100svhSmall viewport height. Fallback for when URL bar is visible.
Large viewport design100lvhMaximum when URL bar hidden. Only for desktop-like experiences.
Width-baseddvwDynamic viewport width. Avoid on scroll-zooming mobile pages.
.hero {
  height: 100dvh;
  min-height: 100svh;  /* Fallback: never smaller than smallest viewport */
}

The h-screen ban

h-screen equals 100vh which equals disaster on iOS Safari. The URL bar entering/exiting causes catastrophic layout jumps. Always use min-h-[100dvh].


Fluid Typography

:root {
  --text-sm:      clamp(0.875rem, 0.8rem + 0.25vw, 1rem);
  --text-base:    clamp(1rem, 0.9rem + 0.35vw, 1.25rem);
  --text-lg:      clamp(1.25rem, 1rem + 0.75vw, 1.75rem);
  --text-xl:      clamp(1.5rem, 1rem + 1.5vw, 2.5rem);
  --text-2xl:     clamp(1.75rem, 1.25rem + 2vw, 3rem);
  --text-3xl:     clamp(2rem, 1.5rem + 3vw, 4rem);
  --text-display: clamp(2.5rem, 1.5rem + 5vw, 6rem);
}

Fluid spacing

:root {
  --space-xs: clamp(0.25rem, 0.2rem + 0.25vw, 0.5rem);
  --space-sm: clamp(0.5rem, 0.4rem + 0.5vw, 1rem);
  --space-md: clamp(1rem, 0.8rem + 1vw, 2rem);
  --space-lg: clamp(2rem, 1.5rem + 2vw, 4rem);
  --space-xl: clamp(3rem, 2rem + 3vw, 6rem);
  --space-2xl: clamp(4rem, 3rem + 5vw, 10rem);
}

Subgrid

.card-list {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: 1rem;
}

.card {
  display: grid;
  grid-template-rows: subgrid;
  grid-row: span 3;
}

All children across cards align to the same row heights.


Parent-Based Responsive with :has()

/* Sidebar mode: when parent has class .sidebar */
.sidebar:has(.card) .card {
  flex-direction: column;
  text-align: center;
}

/* Card layout changes based on number of siblings */
.grid:has(> :last-child:nth-child(3)) .item {
  grid-column: span 1;
}

/* Detect empty state */
.container:has(.empty-state) {
  justify-content: center;
}

Fallback check:

@supports not selector(:has(*)) {
  .grid .item { grid-column: span 1; } /* fallback */
}

Touch Target Physics

ElementMinimumRecommended
Button44×44px48×48px
Link in nav44×44px48×48px
Checkbox / radio24×24px32×32px (invisible hit area)
Input field44px height48px height
Gap between touchable8px12px
.interactive {
  min-width: 44px;
  min-height: 44px;
}

/* Invisible hit area for small controls */
.small-control::after {
  content: '';
  position: absolute;
  inset: -8px;  /* expands hit area without visual change */
}

Layout Strategy by Device

Each layout archetype needs a mobile collapse rule.

Desktop layoutMobile collapse
3 columns1 column stack (grid-cols-1)
Split screen 50/50Full-width stack (w-full)
Asymmetric grid (2fr 1fr)grid-template-columns: 1fr, remove all col-span overrides
Horizontal scrollPreserve if content is images/cards, restack if text
Overlapping elementsRemove all negative margins and rotations below 768px
Sidebar + contentStack: sidebar collapses to top (or hamburger)
/* Universal mobile collapse */
@media (max-width: 767px) {
  .split-layout { grid-template-columns: 1fr; }
  .asymmetric-grid { grid-template-columns: 1fr; }
  .overlap-card { margin-top: 0; transform: none; }
  [class*="col-span"] { grid-column: span 1; }
}

Breakpoint System (global layout only)

NameWidthTarget
sm640pxMobile landscape
md768pxTablet portrait
lg1024pxTablet landscape / small desktop
xl1280pxDesktop
2xl1536pxLarge desktop

Never add a breakpoint "just in case." If you have more than 4 breakpoints, refactor to Container Queries.


Testing Checklist

  • Content does not overflow on 320px width
  • No horizontal scroll on any breakpoint
  • Text readable without zoom (min 16px body)
  • Images scale correctly at all sizes
  • Navigation usable at all breakpoints
  • Forms not broken on mobile
  • Tables have horizontal scroll or responsive variant
  • Container Queries used over media queries where possible
  • h-screen replaced with min-h-[100dvh] everywhere
  • Touch targets ≥ 44×44px with 8px gap
  • Fixed widths in px replaced with clamp(), %, cqi
  • Asymmetric layouts collapse to 1 column below 768px
  • Overlapping elements separated on mobile
  • :has() guarded with @supports fallback

Error Handling

ProblemCauseFix
Horizontal scrollbar on mobileFixed-width element > viewportReplace px with clamp(), %, or 100%
Layout jump on iOS Safarih-screen usedReplace with min-h-[100dvh]
Text unreadable on mobileBody font < 16pxMinimum 16px, scale with clamp()
Touch target too smallClickable < 44pxExpand hit area with padding or ::after
Container Query not workingMissing container-typeSet container-type: inline-size on parent
Subgrid rows not alignedMissing grid-template-rows: subgridVerify parent has explicit rows
100vh causes scrollDidn't account for URL barUse dvh or svh
Hover effect fires on touchNo @media (hover: hover) guardGate hover behind pointer media query

Anti-Patterns

Anti-patternFix
Media queries for component responsivenessContainer Queries
Fixed widths in pxclamp(), %, dvw, or cqi/cqw
Hover-only interactions on mobileAdd @media (hover: hover) guard
Touch targets < 44pxInteractive elements ≥ 44×44px
Body font < 16pxMinimum 16px, clamp() for fluid scaling
No :has() fallback@supports selector(:has(*)) guard
Deeply nested media queriesContainer Queries eliminate most
h-screen for full-heightmin-h-[100dvh]
Same layout at all sizesLayout must collapse on mobile
Asymmetric layout stays asymmetric on mobileForce 1-column below 768px
Overlapping elements on touchSeparate on mobile. Touch layers cause mis-taps.
calc() with mixed units for gridUse CSS Grid fr units + minmax()
Complex flexbox math (w-[calc(33%-1rem)])CSS Grid grid-cols-3 with gap
Testing only at desktop widthTest at 320px, 375px, 768px, 1024px, 1440px

Pre-Flight Checklist

Before delivering responsive layout code:

  • No horizontal scroll at any width (tested at 320px)
  • min-h-[100dvh] used instead of h-screen
  • Body font ≥ 16px at all widths
  • Touch targets ≥ 44×44px, gap ≥ 8px
  • Media queries only for global layout shifts
  • Container Queries for component responsiveness
  • Asymmetric layouts collapse to single column below 768px
  • Overlapping elements separated on mobile
  • Hover interactions gated behind @media (hover: hover)
  • Images have width/height attributes + object-fit or aspect-ratio
  • Forms single-column on mobile, large inputs (44px+)
  • :has() fallbacks defined
  • No px-only spacing — use fluid or relative units
  • Grid used instead of complex flexbox math
  • Table has responsive wrapper or data-label approach
  • Navigation is usable via touch at all widths

Sources

  • Ahmad Shadeed — Container Queries deep dive (ishadeed.com)
  • Jen Simmons — Intrinsic Web Design
  • CSS Container Queries (MDN)
  • CSS :has() selector (MDN)
  • CSS Subgrid (MDN)
  • web.dev — Responsive and fluid typography with clamp()
  • New Viewport Units (dvh, svh, lvh) — web.dev
  • Every Layout — responsive layout patterns
  • WCAG 2.2 — Touch target size
  • iOS Safari viewport bug documentation (WebKit blog)

Workflow

Step 1: Audit existing layout

Before writing any CSS, identify what's broken:

  • Open Chrome DevTools Device Toolbar (Ctrl+Shift+M)
  • Test at 320px, 375px, 768px, 1024px, 1440px
  • Flag: horizontal scrollbars, overflowing content, text < 16px, touch targets < 44px
  • Screenshot at each breakpoint for before/after comparison

Step 2: Establish container query boundaries

  1. Identify components needing independent responsiveness (cards, sidebars, grid items)
  2. Set container-type: inline-size on their direct parent
  3. Name containers with container-name for complex nested layouts
  4. Replace any media queries targeting those components with @container rules

Step 3: Replace fixed units with fluid units

  1. Find all px values for widths, font sizes, spacing
  2. Convert fonts to clamp() (minimum, preferred, maximum)
  3. Convert spacing to clamp() or relative units (%, cqi, cqw)
  4. Replace h-screen with min-h-[100dvh] everywhere

Step 4: Write mobile collapse rules

  1. Identify asymmetric layouts, overlapping elements, multi-column grids
  2. Write @media (max-width: 767px) block collapsing everything to single column
  3. Remove negative margins and rotations on mobile
  4. Ensure touch targets >= 44x44px with 8px gap between interactive elements

Step 5: Add form factor and accessibility guards

  1. Gate hover effects behind @media (hover: hover)
  2. Gate fine-pointer interactions behind @media (pointer: fine)
  3. Add @supports selector(:has(*)) fallbacks for all :has() selectors
  4. Respect prefers-reduced-motion on all animations
  5. Set minimum body font-size to 16px

Step 6: Verify across devices

  1. No horizontal scroll at any width from 320px to 2560px
  2. min-h-[100dvh] replaces all h-screen instances
  3. Touch targets >= 44x44px with 8px gap
  4. Container Queries used for component responsiveness
  5. Asymmetric layouts collapse to single column below 768px
  6. All :has() selectors guarded with @supports fallback

Checklist

  • Skill loads without errors in the AI agent
  • YAML frontmatter is valid (description, compatibility, audience)
  • Workflow section provides clear step-by-step instructions
  • Error handling section covers common failure modes
  • All referenced files (references/, scripts/, assets/) exist
  • Skill triggers correctly for intended use cases
  • No broken links or missing resources
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall