diff --git a/docs/superpowers/specs/2026-03-28-auto-virtual-tryon-admin-frontend-shadcn-rewrite-design.md b/docs/superpowers/specs/2026-03-28-auto-virtual-tryon-admin-frontend-shadcn-rewrite-design.md new file mode 100644 index 0000000..09083a7 --- /dev/null +++ b/docs/superpowers/specs/2026-03-28-auto-virtual-tryon-admin-frontend-shadcn-rewrite-design.md @@ -0,0 +1,297 @@ +# Auto Virtual Tryon Admin Frontend Shadcn Rewrite Design + +Date: 2026-03-28 + +## 1. Background + +The current admin frontend is functionally usable, but the UI no longer fits the actual operating pattern of the product. + +The main problems observed in the current implementation are: + +- the dashboard shell consumes too much of the viewport through max-width limits, oversized padding, and large radii +- page components are visually too large, which reduces the amount of actionable information visible on screen +- `/orders` and `/workflows` still behave like entry pages instead of real operator-facing list pages +- the review flow is technically split into list and detail routes, but the detail page still reads like stacked modules rather than a clear decision surface + +This rewrite is not a backend or product-scope change. It is a UI-system rewrite focused on density, readability, and process clarity. + +## 2. Rewrite Goal + +Rebuild the admin frontend UI around a shadcn-based console system that: + +- shows more operational content per screen without becoming visually noisy +- makes the primary workflows readable in the order operators actually use them +- unifies page structure across `orders`, `reviews`, and `workflows` +- reduces ornamental containers and replaces them with high-signal list, table, and detail layouts + +## 3. Scope + +This rewrite covers: + +- the shared dashboard shell +- the review workbench list and detail experience +- the `/orders` page as a real list page +- the `/workflows` page as a real list page +- a shared shadcn-based page structure and density system + +This rewrite does not change: + +- backend contracts +- route information architecture already approved in the earlier frontend design +- the business flow of order submission, review submission, manual revision registration, or workflow tracking + +## 4. Design Principles + +The rewrite follows these principles: + +- density first, but not compression for its own sake +- one page should communicate one main operator task +- list pages should prioritize scanning and filtering over explanation copy +- detail pages should prioritize decisions over exhaustive exposition +- the shell should frame the product, not dominate it + +## 5. Shared Shell Rewrite + +### 5.1 Shell Structure + +The dashboard shell will be rebuilt around a thinner navigation rail and a wider main content area. + +Approved changes: + +- reduce the left navigation rail to roughly `220-236px` +- remove the current desktop `max-w-7xl` constraint +- let the content region use the full available desktop width +- remove the current "card inside card" page framing pattern +- keep only one shell layer and one page-content layer + +### 5.2 Shared Page Scaffold + +All dashboard pages should use the same top-level scaffold: + +1. `PageHeader` +2. `PageToolbar` +3. `PageBody` + +This replaces the current inconsistent mix of hero-like intros, oversized summary blocks, and content cards. + +### 5.3 Density Rules + +The approved density system is: + +- common control heights shrink from roughly `44-48px` to `36-40px` +- common content radii shrink from roughly `28-32px` to `12-16px` +- page spacing defaults shrink from `24-32px` to `12-20px` +- visual grouping should rely more on spacing and separators than large bordered cards + +## 6. Component System Direction + +The rewrite will standardize on shadcn primitives for layout and interaction. + +Primary primitives: + +- `Sidebar` +- `Button` +- `Input` +- `Select` +- `Badge` +- `Tabs` +- `Table` +- `Sheet` +- `Dialog` +- `ScrollArea` +- `Separator` + +`Card` remains allowed, but only for: + +- local summaries +- exception or warning surfaces +- compact supporting information blocks + +`Card` should no longer be used as the default page-layout primitive. + +## 7. Review Workbench Rewrite + +### 7.1 Review Queue Page + +`/reviews/workbench` becomes a true queue page. + +The page structure is: + +- thin page header +- compact toolbar +- high-density review table + +The toolbar should support: + +- keyword search +- status filtering +- revision-state filtering +- refresh + +The review queue row should show only key triage fields: + +- `orderId` +- `workflowId` +- current review status +- current workflow step +- revision status +- failure count +- updated time +- detail entry + +The purpose of this page is only: + +- scan the queue +- prioritize work +- enter a task + +It should not carry large preview surfaces or action panels. + +### 7.2 Review Detail Page + +`/reviews/workbench/[orderId]` becomes a decision page rather than a module stack. + +The page should begin with a sticky summary bar containing: + +- `orderId` +- `workflowId` +- current step +- current handling state +- whether a manual revision exists +- back-to-list entry + +The body should use a two-column structure: + +- left column: image viewing and version switching +- right column: audit actions, revision actions, workflow summary + +The right action column should remain visible in the viewport so the operator does not need to scroll to find the next action. + +### 7.3 Review Flow Clarity + +The intended operator flow is: + +1. find a task in the queue +2. open the task detail +3. inspect the current candidate result or manual revision +4. execute one of the allowed actions +5. return to the queue + +To reinforce this: + +- `approve` and `rerun` remain the primary action group +- manual revision actions are grouped separately as secondary workflow controls +- workflow timeline data is collapsed into summary-first presentation +- image surfaces should switch between views instead of rendering all variants at once + +## 8. Orders Page Rewrite + +`/orders` becomes a real high-density operations list page. + +The page layout is: + +- compact page header +- compact toolbar +- orders table + +The toolbar should support: + +- keyword search +- status filter +- service mode filter +- pagination controls + +The table columns are: + +- `orderId` +- `workflowId` +- `customerLevel` +- `serviceMode` +- `status` +- `currentStep` +- `revisionCount` +- `updatedAt` +- actions + +The row actions remain intentionally small: + +- view order +- view workflow + +Large explanatory content should be removed from the initial viewport. + +## 9. Workflows Page Rewrite + +`/workflows` also becomes a real list page rather than a search-first placeholder surface. + +The page layout matches the orders page: + +- compact page header +- compact toolbar +- workflows table + +The toolbar should support: + +- keyword search +- status filter +- pagination controls + +The table columns are: + +- `orderId` +- `workflowId` +- `workflowType` +- `workflowStatus` +- `currentStep` +- `failureCount` +- `revisionCount` +- `updatedAt` +- actions + +This page is optimized for execution-state inspection and failure diagnosis. + +## 10. Cross-Page Conventions + +The following conventions apply to `orders`, `reviews`, and `workflows`: + +- status is expressed through compact `Badge` treatments +- filters use a shared `Input + Select` toolbar pattern +- detail entry remains in the rightmost action area +- pagination style is shared instead of custom per page +- explanation copy is secondary and should not occupy the first screen on desktop + +These conventions are meant to make the console feel like one coherent operator product rather than several disconnected feature pages. + +## 11. Migration Strategy + +The rewrite should happen in this order: + +1. rebuild the shared dashboard shell and density tokens +2. rewrite the review workbench list and detail pages inside the new shell +3. rewrite `/orders` as a real list page under the same system +4. rewrite `/workflows` under the same system +5. remove obsolete oversized layout patterns that remain in the old components + +This order minimizes churn because page-specific work will not need to be repeated after the shell changes. + +## 12. Testing and Verification + +The rewrite should be validated through: + +- component and page tests for toolbar behavior +- tests that confirm list-to-detail navigation still works +- tests that preserve review decision actions and return-to-queue behavior +- tests that protect filtering and pagination behavior on `orders` and `workflows` +- browser verification at desktop widths to confirm the effective visible area is materially improved + +The goal is not snapshot-heavy testing. The goal is to protect structure, behavior, and the intended operator flow. + +## 13. Acceptance Boundary + +This rewrite is successful when: + +- the shell no longer artificially compresses the usable desktop viewport +- operators can see materially more rows and actionable information on first load +- the review flow reads as queue -> decision -> submit -> return +- `/orders` and `/workflows` behave like genuine admin list pages instead of transitional entry pages +- the UI system has clearly shifted toward shadcn-based primitives and away from oversized decorative cards