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

Auto Virtual Tryon Admin Frontend Shadcn Rewrite Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Rebuild the frontend admin UI around a denser shadcn-style console shell, a clearer review workflow, and real high-density list pages for orders and workflows.

Architecture: Keep the existing App Router routes, BFF handlers, adapters, and backend contracts intact while replacing the card-heavy presentation layer with shared shell, toolbar, and table primitives. Migrate in layers: first the dashboard shell and reusable UI primitives, then the review flow, then the orders and workflows list pages, so each step lands on top of a stable layout system instead of reworking page code twice.

Tech Stack: Next.js App Router, React, TypeScript, Tailwind CSS v4, Vitest, React Testing Library, jsdom, Lucide React

---

Task 1: Rebuild The Shared Dashboard Shell

Files:

• Modify: src/components/layout/dashboard-shell.tsx

• Modify: src/components/layout/nav-config.ts

• Modify: src/components/ui/page-header.tsx

• Modify: app/globals.css

• Test: tests/ui/dashboard-shell.test.tsx

• Step 1: Write the failing shell-density tests

test("uses a narrow rail and full-width desktop shell", () => {
  render(<DashboardShell>content</DashboardShell>);

  expect(screen.getByLabelText("Dashboard rail").className).toContain(
    "md:w-[228px]",
  );
  expect(screen.getByLabelText("Dashboard content").className).toContain(
    "md:overflow-y-auto",
  );
});

• Step 2: Run the shell test to confirm it fails

Run: npm run test -- tests/ui/dashboard-shell.test.tsx Expected: FAIL because the existing shell still uses the wide 280px rail, large radii, and old container classes

• Step 3: Rewrite the shell layout to use a thinner rail and full-width main area

<div className="min-h-screen bg-[var(--app-bg)] text-[var(--ink)] md:h-screen md:overflow-hidden">
  <div className="grid h-full md:grid-cols-[228px_minmax(0,1fr)]">
    <aside className="border-r border-[var(--shell-border)] bg-[var(--shell)] md:h-full" />
    <main className="min-h-0 md:h-full md:overflow-y-auto" />
  </div>
</div>

• Step 4: Tighten the shared header spacing and typography

<header className="flex items-start justify-between gap-4 border-b border-[var(--border-soft)] pb-4">
  <div className="space-y-1">
    <p className="font-[var(--font-mono)] text-[11px] uppercase tracking-[0.24em]">
      {eyebrow}
    </p>
    <h1 className="text-2xl font-semibold tracking-[-0.03em]">{title}</h1>
  </div>
</header>

• Step 5: Update shell variables and density tokens in global CSS

:root {
  --page-gap: 16px;
  --panel-radius: 14px;
  --control-height: 38px;
}

• Step 6: Re-run the shell test

Run: npm run test -- tests/ui/dashboard-shell.test.tsx Expected: PASS

• Step 7: Commit the shell rewrite

git add src/components/layout/dashboard-shell.tsx src/components/layout/nav-config.ts src/components/ui/page-header.tsx app/globals.css tests/ui/dashboard-shell.test.tsx
git commit -m "feat: tighten dashboard shell density"

Task 2: Add Shared Dense Console Primitives

Files:

• Create: src/components/ui/input.tsx

• Create: src/components/ui/select.tsx

• Create: src/components/ui/table.tsx

• Create: src/components/ui/separator.tsx

• Create: src/components/ui/page-toolbar.tsx

• Create: src/components/ui/metric-chip.tsx

• Modify: src/components/ui/button.tsx

• Modify: src/components/ui/card.tsx

• Modify: src/components/ui/status-badge.tsx

• Test: tests/ui/status-badge.test.tsx

• Create: tests/ui/page-toolbar.test.tsx

• Step 1: Write failing tests for compact toolbar and compact badge behavior

