Parsons/.claude/skills/adapt/SKILL.md

name, description, user-invocable, argument-hint

name	description	user-invocable	argument-hint
adapt	Responsive adaptation review — checks touch targets, overflow, text scaling, content reflow, and mobile spacing across breakpoints.	true	[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.