quangshuynh · quangshuynh · Sep 26, 2026 · Sep 26, 2026 · Sep 26, 2026 · Sep 26, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -26,6 +26,16 @@ search or persistence has changed.
 - **One visual system.** Semantic text roles on SF Pro and SF Mono, a short
   spacing scale and status tones that always pair colour with a word and a
   symbol, in light and dark appearance. Paths are shown from `~`.
+- **VoiceOver hears Start Meeting as Start Meeting.** The window's two tabs
+  put their name on everything inside them that had no label of its own, so
+  since v0.2.0 VoiceOver announced the Start Meeting button, and the sentence
+  beside it, as "Meeting". The tabs are still named by the tab bar.
+- **Narrow windows.** History's file actions become icon buttons, with the same
+  names as tooltips and for VoiceOver, instead of truncating; the meeting's
+  Details wrap long values instead of cutting them off.
+- **New screenshots** of the redesigned interface, captured from real meetings
+  with synthetic speech. The v0.2.0 demo recording, which showed the previous
+  interface, was removed.
 - **Removed** the unused IBM Plex font files; ScribeKit uses the system faces.
 
 ## 0.2.0 — 2026-09-24

diff --git a/CONTEXT.md b/CONTEXT.md
@@ -5,8 +5,9 @@ Current working state of the repository. Keep this short and current; see
 
 ## Current milestone
 
-Interval 32 — UI visual system, on branch `interval/32-ui-visual-system`,
-unreleased. A presentation-only redesign on top of v0.2.0; capture,
+Interval 32 — UI visual system, merged to `main` (pull request 36) and
+unreleased; the real-app pass that followed — its fixes and the new
+screenshots — is on `interval/32-real-app-pass`. A presentation-only redesign on top of v0.2.0; capture,
 recognition, persistence, History search and review semantics are unchanged.
 See **Visual system** below and `docs/development/visual-design.md`.
 
@@ -1990,6 +1991,20 @@ success. Nothing is uploaded and no entitlement was added.
 
 ## Validation status
 
+### Interval 32 visual pass
+
+The redesign was exercised in the real app on this Mac against a demo save
+folder, driven by UI automation with synthetic speech (live `say` into the
+microphone, QuickTime Player for App Audio): both setup modes, live, paused
+(⌃⌘P / ⌃⌘R), finished, an interrupted meeting recovered and marked, History
+search, filter, find, Review and no results, light and dark, the 680 × 560
+minimum and a 980-point window. Keyboard: Return starts, ⌘1 / ⌘2 switch tabs,
+⌘F focuses search. Accessibility was checked by reading the exposed tree, not
+by listening to VoiceOver. Observed CPU for the app process: about 0.04 % idle
+on setup, about 6 % mean during a live meeting with brief peaks of 20–30 % as
+passages finalised (`ps` sampled once a second). The documentation screenshots
+come from those meetings.
+
 ### v0.2.0 release validation
 
 On an M1 MacBook Air, macOS 26.6.2, Xcode 27.0, from a clean clone of the

diff --git a/README.md b/README.md
@@ -27,7 +27,7 @@
 > requirement: ScribeKit runs entirely on your Mac either way.
 
 <p align="center">
-  <img src="docs/images/meeting-live.png" alt="ScribeKit transcribing a Microphone meeting: listening to the MacBook Air Microphone, transcribing on device, and a live transcript with timestamped lines and a grey in-progress hypothesis" width="720">
+  <img src="docs/images/meeting-live.png" alt="ScribeKit during an App Audio meeting called Quarterly Roadmap Sync: a red dot beside Capturing and the elapsed time 00:46, Pause and Stop buttons, the source QuickTime Player and English (United States), and below them ten finalised passages of recognised speech, each beside the time it began" width="720">
 </p>
 
 ScribeKit runs quietly while you work in other applications. You pick what it
@@ -36,16 +36,6 @@ speech on this Mac with Apple's on-device speech models, and it appends a
 timestamped Markdown transcript into a folder you chose — readable in any
 editor while the meeting is still running.
 
-## Demo
-
-Choosing a microphone, starting a Microphone meeting, live transcription,
-stopping, then finding the meeting in History with the source filter and
-search, and stepping through matches with find.
-
-<p align="center">
-  <img src="docs/images/scribekit-demo.gif" alt="A 44-second recording of ScribeKit: choosing the MacBook Air Microphone as the input, starting a Microphone meeting, a transcript filling in line by line, stopping, then filtering History to Microphone meetings, searching for deployment, and stepping through the matches in the transcript with find" width="620">
-</p>
-
 ## What it does
 
 - **Captures the apps you pick**, through ScreenCaptureKit — not the whole
@@ -87,12 +77,20 @@ search, and stepping through matches with find.
 
 <table>
 <tr>
