Files
faunosteo/docs/superpowers/plans/2026-05-23-responsive-mobile.md
T
Bastien ChanotandClaude Opus 4.6 a73d8da263 fix(ui): responsive mobile — full phone/tablet adaptation across all components
Surgical CSS/className-only changes, zero behavior impact. 155/155 tests green.

- Dialog: tighter mobile padding (p-3/px-4), reduced max-height to 85vh
- Button: sm size h-8→h-9 (36px touch target), responsive text sizing
- VertebraPicker: 44px min-height touch targets on mobile region tabs
- SVG editor: sidebar stacks below canvas <768px, full-width mobile,
  zoom controls 40px, canvas min-height 40vh
- AnatomyCanvas: SVG child constrained to fit container
- EditorRoute: responsive gap/padding, canvas max-h-[55vh] on mobile
- ObservationList + ConclusionPanel: responsive section heading typography

Target: 375px+ (iPhone SE) usable, 768px+ (iPad) polished, desktop no regressions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-05-23 20:01:50 +02:00

19 KiB

Responsive Mobile Fixes — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make Faunosteo SPA fully usable on phone screens (375px+) and polished on tablets (768px+) via surgical CSS/className-only changes.

Architecture: No behavior changes — pure Tailwind class and CSS media query updates across ~12 files. No store, schema, or PDF changes. Existing tests must stay green since only visual layout changes.

Tech Stack: Tailwind CSS v4 (CSS-first), React 19, existing component library


Task 1: Dialog viewport clamping

Files:

  • Modify: src/components/ui/Dialog.tsx

  • Step 1: Update Dialog SIZE map and container classes

In src/components/ui/Dialog.tsx, replace the SIZE constant and the dialog container/content classes:

const SIZE: Record<NonNullable<DialogProps['size']>, string> = {
  sm: 'max-w-sm',
  md: 'max-w-md',
  lg: 'max-w-2xl',
  xl: 'max-w-4xl',
}

with:

const SIZE: Record<NonNullable<DialogProps['size']>, string> = {
  sm: 'max-w-sm max-w-[calc(100vw-2rem)]',
  md: 'max-w-md max-w-[calc(100vw-2rem)]',
  lg: 'max-w-2xl max-w-[calc(100vw-2rem)]',
  xl: 'max-w-4xl max-w-[calc(100vw-2rem)]',
}

Note: Tailwind applies the last matching utility — max-w-[calc(100vw-2rem)] wins on small screens where the named max-width exceeds viewport, and the named max-width wins on large screens where it's smaller. Actually, this won't work — Tailwind just uses specificity/order. Need a different approach.

Instead, add the viewport clamp directly on the motion.div alongside the SIZE class. Change:

className={`relative w-full ${SIZE[size]} max-h-[90vh] overflow-y-auto rounded-2xl bg-[var(--color-surface)] shadow-xl`}

to:

className={`relative w-full ${SIZE[size]} max-h-[85vh] overflow-y-auto rounded-2xl bg-[var(--color-surface)] shadow-xl`}

And change the outer container padding from:

<div className="fixed inset-0 z-50 flex items-center justify-center p-4">

to:

<div className="fixed inset-0 z-50 flex items-center justify-center p-3 sm:p-4">

And change the dialog header padding from:

<header className="flex items-center justify-between px-6 py-4 border-b border-[var(--color-border)]">

to:

<header className="flex items-center justify-between px-4 sm:px-6 py-3 sm:py-4 border-b border-[var(--color-border)]">

And change the dialog body padding from:

<div className="px-6 py-4">{children}</div>

to:

<div className="px-4 sm:px-6 py-3 sm:py-4">{children}</div>

