Richie
aa7cdeecf0
Phase 1: Session log archived (1096→91 lines), D031 token access convention
Phase 2: ESLint v9 + Prettier + jsx-a11y, initial config and lint fixes
Phase 3: 7 new skills (polish, harden, normalize, clarify, typeset, quieter, adapt)
+ Vercel reference docs, updated audit/review-component refs
Phase 4: Husky + lint-staged pre-commit hooks, preflight updated to 8 checks
Phase 5: Vitest + Testing Library + /write-tests skill
- Badge.tsx colour maps unified to CSS variables (D031)
- 5 empty interface→type alias fixes (Switch, Radio, Divider, IconButton, Link)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
131 lines
6.9 KiB
Markdown
131 lines
6.9 KiB
Markdown
---
|
|
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.
|