-<td width="50%"><img src="docs/images/meeting-setup.png" alt="ScribeKit's setup screen in Microphone mode: a Before You Start checklist for save location, microphone access, speech recognition and microphone input, above the meeting title and the Input picker set to MacBook Air Microphone"></td>
-<td width="50%"><img src="docs/images/history-review.png" alt="ScribeKit's History filtered to Microphone meetings and searched for deployment, beside a meeting's details with the find bar showing 1 of 2 and both matches highlighted in its transcript"></td>
+<td width="50%"><img src="docs/images/meeting-setup-app-audio.png" alt="ScribeKit's setup form in App Audio mode: the running applications listed with their icons and QuickTime Player checked, the meeting title Quarterly Roadmap Sync, the recognition language, whether to keep audio, the save folder, and Start Meeting beside a line saying what the meeting will do"></td>
+<td width="50%"><img src="docs/images/meeting-setup.png" alt="ScribeKit's setup form in Microphone mode: the Input picker set to MacBook Air Microphone, microphone access shown as Allowed, what a Microphone meeting listens to and keeps, the meeting title and the save folder"></td>
+</tr>
+<tr>
+<td align="center"><em>Setup — App Audio, with the applications to capture</em></td>
+<td align="center"><em>Setup — Microphone, with an explicit input</em></td>
+</tr>
+<tr>
+<td width="50%"><img src="docs/images/history-review.png" alt="ScribeKit's History: six meetings listed by title with their date and capture mode, one marked Interrupted, and the selected Release Readiness Review showing its details and two passages flagged for review — a High priority passage whose wording the recogniser was unsure of, and a Medium one — each with Show in Transcript, Play Audio and Mark Reviewed"></td>
+<td width="50%"><img src="docs/images/history-find.png" alt="ScribeKit's History searched for release, each result quoting the matching words highlighted in context, beside the Release Readiness Review transcript with the find field showing 3 of 5 and the current match highlighted more strongly than the others"></td>
 </tr>
 <tr>
-<td align="center"><em>Setup — choosing the microphone, with readiness before anything is recorded</em></td>
-<td align="center"><em>History — source filter, search, and find within a transcript</em></td>
+<td align="center"><em>History — meetings at a glance, and Review</em></td>
+<td align="center"><em>Search across meetings, and find within a transcript</em></td>
 </tr>
 </table>
 

diff --git a/ScribeKit/Features/Design/Components.swift b/ScribeKit/Features/Design/Components.swift
@@ -249,6 +249,7 @@ struct FactRow: View {
                 .textRole(isTechnical ? .technicalValue : .body)
                 .lineLimit(truncatesMiddle ? 1 : nil)
                 .truncationMode(truncatesMiddle ? .middle : .tail)
+                .fixedSize(horizontal: false, vertical: !truncatesMiddle)
                 .textSelection(.enabled)
                 .frame(maxWidth: .infinity, alignment: .leading)
                 .help(truncatesMiddle ? value : "")

diff --git a/ScribeKit/Features/Design/Metrics.swift b/ScribeKit/Features/Design/Metrics.swift
@@ -89,6 +89,9 @@ nonisolated enum LayoutMetrics {
     /// The space between one transcript passage and the next.
     static let transcriptPassageSpacing: CGFloat = 10
 
+    /// The width of a running meeting's Details popover.
+    static let detailsPopoverWidth: CGFloat = 460
+
     /// The height of the notes editor before the user types into it.
     static let notesEditorMinHeight: CGFloat = 110
 

diff --git a/ScribeKit/Features/History/HistorySessionDetailView.swift b/ScribeKit/Features/History/HistorySessionDetailView.swift
@@ -143,20 +143,32 @@ struct HistorySessionDetailView: View {
         return parts.joined(separator: " · ")
     }
 
+    /// The file actions, titled when the pane is wide enough and reduced to
+    /// their symbols — with the same names as tooltips and for VoiceOver —
+    /// when it is not, so no title is ever cut short.
     private var actions: some View {
+        ViewThatFits(in: .horizontal) {
+            actionButtons.labelStyle(.titleAndIcon)
+            actionButtons.labelStyle(.iconOnly)
+        }
+    }
+
+    private var actionButtons: some View {
         HStack(spacing: Spacing.small) {
             Button {
                 model.openTranscript(session.transcriptURL)
             } label: {
                 Label("Open Transcript", systemImage: "doc.text")
             }
+            .help("Open Transcript")
             .accessibilityHint("Open the transcript in your Markdown application. ScribeKit does not edit it.")
 
             Button {
                 model.showInFinder(session.transcriptURL)
             } label: {
                 Label("Show in Finder", systemImage: "folder")
             }
+            .help("Show Transcript in Finder")
             .accessibilityLabel("Show Transcript in Finder")
             .accessibilityHint("Reveal this meeting's transcript in the Finder")
 
@@ -166,9 +178,11 @@ struct HistorySessionDetailView: View {
                 } label: {
                     Label("Show Audio in Finder", systemImage: "waveform")
                 }
+                .help("Show Audio in Finder")
                 .accessibilityHint("Reveal this meeting's audio file in the Finder")
             }
         }
+        .fixedSize()
     }
 
     // MARK: - Facts

diff --git a/ScribeKit/Features/MeetingSetup/MeetingSessionView.swift b/ScribeKit/Features/MeetingSetup/MeetingSessionView.swift
@@ -353,7 +353,7 @@ private struct MeetingDetailsPopover: View {
                 .fixedSize(horizontal: false, vertical: true)
         }
         .padding(Spacing.large)
-        .frame(width: 420, alignment: .leading)
+        .frame(width: LayoutMetrics.detailsPopoverWidth, alignment: .leading)
     }
 
     /// A short description of what capture is doing.

