responsive-paradigms git:20260710.e1775a8A

Immutable. This exact content is served forever at /api/v1/blob/b31edad8c5494cb5.

---
name: responsive-paradigms
description: Mobile, tablet, and desktop are different interaction paradigms — not the same layout scaled up or down. Sections can be hidden, repositioned, or made sticky on mobile. Navigation and primary actions move. Use when designing responsive layouts, adapting desktop UI for mobile, or deciding what to show on each breakpoint.
metadata:
  priority: 8
  pathPatterns:
    - "**/*.css"
    - "**/*.scss"
    - "**/*.tsx"
    - "**/*.jsx"
    - "tailwind.config.*"
    - "design-system/**"
    - "components/**"
  promptSignals:
    phrases:
      - "responsive"
      - "mobile"
      - "tablet"
      - "breakpoint"
      - "desktop"
      - "adaptive"
      - "bottom nav"
      - "hamburger"
      - "touch"
      - "logo"
      - "header"
retrieval:
  aliases:
    - responsive design
    - mobile layout
    - tablet layout
    - breakpoints
    - adaptive UI
    - bottom navigation
    - mobile navigation
    - responsive logo sizing
  intents:
    - design for mobile
    - adapt desktop layout to mobile
    - decide what to show on each breakpoint
    - design mobile navigation
    - handle layout changes at breakpoints
  examples:
    - how should this sidebar behave on mobile
    - design the mobile version of this dashboard
    - what changes between desktop and mobile for this layout
---

# Responsive Paradigms

Mobile, tablet, and desktop are fundamentally different interaction contexts. The input method, screen real estate, viewing distance, and session intent all differ. Responsive design is not the same layout at different widths — it is a different design decision at each breakpoint.

## The Three Paradigms

### Mobile (< 768px)
- **Input:** Touch — fingers, not a cursor. Tap targets ≥ 44×44px.
- **Navigation:** Bottom tab bar (thumb reachable) or hamburger drawer. Top navigation is hard to reach.
- **Session:** Often interrupted, task-focused, shorter. Show the most important thing first.
- **Content:** Single column. Vertical scroll only. No hover states.
- **Primary action:** Floating action button (FAB) or full-width button at the bottom of the screen.

### Tablet (768px–1024px)
- **Input:** Touch and sometimes keyboard/trackpad. Hybrid paradigm.
- **Navigation:** Can support a persistent sidebar at landscape orientation; collapses to drawer at portrait.
- **Content:** Two-column layouts work. Master-detail patterns (list + detail side by side) are natural.
- **Primary action:** Can be in-line with content, not necessarily floating.

### Desktop (> 1024px)
- **Input:** Mouse with hover states, keyboard shortcuts, precise clicking.
- **Navigation:** Persistent sidebar or top navigation. Both visible simultaneously.
- **Content:** Multi-column, dense information, toolbars, context menus.
- **Primary action:** In-context with content, supported by keyboard shortcuts for power users.

---

## Section Behaviour Across Breakpoints

Not every section needs to appear on every breakpoint at the same position — or at all.

### Sections can be hidden on mobile
Secondary content (related articles, supplementary sidebars, decorative illustrations) can be hidden below a breakpoint. Ask: does a mobile user need this? If no, `display: none` at mobile is correct.

### Stacking is the default; repositioning is allowed within the same container
The default responsive move is simply to **stack** — a horizontal row of blocks becomes a vertical column as the viewport narrows. This preserves order and grouping, so the user's mental model of the page survives the breakpoint unchanged. Reach for it first.

**Repositioning an element is also allowed — but only if it stays within roughly the same container area / region.** A sidebar that sits to the left on desktop can move below the main content on mobile, or collapse into an expandable section: it's still "the stuff next to / around the main content", just re-flowed. That's fine.

What to avoid is repositioning that **moves an element into a different container or scope** — lifting a control out of the card it belongs to and dropping it into the global header, or pulling an item from one logical group into another. That breaks the grouping the user learned on desktop and reads as a different UI, not a reflow of the same one. Keep an element's *parent region* stable across breakpoints; only change how it flows *within* it.

```
Desktop:              Mobile:
[Main] [Sidebar]  →   [Main]
                       [▼ Related]  ← collapsed accordion, still "around the main content"
```

### Sticky behaviour can change per breakpoint
An element that is `position: sticky` on desktop may need to become a fixed bottom bar on mobile, or be removed from sticky positioning entirely to free up screen space.

```css
.toolbar {
  position: static; /* mobile: inline, not sticky */
}

@media (min-width: 1024px) {
  .toolbar {
    position: sticky;
    top: var(--header-height);
  }
}
```

