From 9615ee3f4121bb9e210256064f678b58db1d1504 Mon Sep 17 00:00:00 2001
From: cesnimda <connor.babbington@cesnimda.co.uk>
Date: Sun, 12 Jul 2026 04:14:37 +0200
Subject: [PATCH] feat(ux): per-view subtitles, correspondence cross-links,
 mobile kanban, a11y

Continuing the product/UX review's deferred items:

- Every top-level view now gets a one-line subtitle under its title
  (Dashboard/Jobs/Kanban/Reminders/Correspondence/Gmail review) stating
  what that specific view is for, instead of navigation being the only
  signal of what each page does.
- Correspondence inbox and Gmail review queue cross-link to each other
  instead of being two unexplained flat sidebar items -- kept both nav
  entries (renaming/nesting risked breaking muscle memory) but made the
  relationship between them explicit in the UI itself.
- Kanban board switches to a horizontal scroll-snap row on phone-width
  viewports instead of stacking all 5 columns vertically, which meant
  a lot of scrolling to see anything past "Applied".
- Match-score ring gets an aria-label with the actual percentage --
  it was two nested decorative CircularProgress elements with no
  accessible text. (Keyboard-accessible status changes on kanban cards
  were already covered by the existing "..." menu -- no gap there.)
---
 job-tracker-ui/src/App.tsx                        | 12 ++++++++++++
 .../src/components/JobDetailsDialog.tsx           |  5 +++--
 job-tracker-ui/src/components/KanbanBoard.tsx     | 15 ++++++++++++++-
 job-tracker-ui/src/i18n/translations.ts           | 12 ++++++++++++
 job-tracker-ui/src/layout/AppShell.tsx            |  7 +++++++
 .../src/views/CorrespondenceInboxPage.tsx         |  3 ++-
 job-tracker-ui/src/views/GmailReviewPage.tsx      |  1 +
 7 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/job-tracker-ui/src/App.tsx b/job-tracker-ui/src/App.tsx
index 0210bd3..bb8e0cd 100644
--- a/job-tracker-ui/src/App.tsx
+++ b/job-tracker-ui/src/App.tsx
@@ -100,6 +100,16 @@ function titleFor(path: string, t: (k: any) => string): string {
   return t("appTitle");
 }
 
+function subtitleFor(path: string, t: (k: any) => string): string | undefined {
+  if (path === "/dashboard") return t("dashboardPageSubtitle");
+  if (path.startsWith("/jobs")) return t("jobsPageSubtitle");
+  if (path.startsWith("/kanban")) return t("kanbanPageSubtitle");
+  if (path.startsWith("/reminders")) return t("remindersPageSubtitle");
+  if (path.startsWith("/correspondence/review")) return t("gmailReviewPageSubtitle");
+  if (path.startsWith("/correspondence")) return t("correspondencePageSubtitle");
+  return undefined;
+}
+
 function PageLoader() {
   return <Box sx={{ p: 4 }}><Typography variant="h6">Loading...</Typography></Box>;
 }
