shadcn/ui backfill list (AD #39)
AD #39 (.claude/CLAUDE.md § Architecture Decisions) makes shadcn/ui the CRM’s component library. Every
screen built before it uses the older in-house components in forge-et-fe/src/ui. This file lists each
of those screens until it is moved over, and says how a screen is moved. It covers forge-et-fe only;
the capture app’s screens, which follow by AD #43, are in .forge/design/ui/pwa-shadcn.md.
Two lists, one rule. This file is the screen-by-screen plan. The file-by-file list a test
enforces is forge-et-fe’s src/app/shadcnBackfill.json: src/app/shadcnOnly.test.ts fails
pnpm test, and so the PR’s Test record check, when a file in src/features or src/app uses an
older src/ui component with a shadcn counterpart, react-aria-components, or a raw <button>,
<input>, <select>, <textarea>, <table> or <dialog> that the JSON list does not name. The
JSON list was generated from the tree when the test landed and only shrinks: moving a screen removes
its entries, and an entry a file no longer needs fails the test (design:
.forge/design/harness/shadcn-only-check.md).
Who updates it. This file is in the harness, so a frontend PR cannot change it itself: the
developer who opens the frontend PR updates the row in a harness commit alongside it, as the tracker
is updated — the screen’s status and the PR when a screen is moved, or a new or extended row when
frontend-reviewer lets a component that is not from shadcn merge unconverted (§ How a PR in flight
is handled). Backfill PRs carry no ticket (lead’s direction, 2026-10-09): feat: move the <screen> to shadcn/ui, branch feature/shadcn-<screen>.
Target layouts
A screen moved over is also restructured to the layout the team decided at the internal demo of 2026-10-21 (design-system Rev 70, approved by the lead): every list screen a table like the Users list, each row ending with a ⋯ menu of View, Edit and one action specific to the screen, and the whole row opening the record in view mode; every record page one centred column like the user editor, opening in view mode with an Edit action, which the menu’s Edit opens directly; every create flow a modal, like the create-user dialog; every form field’s placeholder Enter and the field’s name (Enter company name), never an example value; Settings a page of links, with Users and Roles moved onto it; the sidebar reordered. The work goes in this order: the Leads list, then the lead page, then the rest one PR each. A screen’s PR follows its row here, and changes the row when it lands or when a decision changes the target.
| Screen | Target | Still to decide |
|---|---|---|
| Leads list | A table like the Users list, replacing the two-pane list and detail; View opens the lead page | The third row action |
| Lead page | Its own centred page (§6 Detail page), designed afresh; the tabbed detail on feature/shadcn-lead-detail is kept only for comparison. Edited on the page (design-system Rev 74, feature/ui-revamp): /leads/:id/edit is the page’s edit mode with the shared Save bar (LeadEditPage), not the Edit lead dialog |
Its layout |
| Accounts list | Already a table; its row actions become the ⋯ menu. Built in forge-et-fe#337: whole-row click, ⋯ menu of View, Edit, Archive/Restore | The third row action |
| Account page | One centred column instead of the full width | — |
| Account form | New account opens a modal over the list instead of the /accounts/new page; the Edit page stays a centred page. Built in forge-et-fe#337: the modal, /accounts/new removed; a save from the list’s ⋯ Edit returns to the account page. Edit page on the Save bar (design-system Rev 74, feature/ui-revamp): the account’s name as the h1, the shared Save bar at the top in place of the bottom Cancel / Save changes |
— |
| Contacts list | Already a table; its row actions become the ⋯ menu. Built in forge-et-fe#337: whole-row click, ⋯ menu of View, Edit, Archive/Restore, Attach to account | The third row action |
| Contact view | A centred page, as the account page. Built in forge-et-fe#337: /contacts/:id and /contacts/:id/edit, on shadcn, in place of the pop-up. Edited on the page (design-system Rev 74, feature/ui-revamp): /contacts/:id/edit is the page’s edit mode with the shared Save bar (ContactEditForm, on shadcn), not the contact Modal; the account page’s contact Edit opens it |
Whether contact names on the account page link to it (owed.md) |
| Pricing (Buying Standards book) | Its tables’ row actions become the ⋯ menu. Built in forge-et-fe#337 for the standards and weekly-prices tables, with no View and no row click (no record page) | The third row action (Archive was the demo’s example) |
| Users list, Roles list | The table model; they move from the sidebar to the Settings page, and their row menus are checked against View, Edit, one action. Built in forge-et-fe#337: /settings/users and /settings/roles, each with ← Settings, a ⋯ menu of View and Edit |
The third row action |
| User page, role page | Open in view mode with an Edit action, instead of straight into the editor; the menu’s Edit opens the editor. Built in forge-et-fe#337: /settings/users/:id and /settings/roles/:id in view mode, …/edit the editors; a save returns to view mode |
— |
| Unchanged, except that its Email templates button goes when the templates move. Built in forge-et-fe#337: the button is gone | — | |
| Email templates | Move under Settings, reached from the Settings page; New template opens a modal instead of the /email/templates/new page. Built in forge-et-fe#337: /settings/email-templates, a view page at …/:id and the editor at …/:id/edit, and the modal |
— |
| Settings | A page of links, each item (the lead, account and contact tags, the email templates, Users, Roles) opening its own page, in place of the tabs; the entry, the page and every item are shown and guarded on settings.manage (design-system Rev 71; Users and Roles were on access.manage and the email templates on email.manage until AD #34’s refinement of 2026-10-26). Built in forge-et-fe#337: /settings, a grid of cards; each tag type at /settings/tags/<type> |
— |
| App frame | Sidebar order Leads, Accounts, Contacts, Pricing, Email, Settings | — |
| Every table | The whole row opens the record in view mode; the name cell stays the link; the row’s controls never open it. Built in forge-et-fe#337 for every table but Leads (its own branch) and the Settings tag rows. One look for every table (design-system Rev 74, feature/ui-revamp): every table takes the shared classes in src/ui/dataTable.ts; the Settings tag rows’ Edit and Retire/Restore moved into a ⋯ menu |
— |
| Every form (create modals, edit pages, dialogs) | Each typed field’s placeholder is Enter and its name in lower case; a select, date or picker’s is Select and its name (design-system Rev 74); an example value becomes helper text where the format matters. Built on feature/ui-revamp (src/ui/fields/placeholders.ts) |
— |
How a screen is moved over
The Users list is the worked example (forge-et-fe#201, see the table).
- The revamped colours are already on: every route but
/loginhastheme: 'revamp'in itshandleinsrc/app/router.tsx(design-system Rev 74), so the shared components take the revamped colour layer (src/ui/styles/theme-revamp.css) everywhere. A new route adds it too. - Let Tailwind see the feature: add the feature folder to the
@sourcelines insrc/ui/styles/shadcn.css. A class Tailwind does not see in the source is not generated, and a class built from pieces at runtime is never seen. - Replace the components with the ones in
src/ui/shadcn. When one is missing, add it with the shadcn CLI and adapt it asforge-et-fe/CLAUDE.md § Conventionssays (aria-disabled, no own focus ring, registry icons,Fieldwiring, the testid-exempt comment; remove the straycnpackage if the CLI added it). A status stays the §5 Status indicator (dot plus word), never a Badge. - Keep what tests and users rely on: the same test ids and the same accessible names. Where a
control changes kind (a native
<select>becomes the shadcn Select), update the browser specs to open it and choose an option (chooseSelectOptionine2e/browser/users/support.ts). - Check it: unit tests,
pnpm check,typecheck,check:testids,check:boundaries, the screen’s browser specs and its size-matrix states at every size (pnpm e2e:gate --selected); the nightly full run then checks everything onmain. Look at the screen at 1280px and 320px as well: the checks do not catch a control 4px out of line. - Remove the screen’s entries from
src/app/shadcnBackfill.jsonin the frontend PR; the test fails an entry the file no longer needs. - Update this file in a harness commit: the row’s status and PR, and anything the screen still
uses from
src/ui.
How a PR in flight is handled
frontend-reviewer checks every frontend PR for components that are not from shadcn
(.claude/agents/frontend-reviewer.md, dimension 23). For each one it decides, and records in the review:
- Convert before merge — the component is new in this PR, the change is small, and nothing else on the screen is still older code; or
- List it — the screen is still mostly older code, or converting would hold up a delivery date.
The author adds the file and name to
src/app/shadcnBackfill.jsonin the frontend PR, and adds or extends the screen’s row below in a harness commit.
The author may ask the lead to overrule either way. Without a list it decision the test fails, so nothing that is not from shadcn merges unseen.
A PR or local branch started before the test landed. Branches need not be up to date with
main to merge, so such a PR’s own test run does not include the check. Its review does
(frontend-reviewer dimension 23), and once it merges, the next pnpm test on main or on any
branch that has merged main fails on what it added, until the use is converted or listed. To
avoid that, a developer with such a branch merges main in before its test record (a reason
.claude/rules/git-conventions.md § Branching accepts: the branch needs a check that landed on
main) and converts or lists what the test reports.
Screens
Status: not started, in progress (some parts moved; the row says which remain), done.
| Screen | Route | Feature folder | Status | PR | Still on src/ui |
|---|---|---|---|---|---|
| Users list | /settings/users (was /users) |
users |
in progress | forge-et-fe#201 (merged 2026-10-13); forge-et-fe#337 (the move into Settings, the ⋯ menu); feature/ui-rev100 (the created toast is Sonner, design-system Rev 90); feature/ui-polish-round-2 (the create-user dialog’s Role on shadcn’s Select through OptionSelect, design-system Rev 110) |
the create-user dialog (CreateUserModal) is on the shared dialog frame with shadcn’s Button and Input, Role on OptionSelect and Manager on SearchSelect; left: its Field wiring, EmptyState, ErrorPanel, TraceLine |
| User editor | /settings/users/:id/edit (was /users/:id; the view page at /settings/users/:id is shadcn’s) |
users |
in progress | forge-et-fe#201 (merged 2026-10-13); forge-et-fe#337 (the view page) | Field, ActivationFailurePanel (Card), ErrorPanel, the loading placeholders (LoadingSkeleton, in UserEditorRoute and the effective-permissions section). The deactivate and reactivate confirmation (ActivationDialog) is shadcn’s Dialog at the sm size since feature/ui-rev100 (design-system Rev 90, Rev 100), and the Access card’s deactivation for a user who still owns records or has direct reports opens the Deactivate User dialog (next row) |
Deactivate User dialog (was the Offboard user screen, /settings/users/:id/offboard, removed by design-system Rev 100) |
over /settings/users/:id |
users |
in progress | feature/ui-revamp (both tables on shadcn’s Table, the owned records’ pager ListPager); feature/ui-rev100 (the screen, its header and its Deactivate section deleted; the dialog, DeactivateUserDialog, is shadcn’s Dialog at the lg size) |
the sections inside the dialog (F5-h): OffboardRecordsSection (Card, LoadingSkeleton), OffboardReportsSection (Button, Card), OwnedRecordsList (Button), RowSelection and BulkActionBar. Since feature/ui-polish-round-2 the missing-keys notice (MissingKeysNotice) is shadcn’s Alert (warning) and the Change Manager dialog (ChangeManagerDialog) is on the shared dialog frame with OwnerPicker on SearchSelect (design-system Rev 110). Change Owner and its result are the shared src/ui/bulkReassign parts (the Change Owner dialog (shared) row) |
| Roles list | /settings/roles (was /roles) |
roles |
in progress | forge-et-fe#262; forge-et-fe#337 (the move into Settings, the ⋯ menu) | the table is shadcn’s (the Users table’s pattern, no Permissions column — BUG-140); New role is shadcn’s Button (feature/ui-revamp); the deleted toast is Sonner (feature/ui-rev100, design-system Rev 90); left: the create-role dialog (CreateRoleModal: Modal, Button, Input) |
| Role editor | /settings/roles/:id/edit (was /roles/:id; the view page at /settings/roles/:id is shadcn’s) |
roles |
in progress | forge-et-fe#262; forge-et-fe#337 (the view page) | BUG-191 adds the save bar and its Sonner toasts in shadcn components, leaving the rest: Button, Card, Input, the leave and delete dialogs (Modal), the entity choices (Radio), the ticks (Checkbox, Tooltip), LoadingSkeleton |
| Accounts list | /accounts |
accounts |
in progress | forge-et-fe#262; forge-et-fe#337 (whole-row click, the ⋯ menu) | the data bar (search, the Customer type, Country, Region, Tag and Owner multi-choice filters — FilterMultiSelect, shadcn’s Popover, Checkbox and Label, since F32-d-WI-1.2 — the single-choice Pipedrive Owner filter (shadcn’s Select, the shared FilterSelect; F32-c), Show archived and Shared with me, Clear filters, and since F32-d-WI-2.2 the Columns menu — ColumnsMenu, shadcn’s Popover, Checkbox, Label and Button), the saved views row above the data bar (since F32-d-WI-3.2: ViewsRow, shadcn’s Tabs, DropdownMenu, Tooltip, Skeleton, Badge and Button) and its save, rename and delete dialogs (since F32-d-WI-3.3: ViewActions, SaveViewDialog, RenameViewDialog, DeleteViewDialog — shadcn’s Button, DropdownMenu through RowActionsMenu, Dialog through RecordEditDialog, AlertDialog, Input, Checkbox and Label), the table and its card are shadcn’s, and since feature/ui-revamp so are New account and the pager (ListPager); left: the state panels’ buttons (Button), the notice (Toast) and the table’s status Badge. F32-c-WI-1.2 adds row selection and Change Owner (shadcn’s Button and Sonner, and the shared dialog below), leaving two older parts used as they are: the selection cells’ Checkbox (SelectionHeaderCell, SelectionCell, SelectionAnnouncer, useRowSelection) and BulkActionBar’s Buttons — shared with the offboarding lists, moved over with them |
| Account form | /accounts/:id/edit, and the New account dialog over /accounts (/accounts/new removed) |
accounts |
in progress | forge-et-fe#337 (the dialog’s frame and ✕ are shadcn’s); feature/ui-revamp (the edit page’s shared Save bar) |
the form itself (AccountFormPage: its fields — Card, Checkbox, CheckboxGroup, Input — and the New account dialog’s Buttons). The leave and reload questions are shadcn’s (ConfirmDialog) since feature/ui-rev100; Region, Customer Type and Currency are on OptionSelect and Country and Owner on SearchSelect since feature/ui-polish-round-2 (design-system Rev 110) |
| Account page and contacts panel | /accounts/:id |
accounts |
in progress | forge-et-fe#262, forge-et-fe#362 | the Buying standards panel’s table and the card around it are shadcn’s (forge-et-fe#262; the card since design-system Rev 107), and so is the Add contact dialog (F20-l WI-3.1, forge-et-fe#362); left: the rest of the screen (F1-d, on main since its wave merged), including that panel’s Badge, Button, Input, LoadingSkeleton and Switch (its pager is ListPager since feature/ui-revamp), and the archive dialog (a contact’s edit moved to the contact’s page, on shadcn, in feature/ui-revamp); F20-c’s entry points from features/email/recordEntries: AccountComposeAction (Button, the header’s Compose email) and ContactComposeAction (Button, a contact row’s Email) |
| Leads list | /leads |
leads |
in progress | forge-et-fe#338 | the title bar, status pills, data bar (src/ui/filters/DataBarControls, and since F32-d-WI-2.2 the Columns menu, ColumnsMenu on shadcn’s Popover, Checkbox, Label and Button), the saved views row between the title bar and the status pills (since F32-d-WI-3.2: ViewsRow, shadcn’s Tabs, DropdownMenu, Tooltip, Skeleton, Badge and Button) and its save, rename and delete dialogs (since F32-d-WI-3.3: ViewActions, SaveViewDialog, RenameViewDialog, DeleteViewDialog — shadcn’s Button, DropdownMenu through RowActionsMenu, Dialog through RecordEditDialog, AlertDialog, Input, Checkbox and Label), table, row ⋯ menu and pager are shadcn’s, and the route has theme: 'revamp'; left: the New lead form dialog (LeadFormDialog, with LeadTeaRequirementsGroup: Button, DateInput, Input, Modal, Textarea, CheckboxGroup; its selects are on OptionSelect and Country and Owner on SearchSelect since feature/ui-polish-round-2, design-system Rev 110), the inquiry extraction dialog (F12, InquiryExtractionDialog: Button, Modal, Textarea) — both kept on the older Modal’s wide because the hand-off from the extraction to the form relies on the native dialog closing before the next one opens (F11-b Rev 10, F12 Rev 9). The notice (useLeadsNotice) is Sonner since feature/ui-rev100 (design-system Rev 90). F32-c-WI-1.2 adds row selection and Change Owner on shadcn’s Button and Sonner, leaving, as on the Accounts list, the selection cells’ Checkbox and BulkActionBar’s Buttons |
| Change Owner dialog (shared) | over /accounts, /leads and the Deactivate User dialog’s lists |
src/ui/bulkReassign |
done | F32-c-WI-1.2; feature/ui-polish-round-2 (OwnerPicker on SearchSelect, design-system Rev 110) |
nothing with a shadcn counterpart: ChangeOwnerDialog is on the shared Rev 90 frame (RecordEditDialog, shadcn’s Dialog) with shadcn Buttons, PassResult on shadcn’s Card, and OwnerPicker — shared with the account form, the lead form, the follow-up fields and Change Manager — is SearchSelect (shadcn Input + Popover) in a Field instead of a native <select> |
| Lead page | /leads/:id, /leads/:id/edit |
leads |
in progress | feature/ui-revamp (/edit is the page’s edit mode with the shared Save bar and a shadcn Card, LeadEditPage; the route on theme: 'revamp') |
a page of its own since forge-et-fe#338 (the two-pane layout is gone): the lead view, its sections and dialogs, and the lead form’s fields (LeadFormDialog, shared by New lead and the edit page: Button, DateInput, Input, Modal, Textarea; its selects and pickers moved in feature/ui-polish-round-2, as the Leads list row says); the match dialog’s record search (RecordSearchPicker, LeadMatchModal) is on shadcn Input + Popover since feature/ui-polish-round-2, not react-aria-components; F20-c’s email panel, features/email/recordEntries/LeadEmailPanel (Button, Card); F11-h’s features/aiDrafts/LeadApproveSendAction (Toast — the approval’s toast, which needs shadcn’s Sonner, keeping the live region). Already on shadcn: F11-h’s Follow-up draft panel and Approve & send button (features/aiDrafts), and the heading row’s actions list renderer, LeadActionsPlace |
| Sharing panel and dialogs | on /accounts/:id and /leads/:id |
sharing |
done | forge-et-fe#364 | nothing with a shadcn counterpart: the Shared with card and its Access to … dialog (SharingPanel, AddColleagues) are on shadcn’s Card, Button and the shared RecordEditDialogFrame; ShareDialog and RemoveShareDialog are gone (F5-g Rev 1). StatusIndicator, ErrorPanel and TraceLine stay (no shadcn counterpart) |
| Tag and note parts (shared) | every screen that shows tags or notes | src/ui/tags, src/ui/notes, src/ui (TagBadge.tsx) |
in progress | forge-et-fe#364 | raw <button>s kept on purpose, none button-shaped (frontend-reviewer on forge-et-fe#364 decided to list them): TagLine’s +N (TagLine.tsx — a bare count that opens the tag popover); AddTagControl’s dashed + Add tag chip (AddTagControl.tsx — drawn as a tag-sized chip); TagRemoveButton’s ✕ (TagBadge.tsx — a 24px target laid out inside the tag); NoteEntry’s Show more toggle and NoteComposeLine (NoteEntry.tsx — a text toggle in the note’s flow, and a field-shaped line that opens the composer). NoteItem (a note with its Edit and Delete) and noteText.ts moved here from src/features/notesAndTags in feature/ui-polish-round-2, so the account, contact and lead notes share them (F11-f Rev 13); NoteItem is on shadcn’s Button, Textarea and Tooltip and adds nothing older |
/email |
email |
done | forge-et-fe#343; forge-et-fe#348 | nothing with a shadcn counterpart: on theme: 'revamp' since forge-et-fe#348, which moved the cards, buttons and loading state (SkeletonLines, src/ui/skeletonLines.tsx) to shadcn and made the list and the open message two panes at bp/laptop and wider. EmptyState, ErrorPanel, TraceLine and StatusIndicator stay (no shadcn counterpart) |
|
| Mailbox | /email/mailbox |
email |
done | forge-et-fe#382 (F20-i-WI-1.3) | nothing with a shadcn counterpart: PageHeading, PageTitle, StatusIndicator, ErrorPanel, TraceLine, Icon and EmailValue stay; every connect button on the screen is now the shadcn primary Button |
| Email message view | /email/messages/:id |
email |
done | forge-et-fe#348 | nothing with a shadcn counterpart: the email route’s child, on its theme: 'revamp', shown in the inbox’s reading pane at bp/laptop and wider and alone below it; BackLink, ErrorPanel, TraceLine and SafeMessageBody stay (no shadcn counterpart). F20-i WI-2.5 added the categories (shadcn Badge), Mark as unread and Download (shadcn Button) and the attachment list (AttachmentRow, no shadcn counterpart); nothing older added |
| Compose email dialog | on every route (src/app/ComposeEmailProvider.tsx mounts it app-wide; opened over /email, /email/messages/:id, /accounts/:id and /leads/:id) |
email (compose/), src/app |
in progress | forge-et-fe#277 (merged, F20-h Wave 1; WI-1.2); F20-d Wave 1 (WI-1.2) | F20-c’s dialog as F20-c left it: ComposeEmailDialog uses Modal with onCloseRequest (the discard question on ✕, Esc and the browser’s close watcher must survive the move to shadcn’s Dialog), Button, Input and LoadingSkeleton. The sent toast in ComposeEmailLayer and the load-failed toast in ComposeEmailProvider are Sonner since feature/ui-rev100 (design-system Rev 90; F20-c Rev 11). Already on shadcn: the rich-text body’s toolbar, its link field and Insert template (F20-d); F20-h’s attachment sections (ComposeAttachmentsSection, ForwardAttachments) on shadcn Button, Skeleton and Progress, keeping FileUpload, ErrorPanel, TraceLine and AttachmentRow (none has a shadcn counterpart) with CSS Modules on the tokens. Two looks in one dialog until it is moved: the shadcn parts draw the revamp tokens, and F20-c’s older Send and Cancel do too only over a route on theme: 'revamp' — /email and /email/messages/:id since forge-et-fe#348 — so over any other route they still look different (design-system Rev 62) |
| Pricing (Buying Standards book) | /pricing |
pricing |
in progress | forge-et-fe#262; forge-et-fe#337 (the row menus became the shared ⋯ menu) | the title bar, filters, the standards, weekly-prices and auction-sales tables, their pagination and row menus are shadcn’s; left: the tabs (Tabs), the client and sale pickers (Combobox, waiting on approval of cmdk), Badge, the import’s check panels (Card; the page warnings moved to shadcn’s Alert with BUG-423), the round status’s <button> and Tooltip, the dialogs’ contents (Button, Input, DateInput, Textarea, Select, CheckboxGroup; Not in round and Price history also LoadingSkeleton and Pagination — their tables moved to shadcn’s Table in feature/ui-revamp), the draft price dialog (DraftPriceDialog: Modal, kept because its Combobox list would be clipped by the Rev 90 frame) and TabSection’s Select and Switch. Since feature/ui-rev100 every other dialog’s frame is shadcn’s Dialog through PricingDialog (design-system Rev 90) and the toasts are Sonner |
| Pricing import | /pricing/import |
pricing |
in progress | feature/ui-revamp (the rows-to-draft and problems tables on shadcn’s Table; the route on theme: 'revamp'); feature/ui-rev100 (the Replace and create question and New sale on the Rev 90 frame, the result a Sonner toast) |
the rest of the screen, including the tables’ Buttons, the step cards (Card) and the sale picker (Combobox) |
| Sign in | /login |
auth |
not started | — | the whole screen |
| Not found | * |
src/app |
not started | — | the whole screen (NotFoundRoute: Button); the route is on theme: 'revamp' since feature/ui-revamp |
| App frame | every route | src/app |
in progress | forge-et-fe#201 (merged 2026-10-13); forge-et-fe#262 | the sidebar is in-house (the current-user menu is shadcn’s DropdownMenu and Avatar since forge-et-fe#382, F20-i-WI-1.3); on every route the top bar is removed, the sidebar toggle is in the sidebar and the sidebar carries the revamp colours. That toggle is the src/ui ghost-icon Button, whose fill and border Sidebar.module.css .brandToggle > button overrides; it becomes shadcn’s Button (variant="ghost", an icon size) and the override goes. shadcn’s Sidebar is not adopted yet; ComposeEmailProvider’s load-failed Toast (F20-c) |
When every row is done, the in-house components left unused in src/ui are removed, with
react-aria-components and its patch (patches/react-aria@3.52.1.patch), and theme-revamp.css
becomes the only theme. Every route but /login already uses it (design-system Rev 74).