HaiLin/ai-ticket-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add stage 1.8 shadcn ui standardization plan

Browse Source
This commit is contained in:
hailin
2026-07-02 15:23:53 +08:00
parent dbb1ceb0e0
commit 8749faae43
2 changed files with 344 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
docs/superpowers/plans/2026-07-02-stage-1-8-shadcn-admin-ui-standardization.md Normal file
View File

@@ -0,0 +1,267 @@
# Stage 1.8 Shadcn Admin UI Standardization 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 UI foundation around shadcn/ui so future pages inherit a consistent enterprise admin layout, mobile navigation, form standard, select composition, and visual baseline.
**Architecture:** shadcn/ui remains the source component library. Project `App*` components become thin composition wrappers around shadcn primitives, while feature pages consume those wrappers instead of hand-rolled layout. The first implementation batch fixes shell navigation, field primitives, select composition, and high-frequency forms.
**Tech Stack:** React 19, Vite, TypeScript, Tailwind v3, shadcn/ui `radix-nova`, Radix primitives, lucide-react.
---
## File Structure
- Modify: `frontend/src/app/layout/AppShell.tsx` - passes mobile menu state into topbar/sidebar sheet.
- Modify: `frontend/src/components/app/AppSidebar.tsx` - extracts reusable navigation content and adds sheet-friendly rendering.
- Modify: `frontend/src/components/app/AppTopbar.tsx` - adds mobile menu button and keeps desktop actions.
- Create: `frontend/src/components/ui/field.tsx` - shadcn field primitive from CLI, merged without losing local component changes.
- Modify: `frontend/src/components/app/AppField.tsx` - thin wrapper over shadcn field primitives.
- Modify: `frontend/src/features/**` select call sites - wrap `SelectItem` with `SelectGroup`.
- Modify: `frontend/src/features/auth/LoginPage.tsx` - migrate login form fields.
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx` - migrate main create form fields.
- Modify: `frontend/src/features/solutions/SolutionCreatePage.tsx` - migrate solution form fields.
- Modify: `frontend/src/features/system/SystemUsersPage.tsx`, `SystemRolesPage.tsx`, `SystemUserGroupsPage.tsx` - migrate quick-create forms where practical.
- Test/verify: `npm run typecheck`, `npm run build`, grep scans, desktop/mobile browser checks.
---
### Task 1: Mobile Shell Navigation
**Files:**
- Modify: `frontend/src/app/layout/AppShell.tsx`
- Modify: `frontend/src/components/app/AppSidebar.tsx`
- Modify: `frontend/src/components/app/AppTopbar.tsx`
- [ ] **Step 1: Inspect current shell boundaries**
Run:
```powershell
Get-Content frontend/src/app/layout/AppShell.tsx
Get-Content frontend/src/components/app/AppSidebar.tsx
Get-Content frontend/src/components/app/AppTopbar.tsx
```
Expected: `AppShell` renders fixed sidebar and topbar; sidebar is desktop-only.
- [ ] **Step 2: Add mobile menu state in shell**
Implement `mobileNavOpen` state in `AppShell`, pass `onMobileMenuClick` into topbar, and pass `mobileOpen/onMobileOpenChange` into sidebar.
- [ ] **Step 3: Extract sidebar navigation content**
In `AppSidebar`, extract grouped nav rendering into `SidebarNavContent({ onNavigate })`. Use the same component for desktop and mobile sheet.
- [ ] **Step 4: Render mobile Sheet**
Use existing shadcn `Sheet`, `SheetContent`, `SheetHeader`, and `SheetTitle`. The sheet title must be present for accessibility. Menu item clicks call `onNavigate`.
- [ ] **Step 5: Add topbar mobile trigger**
Add a `Button size="icon" variant="ghost"` visible below `lg`, with `Menu` icon using `data-icon` and `aria-label="打开导航"`.
- [ ] **Step 6: Verify**
Run:
```powershell
npm run typecheck
```
Expected: exit code 0.
---
### Task 2: Install and Merge Shadcn Field Primitive
**Files:**
- Create: `frontend/src/components/ui/field.tsx`
- May modify: `frontend/src/components/ui/label.tsx`
- May modify: `frontend/src/components/ui/separator.tsx`
- Modify: `frontend/src/components/app/AppField.tsx`
- [ ] **Step 1: Preview CLI changes**
Run:
```powershell
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest add field --dry-run
```
Expected: creates `field.tsx`, previews updates to `label.tsx` and `separator.tsx`.
- [ ] **Step 2: Inspect diffs before applying**
Run:
```powershell
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest add field --diff field.tsx
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest add field --diff label.tsx
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest add field --diff separator.tsx
```
Expected: understand local changes before applying.
- [ ] **Step 3: Add the field component**
Apply the CLI result, then inspect changed files. If `label.tsx` or `separator.tsx` overwrite local customizations, restore needed local behavior manually.
- [ ] **Step 4: Rebuild AppField**
Make `AppField` render shadcn `Field`, `FieldLabel`, and optional `FieldDescription`. Support `htmlFor`, `required`, `invalid`, and `description` props.
- [ ] **Step 5: Verify**
Run:
```powershell
npm run typecheck
```
Expected: exit code 0.
---
### Task 3: Select Composition Sweep
**Files:**
- Modify: `frontend/src/features/tickets/TicketFilterBar.tsx`
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx`
- Modify: `frontend/src/features/tickets/TicketComments.tsx`
- Modify: `frontend/src/features/solutions/SolutionListPage.tsx`
- Modify: `frontend/src/features/solutions/SolutionCreatePage.tsx`
- Modify: `frontend/src/features/design-system/DesignSystemPreview.tsx`
- [ ] **Step 1: Add SelectGroup imports**
For each file importing select primitives, add `SelectGroup`.
- [ ] **Step 2: Wrap select items**
Change:
```tsx
<SelectContent>
<SelectItem value="all">全部状态</SelectItem>
</SelectContent>
```
to:
```tsx
<SelectContent>
<SelectGroup>
<SelectItem value="all">全部状态</SelectItem>
</SelectGroup>
</SelectContent>
```
- [ ] **Step 3: Scan**
Run:
```powershell
rg "SelectContent>[\\s\\S]*SelectItem|<SelectContent>\\s*<SelectItem" frontend/src -n
```
Expected: no direct `SelectItem` immediately under `SelectContent`.
- [ ] **Step 4: Verify**
Run:
```powershell
npm run typecheck
```
Expected: exit code 0.
---
### Task 4: High-Frequency Form Migration
**Files:**
- Modify: `frontend/src/features/auth/LoginPage.tsx`
- Modify: `frontend/src/features/tickets/TicketCreatePage.tsx`
- Modify: `frontend/src/features/solutions/SolutionCreatePage.tsx`
- Modify: `frontend/src/features/system/SystemUsersPage.tsx`
- Modify: `frontend/src/features/system/SystemRolesPage.tsx`
- Modify: `frontend/src/features/system/SystemUserGroupsPage.tsx`
- [ ] **Step 1: Migrate login fields**
Use `AppField htmlFor="username"` and `AppField htmlFor="password"`. Inputs receive matching `id` and `aria-invalid={Boolean(error)}` only where field-specific invalid state is needed.
- [ ] **Step 2: Migrate create ticket fields**
Use `AppField` for title, priority, impact scope, related system, environment, and description. Required fields use `required`.
- [ ] **Step 3: Migrate create solution fields**
Use `AppField` for title, status, related system, environment scope, problem signature, root cause, solution, and risk note.
- [ ] **Step 4: Migrate quick-create system forms**
Keep compact horizontal layout, but each input lives inside `AppField` so labels remain visible and shadcn field semantics are consistent.
- [ ] **Step 5: Verify**
Run:
```powershell
npm run typecheck
npm run build
```
Expected: both exit code 0.
---
### Task 5: Full UI Verification and Commit
**Files:**
- All modified frontend files
- [ ] **Step 1: Run shadcn context check**
Run:
```powershell
$env:NODE_USE_ENV_PROXY = "1"; $env:HTTP_PROXY = "http://127.0.0.1:7897"; $env:HTTPS_PROXY = "http://127.0.0.1:7897"; cd frontend; npx shadcn@latest info
```
Expected: current project remains `Vite`, `Tailwind v3`, `radix-nova`, `lucide`.
- [ ] **Step 2: Run source scans**
Run:
```powershell
rg "space-[xy]-|<SelectContent>\\s*<SelectItem|className=.*size-4" frontend/src/features frontend/src/components/app -n
```
Expected: no new violations in migrated surfaces. Remaining non-button decorative icon sizes are acceptable only if not inside shadcn components.
- [ ] **Step 3: Browser checks**
Check desktop and mobile widths for:
- Login
- Workbench
- Ticket list
- Create ticket
- System users
Expected: mobile has navigation entry, no horizontal scroll, forms have visible labels.
- [ ] **Step 4: Commit**
Run:
```powershell
git add frontend/src docs/superpowers/specs/2026-07-02-stage-1-8-shadcn-admin-ui-standardization-design.md docs/superpowers/plans/2026-07-02-stage-1-8-shadcn-admin-ui-standardization.md
git commit -m "feat: standardize shadcn admin ui foundation"
```
Expected: commit created on current branch.