docs/plans/2026-04-10-shadcn-design-token-cleanup.md
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Align all React code with shadcn best practices — semantic color tokens, proper spacing utilities, and consistent component patterns.
Architecture: Add missing semantic tokens to the CSS variable system, fix the shared UI components first (highest leverage), then sweep page-level code area by area. Each task is independently mergeable.
Tech Stack: Tailwind CSS v4, CSS custom properties, React + Base UI + cva
background and overlay semantic tokensFiles:
frontend/src/assets/css/tailwind.css (:root block, lines 106-168)Step 1: Add the tokens
In the :root block inside @layer base, add after the --color-control-border line:
/* white - page/card/panel background */
--color-background: 255 255 255; /* #ffffff */
/* black/50 - overlay backdrop */
--color-overlay: 0 0 0; /* #000000, use as bg-overlay/50 */
Step 2: Verify Tailwind picks them up
Run: pnpm --dir frontend type-check
Expected: PASS (CSS vars are auto-available in Tailwind v4 via @config)
Step 3: Commit
git add frontend/src/assets/css/tailwind.css
git commit -m "feat(frontend): add background and overlay semantic color tokens"
dialog.tsx — replace hardcoded colorsFiles:
frontend/src/react/components/ui/dialog.tsxStep 1: Replace bg-black/50 with bg-overlay/50
Line 20: "fixed inset-0 z-50 bg-black/50" → "fixed inset-0 z-50 bg-overlay/50"
Step 2: Replace bg-white with bg-background
Line 42: "rounded-sm bg-white shadow-lg" → "rounded-sm bg-background shadow-lg"
Step 3: Replace text-gray-500 with text-control-light
Line 77: "text-sm text-gray-500" → "text-sm text-control-light"
Step 4: Verify
Run: pnpm --dir frontend type-check
Step 5: Commit
git add frontend/src/react/components/ui/dialog.tsx
git commit -m "fix(frontend): use semantic tokens in Dialog component"
select.tsx — replace hardcoded colors and use size-*Files:
frontend/src/react/components/ui/select.tsxStep 1: Replace bg-white with bg-background
Line 20 (SelectTrigger): bg-white → bg-background
Line 51 (SelectContent): bg-white → bg-background
Step 2: Replace w-3.5 h-3.5 with size-3.5
Line 29: className="w-3.5 h-3.5 opacity-50 shrink-0" → className="size-3.5 opacity-50 shrink-0"
Line 82: className="w-3.5 h-3.5" → className="size-3.5"
Step 3: Verify
Run: pnpm --dir frontend type-check
Step 4: Commit
git add frontend/src/react/components/ui/select.tsx
git commit -m "fix(frontend): use semantic tokens and size shorthand in Select"
combobox.tsx — replace hardcoded colorsFiles:
frontend/src/react/components/ui/combobox.tsxStep 1: Replace all bg-white with bg-background
Lines 328, 365: bg-white → bg-background
Step 2: Replace any w-N h-N pairs with size-N
Scan for matching w/h pairs and replace.
Step 3: Verify
Run: pnpm --dir frontend type-check
Step 4: Commit
git add frontend/src/react/components/ui/combobox.tsx
git commit -m "fix(frontend): use semantic tokens in Combobox"
switch.tsx — replace hardcoded colorsFiles:
frontend/src/react/components/ui/switch.tsxStep 1: Replace bg-white with bg-background
Line 37: bg-white → bg-background
Step 2: Verify & commit
git add frontend/src/react/components/ui/switch.tsx
git commit -m "fix(frontend): use semantic tokens in Switch"
alert.tsx — use size-* shorthandFiles:
frontend/src/react/components/ui/alert.tsxStep 1: Replace h-5 w-5 with size-5
Line 52: className="h-5 w-5 shrink-0 mt-0.5" → className="size-5 shrink-0 mt-0.5"
Step 2: Verify & commit
git add frontend/src/react/components/ui/alert.tsx
git commit -m "fix(frontend): use size shorthand in Alert icon"
space-x/y → gap (23 instances, 7 files)DatabaseObjectExplorer.tsxFiles:
frontend/src/react/pages/project/database-detail/overview/DatabaseObjectExplorer.tsxStep 1: Replace all space-y-* with flex flex-col gap-*
For each occurrence (lines 357, 386, 414, 421, 441, 451, 460, 470, 476, 486):
flex flex-col: just replace space-y-N with gap-Ndiv/section: add flex flex-col and replace space-y-N with gap-NExample: <section className="space-y-4"> → <section className="flex flex-col gap-4">
Step 2: Verify
Run: pnpm --dir frontend type-check
Step 3: Commit
git add frontend/src/react/pages/project/database-detail/overview/DatabaseObjectExplorer.tsx
git commit -m "fix(frontend): replace space-y with flex gap in DatabaseObjectExplorer"
Files:
frontend/src/react/plugins/agent/components/ToolCallCard.tsx (lines 225, 306)frontend/src/react/plugins/agent/components/AgentChat.tsx (line 95)frontend/src/react/pages/settings/PurchaseSection.tsx (lines 366, 608)frontend/src/react/pages/settings/RiskAssessmentPage.tsx (lines 17, 31)frontend/src/react/pages/settings/DataClassificationPage.tsx (lines 333, 606)frontend/src/react/pages/project/database-detail/revision/CreateRevisionDialog.tsx (lines 109, 110, 140, 163)Step 1: Apply the same pattern as Task 7
For each space-y-N or space-x-N:
flex flex-col gap-N (for space-y) or flex gap-N (for space-x)flex: just swap the spacing utilityStep 2: Verify
Run: pnpm --dir frontend type-check
Step 3: Commit
git add frontend/src/react/plugins/agent/components/ToolCallCard.tsx \
frontend/src/react/plugins/agent/components/AgentChat.tsx \
frontend/src/react/pages/settings/PurchaseSection.tsx \
frontend/src/react/pages/settings/RiskAssessmentPage.tsx \
frontend/src/react/pages/settings/DataClassificationPage.tsx \
frontend/src/react/pages/project/database-detail/revision/CreateRevisionDialog.tsx
git commit -m "fix(frontend): replace space-x/y with flex gap across React pages"
Strategy: Work area by area. For each file, replace raw Tailwind colors with the closest semantic token:
| Raw Color | Semantic Token |
|---|---|
bg-white | bg-background |
bg-black/50, bg-black/40, bg-black/30 | bg-overlay/50, bg-overlay/40, bg-overlay/30 |
bg-gray-50, bg-gray-100 | bg-control-bg |
bg-gray-200 | bg-control-bg-hover |
text-gray-400 | text-control-placeholder |
text-gray-500, text-gray-600 | text-control-light |
text-gray-700, text-gray-800, text-gray-900 | text-control or text-main |
border-gray-200 | border-block-border |
border-gray-300 | border-control-border |
bg-blue-500, bg-blue-600, text-blue-600 | bg-info / text-info or bg-accent / text-accent (context-dependent) |
bg-red-500, bg-red-600, text-red-500, text-red-600 | bg-error / text-error |
bg-green-500, bg-green-600, text-green-600 | bg-success / text-success |
bg-yellow-500, text-yellow-600 | bg-warning / text-warning |
bg-indigo-*, text-indigo-* | bg-accent / text-accent variants |
Important: Some raw colors are intentional (e.g., syntax highlighting, status indicators with specific shades). Use judgment — if a color conveys semantic meaning (error, warning, info, success, accent), use the token. If it's decorative or specific to a visualization, leave it.
Files:
frontend/src/react/plugins/agent/components/AgentWindow.tsxfrontend/src/react/plugins/agent/components/AgentChat.tsxfrontend/src/react/plugins/agent/components/AgentInput.tsxfrontend/src/react/plugins/agent/components/ToolCallCard.tsxStep 1: Read each file and identify all raw color classes
Step 2: Replace with semantic tokens per the mapping table above
Step 3: Verify
Run: pnpm --dir frontend type-check
Step 4: Commit
git add frontend/src/react/plugins/agent/
git commit -m "fix(frontend): use semantic color tokens in Agent plugin components"
Files:
frontend/src/react/components/database/CreateDatabaseDrawer.tsxfrontend/src/react/components/database/TransferProjectDrawer.tsxfrontend/src/react/components/database/LabelEditorDrawer.tsxfrontend/src/react/components/EditEnvironmentDrawer.tsxfrontend/src/react/components/CreateWorkloadIdentityDrawer.tsxStep 1: Replace bg-black/50 and bg-black/30 with bg-overlay/50 and bg-overlay/30
Step 2: Replace bg-white with bg-background
Step 3: Verify & commit
git add frontend/src/react/components/database/CreateDatabaseDrawer.tsx \
frontend/src/react/components/database/TransferProjectDrawer.tsx \
frontend/src/react/components/database/LabelEditorDrawer.tsx \
frontend/src/react/components/EditEnvironmentDrawer.tsx \
frontend/src/react/components/CreateWorkloadIdentityDrawer.tsx
git commit -m "fix(frontend): use semantic tokens in Drawer/Dialog components"
Files:
frontend/src/react/components/AuditLogTable.tsxfrontend/src/react/components/IssueTable.tsxfrontend/src/react/components/ExprEditor.tsxfrontend/src/react/components/AdvancedSearch.tsxfrontend/src/react/components/AccountMultiSelect.tsxfrontend/src/react/components/DatabaseGroupForm.tsxfrontend/src/react/components/WorkspaceSwitcher.tsxfrontend/src/react/components/TimeRangePicker.tsxfrontend/src/react/components/MatchedDatabaseView.tsxfrontend/src/react/components/sql-review/Panels.tsxfrontend/src/react/components/sql-review/ReviewCreation.tsxfrontend/src/react/components/CustomApproval/ApprovalStepsTable.tsxfrontend/src/react/components/task-run-log/SectionHeader.tsxfrontend/src/react/components/instance/DataSourceForm.tsxfrontend/src/react/components/instance/InstanceSyncButton.tsxfrontend/src/react/components/instance/InstanceFormButtons.tsxfrontend/src/react/components/instance/InstanceActionDropdown.tsxfrontend/src/react/components/instance/InfoPanel.tsxfrontend/src/react/components/instance/InstanceFormBody.tsxfrontend/src/react/components/instance/SslCertificateForm.tsxStep 1: Read each file and replace raw colors per mapping table
Focus on: bg-white → bg-background, bg-black/* → bg-overlay/*, gray scale → semantic tokens, status colors → error/warning/success/info tokens.
Step 2: Verify
Run: pnpm --dir frontend type-check
Step 3: Commit
git add frontend/src/react/components/
git commit -m "fix(frontend): use semantic color tokens in shared React components"
Files:
frontend/src/react/pages/settings/MembersPage.tsxfrontend/src/react/pages/settings/IDPDetailPage.tsxfrontend/src/react/pages/settings/ServiceAccountsPage.tsxfrontend/src/react/pages/settings/ProjectsPage.tsxfrontend/src/react/pages/settings/InstancesPage.tsxfrontend/src/react/pages/settings/SemanticTypesPage.tsxfrontend/src/react/pages/settings/CreateInstancePage.tsxfrontend/src/react/pages/settings/SQLReviewDetailPage.tsxfrontend/src/react/pages/settings/PurchaseSection.tsxfrontend/src/react/pages/settings/DataClassificationPage.tsxfrontend/src/react/pages/settings/general/GeneralSection.tsxfrontend/src/react/pages/settings/general/AIAugmentationSection.tsxfrontend/src/react/pages/settings/general/GeneralPage.tsxStep 1: Read each file and replace raw colors per mapping table
Step 2: Verify
Run: pnpm --dir frontend type-check
Step 3: Commit
git add frontend/src/react/pages/settings/
git commit -m "fix(frontend): use semantic color tokens in Settings pages"
Files:
frontend/src/react/pages/project/ProjectDataExportPage.tsxfrontend/src/react/pages/project/ProjectSettingsPage.tsxfrontend/src/react/pages/project/ProjectWebhooksPage.tsxfrontend/src/react/pages/project/ProjectReleaseDashboardPage.tsxfrontend/src/react/pages/project/ProjectMaskingExemptionCreatePage.tsxfrontend/src/react/pages/project/ProjectPlanDashboardPage.tsxfrontend/src/react/pages/project/ProjectWebhookForm.tsxfrontend/src/react/pages/project/ProjectSyncSchemaPage.tsxfrontend/src/react/pages/project/DatabaseChangelogDetailPage.tsxfrontend/src/react/pages/project/ProjectDatabasesPage.tsxfrontend/src/react/pages/project/ProjectMaskingExemptionPage.tsxfrontend/src/react/pages/project/ProjectDatabaseGroupDetailPage.tsxfrontend/src/react/pages/project/ProjectDatabaseGroupsPage.tsxfrontend/src/react/pages/project/export-center/DataExportPrepDrawer.tsxfrontend/src/react/pages/project/database-detail/changelog/DatabaseChangelogTable.tsxfrontend/src/react/pages/project/database-detail/DatabaseExportSchemaButton.tsxfrontend/src/react/pages/project/database-detail/overview/TableDetailDialog.tsxfrontend/src/react/pages/project/database-detail/overview/ObjectSectionTable.tsxfrontend/src/react/pages/project/database-detail/overview/DatabaseObjectExplorer.tsxfrontend/src/react/pages/project/database-detail/overview/TableMetadataTable.tsxfrontend/src/react/pages/project/database-detail/revision/DatabaseRevisionTable.tsxStep 1: Read each file and replace raw colors per mapping table
Step 2: Verify
Run: pnpm --dir frontend type-check
Step 3: Commit
git add frontend/src/react/pages/project/
git commit -m "fix(frontend): use semantic color tokens in Project pages"
tailwind.css utility classesFiles:
frontend/src/assets/css/tailwind.cssStep 1: Replace raw colors in legacy utility classes
.textlabeltip — text-red-500 → text-error.textfield — bg-gray-50 → bg-control-bg.radio .label — text-gray-700 → text-control.normal-link — text-blue-600 → text-info, text-blue-800 → text-info-hover.light-link — text-blue-400 / text-blue-200 → keep (dark theme specific)Step 2: Verify & commit
git add frontend/src/assets/css/tailwind.css
git commit -m "fix(frontend): use semantic tokens in legacy CSS utility classes"
After all tasks are complete:
pnpm --dir frontend type-check — passespnpm --dir frontend check — no lint errorspnpm --dir frontend dev — visual spot-check that colors haven't changedrg 'space-[xy]-' frontend/src/react/ --glob '*.tsx' — should return 0 resultsrg 'bg-white|bg-black' frontend/src/react/components/ui/ — should return 0 resultsrg 'bg-(gray|blue|red|green|yellow|orange)-\d' frontend/src/react/ --glob '*.tsx' — should be minimal (only intentional decorative uses)