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