responsive-ui

# Responsive UI — default, not a feature request ## The rule **Every UI change ships working at all four device classes. Nobody has to ask.** | Device | Test width | Tailwind context | |---|---|---| | Mobile | 375px | base (no prefix) | | Tablet | 768px | `md:` | | Desktop | 1280px | `xl:` | | Large desktop | 1920px | beyond `2xl:` | Tailwind is **mobile-first**: unprefixed classes are the mobile layout; prefixes add behavior at wider screens (`sm:` 640, `md:` 768, `lg:` 1024, `xl:` 1280, `2xl:` 1536). Write the mobile layout first, then widen — not the other way around. A change is NOT done until you have reasoned through (or better, viewed via the `webapp-testing` skill / browser dev tools) what it looks like at 375, 768, 1280, and 1920. If you only checked one width, you checked none. ## Works WITH the design system — precedence rules This skill layers on top of the `ui` skill; **where they touch, the design-system rules win**. Responsiveness is achieved THROUGH the DS, never around it: - **Never put responsive classes (or any `className`) on DS components** (`Text`, `Stack`, `HStack`, `Badge`, `Button`, …) — they don't accept it. Put breakpoint utilities on a wrapper `<div>` (the `ui` skill's "Layout with Wrapper Divs" pattern): ```tsx // ✅ breakpoints on the wrapper, DS component untouched <div className="hidden sm:block"><Badge variant="outline">Active</Badge></div> // ❌ className on a DS component <Badge className="hidden sm:block">Active</Badge> ``` - **Reach for DS layout primitives first** (`PageLayout`, `Stack`, `HStack`, `Section`) — they carry responsive spacing already. Raw responsive divs are for what the primitives don't cover, not a replacement for them. - **Arbitrary pixel values stay an anti-pattern** (`w-[847px]` ❌ — per the `ui` skill). Prefer the standard Tailwind scale (`max-w-sm`, `w-48`, `max-w-xs`). A fixed control width like `w-[200px]` is acceptable ONLY when it matches an established pattern already used on that surface, and it must still carry a responsive strategy (see below). ## Non-negotiables 1. **The page body never scrolls horizontally.** Wide content (tables, code, diagrams) scrolls inside its own container, never the page. 2. **No fixed width without a responsive strategy.** A fixed-width control is only acceptable if the element hides, shrinks, or wraps on smaller screens (`hidden sm:block`, `w-full md:max-w-xs`, or a wrapping parent) — with the breakpoint classes on a wrapper div, never on a DS component. 3. **Touch targets** on mobile: interactive elements ≥40px tall; don't rely on hover for anything essential (no hover on touch devices). 4. **Test with real content lengths** — long names, emails, 33-item counts. Use `truncate` / `min-w-0` on flex children that hold text. 5. **Large desktops:** content must not stretch into unreadable full-width lines — cap with `max-w-*` containers where the layout doesn't already. ## Repo patterns (use these, don't invent) - **Tables**: the design-system `Table` already wraps rows in `overflow-x-auto` — wide tables scroll horizontally inside themselves on mobile. That is the accepted pattern for dense admin tables. Do NOT try to reflow table columns per breakpoint; do keep cells reasonable (`min-w-* max-w-*` on cell content is fine). - **Toolbars / filter rows**: primary control (search) is `w-full md:max-w-[300px]`; secondary controls (filters, source selectors) collapse on phones with `hidden sm:block`. Example: the People tab toolbar in `apps/app/.../people/all/components/TeamMembersClient.tsx`. - **Page shells**: use design-system `PageLayout` / `Stack` / `HStack` — they carry the responsive spacing; don't rebuild them with raw divs. - **Grids**: `grid-cols-1 md:grid-cols-2 xl:grid-cols-3` style progressions — never a fixed column count for all widths. - **Sheets/Modals**: design-system `Sheet`/`Dialog` are responsive already; don't fix their widths with arbitrary values. - **Images/logos**: constrain (`max-w-full`, explicit small sizes); never let an image force layout width. ## Checklist before "done" (run mentally or in the browser) - [ ] 375px — nothing overflows the viewport; controls usable or intentionally hidden; text truncates instead of breaking layout - [ ] 768px — secondary controls visible; layout uses available width sensibly - [ ] 1280px — the intended "design" width; matches mockups - [ ] 1920px — no absurdly stretched content; whitespace balanced - [ ] Long content (names, emails, high counts) doesn't break any of the above - [ ] Tests: if a component hides/reflows per breakpoint in a way that matters, its test asserts the class contract (e.g. `hidden sm:block`) ## When you can skip a width Admin-only dense screens (e.g. internal tooling) may treat mobile as "usable via horizontal scroll" rather than fully reflowed — but that must be a conscious choice following the existing pattern of that page, never an accident of not checking.