---
name: adapt
description: Responsive adaptation review — checks touch targets, overflow, text scaling, content reflow, and mobile spacing across breakpoints.
user-invocable: true
argument-hint: "[component or area to check]"
---

Run a responsive design review on a component or area, then **fix issues found**. This is assessment AND fix — diagnose breakpoint problems, touch target failures, and mobile usability issues, then apply corrections.

**Target:** $ARGUMENTS

## Preparation

1. Read `docs/design-system.md` for FA responsive conventions and breakpoints
2. Read the target component/area source files and stories
3. Reference `docs/reference/impeccable/responsive-design.md` for detailed responsive guidelines

**FA context reminder**: Many Funeral Arranger users are older adults, potentially on older or budget devices, and may be using the platform on mobile during a difficult time. Touch interactions must be generous. Layouts must not break on small screens. Nothing should require precise fine-motor control or hover-only interactions. The platform must work on a 5-year-old Android phone on a slow connection just as well as on a modern desktop.

## Diagnostic Checks

Work through each check systematically. For each issue found, note the problem, then fix it.

### 1. Touch Targets

- All interactive elements (buttons, links, form controls, toggles) must have a minimum touch target of 44x44px
- Check `padding`, `min-height`, and `min-width` on clickable elements — the visual size can be smaller if the tap area is padded out
- Text links in body copy need adequate line-height or padding to create 44px+ tap areas
- Adjacent touch targets must have sufficient spacing (at least 8px gap) to prevent mis-taps
- Icon-only buttons are especially prone to being too small — verify dimensions include padding
- This is **critical** for FA's audience — elderly users and users under emotional stress have reduced fine-motor precision

### 2. Horizontal Overflow

- No horizontal scrolling on viewports as narrow as 320px (iPhone SE, older Android devices)
- Check for fixed widths (`width: 400px`, `min-width: 500px`) that exceed narrow viewports
- Check for content that breaks out of containers (long words, URLs, email addresses without `word-break` or `overflow-wrap`)
- Tables must adapt on mobile — use responsive patterns (card layout, horizontal scroll with visual indicator, or progressive disclosure)
- Images must have `max-width: 100%` or equivalent constraint
- Check for `flex-shrink: 0` or `flex: none` on elements that should be allowed to shrink

### 3. Text Readability at Mobile Sizes

- Body text minimum 14px on mobile (16px preferred)
- Use `rem` units for font sizes so text respects browser zoom/accessibility settings
- Never use `user-scalable=no` in viewport meta — this breaks accessibility
- Layouts must not break at 200% browser zoom (WCAG requirement)
- Small/caption text should remain legible — minimum 12px
- Check that heading sizes scale down appropriately on mobile (a 48px desktop heading should not stay 48px on a 320px screen)

### 4. Content Reflow

- Content should reflow logically between breakpoints, not just shrink
- Multi-column layouts should collapse to single column on mobile
- Side-by-side arrangements (image + text, icon + label) should stack vertically when space is constrained
- Check `flex-direction` and `grid-template-columns` for responsive adjustments
- Navigation should adapt: full horizontal on desktop, hamburger/drawer on mobile
- Cards in a grid should reduce column count at narrow widths, not just shrink cards

### 5. Hover-Only Interactions

- No functionality should require hover — touch users cannot hover
- Tooltips that appear only on hover need a touch alternative (tap to show, or visible by default on mobile)
- Hover-revealed actions (edit buttons, delete icons) must have an alternative on touch devices
- Use `@media (hover: hover)` for hover enhancements, with fallback for `@media (hover: none)`
- Dropdown menus triggered by hover must also work on tap
- Check for CSS `:hover` styles that hide/show content without a touch-friendly fallback

### 6. Spacing Adjustments Per Breakpoint

- Padding should be tighter on mobile (16px) and more generous on desktop (24-48px)
- Section spacing should compress on mobile to keep content scannable without excessive scrolling
- Card padding should adapt — desktop cards can be spacious, mobile cards should be compact but not cramped
- Check that spacing uses theme.spacing() or responsive values, not fixed values that work only at one breakpoint
- Container max-widths should be set appropriately for each breakpoint

### 7. Image and Asset Sizing

- Images should have responsive sizing (`max-width: 100%`, `height: auto`)
- Consider `loading="lazy"` for images below the fold (important for FA users on slow connections)
- Decorative images can be hidden on mobile if they add no informational value
- Avatar/icon sizes should be appropriate for mobile — not too large (wasting space) or too small (illegible)
- Check for background images that might not display well on small screens

## Fix Process

For each issue found:

1. **Identify** the file, line, and current value
2. **Test mentally at 320px, 768px, and 1280px** — does the fix work across all three?
3. **Apply the fix** — use responsive utilities (MUI breakpoints, media queries, responsive props)
4. **Verify** the fix does not introduce new issues at other breakpoints
5. **Prefer CSS/theme solutions** over JavaScript breakpoint detection where possible

## Report Format

After fixing, present a summary:

### Responsive Health Summary

| Check | Status | Issues Found | Issues Fixed |
|-------|--------|-------------|-------------|
| Touch Targets (44px min) | pass/warn/fail | N | N |
| Horizontal Overflow (320px) | pass/warn/fail | N | N |
| Text Readability (mobile) | pass/warn/fail | N | N |
| Content Reflow | pass/warn/fail | N | N |
| Hover-Only Interactions | pass/warn/fail | N | N |
| Breakpoint Spacing | pass/warn/fail | N | N |
| Image/Asset Sizing | pass/warn/fail | N | N |

### Breakpoint Walkthrough

Brief assessment of the component at each key breakpoint:
- **320px** (small phone): Does it fit? Is it usable?
- **768px** (tablet): Does the layout adapt sensibly?
- **1280px** (desktop): Does it use the available space well?

### Changes Made

For each fix applied:
- **What changed**: Brief description
- **File**: Path and relevant line(s)
- **Before/After**: The old and new values
- **Breakpoint affected**: Which viewport size(s) this fix targets

### Remaining Concerns

Any issues that need design input, Storybook viewport testing, or are outside the scope of a responsive pass.

**NEVER**: Use fixed pixel widths for containers. Add `user-scalable=no` to viewport meta. Rely on hover for essential functionality. Assume all users have modern large-screen devices. Ignore the 320px viewport — real people use iPhone SE and budget Android phones. Let touch targets fall below 44px.