Fixed in 9169e9db and pushed. Captions now use the text-caption type-scale token (was text-xs) across StepEditor, BindEvent, SpecList, WorkflowSettings, ScheduleTrigger, CuratorCard; TaskHeader's title uses PageHeader's h1 classes; hand-rolled boxes became Card (token reveal, recovery code, pending extension) or CodeView (install progress); SystemStatusPage's startup table is a MetadataList; HarnessPage's empty row is TableEmpty; No-tokens/No-dispatches/No-inputs/Workflow-removed states are Empty; StepEditor's problem line is a destructive Alert; ToolsPage + SystemReposPage risky rows use SettingRow tone="danger" (DANGER_ROW deleted). Verified: task check passed on the committed tree (one vue-tsc error on colspan string vs number, fixed). Sites already conforming (Card/Section/text-caption headings in OrgOverviewPage, PlanDocument, BindingEditor, CaptureDetail/Payload, StepRun) were left as-is.
Fixed in 9169e9db and pushed. Captions now use the text-caption type-scale token (was text-xs) across StepEditor, BindEvent, SpecList, WorkflowSettings, ScheduleTrigger, CuratorCard; TaskHeader's title uses PageHeader's h1 classes; hand-rolled boxes became Card (token reveal, recovery code, pending extension) or CodeView (install progress); SystemStatusPage's startup table is a MetadataList; HarnessPage's empty row is TableEmpty; No-tokens/No-dispatches/No-inputs/Workflow-removed states are Empty; StepEditor's problem line is a destructive Alert; ToolsPage + SystemReposPage risky rows use SettingRow tone="danger" (DANGER_ROW deleted). Verified: task check passed on the committed tree (one vue-tsc error on colspan string vs number, fixed). Sites already conforming (Card/Section/text-caption headings in OrgOverviewPage, PlanDocument, BindingEditor, CaptureDetail/Payload, StepRun) were left as-is.
PRD — Replace hand-rolled headings, one titled card and two notice cards with components/ui (issue #1759)
Problem
ui/CLAUDE.md/ui/AGENTS.md say: "Never hand-roll a card, heading, caption, status dot or date format; if a pattern is missing, add it to components/ui with a real consumer first." The tree already complies with most of that rule — ~60 files import Section/Alert/Empty/MetadataList/TableEmpty, text-xs appears zero times in ui/src, and the risky-row tint is already SettingRow tone="danger". The issue's six-category inventory is largely wrong, so coding it as filed would produce ~25 needless diffs and touch files that are already correct.
What is actually hand-rolled, verified by reading the files:
The uppercase "eyebrow" group label — 11 sites in 6 files, in two inconsistent variants.
With tracking-[0.06em] text-fg-subtle: settings/SettingsShell.vue:40, captures/CaptureDetail.vue:89, captures/CapturePayload.vue:18-21, bindings/BindingEditor.vue:311.
Without tracking, with text-fg-muted: workflows/StepRun.vue:125,138,142,148,153, workflows/WorkflowHistory.vue:85,89. style.css:65-68 documents --text-caption as "section and column labels", so the type scale is the right base, but the letter-spacing/uppercase combination has no component and no shared class.
One titled card that Section replaces:tasks/TaskReviewGate.vue:21-43 is a bare Card+CardHeader+CardTitle+CardContent block. Section is exactly Card + CardHeader + CardTitle as="h2" + CardContent.
Two instruction-plus-action cards:settings/ExtensionsPage.vue:120-126 (pending update with an Approve button) and accounts/PersonalTokensCard.vue:94-101 (a shown-once token with Copy/Dismiss). components/ui/alert exists, already has a reviewed precedent for exactly this shape — sources/SourceSecret.vue builds a shown-once secret with copy and dismiss buttons on Alert/AlertTitle/AlertDescription.
Proposed solution
1. New components/ui/caption-heading (untracked pattern, needs one component)
ui/src/components/ui/caption-heading/CaptionHeading.vue + index.ts, matching the style of Section/MetadataList/SettingRow (all hand-written precedents in this tree):
One canonical style, no tone prop. 11px text-fg-subtle is the dominant secondary tone in the app (100+ sites, e.g. MetadataList labels, SettingRow hints); the text-fg-muted eyebrow is the outlier. Visible effect of unifying: the 7 StepRun/WorkflowHistory labels lose one step of contrast and gain 0.06em tracking. That is the only intentional visual change in this PRD; if the maintainer wants zero visual change in the run log, the alternative is a two-value tone prop — not recommended, it codifies the inconsistency.
as preserves each site's current element and heading level (h4 at StepRun:125, h3 elsewhere, p at SettingsShell:40, span at WorkflowHistory:85,89).
StepRun:138 is a Button (transcript toggle, aria-expanded), not a heading. Keep the Button and render <CaptionHeading as="span">Transcript</CaptionHeading> inside it; the class still comes from one place and the control keeps its semantics.
ui/CLAUDE.md requires the shadcn-vue CLI for new components: search the registry first (pnpm dlx shadcn-vue@latest add <candidate> from ui/; components.json has "registries": {}, so the default registry). shadcn-vue has no section-label/eyebrow primitive; if the search confirms that, write it by hand as the rule permits and say so in the component's doc comment.
11 call sites: replace the class list with <CaptionHeading as="…">, add one import per file. SettingsShell:40 keeps its cn() (passes mb-1 px-3 mt-4 max-lg:hidden through class).
2. tasks/TaskReviewGate.vue:21-43 → Section
<Section title="Review findings" class="mb-6"> wrapping the existing ItemGroup, with the current CardHeader's <p class="break-all font-mono text-caption text-fg-muted">Head commit: …</p> moved to the first child of the body (Section's description is a plain string and would lose font-mono/break-all; extending Section's API for one caller is not worth it). class="mb-6" survives cn/tailwind-merge, so the gap above the task-detail grid (TaskDetailPage.vue:55) is unchanged. Drop the now-unused Card, CardContent, CardHeader, CardTitle import, add Section.
3. Two notice cards → Alert
settings/ExtensionsPage.vue:120-126 → <Alert v-if="extension.pending" variant="warn" class="w-full"> with AlertTitle "Update awaiting approval", AlertDescription holding the existing font-mono grant list, and the Approve Button as a grid child with mt-2 justify-self-start (Alert is grid, so a bare child stretches; AlertAction is absolutely positioned and would collide in a narrow list row). Remove the now-unused Card import; Alert is already imported.
accounts/PersonalTokensCard.vue:94-101 → <Alert v-if="created" class="mb-3"> + AlertTitle "Copy this token now. It cannot be shown again." + AlertDescription holding the read-only Input and the Copy/Dismiss buttons, exactly as sources/SourceSecret.vue does. role="alert" is inserted once when the token is created, so the region announces correctly. Add Alert, AlertTitle, AlertDescription; remove Card.
Files and components affected
New (2): ui/src/components/ui/caption-heading/CaptionHeading.vue, ui/src/components/ui/caption-heading/index.ts.
No server, contract, store, dependency or build change.
Acceptance criteria
grep -r 'tracking-\[0\.06em\]' ui/src and grep -rn 'text-caption font-medium uppercase' ui/src return no feature-folder hits; both existing eyebrow variants are gone.
All 11 sites render through CaptionHeading; rendered heading levels are unchanged (h4 at StepRun:125, h3 elsewhere, p at SettingsShell:40, span at WorkflowHistory:85,89), and the transcript toggle is still a keyboard-reachable Button with aria-expanded.
TaskReviewGate renders as Section; "Review findings" is an h2; the head-commit line is still shown in mono; spacing to the content grid is unchanged.
Both notice cards render as Alert; the Approve, Copy and Dismiss buttons still work; no Card import remains where its last use was removed.
pnpm run typecheck, pnpm test, pnpm run build pass. No new test (root and ui/ policy: no test for markup, and never test CSS classes; no test in ui/test/ imports any of these files).
Browser check in a running dev server, light and dark, compact density: settings sidebar group labels, a capture's Payload/Headers/Dispatches panel, binding editor "Recent dispatches", a task's run panels (tool calls, transcript, captured changes, log), the task-detail review gate, an extension awaiting approval, and creating a personal token.
Non-goals (verified as already done, nonexistent, or wrong target)
text-xs captions, MetadataList for the status table, duplicated risky-row tint:text-xs has zero matches in ui/src; settings/SystemStatusPage.vue:44-46 is already Section+MetadataList; ToolsPage.vue:206 and SystemReposPage.vue:328 already pass :tone="… ? 'danger' : 'default'" (SystemReposPage.vue:47 is a line inside interface Repo).
Alerts and empties the issue lists as hand-rolled: already shared — HarnessPage.vue:171 (TableEmpty), DispatchLinks.vue:88 (Empty), ScheduleTrigger.vue:212 (Empty), StepEditor.vue:160 (Alert), WorkflowHistory.vue:76 (Empty), and Section in PersonalTokensCard, AccountPage, VersionsCard, CuratorCard, AccountEntry.
Form labels and editor group headers (WorkflowSettings.vue:134, ScheduleTrigger.vue:195,201, BindEvent.vue:286,301,312, SpecList.vue:35, StepEditor.vue:164-263): Label/FieldLabel targets, not eyebrow captions. Converting them is not this change.
alerts/AlertsBell.vue:65:text-caption font-semibold text-fg-subtle, no uppercase, no tracking — a third style on a plain type-scale class, which the rule permits. Out.
tasks/PlanDocument.vue h3s, chat/ChatChooseCard.vue:14, tasks/TaskHeader.vue:127, org/OrgOverviewPage.vue:43, tasks/ChangeCapture.vue:17: a document outline (Section would turn prose into a stack of cards), a line inside a chat message, a page header whose breadcrumb/badge/action shape PageHeader does not support, a Card wrapped in a RouterLink (Section has no as-child), and a section header over a table. All stay.
Inline role="alert" + text-danger error text in ~18 workflow/settings files (incl. components/ui/field/FieldError.vue): ui/CLAUDE.md requires showing failures where they occur; field-level errors must not become block Alerts.
accounts/AccountPage.vue:39 (recovery code in a bare Card, role="status"): Card is already a components/ui primitive and this is a value, not a notice. Leave.
Follow-up, not this PRD:TaskHeader.vue duplicates PageHeader's h1; TriggerSettings.vue:56 hand-rolls an inline read error where ReadError exists. File separately if wanted.
Estimated diff size
~11 files, ~85 lines: ~22 added (new component + index), ~45 changed (11 call sites, 6 imports, TaskReviewGate ~8, ExtensionsPage ~9, PersonalTokensCard ~10), 3 removed unused imports. Under the root AGENTS.md ~100-line assessment threshold, no new mechanism, no new dependency. Urgency: not urgent — per "broken beats new" it sits behind open bugs.
Verification I performed for this PRD
Every line number and pattern above was read in the tree this run: grep 'uppercase', grep 'text-xs' (no matches), grep 'tracking-\[0\.06em\]' (4 hits), grep 'text-caption font-medium' (29 hits), grep '<Card[ >]' (14 hits outside components/ui), plus direct reads of Section/Alert/MetadataList/SettingRow/PageHeader/SourceSecret and each listed site. I did not run pnpm typecheck/build (read-only mission) and did not execute any registry search — the claim that shadcn-vue has no eyebrow primitive is an expectation to confirm at implementation time, not a verified fact.
Decide in chat or on the dashboard.
**archie's PRD is ready -- awaiting your go/no-go.**
# PRD — Replace hand-rolled headings, one titled card and two notice cards with components/ui (issue #1759)
## Problem
`ui/CLAUDE.md`/`ui/AGENTS.md` say: *"Never hand-roll a card, heading, caption, status dot or date format; if a pattern is missing, add it to components/ui with a real consumer first."* The tree already complies with most of that rule — ~60 files import Section/Alert/Empty/MetadataList/TableEmpty, `text-xs` appears **zero** times in `ui/src`, and the risky-row tint is already `SettingRow tone="danger"`. The issue's six-category inventory is largely wrong, so coding it as filed would produce ~25 needless diffs and touch files that are already correct.
What is actually hand-rolled, verified by reading the files:
1. **The uppercase "eyebrow" group label — 11 sites in 6 files, in two inconsistent variants.**
With `tracking-[0.06em] text-fg-subtle`: `settings/SettingsShell.vue:40`, `captures/CaptureDetail.vue:89`, `captures/CapturePayload.vue:18-21`, `bindings/BindingEditor.vue:311`.
Without tracking, with `text-fg-muted`: `workflows/StepRun.vue:125,138,142,148,153`, `workflows/WorkflowHistory.vue:85,89`.
`style.css:65-68` documents `--text-caption` as "section and column labels", so the type scale is the right base, but the letter-spacing/uppercase combination has no component and no shared class.
2. **One titled card that `Section` replaces:** `tasks/TaskReviewGate.vue:21-43` is a bare `Card`+`CardHeader`+`CardTitle`+`CardContent` block. Section is exactly Card + CardHeader + `CardTitle as="h2"` + CardContent.
3. **Two instruction-plus-action cards:** `settings/ExtensionsPage.vue:120-126` (pending update with an Approve button) and `accounts/PersonalTokensCard.vue:94-101` (a shown-once token with Copy/Dismiss). `components/ui/alert` exists, already has a reviewed precedent for exactly this shape — `sources/SourceSecret.vue` builds a shown-once secret with copy and dismiss buttons on `Alert`/`AlertTitle`/`AlertDescription`.
## Proposed solution
### 1. New `components/ui/caption-heading` (untracked pattern, needs one component)
`ui/src/components/ui/caption-heading/CaptionHeading.vue` + `index.ts`, matching the style of `Section`/`MetadataList`/`SettingRow` (all hand-written precedents in this tree):
```vue
props: { as?: "h2"|"h3"|"h4"|"p"|"span" (default "h3"), class?: HTMLAttributes["class"] }
render: <component :is="as" :class="cn('text-caption font-medium uppercase tracking-[0.06em] text-fg-subtle', props.class)">
```
- **One canonical style, no tone prop.** 11px `text-fg-subtle` is the dominant secondary tone in the app (100+ sites, e.g. `MetadataList` labels, `SettingRow` hints); the `text-fg-muted` eyebrow is the outlier. Visible effect of unifying: the 7 StepRun/WorkflowHistory labels lose one step of contrast and gain 0.06em tracking. That is the only intentional visual change in this PRD; if the maintainer wants zero visual change in the run log, the alternative is a two-value `tone` prop — not recommended, it codifies the inconsistency.
- `as` preserves each site's current element and heading level (h4 at `StepRun:125`, h3 elsewhere, p at `SettingsShell:40`, span at `WorkflowHistory:85,89`).
- `StepRun:138` is a `Button` (transcript toggle, `aria-expanded`), not a heading. Keep the Button and render `<CaptionHeading as="span">Transcript</CaptionHeading>` inside it; the class still comes from one place and the control keeps its semantics.
- `ui/CLAUDE.md` requires the shadcn-vue CLI for new components: search the registry first (`pnpm dlx shadcn-vue@latest add <candidate>` from `ui/`; `components.json` has `"registries": {}`, so the default registry). shadcn-vue has no section-label/eyebrow primitive; if the search confirms that, write it by hand as the rule permits and say so in the component's doc comment.
11 call sites: replace the class list with `<CaptionHeading as="…">`, add one import per file. `SettingsShell:40` keeps its `cn()` (passes `mb-1 px-3 mt-4 max-lg:hidden` through `class`).
### 2. `tasks/TaskReviewGate.vue:21-43` → `Section`
`<Section title="Review findings" class="mb-6">` wrapping the existing `ItemGroup`, with the current `CardHeader`'s `<p class="break-all font-mono text-caption text-fg-muted">Head commit: …</p>` moved to the first child of the body (Section's `description` is a plain string and would lose `font-mono`/`break-all`; extending Section's API for one caller is not worth it). `class="mb-6"` survives `cn`/tailwind-merge, so the gap above the task-detail grid (`TaskDetailPage.vue:55`) is unchanged. Drop the now-unused `Card, CardContent, CardHeader, CardTitle` import, add `Section`.
### 3. Two notice cards → `Alert`
- **`settings/ExtensionsPage.vue:120-126`** → `<Alert v-if="extension.pending" variant="warn" class="w-full">` with `AlertTitle` "Update awaiting approval", `AlertDescription` holding the existing `font-mono` grant list, and the Approve `Button` as a grid child with `mt-2 justify-self-start` (Alert is `grid`, so a bare child stretches; `AlertAction` is absolutely positioned and would collide in a narrow list row). Remove the now-unused `Card` import; `Alert` is already imported.
- **`accounts/PersonalTokensCard.vue:94-101`** → `<Alert v-if="created" class="mb-3">` + `AlertTitle` "Copy this token now. It cannot be shown again." + `AlertDescription` holding the read-only `Input` and the Copy/Dismiss buttons, exactly as `sources/SourceSecret.vue` does. `role="alert"` is inserted once when the token is created, so the region announces correctly. Add `Alert, AlertTitle, AlertDescription`; remove `Card`.
## Files and components affected
New (2): `ui/src/components/ui/caption-heading/CaptionHeading.vue`, `ui/src/components/ui/caption-heading/index.ts`.
Edited (9): `ui/src/settings/SettingsShell.vue`, `ui/src/captures/CaptureDetail.vue`, `ui/src/captures/CapturePayload.vue`, `ui/src/bindings/BindingEditor.vue`, `ui/src/workflows/StepRun.vue`, `ui/src/workflows/WorkflowHistory.vue`, `ui/src/tasks/TaskReviewGate.vue`, `ui/src/settings/ExtensionsPage.vue`, `ui/src/accounts/PersonalTokensCard.vue`.
No server, contract, store, dependency or build change.
## Acceptance criteria
1. `grep -r 'tracking-\[0\.06em\]' ui/src` and `grep -rn 'text-caption font-medium uppercase' ui/src` return no feature-folder hits; both existing eyebrow variants are gone.
2. All 11 sites render through `CaptionHeading`; rendered heading levels are unchanged (h4 at StepRun:125, h3 elsewhere, p at SettingsShell:40, span at WorkflowHistory:85,89), and the transcript toggle is still a keyboard-reachable `Button` with `aria-expanded`.
3. `TaskReviewGate` renders as `Section`; "Review findings" is an `h2`; the head-commit line is still shown in mono; spacing to the content grid is unchanged.
4. Both notice cards render as `Alert`; the Approve, Copy and Dismiss buttons still work; no `Card` import remains where its last use was removed.
5. `pnpm run typecheck`, `pnpm test`, `pnpm run build` pass. No new test (root and `ui/` policy: no test for markup, and never test CSS classes; no test in `ui/test/` imports any of these files).
6. Browser check in a running dev server, light and dark, compact density: settings sidebar group labels, a capture's Payload/Headers/Dispatches panel, binding editor "Recent dispatches", a task's run panels (tool calls, transcript, captured changes, log), the task-detail review gate, an extension awaiting approval, and creating a personal token.
## Non-goals (verified as already done, nonexistent, or wrong target)
- **`text-xs` captions, `MetadataList` for the status table, duplicated risky-row tint:** `text-xs` has zero matches in `ui/src`; `settings/SystemStatusPage.vue:44-46` is already `Section`+`MetadataList`; `ToolsPage.vue:206` and `SystemReposPage.vue:328` already pass `:tone="… ? 'danger' : 'default'"` (`SystemReposPage.vue:47` is a line inside `interface Repo`).
- **Alerts and empties the issue lists as hand-rolled:** already shared — `HarnessPage.vue:171` (`TableEmpty`), `DispatchLinks.vue:88` (`Empty`), `ScheduleTrigger.vue:212` (`Empty`), `StepEditor.vue:160` (`Alert`), `WorkflowHistory.vue:76` (`Empty`), and `Section` in `PersonalTokensCard`, `AccountPage`, `VersionsCard`, `CuratorCard`, `AccountEntry`.
- **Form labels and editor group headers** (`WorkflowSettings.vue:134`, `ScheduleTrigger.vue:195,201`, `BindEvent.vue:286,301,312`, `SpecList.vue:35`, `StepEditor.vue:164-263`): `Label`/`FieldLabel` targets, not eyebrow captions. Converting them is not this change.
- **`alerts/AlertsBell.vue:65`:** `text-caption font-semibold text-fg-subtle`, no uppercase, no tracking — a third style on a plain type-scale class, which the rule permits. Out.
- **`tasks/PlanDocument.vue` h3s, `chat/ChatChooseCard.vue:14`, `tasks/TaskHeader.vue:127`, `org/OrgOverviewPage.vue:43`, `tasks/ChangeCapture.vue:17`:** a document outline (Section would turn prose into a stack of cards), a line inside a chat message, a page header whose breadcrumb/badge/action shape `PageHeader` does not support, a Card wrapped in a `RouterLink` (Section has no `as-child`), and a section header over a table. All stay.
- **Inline `role="alert"` + `text-danger` error text** in ~18 workflow/settings files (incl. `components/ui/field/FieldError.vue`): `ui/CLAUDE.md` requires showing failures where they occur; field-level errors must not become block Alerts.
- **`accounts/AccountPage.vue:39`** (recovery code in a bare `Card`, `role="status"`): `Card` is already a components/ui primitive and this is a value, not a notice. Leave.
- **Follow-up, not this PRD:** `TaskHeader.vue` duplicates `PageHeader`'s `h1`; `TriggerSettings.vue:56` hand-rolls an inline read error where `ReadError` exists. File separately if wanted.
## Estimated diff size
~11 files, ~85 lines: ~22 added (new component + index), ~45 changed (11 call sites, 6 imports, `TaskReviewGate` ~8, `ExtensionsPage` ~9, `PersonalTokensCard` ~10), 3 removed unused imports. Under the root AGENTS.md ~100-line assessment threshold, no new mechanism, no new dependency. Urgency: not urgent — per "broken beats new" it sits behind open bugs.
## Verification I performed for this PRD
Every line number and pattern above was read in the tree this run: `grep 'uppercase'`, `grep 'text-xs'` (no matches), `grep 'tracking-\[0\.06em\]'` (4 hits), `grep 'text-caption font-medium'` (29 hits), `grep '<Card[ >]'` (14 hits outside components/ui), plus direct reads of Section/Alert/MetadataList/SettingRow/PageHeader/SourceSecret and each listed site. I did not run `pnpm typecheck`/`build` (read-only mission) and did not execute any registry search — the claim that shadcn-vue has no eyebrow primitive is an expectation to confirm at implementation time, not a verified fact.
_Decide in chat or on the dashboard._
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
ui/CLAUDE.mdasks pages to use Section, MetadataList, Alert, Empty and TableEmpty. These hand-roll them instead:ui/src/tasks/TaskHeader.vue:127,PlanDocument.vue:140-172,TaskReviewGate.vue:201-203,ChangeCapture.vue:90,ui/src/chat/ChatChooseCard.vue:75,ui/src/org/OrgOverviewPage.vue:41-48,ui/src/bindings/BindingEditor.vue:309-310,ui/src/alerts/AlertsBell.vue:63,ui/src/curators/CuratorCard.vue:45.text-xs font-mediumdivs:ui/src/workflows/StepEditor.vue,WorkflowSettings.vue:135,ScheduleTrigger.vue:194, 200,BindEvent.vue:266-295,SpecList.vue:35,WorkflowHistory.vue:81, 85,StepRun.vue:125-153,ui/src/captures/CapturePayload.vue:18-22,CaptureDetail.vue:89.ui/src/settings/SystemStatusPage.vue:37-46(MetadataList).ui/src/accounts/PersonalTokensCard.vue:86-93,AccountPage.vue:37,ui/src/settings/VersionsCard.vue:202,ExtensionsPage.vue:118.ui/src/workflows/StepEditor.vue:160,ui/src/harness/HarnessPage.vue:171-173,ui/src/workflows/WorkflowHistory.vue:72,BindEvent.vue:288, 341,ScheduleTrigger.vue:211,TriggerSettings.vue:56,ui/src/bindings/DispatchLinks.vue:82,ui/src/accounts/PersonalTokensCard.vue:94.ui/src/settings/ToolsPage.vue:205,SystemReposPage.vue:47) though SettingRow hastone="danger".Done when: each uses the shared component.
Fixed in
9169e9dband pushed. Captions now use the text-caption type-scale token (was text-xs) across StepEditor, BindEvent, SpecList, WorkflowSettings, ScheduleTrigger, CuratorCard; TaskHeader's title uses PageHeader's h1 classes; hand-rolled boxes became Card (token reveal, recovery code, pending extension) or CodeView (install progress); SystemStatusPage's startup table is a MetadataList; HarnessPage's empty row is TableEmpty; No-tokens/No-dispatches/No-inputs/Workflow-removed states are Empty; StepEditor's problem line is a destructive Alert; ToolsPage + SystemReposPage risky rows use SettingRow tone="danger" (DANGER_ROW deleted). Verified: task check passed on the committed tree (one vue-tsc error on colspan string vs number, fixed). Sites already conforming (Card/Section/text-caption headings in OrgOverviewPage, PlanDocument, BindingEditor, CaptureDetail/Payload, StepRun) were left as-is.archie's PRD is ready -- awaiting your go/no-go.
PRD — Replace hand-rolled headings, one titled card and two notice cards with components/ui (issue #1759)
Problem
ui/CLAUDE.md/ui/AGENTS.mdsay: "Never hand-roll a card, heading, caption, status dot or date format; if a pattern is missing, add it to components/ui with a real consumer first." The tree already complies with most of that rule — ~60 files import Section/Alert/Empty/MetadataList/TableEmpty,text-xsappears zero times inui/src, and the risky-row tint is alreadySettingRow tone="danger". The issue's six-category inventory is largely wrong, so coding it as filed would produce ~25 needless diffs and touch files that are already correct.What is actually hand-rolled, verified by reading the files:
With
tracking-[0.06em] text-fg-subtle:settings/SettingsShell.vue:40,captures/CaptureDetail.vue:89,captures/CapturePayload.vue:18-21,bindings/BindingEditor.vue:311.Without tracking, with
text-fg-muted:workflows/StepRun.vue:125,138,142,148,153,workflows/WorkflowHistory.vue:85,89.style.css:65-68documents--text-captionas "section and column labels", so the type scale is the right base, but the letter-spacing/uppercase combination has no component and no shared class.Sectionreplaces:tasks/TaskReviewGate.vue:21-43is a bareCard+CardHeader+CardTitle+CardContentblock. Section is exactly Card + CardHeader +CardTitle as="h2"+ CardContent.settings/ExtensionsPage.vue:120-126(pending update with an Approve button) andaccounts/PersonalTokensCard.vue:94-101(a shown-once token with Copy/Dismiss).components/ui/alertexists, already has a reviewed precedent for exactly this shape —sources/SourceSecret.vuebuilds a shown-once secret with copy and dismiss buttons onAlert/AlertTitle/AlertDescription.Proposed solution
1. New
components/ui/caption-heading(untracked pattern, needs one component)ui/src/components/ui/caption-heading/CaptionHeading.vue+index.ts, matching the style ofSection/MetadataList/SettingRow(all hand-written precedents in this tree):text-fg-subtleis the dominant secondary tone in the app (100+ sites, e.g.MetadataListlabels,SettingRowhints); thetext-fg-mutedeyebrow is the outlier. Visible effect of unifying: the 7 StepRun/WorkflowHistory labels lose one step of contrast and gain 0.06em tracking. That is the only intentional visual change in this PRD; if the maintainer wants zero visual change in the run log, the alternative is a two-valuetoneprop — not recommended, it codifies the inconsistency.aspreserves each site's current element and heading level (h4 atStepRun:125, h3 elsewhere, p atSettingsShell:40, span atWorkflowHistory:85,89).StepRun:138is aButton(transcript toggle,aria-expanded), not a heading. Keep the Button and render<CaptionHeading as="span">Transcript</CaptionHeading>inside it; the class still comes from one place and the control keeps its semantics.ui/CLAUDE.mdrequires the shadcn-vue CLI for new components: search the registry first (pnpm dlx shadcn-vue@latest add <candidate>fromui/;components.jsonhas"registries": {}, so the default registry). shadcn-vue has no section-label/eyebrow primitive; if the search confirms that, write it by hand as the rule permits and say so in the component's doc comment.11 call sites: replace the class list with
<CaptionHeading as="…">, add one import per file.SettingsShell:40keeps itscn()(passesmb-1 px-3 mt-4 max-lg:hiddenthroughclass).2.
tasks/TaskReviewGate.vue:21-43→Section<Section title="Review findings" class="mb-6">wrapping the existingItemGroup, with the currentCardHeader's<p class="break-all font-mono text-caption text-fg-muted">Head commit: …</p>moved to the first child of the body (Section'sdescriptionis a plain string and would losefont-mono/break-all; extending Section's API for one caller is not worth it).class="mb-6"survivescn/tailwind-merge, so the gap above the task-detail grid (TaskDetailPage.vue:55) is unchanged. Drop the now-unusedCard, CardContent, CardHeader, CardTitleimport, addSection.3. Two notice cards →
Alertsettings/ExtensionsPage.vue:120-126→<Alert v-if="extension.pending" variant="warn" class="w-full">withAlertTitle"Update awaiting approval",AlertDescriptionholding the existingfont-monogrant list, and the ApproveButtonas a grid child withmt-2 justify-self-start(Alert isgrid, so a bare child stretches;AlertActionis absolutely positioned and would collide in a narrow list row). Remove the now-unusedCardimport;Alertis already imported.accounts/PersonalTokensCard.vue:94-101→<Alert v-if="created" class="mb-3">+AlertTitle"Copy this token now. It cannot be shown again." +AlertDescriptionholding the read-onlyInputand the Copy/Dismiss buttons, exactly assources/SourceSecret.vuedoes.role="alert"is inserted once when the token is created, so the region announces correctly. AddAlert, AlertTitle, AlertDescription; removeCard.Files and components affected
New (2):
ui/src/components/ui/caption-heading/CaptionHeading.vue,ui/src/components/ui/caption-heading/index.ts.Edited (9):
ui/src/settings/SettingsShell.vue,ui/src/captures/CaptureDetail.vue,ui/src/captures/CapturePayload.vue,ui/src/bindings/BindingEditor.vue,ui/src/workflows/StepRun.vue,ui/src/workflows/WorkflowHistory.vue,ui/src/tasks/TaskReviewGate.vue,ui/src/settings/ExtensionsPage.vue,ui/src/accounts/PersonalTokensCard.vue.No server, contract, store, dependency or build change.
Acceptance criteria
grep -r 'tracking-\[0\.06em\]' ui/srcandgrep -rn 'text-caption font-medium uppercase' ui/srcreturn no feature-folder hits; both existing eyebrow variants are gone.CaptionHeading; rendered heading levels are unchanged (h4 at StepRun:125, h3 elsewhere, p at SettingsShell:40, span at WorkflowHistory:85,89), and the transcript toggle is still a keyboard-reachableButtonwitharia-expanded.TaskReviewGaterenders asSection; "Review findings" is anh2; the head-commit line is still shown in mono; spacing to the content grid is unchanged.Alert; the Approve, Copy and Dismiss buttons still work; noCardimport remains where its last use was removed.pnpm run typecheck,pnpm test,pnpm run buildpass. No new test (root andui/policy: no test for markup, and never test CSS classes; no test inui/test/imports any of these files).Non-goals (verified as already done, nonexistent, or wrong target)
text-xscaptions,MetadataListfor the status table, duplicated risky-row tint:text-xshas zero matches inui/src;settings/SystemStatusPage.vue:44-46is alreadySection+MetadataList;ToolsPage.vue:206andSystemReposPage.vue:328already pass:tone="… ? 'danger' : 'default'"(SystemReposPage.vue:47is a line insideinterface Repo).HarnessPage.vue:171(TableEmpty),DispatchLinks.vue:88(Empty),ScheduleTrigger.vue:212(Empty),StepEditor.vue:160(Alert),WorkflowHistory.vue:76(Empty), andSectioninPersonalTokensCard,AccountPage,VersionsCard,CuratorCard,AccountEntry.WorkflowSettings.vue:134,ScheduleTrigger.vue:195,201,BindEvent.vue:286,301,312,SpecList.vue:35,StepEditor.vue:164-263):Label/FieldLabeltargets, not eyebrow captions. Converting them is not this change.alerts/AlertsBell.vue:65:text-caption font-semibold text-fg-subtle, no uppercase, no tracking — a third style on a plain type-scale class, which the rule permits. Out.tasks/PlanDocument.vueh3s,chat/ChatChooseCard.vue:14,tasks/TaskHeader.vue:127,org/OrgOverviewPage.vue:43,tasks/ChangeCapture.vue:17: a document outline (Section would turn prose into a stack of cards), a line inside a chat message, a page header whose breadcrumb/badge/action shapePageHeaderdoes not support, a Card wrapped in aRouterLink(Section has noas-child), and a section header over a table. All stay.role="alert"+text-dangererror text in ~18 workflow/settings files (incl.components/ui/field/FieldError.vue):ui/CLAUDE.mdrequires showing failures where they occur; field-level errors must not become block Alerts.accounts/AccountPage.vue:39(recovery code in a bareCard,role="status"):Cardis already a components/ui primitive and this is a value, not a notice. Leave.TaskHeader.vueduplicatesPageHeader'sh1;TriggerSettings.vue:56hand-rolls an inline read error whereReadErrorexists. File separately if wanted.Estimated diff size
~11 files, ~85 lines: ~22 added (new component + index), ~45 changed (11 call sites, 6 imports,
TaskReviewGate~8,ExtensionsPage~9,PersonalTokensCard~10), 3 removed unused imports. Under the root AGENTS.md ~100-line assessment threshold, no new mechanism, no new dependency. Urgency: not urgent — per "broken beats new" it sits behind open bugs.Verification I performed for this PRD
Every line number and pattern above was read in the tree this run:
grep 'uppercase',grep 'text-xs'(no matches),grep 'tracking-\[0\.06em\]'(4 hits),grep 'text-caption font-medium'(29 hits),grep '<Card[ >]'(14 hits outside components/ui), plus direct reads of Section/Alert/MetadataList/SettingRow/PageHeader/SourceSecret and each listed site. I did not runpnpm typecheck/build(read-only mission) and did not execute any registry search — the claim that shadcn-vue has no eyebrow primitive is an expectation to confirm at implementation time, not a verified fact.Decide in chat or on the dashboard.
Fixed in
9169e9dband pushed to main. Gate: task check exited 0 on the committed tree.