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 case	Unit	Why
Full-screen hero	min-h-[100dvh]	Adapts to URL bar on mobile. Never 100vh — iOS Safari viewport jumps.
Minimum safe height	min-height: 100svh	Small viewport height. Fallback for when URL bar is visible.
Large viewport design	100lvh	Maximum when URL bar hidden. Only for desktop-like experiences.
Width-based	dvw	Dynamic 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

Element	Minimum	Recommended
Button	44×44px	48×48px
Link in nav	44×44px	48×48px
Checkbox / radio	24×24px	32×32px (invisible hit area)
Input field	44px height	48px height
Gap between touchable	8px	12px

.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 layout	Mobile collapse
3 columns	1 column stack (grid-cols-1)
Split screen 50/50	Full-width stack (w-full)
Asymmetric grid (2fr 1fr)	grid-template-columns: 1fr, remove all col-span overrides
Horizontal scroll	Preserve if content is images/cards, restack if text
Overlapping elements	Remove all negative margins and rotations below 768px
Sidebar + content	Stack: 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)

Name	Width	Target
sm	640px	Mobile landscape
md	768px	Tablet portrait
lg	1024px	Tablet landscape / small desktop
xl	1280px	Desktop
2xl	1536px	Large 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

Problem	Cause	Fix
Horizontal scrollbar on mobile	Fixed-width element > viewport	Replace px with clamp(), %, or 100%
Layout jump on iOS Safari	h-screen used	Replace with min-h-[100dvh]
Text unreadable on mobile	Body font < 16px	Minimum 16px, scale with clamp()
Touch target too small	Clickable < 44px	Expand hit area with padding or ::after
Container Query not working	Missing container-type	Set container-type: inline-size on parent
Subgrid rows not aligned	Missing grid-template-rows: subgrid	Verify parent has explicit rows
100vh causes scroll	Didn't account for URL bar	Use dvh or svh
Hover effect fires on touch	No @media (hover: hover) guard	Gate hover behind pointer media query

---

Anti-Patterns

Anti-pattern	Fix
Media queries for component responsiveness	Container Queries
Fixed widths in px	clamp(), %, dvw, or cqi/cqw
Hover-only interactions on mobile	Add @media (hover: hover) guard
Touch targets < 44px	Interactive elements ≥ 44×44px
Body font < 16px	Minimum 16px, clamp() for fluid scaling
No :has() fallback	@supports selector(:has(*)) guard
Deeply nested media queries	Container Queries eliminate most
h-screen for full-height	min-h-[100dvh]
Same layout at all sizes	Layout must collapse on mobile
Asymmetric layout stays asymmetric on mobile	Force 1-column below 768px
Overlapping elements on touch	Separate on mobile. Touch layers cause mis-taps.
calc() with mixed units for grid	Use CSS Grid fr units + minmax()
Complex flexbox math (w-[calc(33%-1rem)])	CSS Grid grid-cols-3 with gap
Testing only at desktop width	Test 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