diff --git a/ScribeKit/Features/ScribeKitRootView.swift b/ScribeKit/Features/ScribeKitRootView.swift
@@ -41,11 +41,9 @@ struct ScribeKitRootView: View {
         TabView(selection: Bindable(selection).tab) {
             MeetingSetupView(runtime: runtime, diagnostics: diagnostics)
                 .tabItem { Label(ScribeKitTab.meeting.title, systemImage: ScribeKitTab.meeting.systemImage) }
-                .accessibilityLabel(ScribeKitTab.meeting.title)
                 .tag(ScribeKitTab.meeting)
             HistoryView(runtime: runtime)
                 .tabItem { Label(ScribeKitTab.history.title, systemImage: ScribeKitTab.history.systemImage) }
-                .accessibilityLabel(ScribeKitTab.history.title)
                 .tag(ScribeKitTab.history)
         }
         .frame(minWidth: LayoutMetrics.windowMinWidth, minHeight: LayoutMetrics.windowMinHeight)

diff --git a/docs/getting-started/first-meeting.md b/docs/getting-started/first-meeting.md
@@ -32,6 +32,8 @@ choose a folder — so no warning outlives its cause.
 
 ## Set the meeting up
 
+![ScribeKit's setup form in Microphone mode, with the Input set to MacBook Air Microphone, access shown as Allowed, the meeting title and the save folder.](../images/meeting-setup.png)
+
 The setup screen holds the configuration for the *next* meeting, top to
 bottom in the order the choices are made:
 

diff --git a/docs/images/history-find.png b/docs/images/history-find.png
diff --git a/docs/images/history-review.png b/docs/images/history-review.png
diff --git a/docs/images/meeting-live.png b/docs/images/meeting-live.png
diff --git a/docs/images/meeting-setup-app-audio.png b/docs/images/meeting-setup-app-audio.png
diff --git a/docs/images/meeting-setup.png b/docs/images/meeting-setup.png
diff --git a/docs/images/scribekit-demo.gif b/docs/images/scribekit-demo.gif
diff --git a/docs/using/history-and-search.md b/docs/using/history-and-search.md
@@ -14,6 +14,8 @@ application you use for Markdown.
 
 ## Search
 
+![History searched for "release": each result quotes the matching words in context, and the find field steps through the matches in one transcript.](../images/history-find.png)
+
 Search is plain, case-insensitive substring matching over meeting titles,
 recognised speech, captured application and microphone names, and the name of
 each meeting's capture mode — `App Audio` or `Microphone`. A match in speech

diff --git a/docs/using/keyboard-and-accessibility.md b/docs/using/keyboard-and-accessibility.md
@@ -128,5 +128,9 @@ it; see [Visual Design](../development/visual-design.md).
   included in the keyboard and VoiceOver pass run on an M1 Mac before v0.2.0.
   See
   [Limitations](../reference/limitations.md).
+  The redesigned screens were checked by reading the accessibility tree
+  VoiceOver reads — labels, values and hints on the setup form, a running
+  meeting, recovery, History and Review — but not by listening to VoiceOver
+  itself.
 - **The tab bar is not itself in the Tab-key order.** ⌘1 and ⌘2 are the
   keyboard route between screens.
diff --git a/docs/using/live-transcription.md b/docs/using/live-transcription.md
@@ -5,6 +5,8 @@ the meeting runs.
 
 ## On screen
 
+![A running App Audio meeting: Capturing with the elapsed time, Pause and Stop, and finalised passages beside the times they began.](../images/meeting-live.png)
+
 During a meeting the transcript takes the Meeting screen: each finalised
 passage beside the time it began, measured from the start of the meeting, in a
 column kept to a comfortable reading width however wide the window is. The

diff --git a/docs/using/review-and-playback.md b/docs/using/review-and-playback.md
@@ -13,6 +13,8 @@ passages marked reviewed sits beside the section's heading, and **Show in
 Transcript** moves the preview to the passage and marks it with a bar at its
 edge.
 
+![A meeting's details in History, with a High priority and a Medium priority passage flagged for review, each with Show in Transcript, Play Audio and Mark Reviewed.](../images/history-review.png)
+
 ## The two reasons
 
 They are different kinds of thing, and ScribeKit keeps them distinct: