From a7bc62a5b40f0fa04882571c84298b2db0c18ee8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 28 Sep 2026 23:46:11 +0000
Subject: [PATCH 1/3] feat: touch-first calculator with readable, accessible
 design tokens

Make the app easier to use one-handed on a dock or mid-service, and fix
places where text was unreadable.

Readability
- Add theme-aware text tokens (accent, link, success, danger) and a
  stronger form-control border; fix text-muted. Light text-muted was
  2.6:1 and terracotta links 3.6-4.0:1; dark-mode headings that used
  text-brand-teal were ~2:1 (About, Data Sources, Community, Upload).
- Codemod text-brand-teal/-terracotta/red-500 to the new tokens.
- SyncStatusBadge used teal/gray icons on the teal navbar; use light ones.
- About CTA: white on terracotta was 4.0:1; add AA-safe brand-cta.
- designTokens.test.js enforces WCAG AA on every token pair.

Calculator
- Two numbered steps, plain-language labels, 48px controls, 16px inputs
  (no iOS focus zoom), Enter key calculates, result scrolls into view
  and is announced, disabled button explains why.
- Help tooltips now work on tap and keyboard, stay on screen, and close
  on outside tap or Escape (were hover-only, unreadable on phones).
- Labels bound to fields; "Applied to weight" shows only when a
  processing cost is entered; Sign in uses a router Link so a
  calculation is not lost to a full reload.

Navigation and shell
- 44px nav/menu/theme targets, skip link, aria-expanded, active-page
  underline, global focus ring, reduced-motion support.
- Login: associate the password label, add autocomplete, center icons.
- Favicon and manifest theme color match the current teal brand.

Add docs/DESIGN_SYSTEM.md with token rules and known follow-ups.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ErLEY8gicR3Wg7Q1yXAVaC
---
 app/index.html                             |   4 +-
 app/src/App.jsx                            |  60 +-
 app/src/components/About.jsx               |  20 +-
 app/src/components/Calculator.jsx          | 730 ++++++++++++---------
 app/src/components/CommunityData.jsx       |  12 +-
 app/src/components/ContributorProfile.jsx  |   8 +-
 app/src/components/DataManagement.jsx      |  30 +-
 app/src/components/DataTransparency.jsx    |  44 +-
 app/src/components/Login.jsx               |  23 +-
 app/src/components/PreviewPublishModal.jsx |   2 +-
 app/src/components/RecoveryModal.jsx       |   6 +-
 app/src/components/SignOutGuardModal.jsx   |   2 +-
 app/src/components/SubmitRequest.jsx       |   8 +-
 app/src/components/SyncDetailsPanel.jsx    |   2 +-
 app/src/components/SyncStatusBadge.jsx     |  16 +-
 app/src/components/UploadData.jsx          |  18 +-
 app/src/index.css                          |  97 ++-
 app/src/lib/__tests__/designTokens.test.js |  78 +++
 app/tailwind.config.js                     |  15 +-
 app/vite.config.js                         |   4 +-
 docs/DESIGN_SYSTEM.md                      |  58 ++
 21 files changed, 801 insertions(+), 436 deletions(-)
 create mode 100644 app/src/lib/__tests__/designTokens.test.js
 create mode 100644 docs/DESIGN_SYSTEM.md

diff --git a/app/index.html b/app/index.html
index 91f9a27..afb160d 100644
--- a/app/index.html
+++ b/app/index.html
@@ -2,8 +2,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" type="image/svg+xml" href="/icons/icon-192.svg" />
+    <link rel="apple-touch-icon" href="/icons/apple-touch-icon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#014457" />
     <meta name="description" content="Fish yield and cost calculator for seafood producers, chefs, and wholesalers. Part of the Local Catch Network." />
     <title>Fish Cost Calculator — Local Catch Network</title>
     <link rel="preconnect" href="https://fonts.googleapis.com" />