### Navigation transforms completely
| Desktop | Mobile |
|---|---|
| Persistent top nav or sidebar | Bottom tab bar or hamburger drawer |
| Visible labels + icons | Icons only (bottom nav) or full list (drawer) |
| Hover states on nav items | None — touch only |
| Dropdowns on hover | Tap to expand, full-screen or sheet |

### Labels can be shortened — but the full meaning must be recoverable
As space tightens, a label can be **shortened**, or dropped to an **icon-only** control (the "visible labels → icons only" move in the nav table above). This is legitimate, but shortening hides information, so the full version must stay reachable — never let it just disappear:

- **Tooltip / accessible name** — attach the full text as a `title` and, for icon-only controls, an `aria-label` so it's available on hover and to screen readers.
- **Kept somewhere** — the full label survives in a detail view, a drawer, or the expanded (desktop) layout.
- **Turned into an icon** — replacing a word with a well-known icon is a valid shortening *only if the icon is unambiguous*, and it still carries its label back via tooltip/`aria-label`. A cryptic icon with no recoverable label is worse than the long word.

This is the same "clamp + recover" contract as truncated body text — see [[repeated-component-alignment]]. The rule is constant across breakpoints: shorten freely, but always give the full value back.

---

## Mobile-First Approach

Design and build mobile first, then enhance for larger screens. Mobile forces prioritisation — what makes it onto mobile is what actually matters.

```css
/* Mobile first: base styles are mobile */
.container { padding: var(--space-4); }

/* Enhance for larger screens */
@media (min-width: 768px) {
  .container { padding: var(--space-8); }
}

@media (min-width: 1024px) {
  .container {
    display: grid;
    grid-template-columns: 1fr 300px;
    gap: var(--space-8);
  }
}

/* Ultra-wide protection */
@media (min-width: 1600px) {
  .container {
    max-width: 1440px;
    margin-left: auto;
    margin-right: auto;
  }
}
```

## Max-Width and Ultra-Wide Screens

Responsive design doesn't mean "expand forever." On very large monitors (2K, 4K, and ultra-wide), content must be capped to maintain readability and ergonomic comfort.

- **Ergonomics:** Spreading critical UI elements across the full width of a 4K screen requires excessive neck movement and makes the interface feel "fragmented."
- **Readability:** As noted in typography guidelines, line lengths should not exceed ~75 characters. On a 4K screen without a max-width, a single line of text could span thousands of pixels.
- **The "Safe Zone":** Use a max-width container (typically between **1280px and 1600px**) for all primary content.
- **Full-Bleed Exceptions:** Background colours, decorative images, and secondary footers can remain full-width to maintain the design's "energy" while the content remains centered and contained.

## Header chrome across breakpoints

A fixed header follows the same paradigms. The brand mark and the menu control both scale, and both keep the same inset from the edge.

- **Scale the brand mark.** A logo sized for desktop dominates a phone: smaller on mobile, moderate on tablet, full on desktop. A wordmark around 18 to 24px tall reads cleanly in a mobile header. Constrain by height and let width follow so the aspect ratio holds.
- **Match the edge inset.** Logo and menu control sit at opposite edges with the same inset, scaling with the breakpoint. Too tight reads as cramped and risks colliding with rounded display corners.

## Wrapped rows inherit the parent's alignment

A row of pills, stats, or tags built with `flex-wrap` keeps its own alignment when it wraps. In a centered mobile column the wrapped line hugs the left while everything around it is centered, leaving a lone trailing item in the corner. Match the inner alignment to the context: centered on mobile, left on desktop.

## Review Checklist

- [ ] Does mobile navigation use a bottom tab bar or drawer — not a top nav that requires thumb stretching?
- [ ] Are touch targets ≥ 44×44px on all interactive elements?
- [ ] Are secondary sections hidden or collapsed on mobile rather than just shrunk?
- [ ] Does sticky positioning adapt per breakpoint — not every sticky desktop element stays sticky on mobile?
- [ ] Is the layout built mobile-first with progressive enhancement upward?
- [ ] Are hover-dependent interactions (tooltips, dropdowns) replaced with tap equivalents on touch?
- [ ] Does the primary action remain reachable with one thumb on mobile?
- [ ] Is the primary content capped with a max-width (e.g., 1440px) on ultra-wide/4K monitors?
- [ ] Does the header brand mark scale with the breakpoint, with logo and menu control sharing the same edge inset?
- [ ] Do wrapped rows (pills, stats, tags) match the alignment of the context they sit in, rather than defaulting to left in a centered column?
- [ ] Is stacking the default reflow, with repositioning kept within an element's original container/region rather than moving it into a different scope?
- [ ] Where labels are shortened or reduced to icon-only, is the full meaning recoverable (tooltip/`aria-label`, a kept-elsewhere label, or an unambiguous icon)?