responsive-design

name	responsive-design
description	Enforce mobile-first responsive design — breakpoint definition, content reflow audit, touch target validation, and layout stress testing at each tier.
version	0.1.0
level	2
triggers	["responsive design","responsive check","mobile review","breakpoint audit","/responsive-design"]
context_files	["context/project.md"]
steps	[{"name":"Breakpoint Inventory","description":"Establish the breakpoint system in use. Verify it matches the design brief or project standard."},{"name":"Mobile Audit","description":"Review layout at 375px. Touch targets, content reflow, text legibility, navigation."},{"name":"Tablet Audit","description":"Review layout at 768px. Identify grid collapse, content ordering, any mobile-only or desktop-only elements."},{"name":"Desktop Audit","description":"Review layout at 1280px+. Max-width containers, content density, whitespace."},{"name":"Edge Cases","description":"Check very small (320px), large desktop (1920px), and landscape mobile."},{"name":"Verdict","description":"BLOCK/WARN/CLEAN per breakpoint tier with specific remediation."}]

Responsive Design Skill

Audit layouts at every breakpoint before shipping. The pattern of "it works on my screen" is responsible for most responsive bugs. This skill provides a systematic, breakpoint-by-breakpoint review process.

What Claude Gets Wrong Without This Skill

Claude writes desktop-first code. It builds the full desktop layout and then adds @media (max-width: 768px) overrides as an afterthought. The mobile experience gets minimum viable treatment — a single-column stack with no attention to typography scale, touch target sizes, or navigation patterns.

The second failure: Claude tests at one breakpoint mentally. It imagines the layout at 1280px and considers it done. It does not consider 375px (iPhone SE), 390px (iPhone 15), 414px (larger Android), or 320px (minimum supported width). Small differences in assumptions produce real rendering failures.

The third failure: content ordering. On mobile, a sidebar that appears on the right in the desktop layout often needs to appear above the main content — not below it. CSS grid and flexbox reorder properties solve this, but Claude does not set them unless explicitly directed.

Mobile-First Principle

Write base styles for mobile. Add complexity at larger breakpoints with min-width queries. This is the standard — not because it is a preference, but because it is how the cascade and specificity work most predictably.

Mobile-first:

/* Base: mobile */
.container { padding: 16px; }
.grid { grid-template-columns: 1fr; }

/* Tablet and up */
@media (min-width: 768px) {
  .container { padding: 24px; }
  .grid { grid-template-columns: repeat(2, 1fr); }
}

/* Desktop and up */
@media (min-width: 1280px) {
  .container { : ; : ; :  auto; }
   { : (, fr); }
}