From 7c8e5847936952bc97b6d2cf8cfaef1f040b2580 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 26 Jul 2026 04:44:01 +0000
Subject: [PATCH 1/3] Wrap Consistency, Roles, and Sprint Pulse sections for
 WCAG scan.

Apply Section with When/How copy and clearer verb+object CTAs while
keeping sticky-nav section ids stable.

Co-authored-by: Damon  <Modsofthenation@users.noreply.github.com>
---
 apps/ui/src/pages/ConsistencyPage.tsx | 84 +++++++++++++++---------
 apps/ui/src/pages/RolesPage.tsx       | 93 +++++++++++++++++----------
 apps/ui/src/pages/SprintPulsePage.tsx | 56 +++++++++-------
 3 files changed, 144 insertions(+), 89 deletions(-)

diff --git a/apps/ui/src/pages/ConsistencyPage.tsx b/apps/ui/src/pages/ConsistencyPage.tsx
index 3fb640b..f64e1e5 100644
--- a/apps/ui/src/pages/ConsistencyPage.tsx
+++ b/apps/ui/src/pages/ConsistencyPage.tsx
@@ -4,7 +4,7 @@ import type { CalibBundleDTO, ConsistencyDTO, CycleDTO } from "@prm/shared";
 import { competencyLabel } from "@prm/shared";
 import { api } from "../lib/api";
 import { downloadBinaryExport, openHtmlExport } from "../lib/exports";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout } from "../components/PageSectionsLayout";
 
 export function ConsistencyPage() {
@@ -106,12 +106,28 @@ export function ConsistencyPage() {
             { id: "cons-cards", label: "People" },
           ]}
         >
-<div className="panel stack page-section" id="cons-calib">
-          <h2>Calibration bundles</h2>
-          <p className="muted" style={{ margin: 0 }}>
-            Director round-trip: export cards, capture decisions in the form (or paste JSON), then import
-            back into draft manager reviews for the same cycle.
-          </p>
+          <Section
+            id="cons-calib"
+            title="Calibration bundles"
+            when="Use before a calibration room or director review, once drafts are ready to share."
+            how="Export cards, capture director decisions in the form (or paste JSON), then import them back into drafts."
+            action={
+              <button
+                type="button"
+                className="btn"
+                onClick={async () => {
+                  try {
+                    await openHtmlExport(`/api/exports/calib-room/${data.cycleId}?format=html`);
+                    setCalibMsg("Opened calibration room pack — Print → Save as PDF");
+                  } catch (e) {
+                    setCalibMsg(e instanceof Error ? e.message : "Calib pack failed");
+                  }
+                }}
+              >
+                Print calib room pack
+              </button>
+            }
+          >
           <div className="row" style={{ gap: 8, flexWrap: "wrap" }}>
             <button
               type="button"
@@ -140,21 +156,7 @@ export function ConsistencyPage() {
                 setCalibMsg(`Exported ${bundle.cards.length} card(s) — fill director decisions below`);
               }}
             >
-              Export calib JSON
-            </button>
-            <button
-              type="button"
-              className="btn"
-              onClick={async () => {
-                try {
-                  await openHtmlExport(`/api/exports/calib-room/${data.cycleId}?format=html`);
-                  setCalibMsg("Opened calibration room pack — Print → Save as PDF");
-                } catch (e) {
-                  setCalibMsg(e instanceof Error ? e.message : "Calib pack failed");
-                }
-              }}
-            >
-              Print calib room pack
+              Export calibration JSON
             </button>
             <button
               type="button"
@@ -168,7 +170,7 @@ export function ConsistencyPage() {
                 }
               }}
             >
-              Director briefing
+              Open director briefing
             </button>
           </div>
           <div className="row" style={{ gap: 8, flexWrap: "wrap", alignItems: "end" }}>
@@ -205,7 +207,7 @@ export function ConsistencyPage() {
                 }
               }}
             >
-              Encrypted read-only bundle
+              Download encrypted bundle
             </button>
           </div>
 
@@ -316,10 +318,10 @@ export function ConsistencyPage() {
               await load(data.cycleId);
             }}
           >
-            Import decisions
+            Import calibration decisions
           </button>
           {calibMsg && <p className="muted">{calibMsg}</p>}
-        </div>
+          </Section>
 
           {thin.length > 0 ? (
             <NextStep
@@ -341,8 +343,12 @@ export function ConsistencyPage() {
             />
           )}
 
-          <div className="panel page-section" id="cons-distribution">
-            <h2>Overall distribution</h2>
+          <Section
+            id="cons-distribution"
+            title="Overall distribution"
+            when="Use after drafts have overall ratings, before you finalize the cycle."
+            how="Scan the bars for clustering (everyone a 4) or empty buckets, then open thin cards below."
+          >
             <div className="consistency-bars">
               {["1", "2", "3", "4", "5", "unset"].map((bucket) => {
                 const n = data.distribution[bucket] ?? 0;
@@ -360,9 +366,22 @@ export function ConsistencyPage() {
                 );
               })}
             </div>
-          </div>
+          </Section>
 
-          <div className="consistency-grid page-section" id="cons-cards">
+          <Section
+            id="cons-cards"
+            title="People"
+            when="Use when comparing side-by-side ratings and evidence across your directs."
+            how="Scan flags and competency scores, then open each person’s writing desk to adjust or link evidence."
+            action={
+              data.cards[0] ? (
+                <Link className="btn" to={`/cycles/${data.cycleId}/write/${data.cards[0].personId}`}>
+                  Open first writing desk
+                </Link>
+              ) : undefined
+            }
+          >
+            <div className="consistency-grid">
             {data.cards.map((card) => (
               <div key={card.personId} className="panel consistency-card">
                 <div className="row" style={{ justifyContent: "space-between" }}>
@@ -396,11 +415,12 @@ export function ConsistencyPage() {
                   ))}
                 </ul>
                 <Link className="btn secondary" to={`/cycles/${data.cycleId}/write/${card.personId}`}>
-                  Writing desk
+                  Open writing desk
                 </Link>
               </div>
             ))}
-          </div>
+            </div>
+          </Section>
         </PageSectionsLayout>
       )}
     </div>
diff --git a/apps/ui/src/pages/RolesPage.tsx b/apps/ui/src/pages/RolesPage.tsx
index 6e1befe..ded56c9 100644
--- a/apps/ui/src/pages/RolesPage.tsx
+++ b/apps/ui/src/pages/RolesPage.tsx
@@ -7,7 +7,7 @@ import type {
   RoleFrameworkInfo,
 } from "@prm/shared";
 import { api, getToken, apiUrl } from "../lib/api";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout } from "../components/PageSectionsLayout";
 
 type ExpectationEdit = { id?: string; kind: "responsibility" | "expectation"; text: string };
@@ -386,9 +386,18 @@ export function RolesPage() {
           { id: "roles-assign", label: "Assign" },
         ]}
       >
