auto-virtual-tryon-frontend/docs/superpowers/specs/2026-03-28-auto-virtual-tryon-admin-frontend-shadcn-rewrite-design.md

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