@@ -209,6 +219,7 @@ function Shell({ jobPageSize, setJobPageSize, jobColumns, setJobColumns, themeMo
   if (requireAuth && !me) return <Navigate to="/" replace state={{ from: path }} />;
 
   const pageTitle = titleFor(path, t);
+  const pageSubtitle = subtitleFor(path, t);
   const breadcrumbs = breadcrumbsFor(path, t);
   const setAndPersistPageSize = (n: 15 | 20 | 25) => { setJobPageSize(n); window.localStorage.setItem("jobPageSize", String(n)); };
   const setAndPersistColumns = (next: JobTableColumns) => { setJobColumns(next); window.localStorage.setItem("jobColumns", JSON.stringify(next)); };
@@ -275,6 +286,7 @@ function Shell({ jobPageSize, setJobPageSize, jobColumns, setJobColumns, themeMo
     <>
       <AppShell
         pageTitle={pageTitle}
+        pageSubtitle={pageSubtitle}
         breadcrumbs={breadcrumbs}
         pathname={path}
         nav={nav}
diff --git a/job-tracker-ui/src/components/JobDetailsDialog.tsx b/job-tracker-ui/src/components/JobDetailsDialog.tsx
index cb044fb..c3d5877 100644
--- a/job-tracker-ui/src/components/JobDetailsDialog.tsx
+++ b/job-tracker-ui/src/components/JobDetailsDialog.tsx
@@ -1231,13 +1231,14 @@ function MatchScoreCard({ score, loading }: { score: MatchScore | null; loading:
     <Box sx={{ p: 1.75, mb: 2, borderRadius: 3, border: "1px solid", borderColor: "divider", backgroundColor: "background.default" }}>
       <Box sx={{ display: "flex", gap: 2.5, alignItems: "center", flexWrap: "wrap", mb: 1.5 }}>
         {score.hasEnoughSignal ? (
-          <Box sx={{ position: "relative", width: 92, height: 92, flexShrink: 0 }}>
-            <CircularProgress variant="determinate" value={100} size={92} thickness={4} sx={{ color: "divider", position: "absolute" }} />
+          <Box role="img" aria-label={`${t("matchScoreTitle")}: ${score.score}%`} sx={{ position: "relative", width: 92, height: 92, flexShrink: 0 }}>
+            <CircularProgress variant="determinate" value={100} size={92} thickness={4} aria-hidden="true" sx={{ color: "divider", position: "absolute" }} />
             <CircularProgress
               variant="determinate"
               value={score.score}
               size={92}
               thickness={4}
+              aria-hidden="true"
               color={color === "inherit" ? "primary" : color}
               sx={{ position: "absolute", "& .MuiCircularProgress-circle": { strokeLinecap: "round" } }}
             />
diff --git a/job-tracker-ui/src/components/KanbanBoard.tsx b/job-tracker-ui/src/components/KanbanBoard.tsx
index 8ff8628..81d0164 100644
--- a/job-tracker-ui/src/components/KanbanBoard.tsx
+++ b/job-tracker-ui/src/components/KanbanBoard.tsx
@@ -101,7 +101,18 @@ export default function KanbanBoard() {
       />
 
       {!jobsResource.loading && !jobsResource.error ? (
-        <Box sx={{ display: "grid", gridTemplateColumns: { xs: "1fr", md: "repeat(3, 1fr)", xl: "repeat(6, 1fr)" }, gap: 2, alignItems: "start" }}>
+        <Box
+          sx={{
+            display: { xs: "flex", md: "grid" },
+            gridTemplateColumns: { md: "repeat(3, 1fr)", xl: "repeat(6, 1fr)" },
+            gap: 2,
+            alignItems: "start",
+            overflowX: { xs: "auto", md: "visible" },
+            scrollSnapType: { xs: "x mandatory", md: "none" },
+            pb: { xs: 1, md: 0 },
+            "-webkit-overflow-scrolling": "touch",
+          }}
+        >
           {STATUSES.map((status) => {
             const c = toneColor(theme, status);
             const list = groups.get(status) ?? [];
@@ -114,6 +125,8 @@ export default function KanbanBoard() {
                   p: 1.5,
                   borderRadius: 3,
                   minHeight: 220,
+                  flex: { xs: "0 0 85vw", md: "none" },
+                  scrollSnapAlign: { xs: "start", md: "none" },
                   border: "1px solid",
                   borderColor: "divider",
                   background: theme.palette.mode === "dark" ? alpha(theme.palette.common.white, 0.02) : alpha(theme.palette.text.primary, 0.015),
diff --git a/job-tracker-ui/src/i18n/translations.ts b/job-tracker-ui/src/i18n/translations.ts
index 76432ce..15a1855 100644
--- a/job-tracker-ui/src/i18n/translations.ts
+++ b/job-tracker-ui/src/i18n/translations.ts
@@ -18,6 +18,12 @@ export const translations = {
     home: "Home",
     analytics: "Analytics",
     overview: "Overview",
+    dashboardPageSubtitle: "Your search at a glance — response rate, funnel, and what needs attention.",
+    jobsPageSubtitle: "Filter, search, and manage every application in one table.",
+    kanbanPageSubtitle: "Drag a card between stages to update its status.",
+    remindersPageSubtitle: "Everything due for follow-up, soonest first.",
+    correspondencePageSubtitle: "Every message linked to a job, in one inbox.",
+    gmailReviewPageSubtitle: "Review Gmail threads before linking them to a job.",
     account: "Account",
     profile: "Profile",
     admin: "Admin",
@@ -981,6 +987,12 @@ export const translations = {
     home: "Hjem",
     analytics: "Analyse",
     overview: "Oversikt",
+    dashboardPageSubtitle: "Søket ditt i korte trekk — svarrate, trakt og hva som trenger oppmerksomhet.",
+    jobsPageSubtitle: "Filtrer, søk og administrer alle søknader i én tabell.",
+    kanbanPageSubtitle: "Dra et kort mellom stadier for å oppdatere status.",
+    remindersPageSubtitle: "Alt som trenger oppfølging, snarest først.",
+    correspondencePageSubtitle: "Alle meldinger koblet til en jobb, i én innboks.",
+    gmailReviewPageSubtitle: "Se gjennom Gmail-tråder før du kobler dem til en jobb.",
     account: "Konto",
     profile: "Profil",
     admin: "Admin",
diff --git a/job-tracker-ui/src/layout/AppShell.tsx b/job-tracker-ui/src/layout/AppShell.tsx
index ca6be3c..24ed3c4 100644
--- a/job-tracker-ui/src/layout/AppShell.tsx
+++ b/job-tracker-ui/src/layout/AppShell.tsx
@@ -59,6 +59,7 @@ const SIDEBAR_SELECTED_ICON = "#a5b4fc";
 
 export default function AppShell({
   pageTitle,
+  pageSubtitle,
   breadcrumbs,
   pathname,
   nav,
@@ -76,6 +77,7 @@ export default function AppShell({
   children,
 }: {
   pageTitle: string;
+  pageSubtitle?: string;
   breadcrumbs: string[];
   pathname: string;
   nav: NavItem[];
@@ -481,6 +483,11 @@ export default function AppShell({
               <Typography variant="h5" sx={{ fontWeight: 600, overflowWrap: "anywhere" }}>
                 {pageTitle}
               </Typography>
+              {pageSubtitle ? (
+                <Typography variant="body2" sx={{ color: "text.secondary", mt: 0.25, overflowWrap: "anywhere" }}>
+                  {pageSubtitle}
+                </Typography>
+              ) : null}
             </Box>
           </Box>
 
diff --git a/job-tracker-ui/src/views/CorrespondenceInboxPage.tsx b/job-tracker-ui/src/views/CorrespondenceInboxPage.tsx
index 2aed368..85d6b9f 100644
--- a/job-tracker-ui/src/views/CorrespondenceInboxPage.tsx
+++ b/job-tracker-ui/src/views/CorrespondenceInboxPage.tsx
@@ -82,10 +82,11 @@ export default function CorrespondenceInboxPage() {
             Cross-job view of imported correspondence and Gmail-linked history.
           </Typography>
         </Box>
-        <Box sx={{ display: "flex", gap: 1, flexWrap: "wrap" }}>
+        <Box sx={{ display: "flex", gap: 1, flexWrap: "wrap", alignItems: "center" }}>
           <Chip icon={<MailOutlineIcon />} label={`${items.length} items`} variant="outlined" />
           <Chip label={`${filteredSummary.linked} linked`} variant="outlined" color={filteredSummary.linked > 0 ? "success" : "default"} />
           <Chip label={`${filteredSummary.inbound} inbound`} variant="outlined" />
+          <Button variant="outlined" size="small" onClick={() => navigate("/correspondence/review")}>Review Gmail queue</Button>
         </Box>
       </Box>
 
diff --git a/job-tracker-ui/src/views/GmailReviewPage.tsx b/job-tracker-ui/src/views/GmailReviewPage.tsx
index ea6fc33..4b058e9 100644
--- a/job-tracker-ui/src/views/GmailReviewPage.tsx
+++ b/job-tracker-ui/src/views/GmailReviewPage.tsx
@@ -138,6 +138,7 @@ export default function GmailReviewPage() {
           <Button variant="outlined" onClick={() => void load()} disabled={loading || syncing}>
             {loading ? "Loading..." : "Refresh"}
           </Button>
+          <Button variant="text" onClick={() => navigate("/correspondence")}>Back to inbox</Button>
         </Box>
       </Box>