source: .forge/design/harness/shadcn-only-check.md · generated — edit the markdown, not this file

The shadcn-only check — Design

Status: approved. Approval: Tharinda Rajapaksha (lead), reported by Nanndish, 2026-10-12 Author: Nanndish Date: 2026-10-12 Scope: forge-et-fe — a unit test, src/app/shadcnOnly.test.ts, and the list it reads, src/app/shadcnBackfill.json (forge-et-fe#201); in the harness, the AD #39 row, frontend-reviewer dimension 23, frontend-implementer, .forge/design/ui/shadcn-backfill.md and .forge/owed.md (forge-et-harness#528). No workflow, ruleset or hook changes.

Context

AD #39 (2026-10-09) makes shadcn/ui the CRM’s component library. As first written, a non-shadcn component in a frontend PR was left to frontend-reviewer’s judgement on that PR: convert it before merge, or list the screen on .forge/design/ui/shadcn-backfill.md. Nothing stopped a use the review missed, and the screens built before AD #39 were tracked only in prose.

The developer asked on 2026-10-12 for a check that stops any UI that is not from shadcn from merging, and that covers three groups of code: the screens already built, the PRs and local branches in flight, and all later work. The lead agreed to replacing the per-PR judgement with an automatic check.

How a frontend PR is checked today (.claude/rules/git-conventions.md § Pull Requests, as of origin/main on 2026-10-12): the Fast lane runs the static checks; the test suite runs on the developer’s machine through pnpm test:record, which runs pnpm test and sets the required Test record commit status only when every test passes. So a failing unit test blocks the merge with no workflow change.

Decisions

D-1 — A unit test, not a lint rule or a new CI step. The check is a Vitest test, src/app/shadcnOnly.test.ts, over a helper, src/test/shadcnScan.ts, that parses each file with the TypeScript compiler API (typescript-classic, as scripts/check-testid-coverage.mjs does), so a comment or a string neither hides nor fakes a use. Fixed example sources pin the helper, so it cannot pass unseen once the list is empty. It runs in pnpm test, so it is part of the Test record check and of every developer’s normal test run. A new CI step or hook would need the lead’s approval for a pipeline change and would run in only one place. A Biome or dependency-cruiser rule cannot express “this name from the src/ui barrel”, because the screens import most components from that one barrel.

D-2 — What counts as not shadcn. In files under src/features and src/app (.ts and .tsx, tests excluded):

  • a non-type use of a component from the older src/ui (its barrel or any module in it other than src/ui/shadcn) that has a shadcn counterpart, whether named, aliased, through a namespace import, re-exported or imported dynamically — Avatar, Badge, Button, Card, Checkbox, CheckboxGroup, Combobox, DateInput, DateRangeInput, DropdownMenu, Input, LoadingSkeleton, Modal, OwnerPicker, Pagination, Radio, RecordSearchPicker, Select, StandardPicker, Switch, Tabs, Textarea, Toast, Tooltip (the REPLACED map);
  • any import from react-aria-components, react-aria or @react-aria/*;
  • a raw <button>, <input>, <select>, <textarea>, <table> or <dialog> JSX element.

Every other src/ui export has no shadcn counterpart and is not counted — for example StatusIndicator, ErrorPanel, TraceLine, AiProvenance, EmptyState, Field, FileUpload, BackLink, BulkActionBar, SortableHeaderCell, PriceStateIndicator, the row-selection parts, Icon and the permission guard. A component rebuilt on shadcn inside src/ui (a picker moved onto Command, for example) leaves REPLACED in the same change. src/ui itself is not scanned: it is the library being replaced, and the shadcn components there render raw elements by design.

D-3 — Existing code is listed, file by file, and the list only shrinks. src/app/shadcnBackfill.json maps each file to the names it used on 2026-10-12, generated from the tree with the same helper the test uses (106 files, after forge-et-fe#201’s branch merged main). The test fails:

  1. a use the list does not name (new non-shadcn UI);
  2. an entry the file no longer needs (a screen moved over must remove its entries, so the list cannot keep room for a later regression);
  3. an unsorted list (so each change is a one-line diff).

The granularity is the file and the name, not a count: a second Button in a file already listed for Button passes. That file is moved over whole in its backfill PR, and counting uses would make every unrelated edit to a listed screen churn the list.

D-4 — Adding an entry is the reviewer’s decision. The per-PR choice AD #39 gave frontend-reviewer stays, as the decision to add an entry: list it means the PR adds the file and name to the JSON list and the screen’s row in shadcn-backfill.md. An entry added without that decision in the review is an Important (frontend-reviewer dimension 23). frontend-implementer never adds an entry to make the test pass; it reports the question in its hand-off. Nothing in the test can tell an approved entry from an unapproved one, so the review is the control for growth.

D-5 — Work in flight. A branch does not have to be up to date with main to merge, so a PR or local branch started before the test lands does not run it, and could merge a non-shadcn use. Three things cover that:

  • its review applies dimension 23, and the review record is a required check;
  • once it merges, the next pnpm test on main, or on any branch that has merged main, fails on what it added, so it is caught at once and converted or listed;
  • the day forge-et-fe#201 merges, the team is told and each open frontend PR’s author is asked to merge main in before their test record (.forge/owed.md). That is a reason to merge main that git-conventions.md § Branching accepts: the branch needs a check that landed on main.

What it does not cover

  • forge-et-pwa: AD #39 covered forge-et-fe only; since AD #43 (2026-11-20) the capture app has its own copy of the test, scan and list (.forge/design/ui/pwa-shadcn.md D-4).
  • Class names and styling: a literal colour or a runtime-built class name stays a review finding (dimension 23), as the token scans already cover inline styles.
  • A non-shadcn component built inside a feature folder from raw <div>s with ARIA roles: the scan sees only the six raw controls. The review catches the rest.

Verification (2026-10-12, on forge-et-fe#201’s branch at bcf8546, then 2481f19)

  • vitest run src/app/shadcnOnly.test.ts → 4 passed at bcf8546; 21 passed at 2481f19 (17 fixed examples plus the 4 tree checks), and the parser-based scan regenerated the list unchanged.
  • A probe file in src/features/users importing the older Button and drawing a raw <button> → the test failed and named both; the probe was removed.
  • An added list entry the file did not need (app/TopBar.tsx: Tabs) → the test failed with “remove these entries”; the list was restored.
  • pnpm check, pnpm typecheck, pnpm check:boundaries → exit 0.

Generated from .forge/design/harness/shadcn-only-check.md by .claude/lib/render-docs-html.js. Markdown is canonical.