curiositech/responsive-layout-master

Responsive Layout Master

Build fluid, responsive layouts using CSS Grid, container queries, clamp(), and mobile-first design that adapt from 320px phones to 4K displays without breakpoint jank.

Activation Triggers

Activate on: responsive layout implementation, CSS Grid complex layouts, clamp() fluid sizing, container queries for component responsiveness, mobile-first breakpoint strategy, "layout breaks at X width", sidebar/content/aside patterns.

NOT for: theming/tokens/colors -- use css-in-js-architect. Animating layout changes -- use animation-system-architect. Component library grid systems -- use design-system-creator.

Quick Start

1. Start mobile-first -- write base styles for 320px, then add complexity with min-width media queries.
2. Use CSS Grid for page layout -- grid-template-areas for the main shell (header, sidebar, content, footer).
3. Use clamp() for fluid sizing -- clamp(1rem, 0.5rem + 1.5vw, 2rem) smoothly scales between min and max.
4. Apply container queries -- components that live in variable-width containers (sidebars, modals) should use @container instead of @media.
5. Test at all widths -- drag the browser from 320px to 2560px; there should be no "broken" widths.

Core Capabilities

| Domain | Technologies | Key Patterns | |--------|-------------|--------------| | Page Layout | CSS Grid, grid-template-areas | Named areas, auto-fill, minmax() | | Component Layout | Flexbox, CSS Grid | Intrinsic sizing, gap, align/justify | | Fluid Sizing | clamp(), min(), max(), viewport units | Smooth scaling without breakpoints | | Container Queries | @container, container-type | Component-intrinsic responsiveness | | Fluid Typography | clamp() on font-size, line-height | Readable text at every viewport width | | Breakpoint Strategy | Mobile-first min-width, Tailwind sm:md:lg: | Additive complexity approach |

Architecture Patterns

Pattern 1: CSS Grid Page Shell

.app-shell {
  display: grid;
  min-height: 100dvh;
  grid-template-areas:
    "header"
    "main"
    "footer";
  grid-template-rows: auto 1fr auto;
}

@media (min-width: 768px) {
  .app-shell {
    grid-template-areas:
      "header  header"
      "sidebar main"
      "footer  footer";
    grid-template-columns: 280px 1fr;
    grid-template-rows: auto 1fr auto;
  }
}

@media (min-width: 1280px) {
  .app-shell {
    grid-template-areas:
      "header  header  header"
      "sidebar main   aside"
      "footer  footer  footer";
    grid-template-columns: 280px 1fr 320px;
  }
}

.header  { grid-area: header; }
.sidebar { grid-area: sidebar; }
.main    { grid-area: main; }
.aside   { grid-area: aside; }
.footer  { grid-area: footer; }

  320px (mobile)        768px (tablet)        1280px+ (desktop)
  ┌──────────────┐     ┌───────────────────┐  ┌──────────────────────┐
  │   header     │     │     header        │  │       header         │
  ├──────────────┤     ├──────┬────────────┤  ├──────┬────────┬──────┤
  │              │     │ side │            │  │ side │        │ aside│
  │    main      │     │ bar  │   main     │  │ bar  │  main  │      │
  │              │     │      │            │  │      │        │      │
  ├──────────────┤     ├──────┴────────────┤  ├──────┴────────┴──────┤
  │   footer     │     │     footer        │  │       footer         │
  └──────────────┘     └───────────────────┘  └──────────────────────┘

Pattern 2: Fluid Typography System

:root {
  /* Fluid type scale: min @ 320px → max @ 1280px */
  --text-sm:   clamp(0.8rem,   0.74rem + 0.3vw,   0.875rem);
  --text-base: clamp(1rem,     0.9rem  + 0.5vw,   1.125rem);
  --text-lg:   clamp(1.125rem, 0.95rem + 0.85vw,  1.5rem);
  --text-xl:   clamp(1.25rem,  0.9rem  + 1.7vw,   2rem);
  --text-2xl:  clamp(1.5rem,   0.8rem  + 3.3vw,   3rem);
  --text-3xl:  clamp(2rem,     0.7rem  + 5vw,     4rem);

  /* Fluid spacing */
  --space-sm:  clamp(0.5rem,  0.3rem + 1vw,  1rem);
  --space-md:  clamp(1rem,    0.5rem + 2vw,  2rem);
  --space-lg:  clamp(1.5rem,  0.5rem + 4vw,  4rem);
  --space-xl:  clamp(2rem,    0.5rem + 6vw,  6rem);
}

body { font-size: var(--text-base); }
h1   { font-size: var(--text-3xl); }
h2   { font-size: var(--text-2xl); }
h3   { font-size: var(--text-xl); }

Pattern 3: Auto-Fill Grid for Card Layouts

/* Cards auto-fill available space: minimum 280px, expand to fill */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(280px, 100%), 1fr));
  gap: var(--space-md);
}

This single rule handles 1-column (mobile), 2-column (tablet), 3-column (desktop), and 4-column (wide) without any media queries.

Anti-Patterns

1. Max-width media queries (desktop-first) -- @media (max-width: 768px) leads to overriding desktop styles for mobile. Use min-width (mobile-first) so complexity is added, not subtracted.
2. Fixed pixel breakpoints without fluid behavior -- layout jumps from 1-column to 3-column with no transition. Use clamp() and auto-fill/auto-fit for smooth adaptation.
3. 100vw causing horizontal scroll -- 100vw includes the scrollbar width. Use 100% or 100dvw for the content area width.
4. Viewport media queries for components in variable containers -- a card in a sidebar is 300px wide even on a 1920px screen. Use @container queries for component-level responsiveness.
5. Hardcoded heights -- height: 600px on a container overflows on small screens. Use min-height or let content determine height.

Quality Checklist

• [ ] Layout works from 320px to 2560px with no horizontal scroll
• [ ] Mobile-first approach (base styles = mobile, min-width media queries add complexity)
• [ ] Fluid typography uses clamp() for smooth scaling (no text size jumps)
• [ ] Fluid spacing uses clamp() for padding/margins/gaps
• [ ] grid-template-areas used for main page shell (readable and maintainable)
• [ ] Card/grid layouts use auto-fill/minmax() (no hardcoded column counts)
• [ ] Components in variable-width containers use @container queries
• [ ] No 100vw that could cause horizontal scrollbar overflow
• [ ] min-height: 100dvh used instead of 100vh (mobile browser chrome safe)
• [ ] Touch targets are 44x44px minimum on mobile (WCAG 2.2 Target Size)
• [ ] Layout tested at 320, 375, 768, 1024, 1280, 1920px widths