diff --git a/app/src/App.jsx b/app/src/App.jsx
index 845caab..b9d6fc9 100644
--- a/app/src/App.jsx
+++ b/app/src/App.jsx
@@ -25,24 +25,24 @@ const NavBar = () => {
     const [syncPanelOpen, setSyncPanelOpen] = React.useState(false);
 
     const navLinkClass = ({ isActive }) =>
-        `text-sm font-medium transition-colors ${
+        `inline-flex min-h-[2.75rem] items-center text-sm font-medium transition-colors ${
             isActive
-                ? 'text-brand-yellow'
-                : 'text-white/75 hover:text-white'
+                ? 'text-brand-yellow underline decoration-2 underline-offset-8'
+                : 'text-white/85 hover:text-white'
         }`;
 
     return (
-        <nav className="bg-brand-teal sticky top-0 z-50 border-b border-white/10">
+        <nav aria-label="Main" className="focus-on-dark bg-brand-teal sticky top-0 z-50 border-b border-white/10">
             <div className="max-w-5xl mx-auto px-4 sm:px-6">
                 <div className="flex items-center justify-between h-14">
                     {/* Logo */}
-                    <Link to="/" className="flex items-center gap-2.5 shrink-0">
+                    <Link to="/" className="flex min-h-[2.75rem] items-center gap-2.5 shrink-0">
                         <div className="w-7 h-7 bg-white/15 rounded flex items-center justify-center">
                             <Fish className="text-white h-4 w-4" />
                         </div>
                         <div className="leading-none">
                             <span className="font-semibold text-white text-sm tracking-tight">Local Catch</span>
-                            <span className="hidden sm:inline text-white/50 text-xs ml-1.5">Fish Cost Calculator</span>
+                            <span className="hidden sm:inline text-white/75 text-xs ml-1.5">Fish Cost Calculator</span>
                         </div>
                     </Link>
 
@@ -70,10 +70,10 @@ const NavBar = () => {
                     <div className="flex items-center gap-2">
                         <button
                             onClick={toggleTheme}
-                            className="p-1.5 rounded text-white/60 hover:text-white hover:bg-white/10 transition-colors"
-                            aria-label="Toggle theme"
+                            className="flex h-11 w-11 items-center justify-center rounded-lg text-white/85 hover:text-white hover:bg-white/10 transition-colors"
+                            aria-label={theme === 'dark' ? 'Switch to light theme' : 'Switch to dark theme'}
                         >
-                            {theme === 'dark' ? <Sun size={16} /> : <Moon size={16} />}
+                            {theme === 'dark' ? <Sun size={20} /> : <Moon size={20} />}
                         </button>
 
                         {user && (
@@ -87,10 +87,10 @@ const NavBar = () => {
 
                         {user ? (
                             <div className="hidden md:flex items-center gap-3">
-                                <span className="text-white/60 text-xs">{user.username}</span>
+                                <span className="max-w-[10rem] truncate text-white/80 text-sm">{user.username}</span>
                                 <button
                                     onClick={signOut}
-                                    className="text-white/70 hover:text-white text-xs border border-white/25 px-2.5 py-1 rounded transition-colors"
+                                    className="min-h-[2.5rem] text-white/85 hover:text-white text-sm border border-white/40 px-3 rounded-lg transition-colors"
                                 >
                                     Sign out
                                 </button>
@@ -98,7 +98,7 @@ const NavBar = () => {
                         ) : (
                             <Link
                                 to="/login"
-                                className="hidden md:flex items-center gap-1.5 text-white/75 hover:text-white transition-colors text-sm"
+                                className="hidden md:flex min-h-[2.75rem] items-center gap-1.5 text-white/85 hover:text-white transition-colors text-sm"
                             >
                                 <UserCircle className="h-4 w-4" />
                                 Sign in
@@ -107,10 +107,12 @@ const NavBar = () => {
 
                         <button
                             onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
-                            className="md:hidden p-1.5 text-white/75 hover:text-white transition-colors"
-                            aria-label="Toggle mobile menu"
+                            className="md:hidden flex h-11 w-11 items-center justify-center rounded-lg text-white/85 hover:text-white hover:bg-white/10 transition-colors"
+                            aria-label={mobileMenuOpen ? 'Close menu' : 'Open menu'}
+                            aria-expanded={mobileMenuOpen}
+                            aria-controls="mobile-menu"
                         >
-                            {mobileMenuOpen ? <X className="h-5 w-5" /> : <Menu className="h-5 w-5" />}
+                            {mobileMenuOpen ? <X className="h-6 w-6" /> : <Menu className="h-6 w-6" />}
                         </button>
                     </div>
                 </div>
@@ -118,7 +120,7 @@ const NavBar = () => {
 
             {/* Mobile menu */}
             {mobileMenuOpen && (
-                <div className="md:hidden border-t border-white/10 bg-brand-teal">
+                <div id="mobile-menu" className="md:hidden border-t border-white/10 bg-brand-teal">
                     <div className="max-w-5xl mx-auto px-4 py-3 space-y-0.5">
                         {[
                             { to: '/', label: 'Calculator', end: true },
@@ -134,10 +136,10 @@ const NavBar = () => {
                                 end={end}
                                 onClick={() => setMobileMenuOpen(false)}
                                 className={({ isActive }) =>
-                                    `block px-3 py-2 rounded text-sm font-medium transition-colors ${
+                                    `block px-3 py-3 rounded-lg text-base font-medium transition-colors ${
                                         isActive
                                             ? 'bg-white/15 text-white'
-                                            : 'text-white/75 hover:text-white hover:bg-white/10'
+                                            : 'text-white/85 hover:text-white hover:bg-white/10'
                                     }`
                                 }
                             >
@@ -148,10 +150,10 @@ const NavBar = () => {
                         <div className="pt-2 mt-2 border-t border-white/10">
                             {user ? (
                                 <div className="flex items-center justify-between px-3 py-2">
-                                    <span className="text-white/60 text-sm">{user.username}</span>
+                                    <span className="text-white/80 text-base">{user.username}</span>
                                     <button
                                         onClick={() => { signOut(); setMobileMenuOpen(false); }}
-                                        className="text-white/70 hover:text-white text-sm"
+                                        className="min-h-[2.75rem] px-3 text-white/85 hover:text-white text-base"
                                     >
                                         Sign out
                                     </button>
@@ -160,9 +162,9 @@ const NavBar = () => {
                                 <NavLink
                                     to="/login"
                                     onClick={() => setMobileMenuOpen(false)}
-                                    className="flex items-center gap-2 px-3 py-2 text-sm text-white/75 hover:text-white transition-colors"
+                                    className="flex items-center gap-2 px-3 py-3 text-base text-white/85 hover:text-white transition-colors"
                                 >
-                                    <UserCircle size={16} /> Sign in
+                                    <UserCircle size={18} /> Sign in
                                 </NavLink>
                             )}
                         </div>
@@ -175,9 +177,15 @@ const NavBar = () => {
 
 function AppContent() {
     return (
-        <div className="min-h-screen bg-surface text-text-primary font-sans selection:bg-brand-terracotta/20 selection:text-brand-terracotta">
+        <div className="min-h-screen bg-surface text-text-primary font-sans selection:bg-brand-terracotta/20 selection:text-link">
+            <a
+                href="#main"
+                className="sr-only focus:not-sr-only focus:fixed focus:left-3 focus:top-3 focus:z-[60] focus:rounded-lg focus:bg-surface-raised focus:px-4 focus:py-2 focus:font-semibold focus:text-text-primary focus:shadow-lg"
+            >
+                Skip to main content
+            </a>
             <NavBar />
-            <main className="py-8 px-4">
+            <main id="main" tabIndex={-1} className="py-6 sm:py-8 px-4 focus:outline-none">
                 <Analytics />
                 <Suspense fallback={
                     <div className="flex items-center justify-center py-20 text-text-muted text-sm">Loading…</div>
@@ -198,9 +206,9 @@ function AppContent() {
                         } />
                         <Route path="*" element={
                             <div className="max-w-2xl mx-auto text-center mt-20 space-y-4">
-                                <p className="text-6xl font-bold text-brand-teal">404</p>
+                                <p className="text-6xl font-bold text-accent">404</p>
                                 <p className="text-text-secondary">Page not found.</p>
-                                <Link to="/" className="inline-block text-brand-terracotta hover:underline text-sm font-medium">
+                                <Link to="/" className="inline-block text-link hover:underline text-sm font-medium">
                                     Back to calculator
                                 </Link>
                             </div>
diff --git a/app/src/components/About.jsx b/app/src/components/About.jsx
index 0eb13eb..06f94d5 100644
--- a/app/src/components/About.jsx
+++ b/app/src/components/About.jsx
@@ -11,7 +11,7 @@ const About = () => {
                         <Fish className="h-10 w-10 text-white" />
                     </div>
                 </div>
-                <h1 className="text-3xl font-bold text-brand-teal mb-3">
+                <h1 className="text-3xl font-bold text-accent mb-3">
                     About Local Catch
                 </h1>
                 <p className="text-text-secondary max-w-xl mx-auto">
@@ -22,8 +22,8 @@ const About = () => {
             {/* Origin Story */}
             <div className="card p-8">
                 <div className="flex items-center gap-3 mb-5">
-                    <Anchor className="h-5 w-5 text-brand-terracotta" />
-                    <h2 className="text-xl font-semibold text-brand-teal">The Origin Story</h2>
+                    <Anchor className="h-5 w-5 text-link" />
+                    <h2 className="text-xl font-semibold text-accent">The Origin Story</h2>
                 </div>
 
                 <div className="space-y-4 text-text-secondary leading-relaxed text-sm">
@@ -34,7 +34,7 @@ const About = () => {
                     </p>
                     <p>
                         After some time away from active development, the project was{' '}
-                        <span className="text-brand-terracotta font-medium">reinvigorated
+                        <span className="text-link font-medium">reinvigorated
                         by a conversation on the listserv of the Local Catch network</span>. The discussions about
                         pricing transparency and the challenges fishers face when calculating fair prices for
                         their catch reminded me why this tool matters.
@@ -60,7 +60,7 @@ const About = () => {
                                 href="https://localcatch.org"
                                 target="_blank"
                                 rel="noopener noreferrer"
-                                className="inline-flex items-center gap-2 text-brand-terracotta hover:underline text-sm font-medium"
+                                className="inline-flex items-center gap-2 text-link hover:underline text-sm font-medium"
                             >
                                 Visit Local Catch Network
                                 <ExternalLink className="h-3 w-3" />
@@ -73,13 +73,13 @@ const About = () => {
             {/* Open Source */}
             <div className="card p-8">
                 <div className="flex items-center gap-3 mb-5">
-                    <Github className="h-5 w-5 text-brand-terracotta" />
-                    <h2 className="text-xl font-semibold text-brand-teal">Open Source & Free Forever</h2>
+                    <Github className="h-5 w-5 text-link" />
+                    <h2 className="text-xl font-semibold text-accent">Open Source & Free Forever</h2>
                 </div>
 
                 <p className="text-text-secondary leading-relaxed mb-6 text-sm">
                     This calculator is and will always be{' '}
-                    <span className="text-brand-teal font-medium">free and open source</span>.
+                    <span className="text-accent font-medium">free and open source</span>.
                     It's built for and by the fishing community. Whether you're a small-scale fisher calculating
                     prices for direct sales, or a processor working with multiple species, this tool is here to help.
                 </p>
@@ -103,7 +103,7 @@ const About = () => {
                     </div>
                 </div>
 
-                <h2 className="text-xl font-semibold text-brand-teal mb-3">Support Future Updates</h2>
+                <h2 className="text-xl font-semibold text-accent mb-3">Support Future Updates</h2>
 
                 <p className="text-text-secondary max-w-lg mx-auto mb-6 leading-relaxed text-sm">
                     If you find this tool useful and want to support continued development, consider buying me a coffee!
@@ -114,7 +114,7 @@ const About = () => {
                     href="https://buymeacoffee.com/pcswny"
                     target="_blank"
                     rel="noopener noreferrer"
-                    className="inline-flex items-center gap-2 bg-brand-terracotta hover:bg-brand-terracotta-light text-white font-semibold px-6 py-3 rounded-md transition"
+                    className="inline-flex items-center gap-2 bg-brand-cta hover:bg-brand-cta-hover text-white font-semibold px-6 py-3 rounded-md transition"
                 >
                     <Coffee className="h-4 w-4" />
                     Buy Me a Coffee
diff --git a/app/src/components/Calculator.jsx b/app/src/components/Calculator.jsx
index e2dc05e..dbe2b3b 100644
--- a/app/src/components/Calculator.jsx
+++ b/app/src/components/Calculator.jsx
@@ -1,22 +1,83 @@
-import React, { useState, useEffect, useMemo } from 'react';
+import React, { useState, useEffect, useLayoutEffect, useMemo, useRef, useId } from 'react';
+import { Link } from 'react-router-dom';
 import { ACRONYMS, FISH_DATA_V3, PROFILES_DATA } from '../data/fish_data_v3';
-import { Info, Calculator as CalcIcon, Save, HelpCircle, Download, ChevronRight } from 'lucide-react';
+import { Info, Calculator as CalcIcon, Save, HelpCircle, Download, ChevronRight, ChevronDown } from 'lucide-react';
 import { useAuth } from '../context/AuthContext';
 import { apiUrl } from '../config/api';
 
-const Tooltip = ({ text, children }) => {
+/**
+ * Help bubble that works for mouse (hover), keyboard (focus) and touch (tap).
+ * Hover-only tooltips are invisible on phones, which is where most people use this.
+ *
+ * The bubble is `position: fixed` and placed from the trigger's rect. Fixed elements never add
+ * scrollable overflow, so a bubble near the screen edge can't widen the page on mobile.
+ */
+const Tooltip = ({ text, label, iconOnly = false, children }) => {
   const [show, setShow] = useState(false);
+  const bubbleId = useId();
+  const wrapperRef = useRef(null);
+  const bubbleRef = useRef(null);
+  const lastPointer = useRef('mouse');
+
+  useLayoutEffect(() => {
+    const bubble = bubbleRef.current;
+    const trigger = wrapperRef.current;
+    if (!show || !bubble || !trigger) return;
+    const gap = 8;
+    const vv = window.visualViewport;
+    const minX = (vv?.offsetLeft ?? 0) + gap;
+    const maxX = (vv?.offsetLeft ?? 0) + (vv?.width ?? document.documentElement.clientWidth) - gap;
+    const t = trigger.getBoundingClientRect();
+    const { width, height } = bubble.getBoundingClientRect();
+    const left = Math.min(Math.max(t.left, minX), Math.max(minX, maxX - width));
+    // Prefer above the trigger; drop below when it would slide under the 56px sticky navbar
+    const fitsAbove = t.top - height - gap >= (vv?.offsetTop ?? 0) + 64;
+    bubble.style.left = `${left}px`;
+    bubble.style.top = `${fitsAbove ? t.top - height - gap : t.bottom + gap}px`;
+  }, [show]);
+
+  // Tapping elsewhere closes it (iOS never blurs a tapped button); scrolling would detach it
+  useEffect(() => {
+    if (!show) return undefined;
+    const close = (e) => {
+      if (e.type === 'scroll' || !wrapperRef.current?.contains(e.target)) setShow(false);
+    };
+    document.addEventListener('pointerdown', close);
+    window.addEventListener('scroll', close, true);
+    window.addEventListener('resize', close);
+    return () => {
+      document.removeEventListener('pointerdown', close);
+      window.removeEventListener('scroll', close, true);
+      window.removeEventListener('resize', close);
+    };
+  }, [show]);
+
   return (
-    <span
-      className="relative inline-block cursor-help"
-      onMouseEnter={() => setShow(true)}
-      onMouseLeave={() => setShow(false)}
-    >
-      {children}
+    <span ref={wrapperRef} className="inline-block">
+      <button
+        type="button"
+        aria-label={label}
+        aria-describedby={show ? bubbleId : undefined}
+        aria-expanded={show}
+        className={`cursor-help rounded text-left ${iconOnly ? '-m-2.5 p-2.5' : ''}`}
+        onPointerDown={(e) => { lastPointer.current = e.pointerType; }}
+        onPointerEnter={(e) => { if (e.pointerType === 'mouse') setShow(true); }}
+        onPointerLeave={(e) => { if (e.pointerType === 'mouse') setShow(false); }}
+        onFocus={(e) => { if (e.currentTarget.matches(':focus-visible')) setShow(true); }}
+        onBlur={() => setShow(false)}
+        onKeyDown={(e) => { if (e.key === 'Escape') setShow(false); }}
+        onClick={() => { if (lastPointer.current !== 'mouse') setShow((s) => !s); }}
+      >
+        {children}
+      </button>
       {show && (
-        <span className="absolute z-50 bottom-full left-1/2 -translate-x-1/2 mb-2 px-3 py-2 text-xs bg-surface-raised text-text-primary rounded-md shadow-lg whitespace-nowrap border border-line">
+        <span
+          id={bubbleId}
+          ref={bubbleRef}
+          role="tooltip"
+          className="fixed left-0 top-0 z-50 w-max max-w-[min(16rem,calc(100vw-2rem))] rounded-lg border border-line-strong bg-surface-raised px-3 py-2 text-sm font-normal leading-snug text-text-primary shadow-lg"
+        >
           {text}
-          <span className="absolute top-full left-1/2 -translate-x-1/2 border-4 border-transparent border-t-surface-raised"></span>
         </span>
       )}
     </span>
@@ -46,8 +107,8 @@ const TextWithTooltips = ({ text }) => {
     <>
       {parts.map((part, i) =>
         part.isAcronym ? (
-          <Tooltip key={i} text={part.tooltip}>
-            <span className="border-b border-dashed border-brand-terracotta/50 text-brand-teal dark:text-brand-yellow">{part.text}</span>
+          <Tooltip key={i} text={part.tooltip} label={`${part.text}: ${part.tooltip}`}>
+            <span className="border-b border-dashed border-brand-terracotta/60 font-medium text-accent">{part.text}</span>
           </Tooltip>
         ) : (
           <span key={i}>{part.text}</span>
@@ -59,17 +120,31 @@ const TextWithTooltips = ({ text }) => {
 
 const RangeButton = ({ active, onClick, label }) => (
   <button
+    type="button"
     onClick={onClick}
-    className={`px-3 py-1.5 text-xs rounded font-medium transition-colors ${
+    aria-pressed={active}
+    className={`min-h-[2.75rem] rounded-lg px-4 text-sm font-semibold transition-colors ${
       active
-        ? 'bg-brand-teal text-white'
-        : 'bg-surface border border-line text-text-secondary hover:text-text-primary hover:border-brand-teal/50'
+        ? 'bg-primary text-white'
+        : 'border border-line-strong bg-surface-raised text-text-primary hover:border-accent hover:text-accent'
     }`}
   >
     {label}
   </button>
 );
 
+const StepHeading = ({ number, children }) => (
+  <h2 className="flex items-center gap-2.5 text-lg font-semibold text-text-primary">
+    <span
+      aria-hidden="true"
+      className="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-primary text-sm font-bold text-white"
+    >
+      {number}
+    </span>
+    {children}
+  </h2>
+);
+
 const Calculator = () => {
   const { user, getAuthHeaders } = useAuth();
   const [mode, setMode] = useState('cost');
@@ -85,6 +160,7 @@ const Calculator = () => {
   const [shipping, _setShipping] = useState('');
   const [weightType, setWeightType] = useState('incoming');
   const [result, setResult] = useState(null);
+  const resultRef = useRef(null);
   const [saveStatus, setSaveStatus] = useState('');
   const [useRangeMin, setUseRangeMin] = useState(false);
   const [useRangeMax, setUseRangeMax] = useState(false);
@@ -241,6 +317,13 @@ const Calculator = () => {
     setSaveStatus('');
   };
 
+  // Bring a fresh result into view: on a phone it lands below the fold, under the keyboard
+  useEffect(() => {
+    if (result === null || !resultRef.current) return;
+    const reduceMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+    resultRef.current.scrollIntoView?.({ block: 'nearest', behavior: reduceMotion ? 'auto' : 'smooth' });
+  }, [result]);
+
   const handleSave = async () => {
     if (!user || !result) return;
     try {
@@ -302,310 +385,366 @@ const Calculator = () => {
 
   const canCalculate = species && toState;
 
+  const handleSubmit = (e) => {
+    e.preventDefault();
+    if (canCalculate) calculate();
+  };
+
   return (
-    <div className="max-w-2xl mx-auto space-y-5">
+    <div className="mx-auto max-w-2xl space-y-6">
       {/* Page header */}
-      <div>
-        <h1 className="text-xl font-semibold text-text-primary">Fish Cost Calculator</h1>
-        <p className="text-sm text-text-secondary mt-0.5">
-          Estimate processed cost per pound from raw input cost and yield data.
+      <header>
+        <h1 className="text-2xl font-bold tracking-tight text-text-primary sm:text-3xl">Fish Cost Calculator</h1>
+        <p className="mt-1 text-base text-text-secondary">
+          See what your fish really costs per pound after cutting and trimming.
         </p>
-      </div>
+      </header>
 
       {/* Main calculator card */}
       <div className="card p-5 sm:p-6">
         {/* Mode toggle */}
-        <div className="flex bg-surface rounded-md p-0.5 border border-line mb-6">
-          <button
-            onClick={() => { setMode('cost'); setResult(null); }}
-            className={`flex-1 py-2 px-3 rounded text-sm font-medium transition-colors ${
-              mode === 'cost'
-                ? 'bg-brand-teal text-white shadow-sm'
-                : 'text-text-secondary hover:text-text-primary'
-            }`}
-          >
-            Cost per Pound
-          </button>
-          <button
-            onClick={() => { setMode('weight'); setResult(null); }}
-            className={`flex-1 py-2 px-3 rounded text-sm font-medium transition-colors ${
-              mode === 'weight'
-                ? 'bg-brand-teal text-white shadow-sm'
-                : 'text-text-secondary hover:text-text-primary'
-            }`}
-          >
-            Required Input Weight
-          </button>
+        <div
+          role="group"
+          aria-label="What do you want to work out?"
+          className="mb-6 flex gap-1 rounded-xl border border-line-strong bg-surface p-1"
+        >
+          {[
+            { id: 'cost', label: 'Cost per pound' },
+            { id: 'weight', label: 'Pounds to buy' },
+          ].map(({ id, label }) => (
+            <button
+              key={id}
+              type="button"
+              aria-pressed={mode === id}
+              onClick={() => { setMode(id); setResult(null); }}
+              className={`min-h-[2.75rem] flex-1 rounded-lg px-2 text-sm font-semibold transition-colors sm:px-3 sm:text-base ${
+                mode === id
+                  ? 'bg-primary text-white shadow-sm'
+                  : 'text-text-secondary hover:text-text-primary'
+              }`}
+            >
+              {label}
+            </button>
+          ))}
         </div>
 
-        <div className="space-y-5">
-          {/* Species */}
-          <div>
-            <label className="form-label">Species</label>
-            {dataLoading ? (
-              <div className="form-select text-text-muted">Loading species data…</div>
-            ) : (
-              <select value={species} onChange={handleSpeciesChange} className="form-select">
-                <option value="">Select a species</option>
-                {speciesList.map(s => <option key={s} value={s}>{s}</option>)}
-              </select>
-            )}
-            {scientificName && (
-              <p className="mt-1 text-xs text-text-muted italic">{scientificName}</p>
-            )}
-          </div>
-
-          {/* From / To */}
-          <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
-            <div>
-              <label className="form-label flex items-center gap-1.5">
-                From State
-                <Tooltip text="Starting form of the fish (e.g., Round = whole fish as caught)">
-                  <HelpCircle size={13} className="text-text-muted" />
-                </Tooltip>
-              </label>
-              <select
-                value={fromState}
-                onChange={handleFromChange}
-                className="form-select"
-                disabled={!species}
-              >
-                <option value="">{species ? 'Select starting form' : '— select species first —'}</option>
-                {fromStates.map(f => <option key={f} value={f}>{f}</option>)}
-              </select>
-            </div>
+        <form onSubmit={handleSubmit} noValidate className="space-y-7">
+          {/* Step 1: the fish */}
+          <section className="space-y-4" aria-labelledby="step-fish">
+            <div id="step-fish"><StepHeading number="1">Your fish</StepHeading></div>
 
             <div>
-              <label className="form-label flex items-center gap-1.5">
-                To Product
-                <Tooltip text="Final form after processing">
-                  <HelpCircle size={13} className="text-text-muted" />
-                </Tooltip>
-              </label>
-              <select
-                value={toState}
-                onChange={handleToChange}
-                className="form-select"
-                disabled={!fromState}
-              >
-                <option value="">{fromState ? 'Select product form' : '— select from state first —'}</option>
-                {toStates.map(t => (
-                  <option key={t.to} value={t.to}>
-                    {t.to} ({t.yield}%{t.range ? `, ${t.range[0]}–${t.range[1]}%` : ''})
-                  </option>
-                ))}
-              </select>
-            </div>
-          </div>
-
-          {/* Conversion info */}
-          {currentConversion && (
-            <div className="bg-brand-teal/5 dark:bg-brand-teal/15 border border-brand-teal/20 rounded-md p-4 space-y-3">
-              <div className="flex items-center gap-2 text-xs font-semibold uppercase tracking-wide text-brand-teal dark:text-text-secondary">
-                <Info size={13} />
-                Conversion Details
-              </div>
-              <div className="flex flex-wrap gap-x-6 gap-y-1 text-sm">
-                <span>
-                  <span className="text-text-secondary">Conversion: </span>
-                  <TextWithTooltips text={currentConversion.from} />
-                  <ChevronRight size={12} className="inline mx-0.5 text-text-muted" />
-                  <TextWithTooltips text={currentConversion.to} />
-                </span>
-                <span>
-                  <span className="text-text-secondary">Avg yield: </span>
-                  <span className="font-semibold text-text-primary">{currentConversion.yield}%</span>
-                </span>
-                {currentConversion.range && (
-                  <span>
-                    <span className="text-text-secondary">Range: </span>
-                    <span className="text-text-primary">{currentConversion.range[0]}–{currentConversion.range[1]}%</span>
-                  </span>
-                )}
-              </div>
-
-              {currentConversion.range && (
-                <div className="flex gap-2 flex-wrap">
-                  <RangeButton
-                    active={useRangeMin}
-                    onClick={() => { setUseRangeMin(true); setUseRangeMax(false); }}
-                    label={`Min (${currentConversion.range[0]}%)`}
-                  />
-                  <RangeButton
-                    active={!useRangeMin && !useRangeMax}
-                    onClick={() => { setUseRangeMin(false); setUseRangeMax(false); }}
-                    label={`Avg (${currentConversion.yield}%)`}
-                  />
-                  <RangeButton
-                    active={useRangeMax}
-                    onClick={() => { setUseRangeMax(true); setUseRangeMin(false); }}
-                    label={`Max (${currentConversion.range[1]}%)`}
-                  />
-                </div>
-              )}
-            </div>
-          )}
-
-          {/* Species profile */}
-          {profile && (
-            <div className="text-sm space-y-1 text-text-secondary border-l-2 border-brand-terracotta/40 pl-3">
-              {profile.description && <p>{profile.description}</p>}
-              {profile.edible_portions && (
-                <p><span className="text-text-muted">Edible portions: </span>{profile.edible_portions}</p>
+              <label htmlFor="calc-species" className="form-label">Species</label>
+              {dataLoading ? (
+                <div className="form-select text-text-muted">Loading species data…</div>
+              ) : (
+                <select id="calc-species" value={species} onChange={handleSpeciesChange} className="form-select">
+                  <option value="">Choose a species</option>
+                  {speciesList.map(s => <option key={s} value={s}>{s}</option>)}
+                </select>
               )}
-              {profile.url && (
-                <a href={profile.url} target="_blank" rel="noreferrer" className="text-brand-terracotta hover:underline text-xs">
-                  Read more →
-                </a>
+              {scientificName && (
+                <p className="mt-1.5 text-sm italic text-text-secondary">{scientificName}</p>
               )}
             </div>
-          )}
-
-          <div className="section-divider" />
 
-          {/* Cost/weight + yield row */}
-          <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
-            {mode === 'cost' ? (
+            <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
               <div>
-                <label className="form-label">
-                  Cost per lb ({fromState || 'whole fish'})
-                </label>
-                <div className="relative">
-                  <span className="absolute left-3 top-1/2 -translate-y-1/2 text-text-muted text-sm">$</span>
-                  <input
-                    type="number"
-                    value={cost}
-                    onChange={(e) => setCost(e.target.value)}
-                    className="form-input pl-7"
-                    placeholder="0.00"
-                    inputMode="decimal"
-                  />
+                <div className="mb-1.5 flex items-center gap-1.5">
+                  <label htmlFor="calc-from" className="text-sm font-semibold text-text-primary">What you have</label>
+                  <Tooltip
+                    iconOnly
+                    label="Help: what you have"
+                    text="The form of the fish you're starting with. Round means the whole fish, as caught."
+                  >
+                    <HelpCircle size={18} className="text-text-secondary" aria-hidden="true" />
+                  </Tooltip>
                 </div>
+                <select
+                  id="calc-from"
+                  value={fromState}
+                  onChange={handleFromChange}
+                  className="form-select"
+                  disabled={!species}
+                >
+                  <option value="">{species ? 'Choose starting form' : 'Choose a species first'}</option>
+                  {fromStates.map(f => <option key={f} value={f}>{f}</option>)}
+                </select>
               </div>
-            ) : (
+
               <div>
-                <label className="form-label">
-                  Target output (lbs of {toState || 'product'})
-                </label>
-                <div className="relative">
-                  <input
-                    type="number"
-                    value={targetWeight}
-                    onChange={(e) => setTargetWeight(e.target.value)}
-                    className="form-input pr-10"
-                    placeholder="e.g. 100"
-                    inputMode="decimal"
-                  />
-                  <span className="absolute right-3 top-1/2 -translate-y-1/2 text-text-muted text-xs">lbs</span>
+                <div className="mb-1.5 flex items-center gap-1.5">
+                  <label htmlFor="calc-to" className="text-sm font-semibold text-text-primary">What you're making</label>
+                  <Tooltip
+                    iconOnly
+                    label="Help: what you're making"
+                    text="The finished cut or product you'll sell, such as a skinless fillet."
+                  >
+                    <HelpCircle size={18} className="text-text-secondary" aria-hidden="true" />
+                  </Tooltip>
                 </div>
+                <select
+                  id="calc-to"
+                  value={toState}
+                  onChange={handleToChange}
+                  className="form-select"
+                  disabled={!fromState}
+                >
+                  <option value="">{fromState ? 'Choose finished product' : 'Choose what you have first'}</option>
+                  {toStates.map(t => (
+                    <option key={t.to} value={t.to}>
+                      {t.to} ({t.yield}%{t.range ? `, ${t.range[0]}–${t.range[1]}%` : ''})
+                    </option>
+                  ))}
+                </select>
+              </div>
+            </div>
+
+            {/* Conversion info */}
+            {currentConversion && (
+              <div className="space-y-3 rounded-xl border border-brand-teal/25 bg-brand-teal/5 p-4 dark:bg-brand-teal/15">
+                <div className="flex items-center gap-2 text-sm font-semibold text-accent">
+                  <Info size={16} aria-hidden="true" />
+                  Yield for this cut
+                </div>
+                <div className="flex flex-wrap items-baseline gap-x-6 gap-y-1 text-base">
+                  <span>
+                    <TextWithTooltips text={currentConversion.from} />
+                    <ChevronRight size={14} className="mx-1 inline text-text-secondary" aria-label="to" />
+                    <TextWithTooltips text={currentConversion.to} />
+                  </span>
+                  <span>
+                    <span className="text-text-secondary">Average yield </span>
+                    <span className="font-bold tabular-nums text-text-primary">{currentConversion.yield}%</span>
+                  </span>
+                  {currentConversion.range && (
+                    <span>
+                      <span className="text-text-secondary">Typical range </span>
+                      <span className="tabular-nums text-text-primary">{currentConversion.range[0]}–{currentConversion.range[1]}%</span>
+                    </span>
+                  )}
+                </div>
+
+                {currentConversion.range && (
+                  <div>
+                    <p className="mb-2 text-sm text-text-secondary">
+                      Yield changes with fish size and cutting skill. Pick what fits your shop:
+                    </p>
+                    <div className="flex flex-wrap gap-2">
+                      <RangeButton
+                        active={useRangeMin}
+                        onClick={() => { setUseRangeMin(true); setUseRangeMax(false); }}
+                        label={`Low ${currentConversion.range[0]}%`}
+                      />
+                      <RangeButton
+                        active={!useRangeMin && !useRangeMax}
+                        onClick={() => { setUseRangeMin(false); setUseRangeMax(false); }}
+                        label={`Average ${currentConversion.yield}%`}
+                      />
+                      <RangeButton
+                        active={useRangeMax}
+                        onClick={() => { setUseRangeMax(true); setUseRangeMin(false); }}
+                        label={`High ${currentConversion.range[1]}%`}
+                      />
+                    </div>
+                  </div>
+                )}
               </div>
             )}
 
-            <div>
-              <label className="form-label">Yield percentage</label>
-              <div className="relative">
-                <input
-                  type="number"
-                  value={yieldPercent}
-                  onChange={(e) => { setYieldPercent(e.target.value); setUseRangeMin(false); setUseRangeMax(false); }}
-                  className="form-input pr-8"
-                  placeholder="0"
-                  inputMode="decimal"
-                />
-                <span className="absolute right-3 top-1/2 -translate-y-1/2 text-text-muted text-xs">%</span>
+            {/* Species profile */}
+            {profile && (
+              <div className="space-y-1 border-l-2 border-brand-terracotta/50 pl-3 text-sm text-text-secondary">
+                {profile.description && <p>{profile.description}</p>}
+                {profile.edible_portions && (
+                  <p><span className="font-semibold">Edible portions: </span>{profile.edible_portions}</p>
+                )}
+                {profile.url && (
+                  <a href={profile.url} target="_blank" rel="noreferrer" className="inline-block font-medium text-link underline">
+                    Read more →
+                  </a>
+                )}
               </div>
-              {yieldRange && (
-                <p className="mt-1 text-xs text-text-muted">
-                  Reported range: {yieldRange[0]}–{yieldRange[1]}%
-                </p>
+            )}
+          </section>
+
+          <div className="section-divider !my-0" />
+
+          {/* Step 2: the numbers */}
+          <section className="space-y-4" aria-labelledby="step-numbers">
+            <div id="step-numbers"><StepHeading number="2">Your numbers</StepHeading></div>
+
+            <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+              {mode === 'cost' ? (
+                <div>
+                  <label htmlFor="calc-cost" className="form-label">
+                    What you pay per lb
+                    <span className="font-normal text-text-secondary"> ({fromState || 'whole fish'})</span>
+                  </label>
+                  <div className="relative">
+                    <span aria-hidden="true" className="absolute left-3.5 top-1/2 -translate-y-1/2 text-base text-text-secondary">$</span>
+                    <input
+                      id="calc-cost"
+                      type="number"
+                      min="0"
+                      step="any"
+                      value={cost}
+                      onChange={(e) => setCost(e.target.value)}
+                      className="form-input pl-8 tabular-nums"
+                      placeholder="0.00"
+                      inputMode="decimal"
+                    />
+                  </div>
+                </div>
+              ) : (
+                <div>
+                  <label htmlFor="calc-target" className="form-label">
+                    Pounds of {toState || 'finished product'} you need
+                  </label>
+                  <div className="relative">
+                    <input
+                      id="calc-target"
+                      type="number"
+                      min="0"
+                      step="any"
+                      value={targetWeight}
+                      onChange={(e) => setTargetWeight(e.target.value)}
+                      className="form-input pr-12 tabular-nums"
+                      placeholder="e.g. 100"
+                      inputMode="decimal"
+                    />
+                    <span aria-hidden="true" className="absolute right-3.5 top-1/2 -translate-y-1/2 text-sm text-text-secondary">lbs</span>
+                  </div>
+                </div>
               )}
-            </div>
-          </div>
 
-          {/* Additional costs (cost mode only) */}
-          {mode === 'cost' && (
-            <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
               <div>
-                <label className="form-label">Processing cost (optional)</label>
+                <label htmlFor="calc-yield" className="form-label">Yield</label>
                 <div className="relative">
-                  <span className="absolute left-3 top-1/2 -translate-y-1/2 text-text-muted text-sm">$</span>
                   <input
+                    id="calc-yield"
                     type="number"
-                    value={processingCost}
-                    onChange={(e) => setProcessingCost(e.target.value)}
-                    className="form-input pl-7"
-                    placeholder="0.00"
+                    min="0"
+                    step="any"
+                    value={yieldPercent}
+                    onChange={(e) => { setYieldPercent(e.target.value); setUseRangeMin(false); setUseRangeMax(false); }}
+                    className="form-input pr-10 tabular-nums"
+                    placeholder="0"
                     inputMode="decimal"
+                    aria-describedby={yieldRange ? 'calc-yield-hint' : undefined}
                   />
+                  <span aria-hidden="true" className="absolute right-3.5 top-1/2 -translate-y-1/2 text-base text-text-secondary">%</span>
                 </div>
+                {yieldRange && (
+                  <p id="calc-yield-hint" className="mt-1.5 text-sm text-text-secondary">
+                    Typical range: {yieldRange[0]}–{yieldRange[1]}%
+                  </p>
+                )}
               </div>
+            </div>
 
-              <div>
-                <label className="form-label">Applied to weight</label>
-                <select
-                  value={weightType}
-                  onChange={(e) => setWeightType(e.target.value)}
-                  className="form-select"
-                >
-                  <option value="incoming">Incoming ({fromState || 'whole'})</option>
-                  <option value="outgoing">Outgoing ({toState || 'product'})</option>
-                </select>
+            {/* Additional costs (cost mode only) */}
+            {mode === 'cost' && (
+              <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+                <div>
+                  <label htmlFor="calc-processing" className="form-label">
+                    Processing cost per lb
+                    <span className="font-normal text-text-secondary"> (optional)</span>
+                  </label>
+                  <div className="relative">
+                    <span aria-hidden="true" className="absolute left-3.5 top-1/2 -translate-y-1/2 text-base text-text-secondary">$</span>
+                    <input
+                      id="calc-processing"
+                      type="number"
+                      min="0"
+                      step="any"
+                      value={processingCost}
+                      onChange={(e) => setProcessingCost(e.target.value)}
+                      className="form-input pl-8 tabular-nums"
+                      placeholder="0.00"
+                      inputMode="decimal"
+                    />
+                  </div>
+                </div>
+
+                {/* Only ask which weight it applies to once there is a processing cost */}
+                {processingCost !== '' && (
+                  <div>
+                    <label htmlFor="calc-weight-type" className="form-label">Processing is charged per lb of</label>
+                    <select
+                      id="calc-weight-type"
+                      value={weightType}
+                      onChange={(e) => setWeightType(e.target.value)}
+                      className="form-select"
+                    >
+                      <option value="incoming">Starting fish ({fromState || 'whole'})</option>
+                      <option value="outgoing">Finished product ({toState || 'product'})</option>
+                    </select>
+                  </div>
+                )}
               </div>
-            </div>
-          )}
+            )}
+          </section>
 
           {/* Calculate */}
-          <button
-            onClick={calculate}
-            disabled={!canCalculate}
-            className="btn-primary w-full"
-          >
-            {mode === 'cost' ? 'Calculate Cost per Pound' : 'Calculate Required Input Weight'}
-          </button>
-
-          {/* Result */}
+          <div>
+            <button
+              type="submit"
+              disabled={!canCalculate}
+              aria-describedby={canCalculate ? undefined : 'calc-hint'}
+              className="btn-primary w-full"
+            >
+              <CalcIcon size={20} aria-hidden="true" />
+              {mode === 'cost' ? 'Calculate cost per pound' : 'Calculate pounds to buy'}
+            </button>
+            {!canCalculate && (
+              <p id="calc-hint" className="mt-2 text-center text-sm text-text-secondary">
+                Choose a species, what you have, and what you're making to get started.
+              </p>
+            )}
+          </div>
+        </form>
+
+        {/* Result: announced to screen readers and scrolled into view when it appears */}
+        <div aria-live="polite" ref={resultRef} className="scroll-mt-20">
           {result !== null && (
-            <div className="mt-2 rounded-md border border-brand-teal/25 bg-brand-teal/5 dark:bg-brand-teal/10 p-5">
-              <p className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-1">
-                {mode === 'cost' ? `Cost per lb — ${toState}` : `Required ${fromState} input`}
+            <div className="mt-6 rounded-xl border-2 border-brand-teal bg-brand-teal/5 p-5 dark:border-accent dark:bg-brand-teal/15">
+              <p className="text-sm font-semibold text-text-secondary">
+                {mode === 'cost' ? `Your cost per lb of ${toState}` : `You need to buy (${fromState})`}
               </p>
-              <p className="text-4xl font-bold tracking-tight text-brand-teal dark:text-text-primary">
+              <p className="mt-1 text-5xl font-bold tabular-nums tracking-tight text-accent">
                 {mode === 'cost' ? `$${result.toFixed(2)}` : `${result.toFixed(1)} lbs`}
               </p>
-              <p className="mt-1.5 text-sm text-text-secondary">
+              <p className="mt-2 text-base text-text-secondary">
                 {mode === 'cost'
                   ? `At ${yieldPercent}% yield from ${fromState} to ${toState}`
-                  : `${result.toFixed(1)} lbs ${fromState} needed to yield ${targetWeight} lbs of ${toState}`
+                  : `${result.toFixed(1)} lbs of ${fromState} makes ${targetWeight} lbs of ${toState}`
                 }
               </p>
 
               {user ? (
-                <div className="mt-4 flex items-center gap-4 flex-wrap">
-                  <button
-                    onClick={handleSave}
-                    className="flex items-center gap-1.5 text-sm font-medium text-brand-terracotta hover:text-brand-terracotta-light transition-colors"
-                  >
-                    <Save size={15} /> Save calculation
+                <div className="mt-5 flex flex-wrap items-center gap-x-2 gap-y-1">
+                  <button type="button" onClick={handleSave} className="btn-secondary">
+                    <Save size={18} aria-hidden="true" /> Save calculation
                   </button>
-                  <button
-                    onClick={handleExport}
-                    className="flex items-center gap-1.5 text-sm text-text-secondary hover:text-text-primary transition-colors"
-                  >
-                    <Download size={15} /> Export CSV
+                  <button type="button" onClick={handleExport} className="btn-ghost">
+                    <Download size={16} aria-hidden="true" /> CSV
                   </button>
-                  <button
-                    onClick={handleExportXlsx}
-                    className="flex items-center gap-1.5 text-sm text-text-secondary hover:text-text-primary transition-colors"
-                  >
-                    <Download size={15} /> Export Excel
+                  <button type="button" onClick={handleExportXlsx} className="btn-ghost">
+                    <Download size={16} aria-hidden="true" /> Excel
                   </button>
                   {saveStatus && (
-                    <span className="text-xs text-text-muted">{saveStatus}</span>
+                    <span
+                      role="status"
+                      className={`text-sm font-semibold ${saveStatus === 'Saved!' ? 'text-success' : 'text-danger'}`}
+                    >
+                      {saveStatus}
+                    </span>
                   )}
                 </div>
               ) : (
-                <p className="mt-3 text-xs text-text-muted">
-                  <a href="/login" className="text-brand-terracotta hover:underline">Sign in</a> to save calculations
+                <p className="mt-4 text-sm text-text-secondary">
+                  Want to keep this? <Link to="/login" className="font-semibold text-link underline">Sign in</Link> to save your calculations.
                 </p>
               )}
             </div>
@@ -613,53 +752,54 @@ const Calculator = () => {
         </div>
       </div>
 
-      {/* Acronym reference */}
-      <div className="card p-5">
-        <h3 className="text-sm font-semibold text-text-primary mb-3 flex items-center gap-2">
-          <HelpCircle size={14} className="text-brand-terracotta" />
-          Acronym Reference
-        </h3>
-        <div className="grid grid-cols-2 sm:grid-cols-3 gap-1.5">
-          {Object.entries(ACRONYMS).slice(0, 9).map(([abbr, full]) => (
-            <div key={abbr} className="flex items-baseline gap-1.5 text-sm">
-              <span className="font-semibold text-brand-teal dark:text-brand-yellow shrink-0">{abbr}</span>
-              <span className="text-text-muted text-xs truncate">{full.split(' - ')[0]}</span>
+      {/* Abbreviation reference (collapsed: regulars know these, newcomers can open it) */}
+      <details className="card group">
+        <summary className="flex min-h-[3rem] cursor-pointer list-none items-center gap-2 rounded-xl px-5 py-3 text-base font-semibold text-text-primary [&::-webkit-details-marker]:hidden">
+          <HelpCircle size={18} className="text-link" aria-hidden="true" />
+          What do D/H-On, S/B and Round mean?
+          <ChevronDown size={18} className="ml-auto shrink-0 text-text-secondary transition-transform group-open:rotate-180" aria-hidden="true" />
+        </summary>
+        <dl className="grid grid-cols-1 gap-x-6 gap-y-3 border-t border-line-subtle px-5 py-4 sm:grid-cols-2">
+          {Object.entries(ACRONYMS).map(([abbr, full]) => (
+            <div key={abbr}>
+              <dt className="text-sm font-bold text-accent">{abbr}</dt>
+              <dd className="text-sm text-text-secondary">{full.split(' - ')[0]}</dd>
             </div>
           ))}
-        </div>
-      </div>
+        </dl>
+      </details>
 
       {/* Community recent calculations */}
       {publicHistory.length > 0 && (
-        <div className="card p-5">
-          <h3 className="text-sm font-semibold text-text-primary mb-4 flex items-center gap-2">
-            <CalcIcon size={14} className="text-brand-terracotta" />
-            Recent Community Calculations
-          </h3>
-          <div className="divide-y divide-line-subtle">
+        <section className="card p-5" aria-labelledby="community-calcs">
+          <h2 id="community-calcs" className="mb-4 flex items-center gap-2 text-base font-semibold text-text-primary">
+            <CalcIcon size={18} className="text-link" aria-hidden="true" />
+            Recent community calculations
+          </h2>
+          <ul className="divide-y divide-line-subtle">
             {publicHistory.slice(0, 8).map((calc) => (
-              <div key={calc.id} className="flex items-center justify-between py-2.5 first:pt-0 last:pb-0">
+              <li key={calc.id} className="flex items-center justify-between gap-4 py-3 first:pt-0 last:pb-0">
                 <div className="min-w-0">
-                  <p className="text-sm font-medium text-text-primary truncate">{calc.name || calc.species}</p>
-                  <p className="text-xs text-text-muted mt-0.5">{calc.product} · {calc.yield}% yield</p>
+                  <p className="break-words text-base font-medium text-text-primary">{calc.name || calc.species}</p>
+                  <p className="mt-0.5 text-sm text-text-secondary">{calc.product} · {calc.yield}% yield</p>
                 </div>
-                <div className="text-right ml-4 shrink-0">
-                  <p className="text-sm font-semibold text-brand-teal dark:text-brand-yellow">
+                <div className="shrink-0 text-right">
+                  <p className="text-base font-bold tabular-nums text-accent">
                     ${parseFloat(calc.result).toFixed(2)}/lb
                   </p>
-                  <p className="text-xs text-text-muted">
+                  <p className="text-sm text-text-secondary">
                     {new Date(calc.date).toLocaleDateString()}
                   </p>
                 </div>
-              </div>
+              </li>
             ))}
-          </div>
+          </ul>
           {!user && (
-            <p className="mt-4 text-xs text-text-muted text-center border-t border-line-subtle pt-3">
-              <a href="/login" className="text-brand-terracotta hover:underline">Sign in</a> to save your own calculations
+            <p className="mt-4 border-t border-line-subtle pt-3 text-center text-sm text-text-secondary">
+              <Link to="/login" className="font-semibold text-link underline">Sign in</Link> to save your own calculations
             </p>
           )}
-        </div>
+        </section>
       )}
     </div>
   );
diff --git a/app/src/components/CommunityData.jsx b/app/src/components/CommunityData.jsx
index 240629a..93adb24 100644
--- a/app/src/components/CommunityData.jsx
+++ b/app/src/components/CommunityData.jsx
@@ -57,8 +57,8 @@ const CommunityData = () => {
         <div className="max-w-5xl mx-auto px-4 py-8">
             <div className="flex items-center justify-between mb-8 flex-wrap gap-4">
                 <div>
-                    <h1 className="text-2xl font-bold text-brand-teal flex items-center gap-3">
-                        <Users className="text-brand-terracotta" size={24} />
+                    <h1 className="text-2xl font-bold text-accent flex items-center gap-3">
+                        <Users className="text-link" size={24} />
                         Community Data Pool
                     </h1>
                     <p className="text-text-secondary mt-1 text-sm">
@@ -75,7 +75,7 @@ const CommunityData = () => {
                         Download CSV
                     </button>
                     {downloadError && (
-                        <p className="mt-1 text-xs text-red-500">{downloadError}</p>
+                        <p className="mt-1 text-xs text-danger">{downloadError}</p>
                     )}
                 </div>
             </div>
@@ -101,7 +101,7 @@ const CommunityData = () => {
 
             <div className="card overflow-hidden">
                 <div className="p-4 border-b border-line flex items-center justify-between">
-                    <h2 className="text-base font-semibold text-brand-teal">Shared Yield Data</h2>
+                    <h2 className="text-base font-semibold text-accent">Shared Yield Data</h2>
                     {search && (
                         <span className="text-sm text-text-secondary">{filtered.length} of {data.length} results</span>
                     )}
@@ -134,7 +134,7 @@ const CommunityData = () => {
                                     >
                                         <td className="p-4 text-text-primary font-medium">{row.species}</td>
                                         <td className="p-4 text-text-secondary">{row.product}</td>
-                                        <td className="p-4 text-right text-brand-teal font-semibold">{row.yield}%</td>
+                                        <td className="p-4 text-right text-accent font-semibold">{row.yield}%</td>
                                         <td className="p-4 text-text-secondary">
                                             {row.contributor || 'Anonymous'}
                                             {row.organization && (
@@ -152,7 +152,7 @@ const CommunityData = () => {
 
             <p className="mt-6 text-sm text-text-secondary text-center">
                 Want to contribute?{' '}
-                <Link to="/login" className="text-brand-teal hover:underline">Log in</Link>,
+                <Link to="/login" className="text-accent hover:underline">Log in</Link>,
                 add yield data in <strong>My Data</strong>, then toggle the share icon.
             </p>
         </div>
diff --git a/app/src/components/ContributorProfile.jsx b/app/src/components/ContributorProfile.jsx
index 80d13db..7c3117c 100644
--- a/app/src/components/ContributorProfile.jsx
+++ b/app/src/components/ContributorProfile.jsx
@@ -96,11 +96,11 @@ const ContributorProfile = () => {
                 <div className="bg-surface p-8 rounded-full">
                     <User size={40} className="text-text-secondary" />
                 </div>
-                <h2 className="text-xl font-bold text-brand-teal">Login Required</h2>
+                <h2 className="text-xl font-bold text-accent">Login Required</h2>
                 <p className="text-text-secondary max-w-md text-sm">
                     You need to be logged in to create a contributor profile.
                 </p>
-                <Link to="/login" className="text-brand-terracotta hover:underline text-sm font-medium">
+                <Link to="/login" className="text-link hover:underline text-sm font-medium">
                     Go to Login
                 </Link>
             </div>
@@ -110,8 +110,8 @@ const ContributorProfile = () => {
     return (
         <div className="max-w-2xl mx-auto px-4 py-8">
             <div className="mb-6">
-                <h1 className="text-2xl font-bold text-brand-teal flex items-center gap-3">
-                    <User className="text-brand-terracotta" size={22} />
+                <h1 className="text-2xl font-bold text-accent flex items-center gap-3">
+                    <User className="text-link" size={22} />
                     Contributor Profile
                 </h1>
                 <p className="text-text-secondary mt-1 text-sm">
diff --git a/app/src/components/DataManagement.jsx b/app/src/components/DataManagement.jsx
index 696d3c7..1acffbf 100644
--- a/app/src/components/DataManagement.jsx
+++ b/app/src/components/DataManagement.jsx
@@ -99,7 +99,7 @@ const DataManagement = () => {
         <div className="bg-surface p-8 rounded-full">
           <Database size={40} className="text-text-secondary" />
         </div>
-        <h2 className="text-xl font-bold text-brand-teal">Login Required</h2>
+        <h2 className="text-xl font-bold text-accent">Login Required</h2>
         <p className="text-text-secondary max-w-md text-sm">
           You need to be logged in to manage your custom yield data.
         </p>
@@ -114,13 +114,13 @@ const DataManagement = () => {
     <div className="max-w-4xl mx-auto px-4 py-8">
       <div className="flex items-center justify-between mb-8 flex-wrap gap-4">
         <div>
-          <h1 className="text-2xl font-bold text-brand-teal flex items-center gap-3">
-            <Database className="text-brand-terracotta" size={22} />
+          <h1 className="text-2xl font-bold text-accent flex items-center gap-3">
+            <Database className="text-link" size={22} />
             Manage Your Data
           </h1>
           <p className="text-text-secondary mt-1 text-sm">
             Add, edit, or delete your custom yield data •{' '}
-            <Link to="/profile" className="text-brand-terracotta hover:underline">Edit Contributor Profile</Link>
+            <Link to="/profile" className="text-link hover:underline">Edit Contributor Profile</Link>
           </p>
         </div>
 
@@ -165,7 +165,7 @@ const DataManagement = () => {
       {/* Add/Edit Form */}
       {showForm && (
         <div className="card p-6 mb-8">
-          <h2 className="text-lg font-semibold text-brand-teal mb-4">
+          <h2 className="text-lg font-semibold text-accent mb-4">
             {editingId ? 'Edit Entry' : 'Add New Entry'}
           </h2>
 
@@ -246,7 +246,7 @@ const DataManagement = () => {
       {/* Saved Calculations */}
       <div className="card overflow-hidden mb-8">
         <div className="p-4 border-b border-line">
-          <h2 className="text-base font-semibold text-brand-teal">Saved Calculations</h2>
+          <h2 className="text-base font-semibold text-accent">Saved Calculations</h2>
           <p className="text-xs text-text-secondary mt-0.5">
             Publish a calculation to share it anonymously on the community feed.
           </p>
@@ -267,7 +267,7 @@ const DataManagement = () => {
                   <p className="text-text-primary font-medium flex items-center gap-2 text-sm">
                     {calc.name || `${calc.species} — ${calc.product}`}
                     {calc.is_private === false ? (
-                      <span className="text-xs bg-brand-teal/10 text-brand-teal border border-brand-teal/20 px-2 py-0.5 rounded-full flex items-center gap-1">
+                      <span className="text-xs bg-brand-teal/10 text-accent border border-brand-teal/20 px-2 py-0.5 rounded-full flex items-center gap-1">
                         <Globe size={10} />Public
                       </span>
                     ) : (
@@ -277,7 +277,7 @@ const DataManagement = () => {
                     )}
                   </p>
                   <p className="text-sm text-text-secondary">
-                    {calc.species} · {calc.product} → <span className="text-brand-teal font-medium">${Number(calc.result).toFixed(2)}/lb</span>
+                    {calc.species} · {calc.product} → <span className="text-accent font-medium">${Number(calc.result).toFixed(2)}/lb</span>
                   </p>
                 </div>
                 <div className="flex gap-1">
@@ -294,7 +294,7 @@ const DataManagement = () => {
                     ) : (
                       <button
                         onClick={() => requestPublish(calc)}
-                        className="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded border border-brand-teal/40 text-brand-teal hover:bg-brand-teal/10 transition"
+                        className="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded border border-brand-teal/40 text-accent hover:bg-brand-teal/10 transition"
                         title="Publish to community feed"
                       >
                         <Globe size={13} />
@@ -312,7 +312,7 @@ const DataManagement = () => {
       {/* Data List */}
       <div className="card overflow-hidden">
         <div className="p-4 border-b border-line">
-          <h2 className="text-base font-semibold text-brand-teal">Your Custom Data</h2>
+          <h2 className="text-base font-semibold text-accent">Your Custom Data</h2>
         </div>
 
         {!dataLoaded ? (
@@ -330,7 +330,7 @@ const DataManagement = () => {
                   <p className="text-text-primary font-medium flex items-center gap-2 text-sm">
                     {item.species}
                     {item.is_shared ? (
-                      <span className="text-xs bg-brand-teal/10 text-brand-teal border border-brand-teal/20 px-2 py-0.5 rounded-full">Shared</span>
+                      <span className="text-xs bg-brand-teal/10 text-accent border border-brand-teal/20 px-2 py-0.5 rounded-full">Shared</span>
                     ) : null}
                     {item.syncStatus === 'local' || item.syncStatus === 'pending-delete' ? (
                       <span className="text-xs text-yellow-500 border border-yellow-300 bg-yellow-50 dark:bg-yellow-900/20 px-1.5 py-0.5 rounded-full">
@@ -339,7 +339,7 @@ const DataManagement = () => {
                     ) : null}
                   </p>
                   <p className="text-sm text-text-secondary">
-                    {item.product} → <span className="text-brand-teal font-medium">{item.yield}%</span>
+                    {item.product} → <span className="text-accent font-medium">{item.yield}%</span>
                     {item.source && <span className="ml-2 text-text-muted">({item.source})</span>}
                   </p>
                 </div>
@@ -347,7 +347,7 @@ const DataManagement = () => {
                   {item.serverId && (
                     <button
                       onClick={() => handleToggleShare(item)}
-                      className={`p-2 rounded transition ${item.is_shared ? 'text-brand-teal hover:text-text-secondary' : 'text-text-secondary hover:text-brand-teal'}`}
+                      className={`p-2 rounded transition ${item.is_shared ? 'text-accent hover:text-text-secondary' : 'text-text-secondary hover:text-accent'}`}
                       title={item.is_shared ? 'Remove from community' : 'Share with community'}
                     >
                       {item.is_shared ? <EyeOff size={16} /> : <Share2 size={16} />}
@@ -355,14 +355,14 @@ const DataManagement = () => {
                   )}
                   <button
                     onClick={() => handleEdit(item)}
-                    className="p-2 rounded text-text-secondary hover:text-brand-teal transition"
+                    className="p-2 rounded text-text-secondary hover:text-accent transition"
                     title="Edit"
                   >
                     <Edit2 size={16} />
                   </button>
                   <button
                     onClick={() => handleDelete(item.id)}
-                    className="p-2 rounded text-text-secondary hover:text-red-500 transition"
+                    className="p-2 rounded text-text-secondary hover:text-danger transition"
                     title="Delete"
                   >
                     <Trash2 size={16} />
diff --git a/app/src/components/DataTransparency.jsx b/app/src/components/DataTransparency.jsx
index 6a41fec..9060bb5 100644
--- a/app/src/components/DataTransparency.jsx
+++ b/app/src/components/DataTransparency.jsx
@@ -22,7 +22,7 @@ const DataTransparency = () => {
                         <BookOpen className="h-8 w-8 text-white" />
                     </div>
                 </div>
-                <h1 className="text-3xl font-bold text-brand-teal mb-3">Data Sources & Methodology</h1>
+                <h1 className="text-3xl font-bold text-accent mb-3">Data Sources & Methodology</h1>
                 <p className="text-text-secondary max-w-xl mx-auto text-sm">
                     Transparency in data sourcing for accurate yield calculations
                 </p>
@@ -31,14 +31,14 @@ const DataTransparency = () => {
             {/* Primary Source */}
             <div className="card p-8">
                 <div className="flex items-center gap-3 mb-5">
-                    <FileText className="h-5 w-5 text-brand-terracotta" />
-                    <h2 className="text-xl font-semibold text-brand-teal">Primary Data Source</h2>
+                    <FileText className="h-5 w-5 text-link" />
+                    <h2 className="text-xl font-semibold text-accent">Primary Data Source</h2>
                 </div>
 
                 <div className="bg-surface border border-line rounded p-6 mb-6">
                     <h3 className="text-lg font-bold text-text-primary mb-2">{DATA_SOURCE.title}</h3>
                     <p className="text-text-secondary mb-4 text-sm">
-                        <span className="text-brand-teal font-medium">Publication:</span> {DATA_SOURCE.publication}
+                        <span className="text-accent font-medium">Publication:</span> {DATA_SOURCE.publication}
                     </p>
                     <div className="grid md:grid-cols-2 gap-4 text-sm">
                         <div>
@@ -74,23 +74,23 @@ const DataTransparency = () => {
             {/* Methodology */}
             <div className="card p-8">
                 <div className="flex items-center gap-3 mb-5">
-                    <Database className="h-5 w-5 text-brand-terracotta" />
-                    <h2 className="text-xl font-semibold text-brand-teal">Methodology Notes</h2>
+                    <Database className="h-5 w-5 text-link" />
+                    <h2 className="text-xl font-semibold text-accent">Methodology Notes</h2>
                 </div>
 
                 <div className="space-y-4 text-sm">
                     <div className="bg-surface border border-line rounded p-4">
-                        <h4 className="font-semibold text-brand-teal mb-2">Average Yields</h4>
+                        <h4 className="font-semibold text-accent mb-2">Average Yields</h4>
                         <p className="text-text-secondary">Yields represent high quality, properly handled fresh fish and shellfish in good physiological condition. If fish condition is abnormal (post-spawning or starving state), actual yields may differ.</p>
                     </div>
 
                     <div className="bg-surface border border-line rounded p-4">
-                        <h4 className="font-semibold text-brand-teal mb-2">Yield Ranges</h4>
+                        <h4 className="font-semibold text-accent mb-2">Yield Ranges</h4>
                         <p className="text-text-secondary">Ranges represent typical variations found within fish populations during the year. Many factors including handling, processing conditions, filleting skills, and refrigeration affect actual yields.</p>
                     </div>
 
                     <div className="bg-surface border border-line rounded p-4">
-                        <h4 className="font-semibold text-brand-teal mb-2">Smoked Products</h4>
+                        <h4 className="font-semibold text-accent mb-2">Smoked Products</h4>
                         <p className="text-text-secondary">Smoked fish yields were calculated using an average <strong>15% weight loss</strong> during salting/brining and <strong>10%</strong> during the smoking process.</p>
                     </div>
                 </div>
@@ -98,14 +98,14 @@ const DataTransparency = () => {
 
             {/* Acronym Glossary */}
             <div className="card p-8">
-                <h2 className="text-xl font-semibold text-brand-teal mb-5 flex items-center gap-3">
-                    <span className="text-brand-terracotta font-bold">A–Z</span> Acronym Glossary
+                <h2 className="text-xl font-semibold text-accent mb-5 flex items-center gap-3">
+                    <span className="text-link font-bold">A–Z</span> Acronym Glossary
                 </h2>
 
                 <div className="grid md:grid-cols-2 gap-3">
                     {Object.entries(ACRONYMS).map(([abbr, definition]) => (
                         <div key={abbr} className="bg-surface rounded p-4">
-                            <span className="text-brand-teal font-bold text-base">{abbr}</span>
+                            <span className="text-accent font-bold text-base">{abbr}</span>
                             <p className="text-text-secondary text-sm mt-1">{definition}</p>
                         </div>
                     ))}
@@ -117,7 +117,7 @@ const DataTransparency = () => {
                 <div className="card p-8">
                     <div className="flex items-center gap-3 mb-5">
                         <AlertCircle className="h-5 w-5 text-brand-yellow" />
-                        <h2 className="text-xl font-semibold text-brand-teal">Data Quality Notes</h2>
+                        <h2 className="text-xl font-semibold text-accent">Data Quality Notes</h2>
                     </div>
 
                     <p className="text-text-secondary mb-4 text-sm">
@@ -129,7 +129,7 @@ const DataTransparency = () => {
                             <div key={i} className="bg-brand-yellow/10 border border-brand-yellow/30 rounded p-4">
                                 <p className="text-text-primary font-medium text-sm">{item.species}</p>
                                 <p className="text-sm text-text-secondary">
-                                    <span className="text-brand-terracotta">{item.field}:</span> {item.note}
+                                    <span className="text-link">{item.field}:</span> {item.note}
                                 </p>
                             </div>
                         ))}
@@ -140,8 +140,8 @@ const DataTransparency = () => {
             {/* User Data */}
             <div className="card p-8">
                 <div className="flex items-center gap-3 mb-5">
-                    <Users className="h-5 w-5 text-brand-terracotta" />
-                    <h2 className="text-xl font-semibold text-brand-teal">User-Contributed Data</h2>
+                    <Users className="h-5 w-5 text-link" />
+                    <h2 className="text-xl font-semibold text-accent">User-Contributed Data</h2>
                 </div>
 
                 <p className="text-text-secondary mb-4 text-sm">
@@ -150,15 +150,15 @@ const DataTransparency = () => {
 
                 <ul className="space-y-2 text-text-secondary text-sm">
                     <li className="flex items-start gap-2">
-                        <span className="text-brand-terracotta mt-1">•</span>
+                        <span className="text-link mt-1">•</span>
                         <span>Displayed separately from source data in the calculator</span>
                     </li>
                     <li className="flex items-start gap-2">
-                        <span className="text-brand-terracotta mt-1">•</span>
+                        <span className="text-link mt-1">•</span>
                         <span>Associated with the user's account</span>
                     </li>
                     <li className="flex items-start gap-2">
-                        <span className="text-brand-terracotta mt-1">•</span>
+                        <span className="text-link mt-1">•</span>
                         <span>Can be edited or deleted by the contributing user</span>
                     </li>
                 </ul>
@@ -169,7 +169,7 @@ const DataTransparency = () => {
                 <div className="card p-8">
                     <div className="flex items-center gap-3 mb-5">
                         <Award className="h-5 w-5 text-brand-yellow" />
-                        <h2 className="text-xl font-semibold text-brand-teal">Community Contributors</h2>
+                        <h2 className="text-xl font-semibold text-accent">Community Contributors</h2>
                     </div>
 
                     <p className="text-text-secondary mb-6 text-sm">
@@ -188,7 +188,7 @@ const DataTransparency = () => {
                                             {contributor.display_name}
                                         </h3>
                                         {contributor.organization && (
-                                            <p className="text-sm text-brand-terracotta mt-1">
+                                            <p className="text-sm text-link mt-1">
                                                 {contributor.organization}
                                             </p>
                                         )}
@@ -199,7 +199,7 @@ const DataTransparency = () => {
                                         )}
                                     </div>
                                     <div className="text-right ml-4">
-                                        <p className="text-2xl font-bold text-brand-teal">
+                                        <p className="text-2xl font-bold text-accent">
                                             {contributor.contribution_count}
                                         </p>
                                         <p className="text-xs text-text-secondary">
diff --git a/app/src/components/Login.jsx b/app/src/components/Login.jsx
index 7a63583..999293a 100644
--- a/app/src/components/Login.jsx
+++ b/app/src/components/Login.jsx
@@ -92,9 +92,9 @@ const Login = () => {
     return (
       <div className="flex items-center justify-center min-h-[80vh]">
         <div className="card w-full max-w-md p-8 text-center space-y-4">
-          <h2 className="text-2xl font-bold text-brand-teal">Check your email</h2>
+          <h2 className="text-2xl font-bold text-accent">Check your email</h2>
           {verificationFailed ? (
-            <p className="text-red-500 text-sm">
+            <p className="text-danger text-sm">
               Your account was created but we couldn&apos;t send the verification email to <strong>{email}</strong>. Use the button below to try again.
             </p>
           ) : (
@@ -102,7 +102,7 @@ const Login = () => {
               We sent a verification link to <strong>{email}</strong>. Click it to activate your account, then sign in.
             </p>
           )}
-          {error && <p className="text-red-500 text-sm">{error}</p>}
+          {error && <p className="text-danger text-sm">{error}</p>}
           <button
             onClick={handleResend}
             className="btn-primary w-full"
@@ -111,7 +111,7 @@ const Login = () => {
           </button>
           <button
             onClick={() => { setVerificationSent(false); setVerificationFailed(false); setIsRegister(false); setError(''); }}
-            className="text-brand-terracotta hover:underline text-sm"
+            className="text-link hover:underline text-sm"
           >
             Back to sign in
           </button>
@@ -123,7 +123,7 @@ const Login = () => {
   return (
     <div className="flex items-center justify-center min-h-[80vh]">
       <div className="card w-full max-w-md p-8">
-        <h2 className="text-2xl font-bold mb-6 text-center text-brand-teal">
+        <h2 className="text-2xl font-bold mb-6 text-center text-accent">
           {isRegister ? 'Create Account' : 'Welcome Back'}
         </h2>
 
@@ -133,10 +133,11 @@ const Login = () => {
               {isRegister ? 'Email' : 'Email or Username'}
             </label>
             <div className="relative">
-              <Mail className="absolute left-3 top-3 text-brand-terracotta w-4 h-4" />
+              <Mail aria-hidden="true" className="absolute left-3.5 top-1/2 -translate-y-1/2 text-link w-4 h-4" />
               <input
                 id="email"
                 type={isRegister ? 'email' : 'text'}
+                autoComplete={isRegister ? 'email' : 'username'}
                 value={email}
                 onChange={(e) => setEmail(e.target.value)}
                 className="form-input pl-10"
@@ -146,11 +147,13 @@ const Login = () => {
           </div>
 
           <div>
-            <label className="form-label">Password</label>
+            <label htmlFor="password" className="form-label">Password</label>
             <div className="relative">
-              <Lock className="absolute left-3 top-3 text-brand-terracotta w-4 h-4" />
+              <Lock aria-hidden="true" className="absolute left-3.5 top-1/2 -translate-y-1/2 text-link w-4 h-4" />
               <input
+                id="password"
                 type="password"
+                autoComplete={isRegister ? 'new-password' : 'current-password'}
                 value={password}
                 onChange={(e) => setPassword(e.target.value)}
                 className="form-input pl-10"
@@ -159,7 +162,7 @@ const Login = () => {
             </div>
           </div>
 
-          {error && <p className="text-red-500 text-sm text-center">{error}</p>}
+          {error && <p className="text-danger text-sm text-center">{error}</p>}
 
           <button type="submit" className="btn-primary w-full flex items-center justify-center gap-2">
             {isRegister ? 'Sign Up' : 'Sign In'} <ArrowRight size={18} />
@@ -193,7 +196,7 @@ const Login = () => {
         <div className="mt-5 text-center">
           <button
             onClick={() => { setIsRegister(!isRegister); setError(''); setVerificationSent(false); setVerificationFailed(false); }}
-            className="text-text-secondary hover:text-brand-terracotta text-sm transition"
+            className="text-text-secondary hover:text-link text-sm transition"
           >
             {isRegister ? "Already have an account? Sign In" : "Need an account? Sign Up"}
           </button>
diff --git a/app/src/components/PreviewPublishModal.jsx b/app/src/components/PreviewPublishModal.jsx
index 1801d65..6337cdf 100644
--- a/app/src/components/PreviewPublishModal.jsx
+++ b/app/src/components/PreviewPublishModal.jsx
@@ -62,7 +62,7 @@ export default function PreviewPublishModal({ calc, loading, onConfirm, onCancel
         className="bg-surface border border-border rounded-xl shadow-xl p-6 max-w-sm w-full mx-4"
       >
         <div className="flex items-center gap-2 mb-1">
-          <Globe size={18} className="text-brand-teal" />
+          <Globe size={18} className="text-accent" />
           <h2 id="preview-publish-title" className="text-base font-semibold text-text-primary">
             Publish calculation
           </h2>
diff --git a/app/src/components/RecoveryModal.jsx b/app/src/components/RecoveryModal.jsx
index 58eaaf7..c4b00bd 100644
--- a/app/src/components/RecoveryModal.jsx
+++ b/app/src/components/RecoveryModal.jsx
@@ -30,7 +30,7 @@ export default function RecoveryModal({ calcs, yields, isAuthenticated, assignin
     >
       <div className="bg-surface-raised rounded-lg shadow-xl max-w-md w-full p-6 space-y-4">
         <div className="flex items-start gap-3">
-          <Archive size={22} className="text-brand-terracotta mt-0.5 shrink-0" />
+          <Archive size={22} className="text-link mt-0.5 shrink-0" />
           <div>
             <h2 id="recovery-title" className="text-lg font-bold text-text-primary">
               Recovered data from a previous session
@@ -63,7 +63,7 @@ export default function RecoveryModal({ calcs, yields, isAuthenticated, assignin
               <button
                 onClick={onDiscard}
                 disabled={assigning}
-                className="px-4 py-2 text-sm font-medium text-red-500 hover:text-red-400 border border-line rounded transition flex items-center gap-1.5 disabled:opacity-50"
+                className="px-4 py-2 text-sm font-medium text-danger hover:text-red-400 border border-line rounded transition flex items-center gap-1.5 disabled:opacity-50"
               >
                 <Trash2 size={14} />
                 Discard
@@ -92,7 +92,7 @@ export default function RecoveryModal({ calcs, yields, isAuthenticated, assignin
               </button>
               <button
                 onClick={onDiscard}
-                className="px-4 py-2 text-sm font-medium text-red-500 hover:text-red-400 border border-line rounded transition flex items-center gap-1.5"
+                className="px-4 py-2 text-sm font-medium text-danger hover:text-red-400 border border-line rounded transition flex items-center gap-1.5"
               >
                 <Trash2 size={14} />
                 Discard
diff --git a/app/src/components/SignOutGuardModal.jsx b/app/src/components/SignOutGuardModal.jsx
index 8782dcd..c6a2140 100644
--- a/app/src/components/SignOutGuardModal.jsx
+++ b/app/src/components/SignOutGuardModal.jsx
@@ -79,7 +79,7 @@ export default function SignOutGuardModal({ calcs, yields, onKeep, onDiscard, on
           <button
             onClick={handleDiscard}
             disabled={processing}
-            className="w-full text-sm font-medium px-4 py-2.5 rounded-lg border border-border bg-surface text-text-secondary hover:bg-brand-terracotta/10 hover:text-brand-terracotta hover:border-brand-terracotta/30 transition-colors disabled:opacity-60 disabled:cursor-not-allowed"
+            className="w-full text-sm font-medium px-4 py-2.5 rounded-lg border border-border bg-surface text-text-secondary hover:bg-brand-terracotta/10 hover:text-link hover:border-brand-terracotta/30 transition-colors disabled:opacity-60 disabled:cursor-not-allowed"
           >
             Discard unsaved data and sign out
           </button>
diff --git a/app/src/components/SubmitRequest.jsx b/app/src/components/SubmitRequest.jsx
index 557f9ba..20debb4 100644
--- a/app/src/components/SubmitRequest.jsx
+++ b/app/src/components/SubmitRequest.jsx
@@ -169,7 +169,7 @@ const SubmitRequest = () => {
           <label className="block text-lg font-semibold text-navy dark:text-text-primary mb-4">
             What type of request is this?
             {errors.type && (
-              <span className="text-red-500 text-sm font-normal ml-2">
+              <span className="text-danger text-sm font-normal ml-2">
                 {errors.type}
               </span>
             )}
@@ -241,7 +241,7 @@ const SubmitRequest = () => {
               >
                 Title *
                 {errors.title && (
-                  <span className="text-red-500 ml-2">{errors.title}</span>
+                  <span className="text-danger ml-2">{errors.title}</span>
                 )}
               </label>
               <input
@@ -266,7 +266,7 @@ const SubmitRequest = () => {
               >
                 Description *
                 {errors.description && (
-                  <span className="text-red-500 ml-2">{errors.description}</span>
+                  <span className="text-danger ml-2">{errors.description}</span>
                 )}
               </label>
               <textarea
@@ -323,7 +323,7 @@ const SubmitRequest = () => {
                 >
                   Your Email (optional)
                   {errors.email && (
-                    <span className="text-red-500 ml-2">{errors.email}</span>
+                    <span className="text-danger ml-2">{errors.email}</span>
                   )}
                 </label>
                 <input
diff --git a/app/src/components/SyncDetailsPanel.jsx b/app/src/components/SyncDetailsPanel.jsx
index a7346af..62b0d41 100644
--- a/app/src/components/SyncDetailsPanel.jsx
+++ b/app/src/components/SyncDetailsPanel.jsx
@@ -4,7 +4,7 @@ import { useData } from '../context/DataContext';
 
 const STATUS_COPY = {
   synced:   { icon: CheckCircle,   text: 'All data is up to date.',            color: 'text-green-500' },
-  syncing:  { icon: RefreshCw,     text: 'Synchronizing with server…',         color: 'text-brand-teal' },
+  syncing:  { icon: RefreshCw,     text: 'Synchronizing with server…',         color: 'text-accent' },
   pending:  { icon: Clock,         text: 'Changes queued — syncing soon.',     color: 'text-yellow-400' },
   offline:  { icon: CloudOff,      text: 'You are offline. Changes saved locally.', color: 'text-text-muted' },
   error:    { icon: AlertCircle,   text: 'Sync encountered an error.',         color: 'text-red-400' },
diff --git a/app/src/components/SyncStatusBadge.jsx b/app/src/components/SyncStatusBadge.jsx
index f9f0f18..f31efd5 100644
--- a/app/src/components/SyncStatusBadge.jsx
+++ b/app/src/components/SyncStatusBadge.jsx
@@ -3,13 +3,13 @@ import { Cloud, CloudOff, Loader2, AlertCircle, CheckCircle, TriangleAlert, Cloc
 import { useData } from '../context/DataContext';
 
 const CONFIG = {
-  synced:   { icon: CheckCircle,   label: 'Synced',   color: 'text-green-500' },
-  syncing:  { icon: Loader2,       label: 'Syncing…', color: 'text-brand-teal', spin: true },
-  pending:  { icon: Clock,         label: 'Pending',  color: 'text-yellow-400' },
-  offline:  { icon: CloudOff,      label: 'Offline',  color: 'text-text-muted' },
-  error:    { icon: AlertCircle,   label: 'Error',    color: 'text-red-400' },
-  conflict: { icon: TriangleAlert, label: 'Conflict', color: 'text-orange-400' },
-  idle:     { icon: Cloud,         label: 'Idle',     color: 'text-text-muted' },
+  synced:   { icon: CheckCircle,   label: 'Synced',   color: 'text-green-300' },
+  syncing:  { icon: Loader2,       label: 'Syncing…', color: 'text-brand-yellow', spin: true },
+  pending:  { icon: Clock,         label: 'Pending',  color: 'text-yellow-300' },
+  offline:  { icon: CloudOff,      label: 'Offline',  color: 'text-white/80' },
+  error:    { icon: AlertCircle,   label: 'Error',    color: 'text-red-300' },
+  conflict: { icon: TriangleAlert, label: 'Conflict', color: 'text-orange-300' },
+  idle:     { icon: Cloud,         label: 'Idle',     color: 'text-white/80' },
 };
 
 /**
@@ -23,7 +23,7 @@ export default function SyncStatusBadge({ onToggleDetails }) {
   return (
     <button
       onClick={onToggleDetails}
-      className={`flex items-center gap-1 px-2 py-1 rounded text-xs font-medium transition-colors hover:bg-white/10 ${color}`}
+      className={`flex min-h-[2.75rem] items-center gap-1 px-2.5 rounded-lg text-sm font-medium transition-colors hover:bg-white/10 ${color}`}
       title={`Sync status: ${label}${pendingCount > 0 ? ` (${pendingCount} pending)` : ''}`}
       aria-label={`Sync status: ${label}`}
     >
diff --git a/app/src/components/UploadData.jsx b/app/src/components/UploadData.jsx
index 8e31c4c..209620d 100644
--- a/app/src/components/UploadData.jsx
+++ b/app/src/components/UploadData.jsx
@@ -96,7 +96,7 @@ const UploadData = () => {
         <div className="bg-surface p-8 rounded-full">
           <Upload size={40} className="text-text-secondary" />
         </div>
-        <h2 className="text-xl font-bold text-brand-teal">Login Required</h2>
+        <h2 className="text-xl font-bold text-accent">Login Required</h2>
         <p className="text-text-secondary max-w-md text-sm">
           You need to be logged in to upload your own yield data.
           This allows you to customize the calculator with your specific experience.
@@ -112,13 +112,13 @@ const UploadData = () => {
     <div className="max-w-2xl mx-auto p-4 sm:p-6">
       <div className="card p-6 sm:p-8">
         <div className="flex items-start justify-between mb-2">
-          <h2 className="text-2xl font-bold text-brand-teal flex items-center gap-3">
-            <Upload className="text-brand-terracotta" size={22} />
+          <h2 className="text-2xl font-bold text-accent flex items-center gap-3">
+            <Upload className="text-link" size={22} />
             Upload Yield Data
           </h2>
           <button
             onClick={downloadTemplate}
-            className="flex items-center gap-1.5 text-xs text-text-secondary hover:text-brand-teal transition font-medium"
+            className="flex items-center gap-1.5 text-xs text-text-secondary hover:text-accent transition font-medium"
             title="Download a template CSV"
           >
             <Download size={14} />
@@ -159,7 +159,7 @@ const UploadData = () => {
           />
           {file ? (
             <div className="flex flex-col items-center gap-3">
-              <FileText size={36} className="text-brand-teal" />
+              <FileText size={36} className="text-accent" />
               <div>
                 <p className="text-sm font-medium text-text-primary">{file.name}</p>
                 <p className="text-xs text-text-secondary mt-0.5">{formatBytes(file.size)}</p>
@@ -173,7 +173,7 @@ const UploadData = () => {
             </div>
           ) : (
             <label htmlFor="file-upload" className="cursor-pointer flex flex-col items-center gap-3">
-              <Upload size={36} className={dragOver ? 'text-brand-teal' : 'text-text-secondary'} />
+              <Upload size={36} className={dragOver ? 'text-accent' : 'text-text-secondary'} />
               <div>
                 <p className="text-sm font-medium text-text-primary">
                   {dragOver ? 'Drop to upload' : 'Drag & drop or click to select'}
@@ -196,13 +196,13 @@ const UploadData = () => {
             <div className="flex gap-3 mb-3">
               {status.data.inserted > 0 && (
                 <div className="flex-1 bg-white dark:bg-white/10 rounded p-2 text-center">
-                  <p className="text-xl font-bold text-brand-teal">{status.data.inserted}</p>
+                  <p className="text-xl font-bold text-accent">{status.data.inserted}</p>
                   <p className="text-xs text-text-secondary">added</p>
                 </div>
               )}
               {status.data.updated > 0 && (
                 <div className="flex-1 bg-white dark:bg-white/10 rounded p-2 text-center">
-                  <p className="text-xl font-bold text-brand-teal">{status.data.updated}</p>
+                  <p className="text-xl font-bold text-accent">{status.data.updated}</p>
                   <p className="text-xs text-text-secondary">updated</p>
                 </div>
               )}
@@ -223,7 +223,7 @@ const UploadData = () => {
             )}
             <Link
               to="/manage-data"
-              className="inline-flex items-center gap-1 text-xs text-brand-terracotta hover:underline font-medium"
+              className="inline-flex items-center gap-1 text-xs text-link hover:underline font-medium"
             >
               View your data <ArrowRight size={12} />
             </Link>
diff --git a/app/src/index.css b/app/src/index.css
index 42551ae..2bcf078 100644
--- a/app/src/index.css
+++ b/app/src/index.css
@@ -2,63 +2,126 @@
 @tailwind components;
 @tailwind utilities;
 
+/*
+ * Design tokens.
+ * Text pairs are checked against WCAG AA (4.5:1) and form-control edges against
+ * 3:1 by src/lib/__tests__/designTokens.test.js — change a value here and that
+ * test will tell you if it stops being readable in sunlight or a dim kitchen.
+ */
 :root {
+  color-scheme: light;
   --color-surface: #f5f0eb;
   --color-surface-raised: #ffffff;
   --color-text-primary: #1a2e35;
   --color-text-secondary: #4a6572;
-  --color-text-muted: #7a9aaa;
+  --color-text-muted: #557080;
   --color-border: #d6ccc4;
   --color-border-subtle: #ede7e0;
+  --color-border-strong: #857a70;
+  --color-primary: #014457;
+  --color-primary-hover: #025a72;
   --color-accent: #014457;
-  --color-accent-warm: #CA5F40;
+  --color-link: #a34329;
+  --color-focus: #014457;
+  --color-success: #166534;
+  --color-danger: #b42318;
 }
 
 .dark {
+  color-scheme: dark;
   --color-surface: #0d1f26;
   --color-surface-raised: #132830;
   --color-text-primary: #e8ddd4;
   --color-text-secondary: #8fa8b2;
-  --color-text-muted: #5d7f8c;
+  --color-text-muted: #7f9aa6;
   --color-border: rgba(255, 255, 255, 0.12);
   --color-border-subtle: rgba(255, 255, 255, 0.06);
-  --color-accent: #025a72;
-  --color-accent-warm: #d97356;
+  --color-border-strong: #6f8b96;
+  --color-primary: #0b7a99;
+  --color-primary-hover: #096a86;
+  --color-accent: #7fd0e3;
+  --color-link: #ec8f72;
+  --color-focus: #f7c648;
+  --color-success: #4ade80;
+  --color-danger: #fca5a5;
 }
 
 @layer base {
+  html {
+    -webkit-text-size-adjust: 100%;
+  }
+
   body {
     font-feature-settings: "cv11", "ss01";
     -webkit-font-smoothing: antialiased;
+    -webkit-tap-highlight-color: transparent;
+    line-height: 1.6;
+  }
+
+  /* One clear, high-contrast focus indicator for keyboard and switch users */
+  :focus-visible {
+    outline: 3px solid var(--color-focus);
+    outline-offset: 2px;
+  }
+
+  /* The navbar is teal in both themes, so its focus ring must be light */
+  .focus-on-dark :focus-visible {
+    outline-color: #f7c648;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
   }
 }
 
 @layer components {
+  /* Buttons: 48px tall so they're easy to hit with wet or gloved hands */
+  .btn-primary,
+  .btn-secondary {
+    @apply inline-flex min-h-[3rem] items-center justify-center gap-2 rounded-lg px-5 py-3 text-base font-semibold
+           transition-colors active:translate-y-px disabled:cursor-not-allowed disabled:opacity-60;
+  }
+
   .btn-primary {
-    @apply bg-brand-teal hover:bg-brand-teal-light text-white font-semibold py-3 px-5 rounded-md transition-colors disabled:opacity-50 disabled:cursor-not-allowed;
+    @apply bg-primary text-white hover:bg-primary-hover;
+  }
+
+  .btn-secondary {
+    @apply border-2 border-line-strong bg-surface-raised text-text-primary hover:border-accent hover:text-accent;
+  }
+
+  .btn-ghost {
+    @apply inline-flex min-h-[2.75rem] items-center gap-2 rounded-lg px-3 text-sm font-semibold text-accent
+           transition-colors hover:underline;
   }
 
   .card {
-    @apply bg-surface-raised rounded-lg border border-line shadow-sm;
+    @apply rounded-xl border border-line bg-surface-raised shadow-sm;
   }
 
   .form-label {
-    @apply block text-sm font-medium mb-1.5 text-text-secondary;
+    @apply mb-1.5 block text-sm font-semibold text-text-primary;
   }
 
-  .form-input {
-    @apply w-full bg-surface border border-line rounded-md px-3 py-2.5 text-sm text-text-primary
-           placeholder-text-muted focus:outline-none focus:ring-2 focus:ring-brand-teal focus:border-transparent
-           disabled:opacity-50 disabled:cursor-not-allowed;
+  /* 16px text stops iOS from zooming the page when a field is focused */
+  .form-input,
+  .form-select {
+    @apply min-h-[3rem] w-full rounded-lg border border-line-strong bg-surface px-3.5 py-2.5 text-base text-text-primary
+           disabled:cursor-not-allowed disabled:opacity-60;
   }
 
-  .form-select {
-    @apply w-full bg-surface border border-line rounded-md px-3 py-2.5 text-sm text-text-primary
-           focus:outline-none focus:ring-2 focus:ring-brand-teal focus:border-transparent
-           disabled:opacity-50 disabled:cursor-not-allowed;
+  .form-input {
+    @apply placeholder-text-muted;
   }
 
   .section-divider {
-    @apply border-t border-line-subtle my-5;
+    @apply my-6 border-t border-line-subtle;
   }
 }
diff --git a/app/src/lib/__tests__/designTokens.test.js b/app/src/lib/__tests__/designTokens.test.js
new file mode 100644
index 0000000..d8d78e6
--- /dev/null
+++ b/app/src/lib/__tests__/designTokens.test.js
@@ -0,0 +1,78 @@
+/**
+ * Guards the design tokens in src/index.css against readability regressions.
+ * Users read this on a dock in glare or in a dim kitchen, so text must meet
+ * WCAG AA (4.5:1) and form-control edges / focus rings must meet 3:1.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import tailwindConfig from '../../../tailwind.config.js';
+
+const css = readFileSync(fileURLToPath(new URL('../../index.css', import.meta.url)), 'utf8');
+
+function readTokens(selector) {
+  const block = css.match(new RegExp(`${selector}\\s*\\{([^}]*)\\}`))?.[1] ?? '';
+  const tokens = {};
+  for (const [, name, value] of block.matchAll(/--color-([\w-]+):\s*(#[0-9a-fA-F]{6})\s*;/g)) {
+    tokens[name] = value;
+  }
+  return tokens;
+}
+
+function luminance(hex) {
+  const [r, g, b] = [1, 3, 5]
+    .map((i) => parseInt(hex.slice(i, i + 2), 16) / 255)
+    .map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function contrast(a, b) {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+const themes = { light: readTokens(':root'), dark: readTokens('\\.dark') };
+
+describe.each(Object.entries(themes))('%s theme tokens', (_theme, t) => {
+  const backgrounds = ['surface', 'surface-raised'];
+
+  it('defines every token the tests rely on', () => {
+    for (const name of [
+      ...backgrounds, 'text-primary', 'text-secondary', 'text-muted', 'border-strong',
+      'primary', 'primary-hover', 'accent', 'link', 'focus', 'success', 'danger',
+    ]) {
+      expect(t[name], `--color-${name}`).toMatch(/^#[0-9a-f]{6}$/i);
+    }
+  });
+
+  it.each(['text-primary', 'text-secondary', 'text-muted', 'accent', 'link', 'success', 'danger'])(
+    '%s text is at least 4.5:1 on both surfaces',
+    (name) => {
+      for (const bg of backgrounds) {
+        expect(contrast(t[name], t[bg]), `${name} on ${bg}`).toBeGreaterThanOrEqual(4.5);
+      }
+    },
+  );
+
+  it.each(['border-strong', 'focus'])('%s is at least 3:1 on both surfaces', (name) => {
+    for (const bg of backgrounds) {
+      expect(contrast(t[name], t[bg]), `${name} on ${bg}`).toBeGreaterThanOrEqual(3);
+    }
+  });
+
+  it.each(['primary', 'primary-hover'])('white button text on %s is at least 4.5:1', (name) => {
+    expect(contrast('#ffffff', t[name])).toBeGreaterThanOrEqual(4.5);
+  });
+});
+
+describe('fixed brand colors', () => {
+  const { brand } = tailwindConfig.theme.extend.colors;
+
+  it.each(['cta', 'cta-hover'])('white text on brand.%s is at least 4.5:1', (name) => {
+    expect(contrast('#ffffff', brand[name])).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('keeps yellow readable on the teal navbar', () => {
+    expect(contrast(brand.yellow, brand.teal)).toBeGreaterThanOrEqual(4.5);
+  });
+});
diff --git a/app/tailwind.config.js b/app/tailwind.config.js
index 8df9a47..6d1b76e 100644
--- a/app/tailwind.config.js
+++ b/app/tailwind.config.js
@@ -8,9 +8,10 @@ export default {
   theme: {
     extend: {
       fontFamily: {
-        sans: ['Inter', 'system-ui', 'sans-serif'],
+        sans: ['Inter', 'ui-sans-serif', 'system-ui', '-apple-system', 'Segoe UI', 'Roboto', 'sans-serif'],
       },
       colors: {
+        // Theme-aware tokens (values live in index.css so light/dark stay in one place)
         surface: 'var(--color-surface)',
         'surface-raised': 'var(--color-surface-raised)',
         'text-primary': 'var(--color-text-primary)',
@@ -18,11 +19,23 @@ export default {
         'text-muted': 'var(--color-text-muted)',
         line: 'var(--color-border)',
         'line-subtle': 'var(--color-border-subtle)',
+        'line-strong': 'var(--color-border-strong)', // form-control edges (3:1 against the surface)
+        primary: {
+          DEFAULT: 'var(--color-primary)',
+          hover: 'var(--color-primary-hover)',
+        },
+        accent: 'var(--color-accent)', // teal used as text/icons; lightens in dark mode
+        link: 'var(--color-link)', // terracotta used as text; AA-contrast in both themes
+        success: 'var(--color-success)',
+        danger: 'var(--color-danger)',
+        // Fixed brand colors, for fills/decoration (not for body-size text)
         brand: {
           teal: '#014457',
           'teal-light': '#025a72',
           terracotta: '#CA5F40',
           'terracotta-light': '#d97356',
+          cta: '#B04A2E', // terracotta that keeps white text at AA (5.4:1)
+          'cta-hover': '#963D24',
           yellow: '#F7C648',
         },
       },
diff --git a/app/vite.config.js b/app/vite.config.js
index 8c1d702..c57632f 100644
--- a/app/vite.config.js
+++ b/app/vite.config.js
@@ -32,8 +32,8 @@ export default defineConfig({
         name: 'Fish Cost Calculator',
         short_name: 'Fish Calc',
         description: 'Calculate true costs of fish processing with yield data from Alaska Sea Grant research',
-        theme_color: '#0A2540',
-        background_color: '#0A2540',
+        theme_color: '#014457',
+        background_color: '#014457',
         display: 'standalone',
         scope: '/',
         start_url: '/',
diff --git a/docs/DESIGN_SYSTEM.md b/docs/DESIGN_SYSTEM.md
new file mode 100644
index 0000000..ddd7100
--- /dev/null
+++ b/docs/DESIGN_SYSTEM.md
@@ -0,0 +1,58 @@
+# Design system notes
+
+Supersedes the navy/rust direction in `docs/superpowers/specs/2026-03-27-branding-redesign-design.md`
+(replaced by the teal/terracotta/yellow brand in July 2026).
+
+## Who this is for
+
+Fishers, chefs and fishmongers who use apps every day but are busy: on a dock in glare, in a
+cold-room, in a kitchen mid-service, often on a phone, often with wet or gloved hands. So:
+
+- **Few steps, plain words.** Two numbered steps ("Your fish", "Your numbers"), one primary action,
+  no jargon in labels (help text explains the industry terms instead).
+- **Big targets.** Buttons and form controls are at least 48px tall; other tappable things at least 44px.
+- **Readable in any light.** Text is at least 4.5:1 and form-control edges at least 3:1, in both themes.
+- **Nothing hover-only.** Help works on tap, keyboard focus and hover.
+
+## Color tokens
+
+Values live in `app/src/index.css` (`:root` = light, `.dark` = dark) and are exposed as Tailwind
+colors in `app/tailwind.config.js`.
+
+| Use this | For | Not this |
+|---|---|---|
+| `text-text-primary` / `-secondary` / `-muted` | Body and helper text | `text-gray-*` |
+| `text-accent` | Teal used as text or icons (headings, key numbers) | `text-brand-teal` (about 2:1 in dark mode) |
+| `text-link` | Terracotta used as text (links, small accents) | `text-brand-terracotta` (under 4.5:1 on light) |
+| `bg-primary` / `hover:bg-primary-hover` | Primary buttons (`.btn-primary`) | `bg-brand-teal` in dark mode |
+| `border-line-strong` | Edges of inputs, selects, toggles | `border-line` (1.5:1, decoration only) |
+| `text-success` / `text-danger` | Status text | `text-red-400`, `text-green-300` (fail on light) |
+| `bg-brand-cta` | Terracotta fill with white text | `bg-brand-terracotta` + white text (4.0:1) |
+| `bg-brand-*` (teal, yellow, terracotta) | Fixed brand fills and decoration | body-size text |
+
+Shared classes: `.btn-primary`, `.btn-secondary`, `.btn-ghost`, `.card`, `.form-label`,
+`.form-input`, `.form-select`, `.section-divider`. Inputs are 16px text so iOS does not zoom on focus.
+
+## Guardrails
+
+- `app/src/lib/__tests__/designTokens.test.js` fails if a token pair drops below its contrast target.
+  Change a color, run `npm test`.
+- Keyboard focus uses one 3px outline (`:focus-visible`), yellow on dark surfaces and in the navbar.
+- `prefers-reduced-motion` is honored globally.
+
+## Known follow-ups
+
+- **Reference sites not analyzed.** The redesign request named Grace Communications, namanet.org,
+  the National Family Farm Coalition and localcatch.org, but this environment's network policy blocked
+  them, so nothing here is derived from those sites. Palette and typeface are unchanged from July 2026.
+  Tokens are centralized, so a palette or font pass is a change to `index.css`, `tailwind.config.js`
+  and the font link in `index.html`.
+- **Dark-only status styling** (pale `text-red-300` / `text-green-300` on translucent dark boxes, or
+  `text-amber-*`) is unreadable in light mode. Move these to `text-danger` / `text-success` and
+  theme-aware backgrounds: `UploadData`, `SubmitRequest`, `ConflictResolutionModal`, `RecoveryModal`,
+  `DataManagement`, `ContributorProfile`, `CommunityData`, `FeaturesRoadmap`.
+- **Unused components** `Footer.jsx` and `InstallPrompt.jsx` are not rendered anywhere and use tokens
+  that no longer exist (`bg-navy`, `text-teal`, `bg-rust`). Restyle before wiring them in, or delete.
+- **Offline behavior.** `Calculator` seeds its data from `FISH_DATA_V3`, whose conversions have no
+  `from`/`to` fields (they are derived server-side by `/api/fish-data`). If that request fails, the
+  "What you have" list is empty and the calculator cannot be used, which matters on a boat with poor signal.

From a7feb648438ae1abd02dd1326c57be623e1fe5b3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 29 Sep 2026 00:51:57 +0000
Subject: [PATCH 2/3] fix: address review feedback on tooltips, focus ring and
 live region

- Tooltip: Enter/Space (detail === 0, incl. assistive tech) now reopens
  it after Escape; 44px hit area on icon-only help buttons and on inline
  abbreviation buttons via a pseudo-element, without shifting layout.
- Focus ring: popovers rendered inside the navbar (sync details) use the
  theme focus color instead of the navbar's yellow, which was ~1.6:1 on
  their white surface.
- Result: keep the live region mounted but scope it to the answer only;
  Save/export and a stable role="status" sit outside it, so button labels
  and save status are not announced twice.
- RecoveryModal: drop the fixed hover:text-red-400 (2.8:1 on light) from
  both Discard buttons.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ErLEY8gicR3Wg7Q1yXAVaC
---
 app/src/components/Calculator.jsx    | 104 +++++++++++++++------------
 app/src/components/RecoveryModal.jsx |   4 +-
 app/src/index.css                    |   5 ++
 3 files changed, 65 insertions(+), 48 deletions(-)

diff --git a/app/src/components/Calculator.jsx b/app/src/components/Calculator.jsx
index dbe2b3b..57d1f64 100644
--- a/app/src/components/Calculator.jsx
+++ b/app/src/components/Calculator.jsx
@@ -59,14 +59,23 @@ const Tooltip = ({ text, label, iconOnly = false, children }) => {
         aria-label={label}
         aria-describedby={show ? bubbleId : undefined}
         aria-expanded={show}
-        className={`cursor-help rounded text-left ${iconOnly ? '-m-2.5 p-2.5' : ''}`}
+        className={`cursor-help rounded text-left ${
+          // 44px hit area without moving the layout: padding out, negative margin back in
+          iconOnly
+            ? '-m-[13px] p-[13px]'
+            : "relative before:absolute before:-inset-2.5 before:content-['']"
+        }`}
         onPointerDown={(e) => { lastPointer.current = e.pointerType; }}
         onPointerEnter={(e) => { if (e.pointerType === 'mouse') setShow(true); }}
         onPointerLeave={(e) => { if (e.pointerType === 'mouse') setShow(false); }}
         onFocus={(e) => { if (e.currentTarget.matches(':focus-visible')) setShow(true); }}
         onBlur={() => setShow(false)}
         onKeyDown={(e) => { if (e.key === 'Escape') setShow(false); }}
-        onClick={() => { if (lastPointer.current !== 'mouse') setShow((s) => !s); }}
+        onClick={(e) => {
+          // detail === 0 means keyboard or assistive-tech activation: always open (Esc closes)
+          if (e.detail === 0) setShow(true);
+          else if (lastPointer.current !== 'mouse') setShow((s) => !s);
+        }}
       >
         {children}
       </button>
@@ -450,7 +459,7 @@ const Calculator = () => {
 
             <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
               <div>
-                <div className="mb-1.5 flex items-center gap-1.5">
+                <div className="mb-1.5 flex items-center gap-2.5">
                   <label htmlFor="calc-from" className="text-sm font-semibold text-text-primary">What you have</label>
                   <Tooltip
                     iconOnly
@@ -473,7 +482,7 @@ const Calculator = () => {
               </div>
 
               <div>
-                <div className="mb-1.5 flex items-center gap-1.5">
+                <div className="mb-1.5 flex items-center gap-2.5">
                   <label htmlFor="calc-to" className="text-sm font-semibold text-text-primary">What you're making</label>
                   <Tooltip
                     iconOnly
@@ -705,50 +714,53 @@ const Calculator = () => {
           </div>
         </form>
 
-        {/* Result: announced to screen readers and scrolled into view when it appears */}
-        <div aria-live="polite" ref={resultRef} className="scroll-mt-20">
-          {result !== null && (
-            <div className="mt-6 rounded-xl border-2 border-brand-teal bg-brand-teal/5 p-5 dark:border-accent dark:bg-brand-teal/15">
-              <p className="text-sm font-semibold text-text-secondary">
-                {mode === 'cost' ? `Your cost per lb of ${toState}` : `You need to buy (${fromState})`}
-              </p>
-              <p className="mt-1 text-5xl font-bold tabular-nums tracking-tight text-accent">
-                {mode === 'cost' ? `$${result.toFixed(2)}` : `${result.toFixed(1)} lbs`}
-              </p>
-              <p className="mt-2 text-base text-text-secondary">
-                {mode === 'cost'
-                  ? `At ${yieldPercent}% yield from ${fromState} to ${toState}`
-                  : `${result.toFixed(1)} lbs of ${fromState} makes ${targetWeight} lbs of ${toState}`
-                }
-              </p>
-
-              {user ? (
-                <div className="mt-5 flex flex-wrap items-center gap-x-2 gap-y-1">
-                  <button type="button" onClick={handleSave} className="btn-secondary">
-                    <Save size={18} aria-hidden="true" /> Save calculation
-                  </button>
-                  <button type="button" onClick={handleExport} className="btn-ghost">
-                    <Download size={16} aria-hidden="true" /> CSV
-                  </button>
-                  <button type="button" onClick={handleExportXlsx} className="btn-ghost">
-                    <Download size={16} aria-hidden="true" /> Excel
-                  </button>
-                  {saveStatus && (
-                    <span
-                      role="status"
-                      className={`text-sm font-semibold ${saveStatus === 'Saved!' ? 'text-success' : 'text-danger'}`}
-                    >
-                      {saveStatus}
-                    </span>
-                  )}
-                </div>
-              ) : (
-                <p className="mt-4 text-sm text-text-secondary">
-                  Want to keep this? <Link to="/login" className="font-semibold text-link underline">Sign in</Link> to save your calculations.
-                </p>
+        {/* Result: the live region stays mounted (so the first result is announced) and holds only the
+            answer. Actions and save status live outside it to avoid duplicate announcements. */}
+        <div ref={resultRef} className="scroll-mt-20">
+          <div className={result !== null ? 'mt-6 rounded-xl border-2 border-brand-teal bg-brand-teal/5 p-5 dark:border-accent dark:bg-brand-teal/15' : ''}>
+            <div aria-live="polite">
+              {result !== null && (
+                <>
+                  <p className="text-sm font-semibold text-text-secondary">
+                    {mode === 'cost' ? `Your cost per lb of ${toState}` : `You need to buy (${fromState})`}
+                  </p>
+                  <p className="mt-1 text-5xl font-bold tabular-nums tracking-tight text-accent">
+                    {mode === 'cost' ? `$${result.toFixed(2)}` : `${result.toFixed(1)} lbs`}
+                  </p>
+                  <p className="mt-2 text-base text-text-secondary">
+                    {mode === 'cost'
+                      ? `At ${yieldPercent}% yield from ${fromState} to ${toState}`
+                      : `${result.toFixed(1)} lbs of ${fromState} makes ${targetWeight} lbs of ${toState}`
+                    }
+                  </p>
+                </>
               )}
             </div>
-          )}
+
+            {result !== null && (user ? (
+              <div className="mt-5 flex flex-wrap items-center gap-x-2 gap-y-1">
+                <button type="button" onClick={handleSave} className="btn-secondary">
+                  <Save size={18} aria-hidden="true" /> Save calculation
+                </button>
+                <button type="button" onClick={handleExport} className="btn-ghost">
+                  <Download size={16} aria-hidden="true" /> CSV
+                </button>
+                <button type="button" onClick={handleExportXlsx} className="btn-ghost">
+                  <Download size={16} aria-hidden="true" /> Excel
+                </button>
+                <span
+                  role="status"
+                  className={`text-sm font-semibold ${saveStatus === 'Saved!' ? 'text-success' : 'text-danger'}`}
+                >
+                  {saveStatus}
+                </span>
+              </div>
+            ) : (
+              <p className="mt-4 text-sm text-text-secondary">
+                Want to keep this? <Link to="/login" className="font-semibold text-link underline">Sign in</Link> to save your calculations.
+              </p>
+            ))}
+          </div>
         </div>
       </div>
 
diff --git a/app/src/components/RecoveryModal.jsx b/app/src/components/RecoveryModal.jsx
index c4b00bd..cfc24ab 100644
--- a/app/src/components/RecoveryModal.jsx
+++ b/app/src/components/RecoveryModal.jsx
@@ -63,7 +63,7 @@ export default function RecoveryModal({ calcs, yields, isAuthenticated, assignin
               <button
                 onClick={onDiscard}
                 disabled={assigning}
-                className="px-4 py-2 text-sm font-medium text-danger hover:text-red-400 border border-line rounded transition flex items-center gap-1.5 disabled:opacity-50"
+                className="px-4 py-2 text-sm font-medium text-danger hover:underline border border-line rounded transition flex items-center gap-1.5 disabled:opacity-50"
               >
                 <Trash2 size={14} />
                 Discard
@@ -92,7 +92,7 @@ export default function RecoveryModal({ calcs, yields, isAuthenticated, assignin
               </button>
               <button
                 onClick={onDiscard}
-                className="px-4 py-2 text-sm font-medium text-danger hover:text-red-400 border border-line rounded transition flex items-center gap-1.5"
+                className="px-4 py-2 text-sm font-medium text-danger hover:underline border border-line rounded transition flex items-center gap-1.5"
               >
                 <Trash2 size={14} />
                 Discard
diff --git a/app/src/index.css b/app/src/index.css
index 2bcf078..7807028 100644
--- a/app/src/index.css
+++ b/app/src/index.css
@@ -69,6 +69,11 @@
     outline-color: #f7c648;
   }
 
+  /* ...but popovers rendered inside the navbar (sync details) sit on a normal surface */
+  .focus-on-dark [role="dialog"] :focus-visible {
+    outline-color: var(--color-focus);
+  }
+
   @media (prefers-reduced-motion: reduce) {
     *,
     *::before,

From 3051c3c3a0fd743eded3689d03ba968c5b6c5225 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 29 Sep 2026 01:00:05 +0000
Subject: [PATCH 3/3] fix: keep result text in sync and size tooltips to the
 visual viewport

- Snapshot the yield and target weight when a result is computed and
  render the description from that, so editing either afterwards can no
  longer make the live region announce an impossible combination such as
  "238.1 lbs ... makes 200 lbs".
- Cap the tooltip width to the visual viewport before positioning it, so
  pinch-zoom or high browser zoom cannot clip the right edge of the help
  text.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ErLEY8gicR3Wg7Q1yXAVaC
---
 app/src/components/Calculator.jsx | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/app/src/components/Calculator.jsx b/app/src/components/Calculator.jsx
index 57d1f64..030d469 100644
--- a/app/src/components/Calculator.jsx
+++ b/app/src/components/Calculator.jsx
@@ -25,8 +25,11 @@ const Tooltip = ({ text, label, iconOnly = false, children }) => {
     if (!show || !bubble || !trigger) return;
     const gap = 8;
     const vv = window.visualViewport;
+    const viewportWidth = vv?.width ?? document.documentElement.clientWidth;
     const minX = (vv?.offsetLeft ?? 0) + gap;
-    const maxX = (vv?.offsetLeft ?? 0) + (vv?.width ?? document.documentElement.clientWidth) - gap;
+    const maxX = (vv?.offsetLeft ?? 0) + viewportWidth - gap;
+    // The CSS cap is in layout units; when zoomed in the visible area is narrower, so cap it here too
+    bubble.style.maxWidth = `${Math.min(parseFloat(getComputedStyle(bubble).maxWidth) || Infinity, maxX - minX)}px`;
     const t = trigger.getBoundingClientRect();
     const { width, height } = bubble.getBoundingClientRect();
     const left = Math.min(Math.max(t.left, minX), Math.max(minX, maxX - width));
@@ -169,6 +172,8 @@ const Calculator = () => {
   const [shipping, _setShipping] = useState('');
   const [weightType, setWeightType] = useState('incoming');
   const [result, setResult] = useState(null);
+  // Yield and target as they were when the result was computed, so the description never drifts from the number
+  const [resultMeta, setResultMeta] = useState(null);
   const resultRef = useRef(null);
   const [saveStatus, setSaveStatus] = useState('');
   const [useRangeMin, setUseRangeMin] = useState(false);
@@ -308,6 +313,7 @@ const Calculator = () => {
     if (mode === 'weight') {
       const target = parseFloat(targetWeight) || 0;
       setResult(y > 0 ? target / y : 0);
+      setResultMeta({ yieldPercent, targetWeight });
       setSaveStatus('');
       return;
     }
@@ -323,6 +329,7 @@ const Calculator = () => {
     baseRes += cold + ship;
 
     setResult(baseRes);
+    setResultMeta({ yieldPercent, targetWeight });
     setSaveStatus('');
   };
 
@@ -729,8 +736,8 @@ const Calculator = () => {
                   </p>
                   <p className="mt-2 text-base text-text-secondary">
                     {mode === 'cost'
-                      ? `At ${yieldPercent}% yield from ${fromState} to ${toState}`
-                      : `${result.toFixed(1)} lbs of ${fromState} makes ${targetWeight} lbs of ${toState}`
+                      ? `At ${resultMeta?.yieldPercent}% yield from ${fromState} to ${toState}`
+                      : `${result.toFixed(1)} lbs of ${fromState} makes ${resultMeta?.targetWeight} lbs of ${toState}`
                     }
                   </p>
                 </>