docs: add shadcn ui rewrite design spec
This commit is contained in:
afei A
@@ -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
|
||||||
Reference in New Issue
Block a user