source: .forge/design/ui/shadcn-backfill.md · generated — edit the markdown, not this file

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 —
Email 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).

  1. The revamped colours are already on: every route but /login has theme: 'revamp' in its handle in src/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.
  2. Let Tailwind see the feature: add the feature folder to the @source lines in src/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.
  3. Replace the components with the ones in src/ui/shadcn. When one is missing, add it with the shadcn CLI and adapt it as forge-et-fe/CLAUDE.md § Conventions says (aria-disabled, no own focus ring, registry icons, Field wiring, the testid-exempt comment; remove the stray cn package if the CLI added it). A status stays the §5 Status indicator (dot plus word), never a Badge.
  4. 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 (chooseSelectOption in e2e/browser/users/support.ts).
  5. 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 on main. Look at the screen at 1280px and 320px as well: the checks do not catch a control 4px out of line.
  6. Remove the screen’s entries from src/app/shadcnBackfill.json in the frontend PR; the test fails an entry the file no longer needs.
  7. 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.json in 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 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).

Generated from .forge/design/ui/shadcn-backfill.md by .claude/lib/render-docs-html.js. Markdown is canonical.