-      <div className="grid-2 page-section" id="roles-catalog">
-        <div className="panel">
-          <h2>Catalog</h2>
+      <div className="grid-2">
+        <Section
+          id="roles-catalog"
+          title="Catalog"
+          when="Use when browsing or picking a RoleDefinition to inspect, edit, or assign."
+          how="Select a role in the list. Create one with Add role, or extract from a framework doc below."
+          action={
+            <button className="btn" type="button" onClick={startCreate}>
+              Add role
+            </button>
+          }
+        >
           {roles.length === 0 && <p className="muted">No roles yet — add one or extract from a document.</p>}
           {roles.map((r) => (
             <button
@@ -413,11 +422,23 @@ export function RolesPage() {
               </div>
             </button>
           ))}
-        </div>
-        <div className="panel page-section" id="roles-detail">
-          <h2>{selected?.title ?? "Select a role"}</h2>
+        </Section>
+        <Section
+          id="roles-detail"
+          title="Role detail"
+          when="Use after picking a role from the catalog to review expectations before assigning."
+          how="Read the summary and bar, then edit or delete. Assign people in the section below."
+          action={
+            selected ? (
+              <button className="btn" type="button" onClick={() => startEdit(selected)}>
+                Edit role
+              </button>
+            ) : undefined
+          }
+        >
           {selected ? (
             <>
+              <h3 style={{ margin: 0 }}>{selected.title}</h3>
               <p>{selected.summary}</p>
               <ol>
                 {selected.expectations.map((e) => (
@@ -431,18 +452,15 @@ export function RolesPage() {
                 <p className="muted">Next keys: {selected.nextRoleKeys.join(", ")}</p>
               )}
               <div className="cta-primary-row">
-                <button className="btn secondary" type="button" onClick={() => startEdit(selected)}>
-                  Edit role
-                </button>
                 <button className="btn secondary" type="button" disabled={busy} onClick={() => void deleteRole(selected)}>
-                  Delete
+                  Delete role
                 </button>
               </div>
             </>
           ) : (
             <p className="muted">Pick a role from the catalog or create one.</p>
           )}
-        </div>
+        </Section>
       </div>
 
       {editing && (
@@ -558,7 +576,7 @@ export function RolesPage() {
               Add expectation
             </button>
             <button className="btn" disabled={busy || !editor.title.trim()}>
-              {editor.id ? "Save changes" : "Create role"}
+              {editor.id ? "Save role changes" : "Create role"}
             </button>
             <button type="button" className="btn secondary" onClick={() => setEditing(false)}>
               Cancel
@@ -567,12 +585,17 @@ export function RolesPage() {
         </form>
       )}
 
-      <div className="panel page-section" id="roles-extract">
-        <h2>Extract from document</h2>
-        <p className="muted">
-          Upload an R&amp;R / career framework file (.txt/.md preferred; PDF/DOCX best-effort), or paste text.
-          With AI enabled this proposes RoleDefinitions; otherwise a local markdown/CSV parser runs.
-        </p>
+      <Section
+        id="roles-extract"
+        title="Extract from document"
+        when="Use when you have an R&R or career-framework file to turn into RoleDefinitions."
+        how="Upload or paste text, extract roles & levels, preview the drafts, then add or replace the catalog."
+        action={
+          <button type="button" className="btn" disabled={busy || !extractText.trim()} onClick={() => void runExtract()}>
+            {busy ? "Working…" : "Extract roles & levels"}
+          </button>
+        }
+      >
         <div className="field">
           <label htmlFor="fw-file">Framework file</label>
           <input
@@ -601,11 +624,6 @@ export function RolesPage() {
             available
           </label>
         </div>
-        <div className="cta-primary-row">
-          <button type="button" className="btn" disabled={busy || !extractText.trim()} onClick={() => void runExtract()}>
-            {busy ? "Working…" : "Extract roles & levels"}
-          </button>
-        </div>
         {extractMeta && <p className="muted">{extractMeta}</p>}
         {drafts.length > 0 && (
           <>
@@ -622,19 +640,29 @@ export function RolesPage() {
             </ul>
             <div className="cta-primary-row">
               <button type="button" className="btn" disabled={busy} onClick={() => void applyDrafts(false)}>
-                Add to catalog
+                Add drafts to catalog
               </button>
               <button type="button" className="btn secondary" disabled={busy} onClick={() => void applyDrafts(true)}>
-                Replace catalog
+                Replace catalog with drafts
               </button>
             </div>
           </>
         )}
-      </div>
+      </Section>
 
+      <Section
+        id="roles-assign"
+        title="Assign role"
+        when="Use when a direct is unassigned or their ladder level changed."
+        how="Pick the person, current RoleDefinition, and optional next role, then save the assignment."
+        action={
+          <button className="btn" type="submit" form="assign-role-form" disabled={!personId || !roleId}>
+            Save role assignment
+          </button>
+        }
+      >
       <form
         id="assign-role-form"
-        className="panel"
         onSubmit={async (e) => {
           e.preventDefault();
           await api("/api/roles/assign", {
@@ -650,7 +678,6 @@ export function RolesPage() {
           await load();
         }}
       >
-        <h2>Assign role</h2>
         <p className="muted">
           {selectedPerson
             ? `Editing ${selectedPerson.name}${selectedPerson.roleTitle ? ` (currently ${selectedPerson.roleTitle})` : " (unassigned)"}.`
@@ -690,13 +717,9 @@ export function RolesPage() {
             </select>
           </div>
         </div>
-        <div className="cta-primary-row">
-          <button className="btn" disabled={!personId || !roleId}>
-            Save assignment
-          </button>
-          {saved && <span className="muted">{saved}</span>}
-        </div>
+        {saved && <p className="muted">{saved}</p>}
       </form>
+      </Section>
       </PageSectionsLayout>
     </div>
   );
diff --git a/apps/ui/src/pages/SprintPulsePage.tsx b/apps/ui/src/pages/SprintPulsePage.tsx
index 2c98617..9c1e797 100644
--- a/apps/ui/src/pages/SprintPulsePage.tsx
+++ b/apps/ui/src/pages/SprintPulsePage.tsx
@@ -2,7 +2,7 @@ import { useEffect, useState } from "react";
 import { Link, useSearchParams } from "react-router-dom";
 import type { SprintPulseDTO } from "@prm/shared";
 import { api } from "../lib/api";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout } from "../components/PageSectionsLayout";
 
 const PRESETS = [
@@ -48,7 +48,7 @@ export function SprintPulsePage() {
       <PageHeader
         title="Sprint pulse"
         job="Mid-cycle coaching view: what landed in a date window, not final ratings."
-        primary={<Link className="btn secondary" to="/team-performance">Team performance</Link>}
+        primary={<Link className="btn secondary" to="/team-performance">Open team performance</Link>}
       />
 
       {error && (
@@ -72,7 +72,12 @@ export function SprintPulsePage() {
           { id: "pulse-people", label: "People" },
         ]}
       >
-      <div className="panel stack page-section" id="pulse-window">
+      <Section
+        id="pulse-window"
+        title="Date window"
+        when="Use mid-cycle when you want a coaching snapshot for a sprint or recent weeks."
+        how="Pick a preset or custom from/to dates — counts and people rows update to that range."
+      >
         <div className="row" style={{ flexWrap: "wrap", gap: 12, alignItems: "end" }}>
           <div className="field" style={{ marginBottom: 0 }}>
             <label htmlFor="pulse-preset">Preset</label>
@@ -119,11 +124,7 @@ export function SprintPulsePage() {
             />
           </div>
         </div>
-        <p className="muted" style={{ margin: 0 }}>
-          Counts achievements (including Jira / Bitbucket sync), feedback themes, documents, and open
-          concerns dated in the window. Flags people whose manager-draft cites are all older than the window.
-        </p>
-      </div>
+      </Section>
 
       {!data ? (
         <p>Loading…</p>
@@ -137,7 +138,7 @@ export function SprintPulsePage() {
                 ? `${data.summary.staleCitePeople} draft(s) only cite older evidence. Prefer fresher cites before finalize.`
                 : "Evidence freshness looks healthy for drafts that have cites."
             }
-            action={<Link className="btn secondary" to="/team">Open team</Link>}
+            action={<Link className="btn secondary" to="/team">Open team roster</Link>}
           />
 
           <div className="tp-metrics">
@@ -165,8 +166,12 @@ export function SprintPulsePage() {
           </div>
 
           <div className="tp-grid">
-            <div className="panel stack page-section" id="pulse-themes">
-              <h2 style={{ margin: 0 }}>1:1 themes in window</h2>
+            <Section
+              id="pulse-themes"
+              title="1:1 themes in window"
+              when="Use after 1:1s to see which coaching themes recurred in this date range."
+              how="Scan the bars — high counts flag topics to revisit in the next 1:1."
+            >
               {data.themes.length === 0 ? (
                 <p className="muted">No themes tagged on feedback in this range.</p>
               ) : (
@@ -187,12 +192,14 @@ export function SprintPulsePage() {
                   ))}
                 </div>
               )}
-            </div>
-            <div className="panel stack page-section" id="pulse-freshness">
-              <h2 style={{ margin: 0 }}>Evidence freshness</h2>
-              <p className="muted" style={{ margin: 0 }}>
-                In-window dossier items vs older items, plus whether current draft cites are stale.
-              </p>
+            </Section>
+            <Section
+              id="pulse-freshness"
+              title="Evidence freshness"
+              when="Use before finalize when drafts may only cite older evidence."
+              how="Check stale-only cite count, then open people rows below to refresh links in dossiers."
+              action={<Link className="btn secondary" to="/team">Open team roster</Link>}
+            >
               <ul className="muted" style={{ margin: 0 }}>
                 <li>
                   <strong>{data.summary.staleCitePeople}</strong> people with stale-only cites
@@ -205,11 +212,16 @@ export function SprintPulsePage() {
                   synced tickets / PRs in window
                 </li>
               </ul>
-            </div>
+            </Section>
           </div>
 
-          <div className="panel stack page-section" id="pulse-people">
-            <h2 style={{ margin: 0 }}>People</h2>
+          <Section
+            id="pulse-people"
+            title="People"
+            when="Use when coaching individuals mid-cycle or hunting stale cites."
+            how="Scan each row, then open a dossier to capture fresh evidence or review open concerns."
+            action={<Link className="btn secondary" to="/team">Open team roster</Link>}
+          >
             <div className="table-wrap">
               <table className="table">
                 <thead>
@@ -250,7 +262,7 @@ export function SprintPulsePage() {
                       </td>
                       <td>
                         <Link className="btn secondary" to={`/team/${p.personId}`}>
-                          Dossier
+                          Open dossier
                         </Link>
                       </td>
                     </tr>
@@ -258,7 +270,7 @@ export function SprintPulsePage() {
                 </tbody>
               </table>
             </div>
-          </div>
+          </Section>
         </>
       )}
       </PageSectionsLayout>

From 5ad13c2db284ea50be3154ce88110880c9e961f8 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 26 Jul 2026 04:44:43 +0000
Subject: [PATCH 2/3] Wrap Person, Writing Desk, Team Performance, and Promo
 detail sections for WCAG scan.

Apply the shared Section component (When/How + clearer CTAs) to sticky-nav sections while keeping existing anchor ids.

Co-authored-by: Damon  <Modsofthenation@users.noreply.github.com>
---
 apps/ui/src/pages/PersonPage.tsx          | 168 ++++++++-------
 apps/ui/src/pages/PromotionDetailPage.tsx |  44 ++--
 apps/ui/src/pages/TeamPerformancePage.tsx | 109 ++++++----
 apps/ui/src/pages/WritingDeskPage.tsx     | 240 ++++++++++++++--------
 4 files changed, 342 insertions(+), 219 deletions(-)

diff --git a/apps/ui/src/pages/PersonPage.tsx b/apps/ui/src/pages/PersonPage.tsx
index ef8c65e..bba036a 100644
--- a/apps/ui/src/pages/PersonPage.tsx
+++ b/apps/ui/src/pages/PersonPage.tsx
@@ -12,7 +12,7 @@ import type {
   PersonTimelineDTO,
 } from "@prm/shared";
 import { api, getToken, apiUrl } from "../lib/api";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout, type SectionNavItem } from "../components/PageSectionsLayout";
 import { DeliveryRollupPanel } from "../components/DeliveryRollupPanel";
 
@@ -170,34 +170,12 @@ export function PersonPage() {
 
       <PageSectionsLayout sections={sections}>
       {activeCycle && (
-        <div className="panel stack page-section" id="person-reassign">
-          <h2 style={{ margin: 0 }}>Mid-cycle manager change</h2>
-          <p className="muted" style={{ margin: 0 }}>
-            Reassign for <strong>{activeCycle.name}</strong>: supersedes prior manager drafts/finals as contribution
-            history and opens a fresh draft for the new manager.
-          </p>
-          <div className="row" style={{ alignItems: "end" }}>
-            <div className="field" style={{ margin: 0, minWidth: 220 }}>
-              <label>New manager</label>
-              <select value={reassignManagerId} onChange={(e) => setReassignManagerId(e.target.value)}>
-                <option value="">Select…</option>
-                {roster
-                  .filter((p) => p.id !== person.id)
-                  .map((p) => (
-                    <option key={p.id} value={p.id}>
-                      {p.name}
-                    </option>
-                  ))}
-              </select>
-            </div>
-            <div className="field" style={{ margin: 0, flex: 1 }}>
-              <label>Reason</label>
-              <input
-                value={reassignReason}
-                onChange={(e) => setReassignReason(e.target.value)}
-                placeholder="Org change / coverage"
-              />
-            </div>
+        <Section
+          id="person-reassign"
+          title="Mid-cycle manager change"
+          when={`Use when coverage or org changes mid-${activeCycle.name} and a new manager owns the draft.`}
+          how="Pick the new manager and reason, then reassign — prior drafts become contribution history."
+          action={
             <button
               type="button"
               className="btn secondary"
@@ -225,17 +203,41 @@ export function PersonPage() {
             >
               Reassign in cycle
             </button>
+          }
+        >
+          <div className="row" style={{ alignItems: "end" }}>
+            <div className="field" style={{ margin: 0, minWidth: 220 }}>
+              <label>New manager</label>
+              <select value={reassignManagerId} onChange={(e) => setReassignManagerId(e.target.value)}>
+                <option value="">Select…</option>
+                {roster
+                  .filter((p) => p.id !== person.id)
+                  .map((p) => (
+                    <option key={p.id} value={p.id}>
+                      {p.name}
+                    </option>
+                  ))}
+              </select>
+            </div>
+            <div className="field" style={{ margin: 0, flex: 1 }}>
+              <label>Reason</label>
+              <input
+                value={reassignReason}
+                onChange={(e) => setReassignReason(e.target.value)}
+                placeholder="Org change / coverage"
+              />
+            </div>
           </div>
           {reassignMsg && <p className="muted">{reassignMsg}</p>}
-        </div>
+        </Section>
       )}
 
-      <div className="panel stack page-section" id="timeline">
-        <h2 style={{ margin: 0 }}>Timeline</h2>
-        <p className="muted" style={{ margin: 0 }}>
-          Chronological dossier, reviews, concerns, and rating decisions. Use this to prep a 1:1 or reconstruct
-          why the story changed.
-        </p>
+      <Section
+        id="timeline"
+        title="Timeline"
+        when="Use before a 1:1 or when reconstructing why the performance story changed."
+        how="Scan chronological dossier events, reviews, concerns, and rating decisions below."
+      >
         {!timeline || timeline.entries.length === 0 ? (
           <p className="muted">No timeline events yet.</p>
         ) : (
@@ -249,14 +251,19 @@ export function PersonPage() {
             ))}
           </ul>
         )}
-      </div>
+      </Section>
 
-      <div className="panel stack page-section" id="integrations">
-        <h2>Integrations</h2>
-        <p className="muted">
-          Link remote accounts, then pull tickets / merged PRs for the active review window into achievements.
-          Configure credentials in <Link to="/settings">Settings → Integrations</Link>.
-        </p>
+      <Section
+        id="integrations"
+        title="Integrations"
+        when="Use when you need tickets or merged PRs from the review window on this dossier."
+        how="Search and link remote accounts, then sync into achievements. Credentials live in Settings."
+        action={
+          <Link className="btn secondary" to="/settings">
+            Open integration settings
+          </Link>
+        }
+      >
         {extLinks.length === 0 ? (
           <p className="muted">No external accounts linked yet.</p>
         ) : (
@@ -318,7 +325,7 @@ export function PersonPage() {
               }
             }}
           >
-            Search
+            Search remote users
           </button>
           <button
             type="button"
@@ -400,20 +407,24 @@ export function PersonPage() {
                     await load();
                   }}
                 >
-                  Link
+                  Link account
                 </button>
               </li>
             ))}
           </ul>
         )}
         {linkMsg && <p className="muted">{linkMsg}</p>}
-      </div>
+      </Section>
 
       {id ? <DeliveryRollupPanel personId={id} cycleId={cycles[0]?.id} /> : null}
 
       <div className="grid-2">
-        <div className="panel page-section" id="capture-achievements">
-          <h2>Achievements</h2>
+        <Section
+          id="capture-achievements"
+          title="Achievements"
+          when="Use after a ship, unblock, or win you want on the review dossier."
+          how="Scan linked or manual items below, then add a short titled achievement."
+        >
           <ul>
             {dossier.achievements.map((a) => (
               <li key={a.id}>
@@ -443,9 +454,13 @@ export function PersonPage() {
             <input value={achTitle} onChange={(e) => setAchTitle(e.target.value)} placeholder="Shipped X / unblocked Y…" required />
             <button className="btn">Add achievement</button>
           </form>
-        </div>
-        <div className="panel page-section" id="person-goals">
-          <h2>Goals</h2>
+        </Section>
+        <Section
+          id="person-goals"
+          title="Goals"
+          when="Use when setting or refreshing outcome-oriented goals for this person."
+          how="Review status on existing goals, then add a new outcome-oriented title."
+        >
           <ul>
             {dossier.goals.map((g) => (
               <li key={g.id}><strong>{g.title}</strong> <span className="flag">{g.status}</span></li>
@@ -464,12 +479,15 @@ export function PersonPage() {
             <input value={goalTitle} onChange={(e) => setGoalTitle(e.target.value)} placeholder="Outcome-oriented goal" required />
             <button className="btn">Add goal</button>
           </form>
-        </div>
+        </Section>
       </div>
 
-      <div className="panel stack page-section" id="person-feedback">
-        <h2>Feedback</h2>
-        <p className="muted">EM-entered notes from 1:1s, partners, or incidents. Author names stay on your workspace.</p>
+      <Section
+        id="person-feedback"
+        title="Feedback"
+        when="Use after a 1:1, partner sync, or incident while the detail is fresh."
+        how="Read existing notes, then add from/kind/themes and a specific behavioral note."
+      >
         {dossier.feedback.length === 0 && <p className="muted">No feedback yet — capture a coaching or praise note.</p>}
         {dossier.feedback.map((f) => (
           <p key={f.id}>
@@ -532,11 +550,14 @@ export function PersonPage() {
           </div>
           <button className="btn">Add feedback</button>
         </form>
-      </div>
+      </Section>
 
-      <div className="panel stack page-section" id="person-documents">
-        <h2>Documents</h2>
-        <p className="muted">PDF/DOCX/PPTX/CSV/images — allowlisted. Sealed into the encrypted vault when you lock the workspace.</p>
+      <Section
+        id="person-documents"
+        title="Documents"
+        when="Use when attaching review artifacts, exports, or evidence files to the dossier."
+        how="Download existing files or upload an allowlisted PDF/DOCX/PPTX/CSV/image (sealed on lock)."
+      >
         <ul>
           {(dossier.documents ?? []).map((d) => (
             <li key={d.id}>
@@ -592,16 +613,16 @@ export function PersonPage() {
           <button className="btn" disabled={!docFile}>Upload document</button>
           {docMsg && <p className="muted">{docMsg}</p>}
         </form>
-      </div>
+      </Section>
 
       {captureMsg && <p className="muted">{captureMsg}</p>}
 
-      <div className="panel stack page-section" id="person-meetings">
-        <h2>Meeting summaries</h2>
-        <p className="muted">
-          Structured notes from 1:1s / meetings. Default visibility is <strong>EM only</strong>. Raw transcripts stay
-          private on the dossier. Confirm consent before storing — local vault notes are not a legal privilege.
-        </p>
+      <Section
+        id="person-meetings"
+        title="Meeting summaries"
+        when="Use after a 1:1 or meeting when you want structured notes on the dossier."
+        how="Paste or load a transcript, confirm consent, optionally summarize with AI, then save (EM-only)."
+      >
         {meetings.length === 0 ? (
           <p className="muted">No meeting summaries yet.</p>
         ) : (
@@ -721,13 +742,14 @@ export function PersonPage() {
             Save meeting summary
           </button>
         </form>
-      </div>
+      </Section>
 
-      <div className="panel stack page-section" id="person-concerns">
-        <h2>Concern log</h2>
-        <p className="muted">
-          Private performance concerns and follow-up plans. AI is off by default — these stay out of digests and drafts unless you later opt a concern in.
-        </p>
+      <Section
+        id="person-concerns"
+        title="Concern log"
+        when="Use when a performance concern needs a private record and follow-up plan."
+        how="Log title, body, expectation, and plan. Toggle open/closed or AI opt-in per concern — AI stays off by default."
+      >
         {concerns.length === 0 ? (
           <p className="muted">No concerns logged.</p>
         ) : (
@@ -828,7 +850,7 @@ export function PersonPage() {
           </div>
           <button className="btn">Add concern</button>
         </form>
-      </div>
+      </Section>
 
       {person.targetNextRoleTitle && (
         <NextStep
diff --git a/apps/ui/src/pages/PromotionDetailPage.tsx b/apps/ui/src/pages/PromotionDetailPage.tsx
index b618845..f8d5ea6 100644
--- a/apps/ui/src/pages/PromotionDetailPage.tsx
+++ b/apps/ui/src/pages/PromotionDetailPage.tsx
@@ -2,7 +2,7 @@ import { useEffect, useState } from "react";
 import { Link, useParams } from "react-router-dom";
 import type { GapMark, RoleDefinitionDTO } from "@prm/shared";
 import { api, getToken, apiUrl } from "../lib/api";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout } from "../components/PageSectionsLayout";
 
 type PromoDetail = {
@@ -199,9 +199,12 @@ export function PromotionDetailPage() {
         ]}
       >
       <div className="writing">
-        <div className="panel stack page-section" id="promo-expectations">
-          <div className="row">
-            <h2 style={{ flex: 1, margin: 0 }}>Next-role expectations</h2>
+        <Section
+          id="promo-expectations"
+          title="Next-role expectations"
+          when="Use when assessing readiness against the target role definition."
+          how="Mark each expectation as demonstrating, emerging, or not yet — optionally AI-draft the case first."
+          action={
             <button
               className="btn secondary"
               onClick={async () => {
@@ -226,9 +229,10 @@ export function PromotionDetailPage() {
                 }
               }}
             >
-              AI draft case
+              AI draft promotion case
             </button>
-          </div>
+          }
+        >
           {(detail.targetRole?.expectations ?? []).map((e) => (
             <div key={e.id} className="field">
               <label><span className="flag">{e.kind}</span> {e.text}</label>
@@ -243,10 +247,26 @@ export function PromotionDetailPage() {
             </div>
           ))}
           {aiOut && <pre className="digest">{aiOut}</pre>}
-        </div>
+        </Section>
 
-        <div className="panel stack page-section" id="promo-narrative">
-          <h2>Case narrative</h2>
+        <Section
+          id="promo-narrative"
+          title="Case narrative"
+          when="Use when writing or updating the promotion packet before submit."
+          how="Fill summary, demonstrated scope, gaps, and recommendation — then save draft or submit."
+          action={
+            !submitted ? (
+              <>
+                <button className="btn secondary" onClick={() => save("draft")}>
+                  Save packet draft
+                </button>
+                <button className="btn" onClick={() => save("submitted")}>
+                  Submit promotion packet
+                </button>
+              </>
+            ) : undefined
+          }
+        >
           <div className="field">
             <label>Case summary</label>
             <textarea value={summary} onChange={(e) => setSummary(e.target.value)} />
@@ -277,11 +297,11 @@ export function PromotionDetailPage() {
           </div>
           {!submitted && (
             <div className="cta-primary-row">
-              <button className="btn secondary" onClick={() => save("draft")}>Save draft</button>
-              <button className="btn" onClick={() => save("submitted")}>Submit packet</button>
+              <button className="btn secondary" onClick={() => save("draft")}>Save packet draft</button>
+              <button className="btn" onClick={() => save("submitted")}>Submit promotion packet</button>
             </div>
           )}
-        </div>
+        </Section>
       </div>
       </PageSectionsLayout>
     </div>
diff --git a/apps/ui/src/pages/TeamPerformancePage.tsx b/apps/ui/src/pages/TeamPerformancePage.tsx
index 52c1408..7ad673b 100644
--- a/apps/ui/src/pages/TeamPerformancePage.tsx
+++ b/apps/ui/src/pages/TeamPerformancePage.tsx
@@ -4,7 +4,7 @@ import type { CycleCompareDTO, CycleDTO, RatingTrendsDTO, TeamPerformanceDTO } f
 import { competencyLabel } from "@prm/shared";
 import { api } from "../lib/api";
 import { openHtmlExport } from "../lib/exports";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout, type SectionNavItem } from "../components/PageSectionsLayout";
 
 const PROMO_LABELS: Record<string, string> = {
@@ -344,30 +344,43 @@ export function TeamPerformancePage() {
               { id: "tp-compare", label: "Compare" },
             ] satisfies SectionNavItem[]}
           >
-          <div className="tp-metrics page-section" id="tp-overview">
-            <div className="tp-metric">
-              <div className="muted">Avg overall</div>
-              <strong>{data.avgOverall ?? "—"}</strong>
-            </div>
-            <div className="tp-metric">
-              <div className="muted">Evidence coverage</div>
-              <strong>{data.evidence.coveragePct}%</strong>
-              <span className="muted"> · avg {data.evidence.avgLinkedSources} sources</span>
-            </div>
-            <div className="tp-metric">
-              <div className="muted">Thin dossiers</div>
-              <strong>{data.evidence.thinDossierCount}</strong>
-              <span className="muted"> / {data.participantCount}</span>
-            </div>
-            <div className="tp-metric">
-              <div className="muted">Open concerns</div>
-              <strong>{data.openConcerns}</strong>
+          <Section
+            id="tp-overview"
+            title="Overview"
+            when="Use first to see whether this cycle’s ratings, evidence, and concerns look healthy."
+            how="Read the four metrics below, then drill into charts or people when something looks off."
+          >
+            <div className="tp-metrics">
+              <div className="tp-metric">
+                <div className="muted">Avg overall</div>
+                <strong>{data.avgOverall ?? "—"}</strong>
+              </div>
+              <div className="tp-metric">
+                <div className="muted">Evidence coverage</div>
+                <strong>{data.evidence.coveragePct}%</strong>
+                <span className="muted"> · avg {data.evidence.avgLinkedSources} sources</span>
+              </div>
+              <div className="tp-metric">
+                <div className="muted">Thin dossiers</div>
+                <strong>{data.evidence.thinDossierCount}</strong>
+                <span className="muted"> / {data.participantCount}</span>
+              </div>
+              <div className="tp-metric">
+                <div className="muted">Open concerns</div>
+                <strong>{data.openConcerns}</strong>
+              </div>
             </div>
-          </div>
+          </Section>
 
-          <div className="tp-grid page-section" id="tp-charts">
+          <Section
+            id="tp-charts"
+            title="Charts"
+            when="Use mid-cycle or before finalize to spot clustering, thin evidence, or promo skew."
+            how="Scan each chart panel — distribution, evidence scatter, competencies, promo, writing time, levels, and themes."
+          >
+            <div className="tp-grid">
             <div className="panel stack">
-              <h2 style={{ margin: 0 }}>Overall distribution</h2>
+              <h3 style={{ margin: 0 }}>Overall distribution</h3>
               <p className="muted" style={{ margin: 0 }}>
                 Watch for clustering (everyone a 3 or 4) before you finalize.
               </p>
@@ -375,7 +388,7 @@ export function TeamPerformancePage() {
             </div>
 
             <div className="panel stack">
-              <h2 style={{ margin: 0 }}>Evidence vs overall</h2>
+              <h3 style={{ margin: 0 }}>Evidence vs overall</h3>
               <p className="muted" style={{ margin: 0 }}>
                 Thin dossiers sit lower; extreme scores should sit higher.
               </p>
@@ -383,7 +396,7 @@ export function TeamPerformancePage() {
             </div>
 
             <div className="panel stack">
-              <h2 style={{ margin: 0 }}>Competency averages</h2>
+              <h3 style={{ margin: 0 }}>Competency averages</h3>
               <p className="muted" style={{ margin: 0 }}>
                 Team mean on the 1–5 scale (people with that competency scored).
               </p>
@@ -410,7 +423,7 @@ export function TeamPerformancePage() {
             </div>
 
             <div className="panel stack">
-              <h2 style={{ margin: 0 }}>Promo readiness</h2>
+              <h3 style={{ margin: 0 }}>Promo readiness</h3>
               <BarChart
                 rows={Object.entries(data.promoReadiness).map(([key, count]) => ({
                   key,
@@ -422,7 +435,7 @@ export function TeamPerformancePage() {
             </div>
 
             <div className="panel stack">
-              <h2 style={{ margin: 0 }}>Writing time</h2>
+              <h3 style={{ margin: 0 }}>Writing time</h3>
               <BarChart
                 rows={data.writingBuckets.map((b) => ({
                   key: b.id,
@@ -434,7 +447,7 @@ export function TeamPerformancePage() {
             </div>
 
             <div className="panel stack">
-              <h2 style={{ margin: 0 }}>Levels</h2>
+              <h3 style={{ margin: 0 }}>Levels</h3>
               {data.levels.length === 0 ? (
                 <p className="muted">No people in this cycle.</p>
               ) : (
@@ -450,7 +463,7 @@ export function TeamPerformancePage() {
             </div>
 
             <div className="panel stack tp-span-2">
-              <h2 style={{ margin: 0 }}>1:1 themes</h2>
+              <h3 style={{ margin: 0 }}>1:1 themes</h3>
               <p className="muted" style={{ margin: 0 }}>
                 Tags from feedback notes across the team (year-round coaching signal).
               </p>
@@ -467,10 +480,15 @@ export function TeamPerformancePage() {
                 />
               )}
             </div>
-          </div>
+            </div>
+          </Section>
 
-          <div className="panel stack page-section" id="tp-people">
-            <h2 style={{ margin: 0 }}>People</h2>
+          <Section
+            id="tp-people"
+            title="People"
+            when="Use to find individuals with thin evidence, rating deltas, or open writing work."
+            how="Sort the table visually, then open a writing desk for anyone who needs a draft update."
+          >
             <div className="table-wrap">
               <table className="table">
                 <thead>
@@ -546,7 +564,7 @@ export function TeamPerformancePage() {
                         </td>
                         <td>
                           <Link className="btn secondary" to={`/cycles/${data.cycleId}/write/${p.personId}`}>
-                            Desk
+                            Open writing desk
                           </Link>
                         </td>
                       </tr>
@@ -555,15 +573,15 @@ export function TeamPerformancePage() {
                 </tbody>
               </table>
             </div>
-          </div>
+          </Section>
 
           {trends && trends.cycles.length > 0 && (
-            <div className="tp-grid page-section" id="tp-trends">
-              <div className="panel stack tp-span-2">
-                <h2 style={{ margin: 0 }}>Rating trends across cycles</h2>
-                <p className="muted" style={{ margin: 0 }}>
-                  Team averages (manager ratings). Spot stagnation or sudden jumps before the next packet.
-                </p>
+            <Section
+              id="tp-trends"
+              title="Rating trends across cycles"
+              when="Use when you have multiple cycles and want to spot stagnation or sudden jumps."
+              how="Read team average sparklines and per-cycle cells before the next packet."
+            >
                 <div className="table-wrap">
                   <table className="table">
                     <thead>
@@ -596,13 +614,16 @@ export function TeamPerformancePage() {
                     </tbody>
                   </table>
                 </div>
-              </div>
-            </div>
+            </Section>
           )}
 
           {compare && (
-            <div className="panel stack page-section" id="tp-compare">
-              <h2 style={{ margin: 0 }}>Cycle compare</h2>
+            <Section
+              id="tp-compare"
+              title="Cycle compare"
+              when="Use after a new cycle has ratings to see what moved versus the prior window."
+              how="Compare distribution shift, movers (±1+), repeat thin dossiers, and theme drift below."
+            >
               <p className="muted" style={{ margin: 0 }}>
                 {compare.prior
                   ? `${compare.prior.cycleName} → ${compare.current.cycleName}`
@@ -675,7 +696,7 @@ export function TeamPerformancePage() {
               ) : (
                 <p className="muted">Add another cycle with ratings to unlock compare.</p>
               )}
-            </div>
+            </Section>
           )}
           </PageSectionsLayout>
         </>
diff --git a/apps/ui/src/pages/WritingDeskPage.tsx b/apps/ui/src/pages/WritingDeskPage.tsx
index 27acf3d..12b0832 100644
--- a/apps/ui/src/pages/WritingDeskPage.tsx
+++ b/apps/ui/src/pages/WritingDeskPage.tsx
@@ -5,7 +5,7 @@ import { COMPETENCY_CATALOG, MIDDLE_BAND, competencyLabel } from "@prm/shared";
 import { api, getToken, apiUrl } from "../lib/api";
 import { estimateThenConfirm } from "../lib/aiEstimate";
 import { openHtmlExport } from "../lib/exports";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout, type SectionNavItem } from "../components/PageSectionsLayout";
 import { DeliveryRollupPanel } from "../components/DeliveryRollupPanel";
 
@@ -487,9 +487,12 @@ export function WritingDeskPage() {
 
       <PageSectionsLayout sections={sections}>
       {hasOutOfWindow && outOfWindowTray && (
-        <div className="panel page-section" id="desk-oow">
-          <h2>Out of window</h2>
-          <p className="muted">Evidence dated outside the cycle window — still citable.</p>
+        <Section
+          id="desk-oow"
+          title="Out of window"
+          when="Use when evidence falls outside the cycle window but you still want to cite it."
+          how="Scan dated-out achievements, feedback, and documents below — they remain citable."
+        >
           <ul>
             {outOfWindowTray.achievements.map((a) => (
               <li key={a.id}>
@@ -508,69 +511,75 @@ export function WritingDeskPage() {
               </li>
             ))}
           </ul>
-        </div>
+        </Section>
       )}
 
       <div className="writing">
         <div className="stack">
           {personId ? <DeliveryRollupPanel personId={personId} cycleId={cycleId} /> : null}
-          <div className="panel stack page-section" id="desk-digest">
-            <div className="row">
-              <h2 style={{ flex: 1, margin: 0 }}>Evidence digest</h2>
-              <button
-                className="btn secondary"
-                type="button"
-                onClick={async () => {
-                  const ok = await estimateThenConfirm(
-                    "evidence_digest",
-                    { cycleId, personId },
-                    "Generate evidence digest",
-                  );
-                  if (!ok) return;
-                  const res = await api<{ outputText: string; citeSuggestions?: DeliveryCiteSuggestion[] }>(
-                    "/api/ai/digest",
-                    {
+          <Section
+            id="desk-digest"
+            title="Evidence digest"
+            when="Use before drafting to ground the story in dossier and import evidence."
+            how="Generate a digest, optional skip-level talking points, or open a director briefing card."
+            action={
+              <>
+                <button
+                  className="btn secondary"
+                  type="button"
+                  onClick={async () => {
+                    const ok = await estimateThenConfirm(
+                      "evidence_digest",
+                      { cycleId, personId },
+                      "Generate evidence digest",
+                    );
+                    if (!ok) return;
+                    const res = await api<{ outputText: string; citeSuggestions?: DeliveryCiteSuggestion[] }>(
+                      "/api/ai/digest",
+                      {
+                        method: "POST",
+                        body: JSON.stringify({ cycleId, personId }),
+                      },
+                    );
+                    setDigest(res.outputText);
+                    setCiteSuggestions(res.citeSuggestions ?? []);
+                  }}
+                >
+                  Generate evidence digest
+                </button>
+                <button
+                  className="btn secondary"
+                  type="button"
+                  onClick={async () => {
+                    const ok = await estimateThenConfirm(
+                      "skip_level_talking_points",
+                      { cycleId, personId },
+                      "Generate skip-level talking points",
+                    );
+                    if (!ok) return;
+                    const res = await api<{ outputText: string }>("/api/ai/skip-level-talking-points", {
                       method: "POST",
                       body: JSON.stringify({ cycleId, personId }),
-                    },
-                  );
-                  setDigest(res.outputText);
-                  setCiteSuggestions(res.citeSuggestions ?? []);
-                }}
-              >
-                Generate digest
-              </button>
-              <button
-                className="btn secondary"
-                type="button"
-                onClick={async () => {
-                  const ok = await estimateThenConfirm(
-                    "skip_level_talking_points",
-                    { cycleId, personId },
-                    "Generate skip-level talking points",
-                  );
-                  if (!ok) return;
-                  const res = await api<{ outputText: string }>("/api/ai/skip-level-talking-points", {
-                    method: "POST",
-                    body: JSON.stringify({ cycleId, personId }),
-                  });
-                  setSkipLevel(res.outputText);
-                }}
-              >
-                Skip-level talking points
-              </button>
-              <button
-                className="btn ghost"
-                type="button"
-                onClick={() =>
-                  void openHtmlExport(
-                    `/api/exports/director-briefing/${cycleId}?personId=${encodeURIComponent(personId ?? "")}&format=html`,
-                  )
-                }
-              >
-                Director card
-              </button>
-            </div>
+                    });
+                    setSkipLevel(res.outputText);
+                  }}
+                >
+                  Generate skip-level talking points
+                </button>
+                <button
+                  className="btn ghost"
+                  type="button"
+                  onClick={() =>
+                    void openHtmlExport(
+                      `/api/exports/director-briefing/${cycleId}?personId=${encodeURIComponent(personId ?? "")}&format=html`,
+                    )
+                  }
+                >
+                  Open director briefing card
+                </button>
+              </>
+            }
+          >
             <div className="digest">{digest ?? "Generate a grounded digest from dossier + imports before drafting."}</div>
             {skipLevel && (
               <div>
@@ -606,9 +615,13 @@ export function WritingDeskPage() {
                 </ul>
               </div>
             )}
-          </div>
-          <div className="panel page-section" id="desk-expectations">
-            <h2>Current role expectations</h2>
+          </Section>
+          <Section
+            id="desk-expectations"
+            title="Current role expectations"
+            when="Use while scoring role fit so ratings stay tied to the assigned role definition."
+            how="Read each expectation kind and text below as you draft competencies and narrative."
+          >
             <ol>
               {(packet.currentRole?.expectations ?? []).map((e) => (
                 <li key={e.id}>
@@ -616,10 +629,13 @@ export function WritingDeskPage() {
                 </li>
               ))}
             </ol>
-          </div>
-          <div className="panel page-section" id="desk-peer">
-            <div className="row" style={{ justifyContent: "space-between", alignItems: "center" }}>
-              <h2 style={{ margin: 0 }}>Peer synthesize</h2>
+          </Section>
+          <Section
+            id="desk-peer"
+            title="Peer synthesize"
+            when="Use when peer imports exist and you want themes instead of raw JSON."
+            how="Run the roll-up to get strength/growth themes (authors stay EM-visible here)."
+            action={
               <button
                 className="btn secondary"
                 type="button"
@@ -638,25 +654,30 @@ export function WritingDeskPage() {
                   setPeerSynth(res.outputText);
                 }}
               >
-                Roll up themes
+                Synthesize peer themes
               </button>
-            </div>
+            }
+          >
             <p className="muted">
               {packet.peerReviews.length
-                ? `${packet.peerReviews.length} peer import(s) — synthesize themes instead of reading raw JSON.`
-                : "No peer imports yet."}
+                ? `${packet.peerReviews.length} peer import(s) available.`
+                : "No peer imports yet — import peer bundles from Cycles first."}
             </p>
             <div className="digest">
               {peerSynth ??
                 (packet.peerReviews.length
-                  ? "Run roll-up to get strength/growth themes (authors stay EM-visible here; hidden in subject packet)."
+                  ? "Run synthesize to get strength/growth themes (authors stay EM-visible here; hidden in subject packet)."
                   : "Import peer bundles from Cycles first.")}
             </div>
-          </div>
+          </Section>
 
           {packet.priorCycle && (
-            <div className="panel page-section" id="desk-prior">
-              <h2>Prior cycle — {packet.priorCycle.cycleName}</h2>
+            <Section
+              id="desk-prior"
+              title={`Prior cycle — ${packet.priorCycle.cycleName}`}
+              when="Use to compare continuity with the previous review window before changing scores."
+              how="Read prior overall, summary, strengths, and growth — then mirror or deliberately diverge with a reason."
+            >
               <p className="muted">
                 Ended {packet.priorCycle.windowEnd}
                 {packet.priorCycle.overall != null ? ` · Overall ${packet.priorCycle.overall}/5` : ""}
@@ -676,11 +697,22 @@ export function WritingDeskPage() {
                   <strong>Growth:</strong> {packet.priorCycle.growthAreas}
                 </p>
               )}
-            </div>
+            </Section>
           )}
 
-          <div className="panel page-section" id="desk-timeline">
-            <h2>Person timeline</h2>
+          <Section
+            id="desk-timeline"
+            title="Person timeline"
+            when="Use for quick dossier context while writing without leaving the desk."
+            how="Scan recent milestones below; open the person page for the full chronology."
+            action={
+              personId ? (
+                <Link className="btn secondary" to={`/team/${personId}`}>
+                  Open person dossier
+                </Link>
+              ) : undefined
+            }
+          >
             {(packet.timeline ?? []).length === 0 ? (
               <p className="muted">No dossier milestones yet.</p>
             ) : (
@@ -696,10 +728,14 @@ export function WritingDeskPage() {
                 ))}
               </ul>
             )}
-          </div>
+          </Section>
 
-          <div className="panel page-section" id="desk-imports">
-            <h2>Imports & dossier</h2>
+          <Section
+            id="desk-imports"
+            title="Imports & dossier"
+            when="Use to verify self-review, achievements, feedback, and frozen citations before finalize."
+            how="Check self-review status, then cite achievement/feedback IDs from the lists below."
+          >
             <p>
               <strong>Self:</strong> {packet.selfReview ? "imported" : "missing"}
             </p>
@@ -740,11 +776,35 @@ export function WritingDeskPage() {
                 </ul>
               </>
             )}
-          </div>
+          </Section>
         </div>
 
-        <div className="panel stack page-section" id="desk-draft">
-          <h2>Manager draft</h2>
+        <Section
+          id="desk-draft"
+          title="Manager draft"
+          when="Use throughout the cycle to score, write narrative, and finalize the manager review."
+          how="Set overall and competencies with evidence links, draft the narrative fields, then save or finalize."
+          action={
+            !finalized ? (
+              <>
+                <button className="btn secondary" type="button" onClick={() => void save("draft")}>
+                  Save manager draft
+                </button>
+                <button className="btn" type="button" onClick={() => void save("finalized")}>
+                  Finalize review
+                </button>
+              </>
+            ) : (
+              <button
+                className="btn secondary"
+                type="button"
+                onClick={() => void openSubjectHtml()}
+              >
+                Open HTML packet
+              </button>
+            )
+          }
+        >
           <div className="field">
             <label>Overall (1–5)</label>
             <input
@@ -891,7 +951,7 @@ export function WritingDeskPage() {
                   markDirty();
                 }}
               >
-                AI draft
+                AI draft this section
               </button>
             </label>
             <textarea
@@ -925,7 +985,7 @@ export function WritingDeskPage() {
                   markDirty();
                 }}
               >
-                AI draft
+                AI draft this section
               </button>
             </label>
             <textarea
@@ -959,7 +1019,7 @@ export function WritingDeskPage() {
                   markDirty();
                 }}
               >
-                AI draft
+                AI draft this section
               </button>
             </label>
             <textarea
@@ -1155,7 +1215,7 @@ export function WritingDeskPage() {
             {!finalized && (
               <>
                 <button className="btn secondary" type="button" onClick={() => void save("draft")}>
-                  Save draft
+                  Save manager draft
                 </button>
                 <button className="btn" type="button" onClick={() => void save("finalized")}>
                   Finalize review
@@ -1179,11 +1239,11 @@ export function WritingDeskPage() {
                 setSubjectExport(exp);
               }}
             >
-              Preview JSON
+              Preview JSON export
             </button>
           </div>
           {subjectExport != null ? <pre className="digest">{JSON.stringify(subjectExport, null, 2)}</pre> : null}
-        </div>
+        </Section>
       </div>
       </PageSectionsLayout>
     </div>

From 1eef3b39b9bde18ee9a86913adb1eef017e52c29 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 26 Jul 2026 04:45:53 +0000
Subject: [PATCH 3/3] Wrap Settings and Cycles sections for WCAG scan.

Apply shared Section (When/How + clearer CTAs) to Settings, Retention,
Integrations, and Cycles sticky-nav anchors; include Section chrome styles
and Home page wrap so the shared component is on the branch.

Co-authored-by: Damon  <Modsofthenation@users.noreply.github.com>
---
 apps/ui/src/components/IntegrationsPanel.tsx | 102 +++---
 apps/ui/src/components/PageChrome.tsx        |  57 +++-
 apps/ui/src/components/RetentionPanel.tsx    |  72 +++--
 apps/ui/src/pages/CyclesPage.tsx             | 247 +++++++++------
 apps/ui/src/pages/HomePage.tsx               | 200 ++++++++----
 apps/ui/src/pages/SettingsPage.tsx           | 311 ++++++++++---------
 apps/ui/src/styles.css                       |  80 ++++-
 7 files changed, 661 insertions(+), 408 deletions(-)

diff --git a/apps/ui/src/components/IntegrationsPanel.tsx b/apps/ui/src/components/IntegrationsPanel.tsx
index f7ab604..300a64c 100644
--- a/apps/ui/src/components/IntegrationsPanel.tsx
+++ b/apps/ui/src/components/IntegrationsPanel.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useState } from "react";
 import type { IntegrationSettingsDTO, IntegrationSyncResult } from "@prm/shared";
 import { api } from "../lib/api";
+import { Section } from "./PageChrome";
 
 type IntegrationsState = {
   jira: IntegrationSettingsDTO;
@@ -48,12 +49,48 @@ export function IntegrationsPanel() {
   const jiraExtra = state.jira.extra ?? {};
 
   return (
-    <div className="panel stack">
-      <h2>Integrations</h2>
-      <p className="muted">
-        Pull cycle-scoped Jira / Linear issues and merged Bitbucket / GitHub PRs into each person’s dossier as
-        achievements (citable on the writing desk). Tokens are encrypted with the workspace secret.
-        Sync is explicit egress — no leaderboards, LOC scores, or Slack mining.
+    <Section
+      id="settings-integrations"
+      title="Integrations"
+      when="Connect trackers when you want cycle-scoped issues and merged PRs as citable dossier achievements."
+      how="Enable a provider, save credentials (encrypted with the workspace secret), test, then sync linked people."
+      action={
+        <button
+          type="button"
+          className="btn"
+          disabled={busy}
+          onClick={async () => {
+            setBusy(true);
+            try {
+              const res = await api<{ count: number; results: IntegrationSyncResult[] }>(
+                "/api/integrations/sync-all",
+                { method: "POST", body: "{}" },
+              );
+              const imported = res.results.reduce(
+                (n, r) =>
+                  n +
+                  r.jira.imported +
+                  r.bitbucket.imported +
+                  r.github.imported +
+                  (r.linear?.imported ?? 0),
+                0,
+              );
+              setMsg(`Synced ${res.count} linked people (${imported} new achievements)`);
+              await load();
+            } catch (err) {
+              setMsg(err instanceof Error ? err.message : "Sync-all failed");
+            } finally {
+              setBusy(false);
+            }
+          }}
+        >
+          Sync all linked people
+        </button>
+      }
+    >
+      <p className="muted" style={{ marginTop: 0 }}>
+        Sync is explicit egress — no leaderboards, LOC scores, or Slack mining. Link each direct’s accounts
+        on their person page, then sync there or use Sync all above (active review cycle window).
       </p>
 
       <form
@@ -143,7 +180,7 @@ export function IntegrationsPanel() {
         </div>
         <div className="cta-primary-row">
           <button className="btn" disabled={busy}>
-            Save Jira
+            Save Jira settings
           </button>
           <button
             type="button"
@@ -164,7 +201,7 @@ export function IntegrationsPanel() {
               }
             }}
           >
-            Test Jira
+            Test Jira connection
           </button>
         </div>
         {state.jira.lastSyncAt && (
@@ -250,7 +287,7 @@ export function IntegrationsPanel() {
         </div>
         <div className="cta-primary-row">
           <button className="btn" disabled={busy}>
-            Save Bitbucket
+            Save Bitbucket settings
           </button>
           <button
             type="button"
@@ -275,7 +312,7 @@ export function IntegrationsPanel() {
               }
             }}
           >
-            Test Bitbucket
+            Test Bitbucket connection
           </button>
         </div>
         {state.bitbucket.lastSyncAt && (
@@ -357,7 +394,7 @@ export function IntegrationsPanel() {
         </div>
         <div className="cta-primary-row">
           <button className="btn" disabled={busy}>
-            Save GitHub
+            Save GitHub settings
           </button>
           <button
             type="button"
@@ -378,38 +415,7 @@ export function IntegrationsPanel() {
               }
             }}
           >
-            Test GitHub
-          </button>
-          <button
-            type="button"
-            className="btn secondary"
-            disabled={busy}
-            onClick={async () => {
-              setBusy(true);
-              try {
-                const res = await api<{ count: number; results: IntegrationSyncResult[] }>(
-                  "/api/integrations/sync-all",
-                  { method: "POST", body: "{}" },
-                );
-                const imported = res.results.reduce(
-                  (n, r) =>
-                    n +
-                    r.jira.imported +
-                    r.bitbucket.imported +
-                    r.github.imported +
-                    (r.linear?.imported ?? 0),
-                  0,
-                );
-                setMsg(`Synced ${res.count} linked people (${imported} new achievements)`);
-                await load();
-              } catch (err) {
-                setMsg(err instanceof Error ? err.message : "Sync-all failed");
-              } finally {
-                setBusy(false);
-              }
-            }}
-          >
-            Sync all linked people
+            Test GitHub connection
           </button>
         </div>
         {state.github.lastSyncAt && (
@@ -489,7 +495,7 @@ export function IntegrationsPanel() {
         </div>
         <div className="cta-primary-row">
           <button className="btn" disabled={busy}>
-            Save Linear
+            Save Linear settings
           </button>
           <button
             type="button"
@@ -510,17 +516,13 @@ export function IntegrationsPanel() {
               }
             }}
           >
-            Test Linear
+            Test Linear connection
           </button>
         </div>
         {state.linear.lastSyncAt && <p className="muted">Last sync: {state.linear.lastSyncAt}</p>}
       </form>
 
-      <p className="muted">
-        Link each direct’s Jira / Bitbucket / GitHub / Linear account on their person page, then sync there or use Sync
-        all above. Sync uses the active review cycle window.
-      </p>
       {msg && <p className="muted">{msg}</p>}
-    </div>
+    </Section>
   );
 }
diff --git a/apps/ui/src/components/PageChrome.tsx b/apps/ui/src/components/PageChrome.tsx
index 80cd54c..e2dc54d 100644
--- a/apps/ui/src/components/PageChrome.tsx
+++ b/apps/ui/src/components/PageChrome.tsx
@@ -13,7 +13,7 @@ export function PageHeader({
   secondary?: ReactNode;
 }) {
   return (
-    <div className="page-header">
+    <header className="page-header">
       <div className="page-header-copy">
         <h1>{title}</h1>
         <p className="page-job">{job}</p>
@@ -24,7 +24,58 @@ export function PageHeader({
           {primary}
         </div>
       )}
-    </div>
+    </header>
+  );
+}
+
+/**
+ * Scannable page section: clear heading, when/how copy, and an optional CTA.
+ * Keep `id` stable for sticky “On this page” anchors.
+ */
+export function Section({
+  id,
+  title,
+  when,
+  how,
+  action,
+  children,
+  className = "",
+}: {
+  id: string;
+  title: string;
+  /** When to open this section (one short sentence). */
+  when: string;
+  /** How to use it (one short sentence). */
+  how: string;
+  action?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+}) {
+  const titleId = `${id}-heading`;
+  return (
+    <section
+      id={id}
+      className={`panel stack page-section settings-section section-block ${className}`.trim()}
+      aria-labelledby={titleId}
+    >
+      <header className="section-header">
+        <div className="section-header-copy">
+          <h2 id={titleId}>{title}</h2>
+          <dl className="section-guide">
+            <div>
+              <dt>When</dt>
+              <dd>{when}</dd>
+            </div>
+            <div>
+              <dt>How</dt>
+              <dd>{how}</dd>
+            </div>
+          </dl>
+        </div>
+        {action != null ? <div className="section-header-actions">{action}</div> : null}
+      </header>
+      {children ? <div className="section-body">{children}</div> : null}
+    </section>
   );
 }
 
@@ -41,7 +92,7 @@ export function NextStep({
   tone?: "brand" | "warn" | "ok";
 }) {
   return (
-    <div className={`next-step next-step-${tone}`}>
+    <div className={`next-step next-step-${tone}`} role="status" aria-live="polite">
       <div className="next-step-copy">
         <div className="next-step-label">{label}</div>
         <p>{detail}</p>
diff --git a/apps/ui/src/components/RetentionPanel.tsx b/apps/ui/src/components/RetentionPanel.tsx
index 64cf3ad..360ada5 100644
--- a/apps/ui/src/components/RetentionPanel.tsx
+++ b/apps/ui/src/components/RetentionPanel.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useState } from "react";
 import type { WorkspaceSettingsDTO } from "@prm/shared";
 import { api } from "../lib/api";
+import { Section } from "./PageChrome";
 
 export function RetentionPanel() {
   const [settings, setSettings] = useState<WorkspaceSettingsDTO | null>(null);
@@ -18,14 +19,43 @@ export function RetentionPanel() {
   if (!settings) return <p className="muted">Loading retention…</p>;
 
   return (
-    <div className="panel stack">
-      <div className="panel-title">
-        <h2>Retention & legal hold</h2>
-      </div>
+    <Section
+      id="settings-retention"
+      title="Retention & legal hold"
+      when="Set policy when you start keeping multiple cycles, before a purge, or when legal hold is required."
+      how="Choose how many cycles to keep, toggle legal hold if needed, save, then purge older closed cycles only when hold is off."
+      action={
+        <button
+          type="button"
+          className="btn"
+          disabled={busy}
+          onClick={async () => {
+            setBusy(true);
+            try {
+              const next = await api<WorkspaceSettingsDTO>("/api/workspace/settings", {
+                method: "PUT",
+                body: JSON.stringify({
+                  retention: settings.retention,
+                  legalHold: settings.legalHold,
+                }),
+              });
+              setSettings({ ...settings, ...next });
+              setMsg("Retention settings saved");
+              await load();
+            } catch (e) {
+              setMsg(e instanceof Error ? e.message : "Save failed");
+            } finally {
+              setBusy(false);
+            }
+          }}
+        >
+          Save retention settings
+        </button>
+      }
+    >
       <p className="muted" style={{ marginTop: 0 }}>
-        Default policy keeps the <strong>current + previous</strong> cycle. Older closed cycles can be
-        purged when legal hold is off. Purge marks cycles as purged (audit trail kept) — it does not
-        shred the vault.
+        Default policy keeps the <strong>current + previous</strong> cycle. Purge marks cycles as purged
+        (audit trail kept) — it does not shred the vault.
       </p>
       <div className="field">
         <label htmlFor="retention-select">Retention policy</label>
@@ -55,32 +85,6 @@ export function RetentionPanel() {
         </label>
       </div>
       <div className="cta-primary-row">
-        <button
-          type="button"
-          className="btn"
-          disabled={busy}
-          onClick={async () => {
-            setBusy(true);
-            try {
-              const next = await api<WorkspaceSettingsDTO>("/api/workspace/settings", {
-                method: "PUT",
-                body: JSON.stringify({
-                  retention: settings.retention,
-                  legalHold: settings.legalHold,
-                }),
-              });
-              setSettings({ ...settings, ...next });
-              setMsg("Retention settings saved");
-              await load();
-            } catch (e) {
-              setMsg(e instanceof Error ? e.message : "Save failed");
-            } finally {
-              setBusy(false);
-            }
-          }}
-        >
-          Save retention
-        </button>
         <button
           type="button"
           className="btn secondary"
@@ -126,6 +130,6 @@ export function RetentionPanel() {
         <p className="muted">No cycles eligible for purge under the current policy.</p>
       )}
       {msg && <p className="muted">{msg}</p>}
-    </div>
+    </Section>
   );
 }
diff --git a/apps/ui/src/pages/CyclesPage.tsx b/apps/ui/src/pages/CyclesPage.tsx
index 36a7f47..7f683d9 100644
--- a/apps/ui/src/pages/CyclesPage.tsx
+++ b/apps/ui/src/pages/CyclesPage.tsx
@@ -2,7 +2,7 @@ import { useEffect, useState } from "react";
 import { Link } from "react-router-dom";
 import type { CycleDTO, PersonDTO } from "@prm/shared";
 import { api } from "../lib/api";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout } from "../components/PageSectionsLayout";
 
 const PHASE_STATUSES = [
@@ -51,7 +51,7 @@ export function CyclesPage() {
         job="Export fillable JSON for self/peer reviews, send outside the app, then import completed files. ICs do not log in."
         primary={
           cycles.length === 0 ? (
-            <button className="btn" form="create-cycle-form" type="submit">Create cycle</button>
+            <button className="btn" form="create-cycle-form" type="submit">Create cycle with directs</button>
           ) : (
             <button className="btn" type="submit" form="export-bundle-form">Download JSON bundle</button>
           )
@@ -66,7 +66,7 @@ export function CyclesPage() {
           tone="warn"
           label="Create your first cycle"
           detail="A cycle snapshots your directs as participants and unlocks self/peer bundle export."
-          action={<button className="btn" form="create-cycle-form" type="submit">Create cycle (directs)</button>}
+          action={<button className="btn" form="create-cycle-form" type="submit">Create cycle with directs</button>}
         />
       ) : (
         <NextStep
@@ -90,8 +90,17 @@ export function CyclesPage() {
           { id: "import-bundle", label: "Import" },
         ]}
       >
-      <div className="panel page-section" id="cycles-list">
-        <h2>Cycles</h2>
+      <Section
+        id="cycles-list"
+        title="Cycles"
+        when="Create a cycle when a review window starts; select a row anytime to export, import, or write for that cycle."
+        how="Fill name, window, and optional due dates, then create with your current directs — or click a cycle to select it."
+        action={
+          <button className="btn" form="create-cycle-form" type="submit">
+            Create cycle with directs
+          </button>
+        }
+      >
         {cycles.length === 0 ? (
           <p className="muted">No cycles yet.</p>
         ) : (
@@ -159,17 +168,27 @@ export function CyclesPage() {
               <label>Manager due (optional)</label>
               <input type="date" value={managerDue} onChange={(e) => setManagerDue(e.target.value)} />
             </div>
-            <button className="btn secondary" style={{ alignSelf: "end" }}>Create cycle (directs)</button>
+            <button className="btn secondary" style={{ alignSelf: "end" }}>Create cycle with directs</button>
           </div>
         </form>
-      </div>
+      </Section>
 
       {selected && (
-        <div className="panel stack page-section" id="cycles-phases">
-          <h2>Phase wizard — {selected.name}</h2>
-          <p className="muted">
-            Soft gates only: advance phases when ready. Waive missing self/peer from the writing desk with a reason.
-          </p>
+        <Section
+          id="cycles-phases"
+          title={`Phase wizard — ${selected.name}`}
+          when="Advance phases when self, peer, or manager writing is ready to open or close."
+          how="Tap a phase to set soft status, or update the review window dates below. Waive missing self/peer from the writing desk with a reason."
+          action={
+            <button
+              className="btn secondary"
+              type="submit"
+              form={`cycle-window-form-${selected.id}`}
+            >
+              Update cycle window
+            </button>
+          }
+        >
           <div className="row" style={{ flexWrap: "wrap", gap: 8 }}>
             {PHASE_STATUSES.map((phase) => (
               <button
@@ -185,11 +204,12 @@ export function CyclesPage() {
                   await load();
                 }}
               >
-                {phase.label}
+                Set phase: {phase.label}
               </button>
             ))}
           </div>
           <form
+            id={`cycle-window-form-${selected.id}`}
             className="row"
             style={{ flexWrap: "wrap", gap: 8, alignItems: "end" }}
             onSubmit={async (e) => {
@@ -214,112 +234,133 @@ export function CyclesPage() {
               <label>Window end</label>
               <input type="date" name="windowEnd" defaultValue={selected.windowEnd} key={`${selected.id}-end`} />
             </div>
-            <button className="btn secondary" type="submit">Update window</button>
+            <button className="btn secondary" type="submit">Update cycle window</button>
           </form>
-        </div>
+        </Section>
       )}
 
       <div className="grid-2">
-        <form
-          id="export-bundle-form"
-          className="panel stack"
-          onSubmit={async (e) => {
-            e.preventDefault();
-            if (!selectedCycle || !subjectId) return;
-            const bundle = await api<Record<string, unknown>>("/api/bundles/export", {
-              method: "POST",
-              body: JSON.stringify({
-                kind: bundleKind,
-                cycleId: selectedCycle,
-                subjectPersonId: subjectId,
-                peerAuthorName: peerName || undefined,
-              }),
-            });
-            const blob = new Blob([JSON.stringify(bundle, null, 2)], { type: "application/json" });
-            const url = URL.createObjectURL(blob);
-            const a = document.createElement("a");
-            a.href = url;
-            a.download = `${bundleKind}-${(bundle.subjectName as string)?.replace(/\s+/g, "-") ?? "bundle"}.json`;
-            a.click();
-            setMessage(
-              `Bundle downloaded — ${bundleKind} pipeline marked exported. Send outside the app, then import the filled JSON below.`,
-            );
-          }}
+        <Section
+          id="cycles-export"
+          title="Export bundle"
+          when="Export when you need a fillable self or peer JSON to send outside the app (ICs never log in)."
+          how="Pick cycle, subject, and kind, then download the JSON bundle and send it outside PRM."
+          action={
+            <button
+              className="btn"
+              type="submit"
+              form="export-bundle-form"
+              disabled={!selectedCycle || !subjectId}
+            >
+              Download JSON bundle
+            </button>
+          }
         >
-          <h2>1. Export bundle</h2>
-          <div className="field">
-            <label>Cycle</label>
-            <select value={selectedCycle} onChange={(e) => setSelectedCycle(e.target.value)}>
-              {cycles.map((c) => <option key={c.id} value={c.id}>{c.name}</option>)}
-            </select>
-          </div>
-          <div className="field">
-            <label>Subject</label>
-            <select value={subjectId} onChange={(e) => setSubjectId(e.target.value)}>
-              {people.map((p) => <option key={p.id} value={p.id}>{p.name}</option>)}
-            </select>
-          </div>
-          <div className="field">
-            <label>Kind</label>
-            <select value={bundleKind} onChange={(e) => setBundleKind(e.target.value as "self" | "peer")}>
-              <option value="self">Self-review</option>
-              <option value="peer">Peer feedback</option>
-            </select>
-          </div>
-          {bundleKind === "peer" && (
+          <form
+            id="export-bundle-form"
+            className="stack"
+            onSubmit={async (e) => {
+              e.preventDefault();
+              if (!selectedCycle || !subjectId) return;
+              const bundle = await api<Record<string, unknown>>("/api/bundles/export", {
+                method: "POST",
+                body: JSON.stringify({
+                  kind: bundleKind,
+                  cycleId: selectedCycle,
+                  subjectPersonId: subjectId,
+                  peerAuthorName: peerName || undefined,
+                }),
+              });
+              const blob = new Blob([JSON.stringify(bundle, null, 2)], { type: "application/json" });
+              const url = URL.createObjectURL(blob);
+              const a = document.createElement("a");
+              a.href = url;
+              a.download = `${bundleKind}-${(bundle.subjectName as string)?.replace(/\s+/g, "-") ?? "bundle"}.json`;
+              a.click();
+              setMessage(
+                `Bundle downloaded — ${bundleKind} pipeline marked exported. Send outside the app, then import the filled JSON below.`,
+              );
+            }}
+          >
             <div className="field">
-              <label>Peer author name</label>
-              <input value={peerName} onChange={(e) => setPeerName(e.target.value)} placeholder="Jordan Lee" />
+              <label>Cycle</label>
+              <select value={selectedCycle} onChange={(e) => setSelectedCycle(e.target.value)}>
+                {cycles.map((c) => <option key={c.id} value={c.id}>{c.name}</option>)}
+              </select>
             </div>
-          )}
-          <button className="btn" disabled={!selectedCycle || !subjectId}>Download JSON bundle</button>
-        </form>
+            <div className="field">
+              <label>Subject</label>
+              <select value={subjectId} onChange={(e) => setSubjectId(e.target.value)}>
+                {people.map((p) => <option key={p.id} value={p.id}>{p.name}</option>)}
+              </select>
+            </div>
+            <div className="field">
+              <label>Kind</label>
+              <select value={bundleKind} onChange={(e) => setBundleKind(e.target.value as "self" | "peer")}>
+                <option value="self">Self-review</option>
+                <option value="peer">Peer feedback</option>
+              </select>
+            </div>
+            {bundleKind === "peer" && (
+              <div className="field">
+                <label>Peer author name</label>
+                <input value={peerName} onChange={(e) => setPeerName(e.target.value)} placeholder="Jordan Lee" />
+              </div>
+            )}
+          </form>
+        </Section>
 
-        <div className="panel stack page-section" id="import-bundle">
-          <h2>2. Import completed bundle</h2>
+        <Section
+          id="import-bundle"
+          title="Import completed bundle"
+          when="Import after the IC or peer returns a filled JSON file so evidence lands in the dossier."
+          how="Paste the completed bundle JSON, import it, then open the writing desk to draft the manager review."
+          action={
+            <button
+              className="btn"
+              disabled={!importText.trim()}
+              onClick={async () => {
+                const parsed = JSON.parse(importText) as Record<string, unknown>;
+                const fields = (parsed.fields ?? {}) as Record<string, string>;
+                if (parsed.kind === "self" && !fields.top_outcomes) {
+                  fields.top_outcomes = "Shipped reliability work; mentored a new joiner; unblocked checkout migration.";
+                  fields.growth_areas = "Take more cross-team design leadership.";
+                  fields.proposed_goals = "Own Q3 platform migration milestones.";
+                  parsed.fields = fields;
+                }
+                if (parsed.kind === "peer" && !fields.strengths) {
+                  fields.context = "Paired on API design for 6 weeks.";
+                  fields.strengths = "Clear written RFCs; calm under incident pressure.";
+                  fields.growth = "Could socialize designs earlier with partner teams.";
+                  parsed.fields = fields;
+                  parsed.peerAuthorName = parsed.peerAuthorName || "Peer Reviewer";
+                }
+                await api("/api/bundles/import", {
+                  method: "POST",
+                  body: JSON.stringify({ bundle: parsed, sourceFilename: "paste.json" }),
+                });
+                const sid = String(parsed.subjectPersonId ?? subjectId);
+                const cid = String(parsed.cycleId ?? selectedCycle);
+                setMessage("Imported. Next: open the writing desk and draft the manager review.");
+                setImportText("");
+                setSubjectId(sid);
+                setSelectedCycle(cid);
+              }}
+            >
+              Import completed JSON
+            </button>
+          }
+        >
           <div className="field">
             <label>Paste completed bundle JSON</label>
             <textarea value={importText} onChange={(e) => setImportText(e.target.value)} placeholder='{ "kind": "self", ... }' />
           </div>
-          <button
-            className="btn"
-            disabled={!importText.trim()}
-            onClick={async () => {
-              const parsed = JSON.parse(importText) as Record<string, unknown>;
-              const fields = (parsed.fields ?? {}) as Record<string, string>;
-              if (parsed.kind === "self" && !fields.top_outcomes) {
-                fields.top_outcomes = "Shipped reliability work; mentored a new joiner; unblocked checkout migration.";
-                fields.growth_areas = "Take more cross-team design leadership.";
-                fields.proposed_goals = "Own Q3 platform migration milestones.";
-                parsed.fields = fields;
-              }
-              if (parsed.kind === "peer" && !fields.strengths) {
-                fields.context = "Paired on API design for 6 weeks.";
-                fields.strengths = "Clear written RFCs; calm under incident pressure.";
-                fields.growth = "Could socialize designs earlier with partner teams.";
-                parsed.fields = fields;
-                parsed.peerAuthorName = parsed.peerAuthorName || "Peer Reviewer";
-              }
-              await api("/api/bundles/import", {
-                method: "POST",
-                body: JSON.stringify({ bundle: parsed, sourceFilename: "paste.json" }),
-              });
-              const sid = String(parsed.subjectPersonId ?? subjectId);
-              const cid = String(parsed.cycleId ?? selectedCycle);
-              setMessage("Imported. Next: open the writing desk and draft the manager review.");
-              setImportText("");
-              setSubjectId(sid);
-              setSelectedCycle(cid);
-            }}
-          >
-            Import completed JSON
-          </button>
           {selectedCycle && subjectId && (
             <Link className="btn secondary" to={`/cycles/${selectedCycle}/write/${subjectId}`}>
-              3. Open writing desk for {subject?.name ?? "subject"}
+              Open writing desk for {subject?.name ?? "subject"}
             </Link>
           )}
-        </div>
+        </Section>
       </div>
       {message && (
         <NextStep
diff --git a/apps/ui/src/pages/HomePage.tsx b/apps/ui/src/pages/HomePage.tsx
index 0556566..8361d9f 100644
--- a/apps/ui/src/pages/HomePage.tsx
+++ b/apps/ui/src/pages/HomePage.tsx
@@ -2,7 +2,7 @@ import { useEffect, useMemo, useState, type ReactNode } from "react";
 import { Link } from "react-router-dom";
 import type { CycleDTO, CycleStatsDTO, DeadlineNudge, DirectorAttentionDTO, DueThisWeekItem, WorkspaceStatus } from "@prm/shared";
 import { api } from "../lib/api";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout } from "../components/PageSectionsLayout";
 import { OnboardingWizard } from "../components/OnboardingWizard";
 
@@ -259,23 +259,46 @@ export function HomePage() {
           { id: "home-queue", label: "Queue" },
         ]}
       >
-      <div className="panel row page-section" id="home-cycle">
-        <label className="muted">Cycle</label>
-        <select value={cycleId ?? ""} onChange={(e) => setCycleId(e.target.value || null)}>
-          {cycles.length === 0 && <option value="">No cycles yet</option>}
-          {cycles.map((c) => (
-            <option key={c.id} value={c.id}>{c.name}</option>
-          ))}
-        </select>
-        {active && <span className="muted">{active.windowStart} → {active.windowEnd} · {active.status}</span>}
-      </div>
+      <Section
+        id="home-cycle"
+        title="Active cycle"
+        when="Switch cycles when you start a new review window or need to revisit a closed one."
+        how="Pick the cycle below. The rest of this page filters to that window’s pipeline and flags."
+      >
+        <div className="row" style={{ flexWrap: "wrap", gap: 12, alignItems: "center" }}>
+          <label className="muted" htmlFor="home-cycle-select">
+            Cycle
+          </label>
+          <select
+            id="home-cycle-select"
+            value={cycleId ?? ""}
+            onChange={(e) => setCycleId(e.target.value || null)}
+          >
+            {cycles.length === 0 && <option value="">No cycles yet</option>}
+            {cycles.map((c) => (
+              <option key={c.id} value={c.id}>{c.name}</option>
+            ))}
+          </select>
+          {active && (
+            <span className="muted">
+              {active.windowStart} → {active.windowEnd} · {active.status}
+            </span>
+          )}
+        </div>
+      </Section>
 
       {attention && attention.items.length > 0 && (
-        <div className="panel stack page-section" id="home-attention">
-          <h2 style={{ margin: 0 }}>Needs director attention</h2>
-          <p className="muted" style={{ margin: 0 }}>
-            Flags only — stagnant ratings, thin evidence, promo-ready, open concern counts. No private note bodies.
-          </p>
+        <Section
+          id="home-attention"
+          title="Needs director attention"
+          when="Use before a skip-level or calibration conversation — flags only, no private note bodies."
+          how="Scan reasons, open a writing desk to fix evidence, or jump to consistency / director packs."
+          action={
+            <Link className="btn" to={`/consistency?cycleId=${attention.cycleId}`}>
+              Open consistency packs
+            </Link>
+          }
+        >
           <ul>
             {attention.items.slice(0, 10).map((item) => (
               <li key={item.personId}>
@@ -286,25 +309,26 @@ export function HomePage() {
                   {item.reasons.join(" · ")}
                   {item.overall != null ? ` · overall ${item.overall}` : ""}
                 </span>{" "}
-                <Link className="btn ghost" to={`/cycles/${attention.cycleId}/write/${item.personId}`}>
-                  Desk
+                <Link
+                  className="btn secondary"
+                  to={`/cycles/${attention.cycleId}/write/${item.personId}`}
+                >
+                  Open writing desk
                 </Link>
               </li>
             ))}
           </ul>
-          <Link className="btn secondary" to={`/consistency?cycleId=${attention.cycleId}`}>
-            Open consistency / director packs
-          </Link>
-        </div>
+        </Section>
       )}
 
       {dueWeek.length > 0 && (
-        <div className="panel stack page-section" id="home-due" style={{ borderColor: "var(--warn, #c4a35a)" }}>
-          <h2 style={{ margin: 0 }}>Due this week</h2>
-          <p className="muted" style={{ margin: 0 }}>
-            Sticky tray for cycle work ending within 7 days. OS notification fires once per session when permission is
-            granted (app must be open).
-          </p>
+        <Section
+          id="home-due"
+          title="Due this week"
+          when="Use in the last 7 days of a cycle window when drafts or self-reviews are still open."
+          how="Open each person’s writing desk from the list. OS notifications fire once per session if permitted."
+          className="section-due"
+        >
           <ul>
             {dueWeek.slice(0, 12).map((d) => (
               <li key={`${d.cycleId}-${d.personId}`}>
@@ -318,15 +342,29 @@ export function HomePage() {
               </li>
             ))}
           </ul>
-        </div>
+        </Section>
       )}
 
       {cycleStats && (
-        <div className="panel stack page-section" id="home-dashboard">
-          <h2 style={{ margin: 0 }}>Cycle dashboard</h2>
-          <p className="muted" style={{ margin: 0 }}>
-            Writing time, evidence coverage, and thin dossiers for {cycleStats.cycleName}.
-          </p>
+        <Section
+          id="home-dashboard"
+          title="Cycle dashboard"
+          when={`Use mid-cycle or before finalize to see whether ${cycleStats.cycleName} is on track.`}
+          how="Check writing time, evidence coverage, and thin dossiers. Open charts when the shape looks off."
+          action={
+            <>
+              <Link
+                className="btn secondary"
+                to={cycleId ? `/team-performance?cycleId=${cycleId}` : "/team-performance"}
+              >
+                Open team performance
+              </Link>
+              <Link className="btn secondary" to="/sprint-pulse">
+                Open sprint pulse
+              </Link>
+            </>
+          }
+        >
           <div className="row" style={{ flexWrap: "wrap", gap: 16 }}>
             <div>
               <div className="muted">Avg writing time</div>
@@ -358,29 +396,26 @@ export function HomePage() {
               {cycleStats.thinDossierCount > 0 ? (
                 <>
                   {" "}
-                  <Link to="/backfill">Backfill</Link>
+                  <Link className="btn secondary" to="/backfill">
+                    Open backfill
+                  </Link>
                 </>
               ) : null}
             </div>
-            <div>
-              <div className="muted">Charts</div>
-              <Link to={cycleId ? `/team-performance?cycleId=${cycleId}` : "/team-performance"}>
-                Team performance
-              </Link>
-              {" · "}
-              <Link to="/sprint-pulse">Sprint pulse</Link>
-            </div>
           </div>
-        </div>
+        </Section>
       )}
 
       {cycleId && nudges.length > 0 && (
-        <div className="panel stack page-section" id="home-nudges">
-          <div className="row" style={{ justifyContent: "space-between", alignItems: "center" }}>
-            <h2 style={{ margin: 0 }}>Deadline nudges</h2>
+        <Section
+          id="home-nudges"
+          title="Deadline nudges"
+          when="Use when self-reviews are still missing near the cycle deadline."
+          how="Copy mailto links (or all at once) and send outside the app — ICs never log in here."
+          action={
             <button
               type="button"
-              className="btn secondary"
+              className="btn"
               onClick={async () => {
                 const text = nudges
                   .map((n) => `${n.personName}${n.email ? ` <${n.email}>` : ""} — ${n.mailtoHref}`)
@@ -393,9 +428,10 @@ export function HomePage() {
                 }
               }}
             >
-              Copy all
+              Copy all nudge links
             </button>
-          </div>
+          }
+        >
           <p className="muted" style={{ margin: 0 }}>
             {nudges.length} missing self-review
             {nudgeDays != null ? ` · ${nudgeDays} day(s) until window end` : ""}
@@ -405,15 +441,31 @@ export function HomePage() {
               <li key={n.personId}>
                 <strong>{n.personName}</strong>{" "}
                 <span className="muted">({n.selfStatus})</span>{" "}
-                <a href={n.mailtoHref}>mailto</a>
+                <a href={n.mailtoHref}>Email nudge</a>
               </li>
             ))}
           </ul>
           {nudgeMsg && <p className="muted">{nudgeMsg}</p>}
-        </div>
+        </Section>
       )}
 
-      <div className="panel page-section" id="home-queue">
+      <Section
+        id="home-queue"
+        title="Writing queue"
+        when="Use throughout the cycle to see who still needs a role, self-review, or manager draft."
+        how="Read each row’s status, then take the action in Your move — or open Cycles to export self-review packs."
+        action={
+          cycleId ? (
+            <Link className="btn secondary" to="/cycles">
+              Manage cycle roster
+            </Link>
+          ) : (
+            <Link className="btn" to="/cycles">
+              Create cycle
+            </Link>
+          )
+        }
+      >
         {items.length === 0 ? (
           <p className="muted" style={{ margin: 0 }}>
             {cycleId ? "No participants in this cycle." : "Create a cycle to see your writing queue."}
@@ -422,14 +474,14 @@ export function HomePage() {
           <table className="table">
             <thead>
               <tr>
-                <th>Person</th>
-                <th>Role</th>
-                <th>Self</th>
-                <th>Self pipeline</th>
-                <th>Peers</th>
-                <th>Peer pipeline</th>
-                <th>Manager</th>
-                <th>Your move</th>
+                <th scope="col">Person</th>
+                <th scope="col">Role</th>
+                <th scope="col">Self</th>
+                <th scope="col">Self pipeline</th>
+                <th scope="col">Peers</th>
+                <th scope="col">Peer pipeline</th>
+                <th scope="col">Manager</th>
+                <th scope="col">Your move</th>
               </tr>
             </thead>
             <tbody>
@@ -446,16 +498,30 @@ export function HomePage() {
                 } else if (needsSelf) {
                   cta = (
                     <div className="row">
-                      <Link className="btn" to="/cycles">Get self-review</Link>
-                      <Link className="btn secondary" to={`/cycles/${cycleId}/write/${person.id}`}>Write</Link>
+                      <Link className="btn" to="/cycles">Export self-review pack</Link>
+                      <Link className="btn secondary" to={`/cycles/${cycleId}/write/${person.id}`}>
+                        Open writing desk
+                      </Link>
                     </div>
                   );
                 } else if (finalized) {
-                  cta = <Link className="btn secondary" to={`/cycles/${cycleId}/write/${person.id}`}>Open / export</Link>;
+                  cta = (
+                    <Link className="btn secondary" to={`/cycles/${cycleId}/write/${person.id}`}>
+                      Open or export draft
+                    </Link>
+                  );
                 } else if (item.managerStatus === "draft") {
-                  cta = <Link className="btn" to={`/cycles/${cycleId}/write/${person.id}`}>Continue writing</Link>;
+                  cta = (
+                    <Link className="btn" to={`/cycles/${cycleId}/write/${person.id}`}>
+                      Continue writing
+                    </Link>
+                  );
                 } else {
-                  cta = <Link className="btn" to={`/cycles/${cycleId}/write/${person.id}`}>Write review</Link>;
+                  cta = (
+                    <Link className="btn" to={`/cycles/${cycleId}/write/${person.id}`}>
+                      Start writing review
+                    </Link>
+                  );
                 }
                 return (
                   <tr key={person.id}>
@@ -481,7 +547,7 @@ export function HomePage() {
             </tbody>
           </table>
         )}
-      </div>
+      </Section>
       </PageSectionsLayout>
     </div>
   );
diff --git a/apps/ui/src/pages/SettingsPage.tsx b/apps/ui/src/pages/SettingsPage.tsx
index 5ffc3ab..00a2ffc 100644
--- a/apps/ui/src/pages/SettingsPage.tsx
+++ b/apps/ui/src/pages/SettingsPage.tsx
@@ -3,7 +3,7 @@ import type { AuditVerifyResult } from "@prm/shared";
 import { api } from "../lib/api";
 import { useTheme } from "../hooks/useTheme";
 import { ACCENTS, type Accent, type ColorMode } from "../lib/theme";
-import { NextStep, PageHeader } from "../components/PageChrome";
+import { NextStep, PageHeader, Section } from "../components/PageChrome";
 import { PageSectionsLayout, type SectionNavItem } from "../components/PageSectionsLayout";
 import { IntegrationsPanel } from "../components/IntegrationsPanel";
 import { RetentionPanel } from "../components/RetentionPanel";
@@ -122,19 +122,18 @@ export function SettingsPage({
               setMsg(res.ok ? `Connection OK (${res.model})` : `Failed: ${res.error}`);
             }}
           >
-            Test connection
+            Test AI connection
           </button>
         }
       />
 
       <PageSectionsLayout sections={SETTINGS_SECTIONS}>
-      <div id="settings-appearance" className="panel stack settings-section page-section">
-        <div className="panel-title">
-          <h2>Appearance</h2>
-        </div>
-        <p className="muted" style={{ marginTop: 0 }}>
-          Color mode and accent are stored in this browser. System follows your OS preference ({resolved} right now).
-        </p>
+      <Section
+        id="settings-appearance"
+        title="Appearance"
+        when="Change color mode or accent whenever the UI feels too bright, too dark, or hard to scan."
+        how={`Pick a mode and accent below. Preferences stay in this browser; System follows your OS (${resolved} right now).`}
+      >
         <div className="field">
           <label htmlFor="theme-select">Color mode</label>
           <select
@@ -177,74 +176,75 @@ export function SettingsPage({
             ))}
           </div>
         </div>
-      </div>
+      </Section>
 
-      <div id="settings-retention" className="settings-section">
-        <RetentionPanel />
-      </div>
+      <RetentionPanel />
 
-      <div id="settings-integrations" className="settings-section">
-        <IntegrationsPanel />
-      </div>
+      <IntegrationsPanel />
 
-      <div id="settings-audit" className="panel settings-section">
-        <h2>Activity audit</h2>
-        <p className="muted">
-          Hash-chained local activity log with append-only SQLite triggers. Verify recomputes the chain;
-          export signs a pack with the unlocked workspace key. Tamper-evident for this machine — not
-          external legal custody (anyone with the vault password can re-sign).
+      <Section
+        id="settings-audit"
+        title="Activity audit"
+        when="Use when you want to check that the local activity log has not been tampered with on this machine."
+        how="Verify recomputes the hash chain; export downloads a pack signed with the unlocked workspace key."
+        action={
+          <>
+            <button
+              type="button"
+              className="btn"
+              disabled={auditBusy}
+              onClick={async () => {
+                setAuditBusy(true);
+                try {
+                  const result = await api<AuditVerifyResult>("/api/activity/verify");
+                  setAudit(result);
+                  setMsg(result.ok ? `Chain OK (${result.count} events)` : `Chain broken: ${result.error}`);
+                } catch (e) {
+                  setMsg(e instanceof Error ? e.message : "Verify failed");
+                } finally {
+                  setAuditBusy(false);
+                }
+              }}
+            >
+              Verify audit chain
+            </button>
+            <button
+              type="button"
+              className="btn secondary"
+              disabled={auditBusy}
+              onClick={async () => {
+                setAuditBusy(true);
+                try {
+                  const pack = await api<Record<string, unknown>>("/api/activity/export", {
+                    method: "POST",
+                    body: "{}",
+                  });
+                  const blob = new Blob([JSON.stringify(pack, null, 2)], { type: "application/json" });
+                  const url = URL.createObjectURL(blob);
+                  const a = document.createElement("a");
+                  a.href = url;
+                  a.download = `prm-audit-${new Date().toISOString().slice(0, 10)}.json`;
+                  a.click();
+                  URL.revokeObjectURL(url);
+                  const v = pack.verification as AuditVerifyResult | undefined;
+                  if (v) setAudit(v);
+                  setMsg("Audit pack downloaded");
+                } catch (e) {
+                  setMsg(e instanceof Error ? e.message : "Export failed");
+                } finally {
+                  setAuditBusy(false);
+                }
+              }}
+            >
+              Export signed audit pack
+            </button>
+          </>
+        }
+      >
+        <p className="muted" style={{ margin: 0 }}>
+          Append-only SQLite triggers keep a local chain. Tamper-evident for this machine — not external legal
+          custody (anyone with the vault password can re-sign).
         </p>
-        <div className="cta-primary-row">
-          <button
-            type="button"
-            className="btn"
-            disabled={auditBusy}
-            onClick={async () => {
-              setAuditBusy(true);
-              try {
-                const result = await api<AuditVerifyResult>("/api/activity/verify");
-                setAudit(result);
-                setMsg(result.ok ? `Chain OK (${result.count} events)` : `Chain broken: ${result.error}`);
-              } catch (e) {
-                setMsg(e instanceof Error ? e.message : "Verify failed");
-              } finally {
-                setAuditBusy(false);
-              }
-            }}
-          >
-            Verify chain
-          </button>
-          <button
-            type="button"
-            className="btn secondary"
-            disabled={auditBusy}
-            onClick={async () => {
-              setAuditBusy(true);
-              try {
-                const pack = await api<Record<string, unknown>>("/api/activity/export", {
-                  method: "POST",
-                  body: "{}",
-                });
-                const blob = new Blob([JSON.stringify(pack, null, 2)], { type: "application/json" });
-                const url = URL.createObjectURL(blob);
-                const a = document.createElement("a");
-                a.href = url;
-                a.download = `prm-audit-${new Date().toISOString().slice(0, 10)}.json`;
-                a.click();
-                URL.revokeObjectURL(url);
-                const v = pack.verification as AuditVerifyResult | undefined;
-                if (v) setAudit(v);
-                setMsg("Audit pack downloaded");
-              } catch (e) {
-                setMsg(e instanceof Error ? e.message : "Export failed");
-              } finally {
-                setAuditBusy(false);
-              }
-            }}
-          >
-            Export signed pack
-          </button>
-        </div>
         {audit && (
           <p className="muted" style={{ marginBottom: 0 }}>
             {audit.ok ? "Intact" : "Broken"} · {audit.count} events
@@ -252,15 +252,14 @@ export function SettingsPage({
             {audit.error ? ` · ${audit.error}` : ""}
           </p>
         )}
-      </div>
+      </Section>
 
-      <div id="settings-backup" className="panel stack settings-section">
-        <h2>Backup & restore</h2>
-        <p className="muted">
-          Encrypted snapshots of the unlocked SQLite DB under data/backups. Restore replaces the live
-          database — confirm carefully.
-        </p>
-        <div className="cta-primary-row">
+      <Section
+        id="settings-backup"
+        title="Backup & restore"
+        when="Snapshot before a risky restore, purge, or workspace change; restore only when you intend to replace the live DB."
+        how="Create an encrypted snapshot under data/backups, then restore a listed file if you need to roll back."
+        action={
           <button
             type="button"
             className="btn"
@@ -281,9 +280,10 @@ export function SettingsPage({
               }
             }}
           >
-            Create backup
+            Create encrypted backup
           </button>
-        </div>
+        }
+      >
         {backups.length === 0 ? (
           <p className="muted">No backups yet.</p>
         ) : (
@@ -320,13 +320,13 @@ export function SettingsPage({
                     }
                   }}
                 >
-                  Restore
+                  Restore this backup
                 </button>
               </li>
             ))}
           </ul>
         )}
-      </div>
+      </Section>
 
       {needsKey ? (
         <NextStep
@@ -352,7 +352,7 @@ export function SettingsPage({
                 setMsg(res.ok ? `Connection OK (${res.model})` : `Failed: ${res.error}`);
               }}
             >
-              Test connection
+              Test AI connection
             </button>
           }
         />
@@ -365,10 +365,16 @@ export function SettingsPage({
         />
       )}
 
-      <div id="settings-ai" className="settings-section">
+      <Section
+        id="settings-ai"
+        title="AI"
+        when="Enable when you want grounded digests and section drafts on the writing desk; leave off to draft from packet evidence only."
+        how="Choose a provider, paste a key if needed, set models and private-tier egress, then save and test the connection."
+        action={<button className="btn" form="ai-settings-form" type="submit">Save AI settings</button>}
+      >
       <form
         id="ai-settings-form"
-        className="panel"
+        className="stack"
         onSubmit={async (e) => {
           e.preventDefault();
           await api("/api/ai/settings", {
@@ -383,7 +389,6 @@ export function SettingsPage({
           await load();
         }}
       >
-        <h2>AI</h2>
         <div className="field">
           <label>
             <input
@@ -524,21 +529,20 @@ export function SettingsPage({
               setMsg(res.ok ? `Connection OK (${res.model})` : `Failed: ${res.error}`);
             }}
           >
-            Test connection
+            Test AI connection
           </button>
         </div>
         {msg && <p className="muted">{msg}</p>}
       </form>
-      </div>
+      </Section>
 
-      <div id="settings-danger" className="panel stack settings-section">
-        <h2>Danger zone</h2>
-        <p className="muted" style={{ margin: 0 }}>
-          Permanently erase this local workspace (database, vault, uploads, and backups), then create a
-          new empty or demo workspace. Legal hold must be off. This cannot be undone.
-        </p>
-        {!destroyOpen ? (
-          <div className="cta-primary-row">
+      <Section
+        id="settings-danger"
+        title="Danger zone"
+        when="Only when you intend to wipe this local workspace and start over (empty or demo)."
+        how="Open the form, enter the workspace password, type DELETE, then erase permanently — legal hold must be off."
+        action={
+          !destroyOpen ? (
             <button
               type="button"
               className="btn danger"
@@ -551,8 +555,14 @@ export function SettingsPage({
             >
               Delete workspace…
             </button>
-          </div>
-        ) : (
+          ) : undefined
+        }
+      >
+        <p className="muted" style={{ margin: 0 }}>
+          Permanently erase this local workspace (database, vault, uploads, and backups), then create a
+          new empty or demo workspace. This cannot be undone.
+        </p>
+        {destroyOpen ? (
           <form
             className="stack"
             onSubmit={async (e) => {
@@ -613,60 +623,65 @@ export function SettingsPage({
                   setDestroyError(null);
                 }}
               >
-                Cancel
+                Cancel delete
               </button>
             </div>
           </form>
-        )}
-      </div>
+        ) : null}
+      </Section>
 
-      <div id="settings-desktop" className="panel stack settings-section">
-        <h2>Desktop updates</h2>
-        <p className="muted" style={{ margin: 0 }}>
-          Packaged builds serve the UI from the local API (same-origin) to avoid WebView “Failed to fetch”. Check GitHub
-          Releases for a newer installer; signed auto-update needs Tauri updater keys in CI.
-        </p>
-        <button
-          type="button"
-          className="btn secondary"
+      <Section
+        id="settings-desktop"
+        title="Desktop updates"
+        when="Use on packaged desktop builds when you want to know if a newer installer is available."
+        how="Check GitHub Releases for the latest tag versus your installed version; signed auto-update needs Tauri updater keys in CI."
+        action={
+          <button
+            type="button"
+            className="btn secondary"
             onClick={async () => {
-            try {
-              let localVersion = "0.1.0";
-              const invoke = (window as unknown as {
-                __TAURI__?: { core?: { invoke?: (cmd: string) => Promise<string> } };
-              }).__TAURI__?.core?.invoke;
-              if (invoke) {
-                try {
-                  localVersion = await invoke("get_app_version");
-                } catch {
-                  /* browser / unsigned */
+              try {
+                let localVersion = "0.1.0";
+                const invoke = (window as unknown as {
+                  __TAURI__?: { core?: { invoke?: (cmd: string) => Promise<string> } };
+                }).__TAURI__?.core?.invoke;
+                if (invoke) {
+                  try {
+                    localVersion = await invoke("get_app_version");
+                  } catch {
+                    /* browser / unsigned */
+                  }
                 }
+                const res = await fetch(
+                  "https://api.github.com/repos/Modsofthenation/PerformanceReviewManager/releases/latest",
+                  { headers: { Accept: "application/vnd.github+json" } },
+                );
+                if (!res.ok) {
+                  setMsg(`Could not reach GitHub releases (${res.status}). Download artifacts from Actions on main.`);
+                  return;
+                }
+                const json = (await res.json()) as { tag_name?: string; html_url?: string; name?: string };
+                const tag = json.tag_name ?? json.name ?? "unknown";
+                setMsg(
+                  `Installed app version ${localVersion}. Latest GitHub release: ${tag}. ${json.html_url ?? ""}`,
+                );
+              } catch (e) {
+                setMsg(
+                  e instanceof Error
+                    ? `${e.message} — use CI artifact desktop-windows-x86_64 / desktop-linux / desktop-macos`
+                    : "Update check failed",
+                );
               }
-              const res = await fetch(
-                "https://api.github.com/repos/Modsofthenation/PerformanceReviewManager/releases/latest",
-                { headers: { Accept: "application/vnd.github+json" } },
-              );
-              if (!res.ok) {
-                setMsg(`Could not reach GitHub releases (${res.status}). Download artifacts from Actions on main.`);
-                return;
-              }
-              const json = (await res.json()) as { tag_name?: string; html_url?: string; name?: string };
-              const tag = json.tag_name ?? json.name ?? "unknown";
-              setMsg(
-                `Installed app version ${localVersion}. Latest GitHub release: ${tag}. ${json.html_url ?? ""}`,
-              );
-            } catch (e) {
-              setMsg(
-                e instanceof Error
-                  ? `${e.message} — use CI artifact desktop-windows-x86_64 / desktop-linux / desktop-macos`
-                  : "Update check failed",
-              );
-            }
-          }}
-        >
-          Check for updates
-        </button>
-      </div>
+            }}
+          >
+            Check for desktop updates
+          </button>
+        }
+      >
+        <p className="muted" style={{ margin: 0 }}>
+          Packaged builds serve the UI from the local API (same-origin) to avoid WebView “Failed to fetch”.
+        </p>
+      </Section>
       </PageSectionsLayout>
     </div>
   );
diff --git a/apps/ui/src/styles.css b/apps/ui/src/styles.css
index fd8966f..063bb0d 100644
--- a/apps/ui/src/styles.css
+++ b/apps/ui/src/styles.css
@@ -37,8 +37,8 @@
   --bg: #0f1419;
   --bg-soft: #1a222c;
   --ink: #e8eef4;
-  --ink-soft: #c5d0db;
-  --muted: #8b9aab;
+  --ink-soft: #c9d4e0;
+  --muted: #9aa8b8;
   --line: #243040;
   --line-strong: #334155;
   --panel: #161d26;
@@ -61,7 +61,7 @@
   --bg-soft: #e8eef4;
   --ink: #0f172a;
   --ink-soft: #334155;
-  --muted: #64748b;
+  --muted: #475569;
   --line: #dde5ee;
   --line-strong: #c8d3e0;
   --panel: #ffffff;
@@ -713,6 +713,80 @@ strong { color: var(--ink-soft); font-weight: 600; }
 }
 .next-step-action { display: flex; gap: 0.5rem; flex-wrap: wrap; }
 
+/* ---------- Section scan chrome (WCAG-oriented) ---------- */
+.section-block {
+  gap: var(--space-4);
+}
+.section-header {
+  display: flex;
+  gap: var(--space-4);
+  align-items: flex-start;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  padding-bottom: var(--space-3);
+  border-bottom: 1px solid var(--line);
+  margin-bottom: 0;
+}
+.section-header-copy {
+  flex: 1;
+  min-width: min(100%, 18rem);
+}
+.section-header-copy h2 {
+  margin: 0 0 var(--space-3);
+  font-size: var(--text-lg);
+  line-height: 1.3;
+}
+.section-guide {
+  margin: 0;
+  display: grid;
+  gap: var(--space-2);
+}
+.section-guide > div {
+  display: grid;
+  grid-template-columns: 3.25rem minmax(0, 1fr);
+  gap: var(--space-2) var(--space-3);
+  align-items: start;
+}
+.section-guide dt {
+  margin: 0;
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--brand-strong);
+  line-height: 1.45;
+  padding-top: 0.1rem;
+}
+.section-guide dd {
+  margin: 0;
+  color: var(--ink-soft);
+  font-size: 0.95rem;
+  line-height: 1.5;
+  max-width: 62ch;
+}
+.section-header-actions {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  align-items: center;
+}
+.section-body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  min-width: 0;
+}
+.section-body > :first-child { margin-top: 0; }
+.section-body .muted {
+  color: var(--ink-soft);
+}
+
+.page-section-nav-link:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 3px var(--brand-ring);
+  color: var(--ink);
+}
+
 .status-pill {
   display: inline-flex;
   align-items: center;