test("renders a dense toolbar row with compact controls", () => {
  render(
    <PageToolbar>
      <Input aria-label="search" />
      <Select aria-label="status" />
    </PageToolbar>,
  );

  expect(screen.getByLabelText("search").className).toContain("h-9");
});

• Step 2: Run the toolbar and badge tests to confirm they fail

Run: npm run test -- tests/ui/page-toolbar.test.tsx tests/ui/status-badge.test.tsx Expected: FAIL because the new primitives do not exist yet and current badge sizing is larger than the dense target

• Step 3: Implement the shared compact primitives

export function PageToolbar({ children }: PropsWithChildren) {
  return (
    <div className="flex flex-wrap items-center gap-3 border-b border-[var(--border-soft)] pb-4">
      {children}
    </div>
  );
}

• Step 4: Normalize button, card, and status badge sizes to the new density

const buttonVariants = {
  default: "h-9 rounded-md px-3 text-sm",
  secondary: "h-9 rounded-md px-3 text-sm",
};

• Step 5: Re-run the toolbar and badge tests

Run: npm run test -- tests/ui/page-toolbar.test.tsx tests/ui/status-badge.test.tsx Expected: PASS

• Step 6: Commit the shared primitives

git add src/components/ui tests/ui
git commit -m "feat: add dense console ui primitives"

Task 3: Rewrite The Review Queue Page As A High-Density Table

Files:

• Modify: src/features/reviews/review-workbench-list.tsx

• Modify: src/features/reviews/components/review-queue.tsx

• Create: src/features/reviews/components/review-filters.tsx

• Modify: app/(dashboard)/reviews/workbench/page.tsx

• Test: tests/features/reviews/review-workbench-list.test.tsx

• Step 1: Replace the current list-page expectations with queue-table expectations

test("renders a compact review queue table with triage columns", async () => {
  render(<ReviewWorkbenchListScreen />);

  expect(await screen.findByRole("columnheader", { name: "订单号" })).toBeInTheDocument();
  expect(screen.getByRole("columnheader", { name: "修订状态" })).toBeInTheDocument();
  expect(screen.getByRole("button", { name: "刷新队列" })).toBeInTheDocument();
});

• Step 2: Run the review queue test to confirm it fails

Run: npm run test -- tests/features/reviews/review-workbench-list.test.tsx Expected: FAIL because the current page still renders the old prose-heavy layout instead of the table and compact toolbar

• Step 3: Add a compact filter row for query, status, revision state, and refresh

<PageToolbar>
  <Input aria-label="审核关键词搜索" />
  <Select aria-label="审核状态筛选" />
  <Select aria-label="修订状态筛选" />
  <Button variant="secondary">刷新队列</Button>
</PageToolbar>

• Step 4: Rebuild the queue body as a compact table

<Table>
  <TableHeader>
    <TableRow>
      <TableHead>订单号</TableHead>
      <TableHead>workflowId</TableHead>
      <TableHead>当前状态</TableHead>
      <TableHead>当前步骤</TableHead>
      <TableHead>修订状态</TableHead>
      <TableHead>失败次数</TableHead>
      <TableHead>更新时间</TableHead>
      <TableHead className="text-right">操作</TableHead>
    </TableRow>
  </TableHeader>
</Table>

• Step 5: Re-run the review queue test

Run: npm run test -- tests/features/reviews/review-workbench-list.test.tsx Expected: PASS

• Step 6: Commit the queue rewrite

git add src/features/reviews app/\(dashboard\)/reviews/workbench/page.tsx tests/features/reviews/review-workbench-list.test.tsx
git commit -m "feat: rewrite review queue as dense table"

Task 4: Rewrite The Review Detail Page As A Decision Surface

Files:

• Modify: src/features/reviews/review-workbench-detail.tsx

• Modify: src/features/reviews/components/review-action-panel.tsx

• Modify: src/features/reviews/components/review-image-panel.tsx

• Modify: src/features/reviews/components/review-revision-panel.tsx