The key fix: since all sizes already use w-full with max-w-*, the dialog box naturally fills available width minus padding. Reducing container padding from p-4 to p-3 on small screens gives 6px more breathing room per side. The max-w-sm (384px) fits within 375px - 24px = 351px viewport on phones (it doesn't — 384 > 351). The real fix is that w-full makes the dialog width = container width = viewport - 2padding, so the max-w- values are upper caps that only kick in when there's room.

Wait — w-full with max-w-md means the dialog takes min(100%, 448px). On a 375px phone with p-3 (12px each side), available width = 375 - 24 = 351px. w-full = 351px which is < 448px, so dialog = 351px. This already works correctly. No extra max-w-[calc(...)] needed. The existing w-full + max-w-* pattern is responsive by design.

So the actual changes are: tighten padding for mobile comfort + reduce max-h for better mobile viewport fit.

  • Step 2: Run tests

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm test:run Expected: All tests pass (no behavior change)

  • Step 3: Run typecheck

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm typecheck Expected: No errors

  • Step 4: Commit
git add src/components/ui/Dialog.tsx
git commit -m "fix(ui): responsive dialog — tighter mobile padding and max-height"

Task 2: Button touch targets

Files:

  • Modify: src/components/ui/Button.tsx

  • Step 1: Update SIZES to ensure mobile-friendly touch targets

In src/components/ui/Button.tsx, change the SIZES constant from:

const SIZES: Record<NonNullable<ButtonProps['size']>, string> = {
  sm: 'h-8 px-3 text-sm rounded-md',
  md: 'h-10 px-4 text-base rounded-lg',
  lg: 'h-12 px-6 text-base rounded-lg',
}

to:

const SIZES: Record<NonNullable<ButtonProps['size']>, string> = {
  sm: 'h-9 px-3 text-sm rounded-md',
  md: 'h-10 px-4 text-sm sm:text-base rounded-lg',
  lg: 'h-12 px-5 sm:px-6 text-base rounded-lg',
}

Changes:

  • sm: h-8 → h-9 (36px, closer to 44px minimum)

  • md: add responsive text text-sm sm:text-base

  • lg: tighter padding on mobile px-5 sm:px-6

  • Step 2: Run tests

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm test:run Expected: All tests pass

  • Step 3: Commit
git add src/components/ui/Button.tsx
git commit -m "fix(ui): increase button sm touch target to 36px, responsive text sizing"

Task 3: VertebraPicker touch targets

Files:

  • Modify: src/components/observation/VertebraPicker.tsx

  • Step 1: Increase region tab touch targets

In src/components/observation/VertebraPicker.tsx, change the region tab button className from:

'rounded-full px-4 py-1.5 text-sm font-medium border',

to:

'rounded-full px-4 py-2.5 sm:py-1.5 text-sm font-medium border min-h-[2.75rem]',

This ensures 44px minimum height on mobile (py-2.5 = 10px top+bottom + text ≈ 44px), drops back to denser on desktop.

  • Step 2: Run tests

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm test:run Expected: All tests pass

  • Step 3: Commit
git add src/components/observation/VertebraPicker.tsx
git commit -m "fix(ui): vertebra picker region tabs — 44px touch target on mobile"

Task 4: SVG editor sidebar responsive stacking

Files:

  • Modify: src/styles/svg-editor.css

  • Step 1: Add media query for sidebar stacking

In src/styles/svg-editor.css, change the .svg-editor-root rule from:

.svg-editor-root {
  display: flex;
  flex: 1;
  min-height: 0;
  overflow: hidden;
  font-family: var(--font-sans);
  color: var(--color-ink);
  background: var(--color-bg);
}

to:

.svg-editor-root {
  display: flex;
  flex-direction: column;
  flex: 1;
  min-height: 0;
  overflow: hidden;
  font-family: var(--font-sans);
  color: var(--color-ink);
  background: var(--color-bg);
}

@media (min-width: 768px) {
  .svg-editor-root {
    flex-direction: row;
  }
}

Then change the .svg-editor-sidebar rule from:

.svg-editor-sidebar {
  width: 380px;
  background: var(--color-surface);
  border-left: 1px solid var(--color-border);
  display: flex;
  flex-direction: column;
  overflow: hidden;
}

to:

.svg-editor-sidebar {
  width: 100%;
  background: var(--color-surface);
  border-top: 1px solid var(--color-border);
  display: flex;
  flex-direction: column;
  overflow: hidden;
  max-height: 50vh;
}

@media (min-width: 768px) {
  .svg-editor-sidebar {
    width: 380px;
    max-height: none;
    border-top: none;
    border-left: 1px solid var(--color-border);
  }
}

Also update .svg-editor-canvas to ensure minimum usable height on mobile by changing:

.svg-editor-canvas {
  flex: 1;
  position: relative;
  background: var(--color-surface);
  overflow: hidden;
  padding: 10px;
}

to:

.svg-editor-canvas {
  flex: 1;
  position: relative;
  background: var(--color-surface);
  overflow: hidden;
  padding: 10px;
  min-height: 40vh;
}

@media (min-width: 768px) {
  .svg-editor-canvas {
    min-height: 0;
  }
}

Also update the zoom controls for mobile — make buttons bigger:

.svg-editor-zoom-controls button {
  width: 32px;
  height: 32px;
  padding: 0;
  margin: 0;
  font-size: 16px;
  display: flex;
  align-items: center;
  justify-content: center;
}

to:

.svg-editor-zoom-controls button {
  width: 40px;
  height: 40px;
  padding: 0;
  margin: 0;
  font-size: 18px;
  display: flex;
  align-items: center;
  justify-content: center;
}

@media (min-width: 768px) {
  .svg-editor-zoom-controls button {
    width: 32px;
    height: 32px;
    font-size: 16px;
  }
}
  • Step 2: Run typecheck and build

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm typecheck && ~/.local/share/pnpm/bin/pnpm build Expected: Clean

  • Step 3: Commit
git add src/styles/svg-editor.css
git commit -m "fix(ui): SVG editor sidebar stacks below canvas on mobile (<768px)"

Task 5: AnatomyCanvas height constraint + EditorRoute responsive

Files:

  • Modify: src/components/canvas/AnatomyCanvas.tsx

  • Modify: src/app/routes/EditorRoute.tsx

  • Step 1: Add responsive classes to AnatomyCanvas wrapper

In src/components/canvas/AnatomyCanvas.tsx, change the wrapper div from:

<div
  data-testid="anatomy-canvas"
  ref={wrapperRef}
  className={`svg-canvas relative w-full h-full ${className}`}
>
  <div ref={svgRef} className="w-full h-full" />

to:

<div
  data-testid="anatomy-canvas"
  ref={wrapperRef}
  className={`svg-canvas relative w-full h-full ${className}`}
>
  <div ref={svgRef} className="w-full h-full [&>svg]:max-w-full [&>svg]:max-h-full [&>svg]:mx-auto" />

This ensures the SVG inside doesn't overflow and centers horizontally.

  • Step 2: Update EditorRoute grid layout for mobile

In src/app/routes/EditorRoute.tsx, change the main grid container from:

<div className="flex-1 grid grid-cols-1 lg:grid-cols-[2fr_3fr] gap-6 p-6">
  <section className="border border-[var(--color-border)] rounded-2xl bg-[var(--color-surface)] overflow-hidden">

to:

<div className="flex-1 grid grid-cols-1 lg:grid-cols-[2fr_3fr] gap-4 sm:gap-6 p-4 sm:p-6">
  <section className="border border-[var(--color-border)] rounded-2xl bg-[var(--color-surface)] overflow-hidden max-h-[55vh] lg:max-h-none">

The max-h-[55vh] lg:max-h-none constrains the SVG canvas on mobile/tablet (single-column) so the observation list is visible without scrolling past the entire SVG. On desktop (lg+, two-column), it fills naturally.

Also change the observations section from:

<section className="space-y-6">

to:

<section className="space-y-4 sm:space-y-6">
  • Step 3: Run tests

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm test:run Expected: All tests pass

  • Step 4: Run typecheck

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm typecheck Expected: No errors

  • Step 5: Commit
git add src/components/canvas/AnatomyCanvas.tsx src/app/routes/EditorRoute.tsx
git commit -m "fix(ui): constrain anatomy canvas height on mobile, responsive editor spacing"

Task 6: Responsive typography and padding — HomeRoute + EditorsRoute

Files:

  • Modify: src/app/routes/HomeRoute.tsx

  • Modify: src/app/routes/EditorsRoute.tsx

  • Step 1: Update HomeRoute

In src/app/routes/HomeRoute.tsx, change:

<section className="flex-1 grid place-items-center px-6">
  <div className="grid gap-4 md:grid-cols-2 max-w-3xl w-full">
    <Card className="p-6 space-y-4">
      <h2 className="font-serif text-2xl">{t('home.new_report.title')}</h2>

to:

<section className="flex-1 grid place-items-center px-4 sm:px-6">
  <div className="grid gap-4 md:grid-cols-2 max-w-3xl w-full">
    <Card className="p-4 sm:p-6 space-y-3 sm:space-y-4">
      <h2 className="font-serif text-xl sm:text-2xl">{t('home.new_report.title')}</h2>

And the second card heading too:

<Card className="p-6 space-y-4">
  <h2 className="font-serif text-2xl">{t('home.import.title')}</h2>

to:

<Card className="p-4 sm:p-6 space-y-3 sm:space-y-4">
  <h2 className="font-serif text-xl sm:text-2xl">{t('home.import.title')}</h2>
  • Step 2: Update EditorsRoute

In src/app/routes/EditorsRoute.tsx, change:

<section className="flex-1 grid place-items-center px-6">
  <div className="grid gap-4 md:grid-cols-2 max-w-3xl w-full">
      <Card className="p-6 space-y-4">
        <h2 className="font-serif text-2xl">{t('editors.svg.title')}</h2>

to:

<section className="flex-1 grid place-items-center px-4 sm:px-6">
  <div className="grid gap-4 md:grid-cols-2 max-w-3xl w-full">
      <Card className="p-4 sm:p-6 space-y-3 sm:space-y-4">
        <h2 className="font-serif text-xl sm:text-2xl">{t('editors.svg.title')}</h2>

And the second card:

<Card className="p-6 space-y-4">
  <h2 className="font-serif text-2xl">{t('editors.pathology.title')}</h2>

to:

<Card className="p-4 sm:p-6 space-y-3 sm:space-y-4">
  <h2 className="font-serif text-xl sm:text-2xl">{t('editors.pathology.title')}</h2>
  • Step 3: Run tests

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm test:run Expected: All tests pass

  • Step 4: Commit
git add src/app/routes/HomeRoute.tsx src/app/routes/EditorsRoute.tsx
git commit -m "fix(ui): responsive padding and typography on home and editors pages"

Task 7: Responsive typography and padding — NewReportRoute

Files:

  • Modify: src/app/routes/NewReportRoute.tsx

  • Step 1: Update NewReportRoute responsive classes

In src/app/routes/NewReportRoute.tsx, change:

<div className="max-w-3xl mx-auto px-6 py-8 space-y-8">
  <h1 className="font-serif text-3xl">{t('new_report.title')}</h1>

to:

<div className="max-w-3xl mx-auto px-4 sm:px-6 py-6 sm:py-8 space-y-6 sm:space-y-8">
  <h1 className="font-serif text-2xl sm:text-3xl">{t('new_report.title')}</h1>
  • Step 2: Run tests

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm test:run Expected: All tests pass

  • Step 3: Commit
git add src/app/routes/NewReportRoute.tsx
git commit -m "fix(ui): responsive padding and typography on new report page"

Task 8: Responsive typography — ObservationList + ConclusionPanel

Files:

  • Modify: src/components/observation/ObservationList.tsx

  • Modify: src/components/report/ConclusionPanel.tsx

  • Step 1: Update ObservationList heading

In src/components/observation/ObservationList.tsx, change:

<h2 className="font-serif text-xl text-[var(--color-ink)]">

to:

<h2 className="font-serif text-lg sm:text-xl text-[var(--color-ink)]">
  • Step 2: Update ConclusionPanel heading

In src/components/report/ConclusionPanel.tsx, change:

<h2 className="font-serif text-xl text-[var(--color-ink)]">

to:

<h2 className="font-serif text-lg sm:text-xl text-[var(--color-ink)]">
  • Step 3: Run tests

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm test:run Expected: All tests pass

  • Step 4: Commit
git add src/components/observation/ObservationList.tsx src/components/report/ConclusionPanel.tsx
git commit -m "fix(ui): responsive typography for observation and conclusion headings"

Files:

  • Modify: src/components/brand/Footer.tsx

  • Modify: src/components/brand/AppHeader.tsx

  • Step 1: Update Footer spacing

In src/components/brand/Footer.tsx, change:

<footer className="mt-12 border-t border-neutral-200 bg-neutral-50 py-6 text-center text-sm text-neutral-600">

to:

<footer className="mt-8 sm:mt-12 border-t border-neutral-200 bg-neutral-50 py-4 sm:py-6 text-center text-xs sm:text-sm text-neutral-600">

And the flex container from:

<div className="flex flex-wrap items-center justify-center gap-4">

to:

<div className="flex flex-wrap items-center justify-center gap-2 sm:gap-4">
  • Step 2: Update AppHeader padding

In src/components/brand/AppHeader.tsx, change:

<header className="px-6 py-3 border-b border-[var(--color-border)] flex items-center justify-between bg-[var(--color-surface)]">

to:

<header className="px-3 sm:px-6 py-2 sm:py-3 border-b border-[var(--color-border)] flex items-center justify-between bg-[var(--color-surface)]">

And the right-side gap from:

<div className="flex items-center gap-4">

to:

<div className="flex items-center gap-2 sm:gap-4">
  • Step 3: Run tests

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm test:run Expected: All tests pass

  • Step 4: Commit
git add src/components/brand/Footer.tsx src/components/brand/AppHeader.tsx
git commit -m "fix(ui): responsive footer and header spacing for mobile"

Task 10: ReportHeader mobile polish

Files:

  • Modify: src/components/report/ReportHeader.tsx

  • Step 1: Make report info responsive on mobile

In src/components/report/ReportHeader.tsx, change:

<div className="text-sm text-right text-[var(--color-ink-muted)]">
  <div className="text-[var(--color-ink)] font-medium">
    {report.animal.name} · {report.owner.name}
  </div>
  <div>{formatDate(report.date, locale)}</div>
</div>

to:

<div className="text-xs sm:text-sm text-right text-[var(--color-ink-muted)]">
  <div className="text-[var(--color-ink)] font-medium truncate max-w-[10rem] sm:max-w-none">
    {report.animal.name} · {report.owner.name}
  </div>
  <div className="hidden sm:block">{formatDate(report.date, locale)}</div>
</div>

Changes:

  • Smaller text on mobile (text-xs sm:text-sm)

  • Truncate long names on narrow screens (truncate max-w-[10rem])

  • Hide date on very small screens (header is already tight)

  • Step 2: Run tests

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm test:run Expected: All tests pass

  • Step 3: Commit
git add src/components/report/ReportHeader.tsx
git commit -m "fix(ui): responsive report header — compact on mobile"

Task 11: Final verification

  • Step 1: Run full verification suite

Run:

cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm typecheck && ~/.local/share/pnpm/bin/pnpm test:run && ~/.local/share/pnpm/bin/pnpm lint && ~/.local/share/pnpm/bin/pnpm build

Expected: All clean — typecheck, tests, lint (0 warnings), build success.

  • Step 2: Dev server visual check

Run: cd /home/bchanot-ubuntu/Documents/osteo && ~/.local/share/pnpm/bin/pnpm dev

Open in browser, test at:

  • 375px width (iPhone SE): all pages, editor, dialogs
  • 768px width (iPad): editor two-panel, SVG editor with sidebar
  • 1280px width (desktop): no regressions

Check:

  • No horizontal overflow on any page at 375px

  • Dialogs fit within viewport

  • SVG editor sidebar stacks below canvas at <768px

  • AnatomyCanvas constrained in height on single-column layout

  • All buttons tappable (no tiny targets)

  • Typography scales appropriately

  • Footer wraps cleanly

  • Step 3: Stop dev server