• Modify: src/features/reviews/components/review-workflow-summary.tsx

• Modify: app/(dashboard)/reviews/workbench/[orderId]/page.tsx

• Test: tests/features/reviews/review-workbench-detail.test.tsx

• Step 1: Rewrite the detail-page tests around sticky summary and two-column decision layout

test("keeps the decision actions visible next to the image workspace", async () => {
  render(<ReviewWorkbenchDetailScreen orderId={101} />);

  expect(await screen.findByText("返回审核列表")).toBeInTheDocument();
  expect(screen.getByText("审核动作")).toBeInTheDocument();
  expect(screen.getByText("人工修订")).toBeInTheDocument();
});

• Step 2: Run the review detail test to confirm it fails

Run: npm run test -- tests/features/reviews/review-workbench-detail.test.tsx Expected: FAIL because the current detail page still renders the old header and stacked module layout

• Step 3: Add the sticky summary bar and two-column page frame

<div className="sticky top-0 z-10 border-b border-[var(--border-soft)] bg-[var(--surface)]/95 backdrop-blur">
  <div className="flex items-center justify-between gap-4 py-3">
    <Button variant="secondary" asChild>
      <Link href="/reviews/workbench">返回审核列表</Link>
    </Button>
  </div>
</div>

• Step 4: Collapse workflow timeline content into a compact summary block and keep primary actions grouped

<Tabs defaultValue="audit">
  <TabsList>
    <TabsTrigger value="audit">审核动作</TabsTrigger>
    <TabsTrigger value="revision">人工修订</TabsTrigger>
  </TabsList>
</Tabs>

• Step 5: Re-run the review detail test

Run: npm run test -- tests/features/reviews/review-workbench-detail.test.tsx Expected: PASS

• Step 6: Commit the review detail rewrite

git add src/features/reviews app/\(dashboard\)/reviews/workbench/\[orderId\]/page.tsx tests/features/reviews/review-workbench-detail.test.tsx
git commit -m "feat: rebuild review detail decision surface"

Task 5: Rewrite Orders As A Real Dense List Page

Files:

• Modify: src/features/orders/orders-home.tsx

• Create: src/features/orders/components/orders-toolbar.tsx

• Create: src/features/orders/components/orders-table.tsx

• Modify: app/(dashboard)/orders/page.tsx

• Test: tests/features/orders/orders-home.test.tsx

• Step 1: Replace the current orders-home expectations with dense-table expectations

test("renders orders as a high-density table with shared toolbar controls", async () => {
  render(<OrdersHome recentOrders={[order]} />);

  expect(screen.getByRole("columnheader", { name: "订单号" })).toBeInTheDocument();
  expect(screen.getByRole("columnheader", { name: "服务模式" })).toBeInTheDocument();
  expect(screen.getByLabelText("订单状态筛选")).toBeInTheDocument();
});

• Step 2: Run the orders-home test to confirm it fails

Run: npm run test -- tests/features/orders/orders-home.test.tsx Expected: FAIL because the current page still renders direct-lookup and recent-visits cards rather than a dense list table

• Step 3: Extract the compact toolbar with keyword, status, service mode, and pagination controls

<OrdersToolbar
  query={selectedQuery}
  status={selectedStatus}
  onQuerySubmit={onQuerySubmit}
  onStatusChange={onStatusChange}
  onPageChange={onPageChange}
/>

• Step 4: Replace the card list with a real orders table and compact row actions

<OrdersTable
  items={recentOrders}
  onOpenOrder={onOpenOrder}
  onOpenWorkflow={onOpenWorkflow}
/>

• Step 5: Re-run the orders-home test

Run: npm run test -- tests/features/orders/orders-home.test.tsx Expected: PASS

• Step 6: Commit the orders page rewrite

git add src/features/orders app/\(dashboard\)/orders/page.tsx tests/features/orders/orders-home.test.tsx
git commit -m "feat: rewrite orders page as dense list"

Task 6: Rewrite Workflows As A Real Dense List Page

Files:

• Modify: src/features/workflows/workflow-lookup.tsx

• Create: src/features/workflows/components/workflow-toolbar.tsx

• Create: src/features/workflows/components/workflow-table.tsx

• Modify: app/(dashboard)/workflows/page.tsx

• Test: tests/features/workflows/workflow-lookup.test.tsx

• Step 1: Replace the current workflow-page expectations with dense-table expectations

test("renders workflows as a high-density table with shared toolbar controls", async () => {
  render(<WorkflowLookup items={[workflow]} />);

  expect(screen.getByRole("columnheader", { name: "流程类型" })).toBeInTheDocument();
  expect(screen.getByRole("columnheader", { name: "失败次数" })).toBeInTheDocument();
  expect(screen.getByLabelText("流程状态筛选")).toBeInTheDocument();
});

• Step 2: Run the workflow-page test to confirm it fails

Run: npm run test -- tests/features/workflows/workflow-lookup.test.tsx Expected: FAIL because the current page still renders direct-lookup and placeholder index cards rather than a dense table

• Step 3: Extract the compact workflow toolbar

<WorkflowToolbar
  query={selectedQuery}
  status={selectedStatus}
  onQuerySubmit={onQuerySubmit}
  onStatusChange={onStatusChange}
  onPageChange={onPageChange}
/>

• Step 4: Replace the workflow card list with a diagnostic table

<WorkflowTable items={items} onOpenWorkflow={onOpenWorkflow} />

• Step 5: Re-run the workflow-page test

Run: npm run test -- tests/features/workflows/workflow-lookup.test.tsx Expected: PASS

• Step 6: Commit the workflows page rewrite

git add src/features/workflows app/\(dashboard\)/workflows/page.tsx tests/features/workflows/workflow-lookup.test.tsx
git commit -m "feat: rewrite workflows page as dense list"

Task 7: Clean Up Old Oversized Patterns And Verify The Whole Rewrite

Files:

• Modify: src/features/orders/components/order-summary-card.tsx

• Modify: src/features/orders/components/order-workflow-card.tsx

• Modify: src/features/workflows/components/workflow-status-card.tsx

• Modify: src/features/workflows/components/workflow-timeline.tsx

• Modify: README.md

• Test: tests/features/orders/order-detail.test.tsx

• Test: tests/features/workflows/workflow-detail.test.tsx

• Step 1: Write or adjust any failing detail-page tests caused by the density-system changes

test("keeps order detail summaries compact under the new density rules", () => {
  render(<OrderDetailScreen orderId={101} />);

  expect(screen.getByText("订单摘要")).toBeInTheDocument();
});

• Step 2: Run the affected detail tests to confirm what regressed

Run: npm run test -- tests/features/orders/order-detail.test.tsx tests/features/workflows/workflow-detail.test.tsx Expected: FAIL only if the shared primitive changes require updated structure or copy assertions

• Step 3: Remove any leftover oversized radii, padding, and stacked-card patterns from detail support components

<section className="rounded-[14px] border border-[var(--border-soft)] bg-[var(--surface)] p-4">
  ...
</section>

• Step 4: Update the README to mention the shadcn-style dense console direction

- shared admin shell uses compact toolbar and table patterns
- review, orders, and workflows pages are optimized for desktop operator density

• Step 5: Run full verification

Run: npm run verify Expected: PASS with all Vitest suites green, ESLint green, TypeScript green, and next build green

• Step 6: Run a browser smoke test on the three main surfaces

Run: npm run dev Expected: desktop manual check confirms wider shell, denser lists, and clearer review flow on /orders, /reviews/workbench, /workflows

• Step 7: Commit the cleanup and verification pass

git add src/features/orders/components src/features/workflows/components README.md
git commit -m "refactor: align detail views with dense console ui"