docs: add stage 1.5 shadcn ui design
This commit is contained in:
hailin
@@ -24,6 +24,7 @@ The product contains multiple independent subsystems. Do not implement the entir
|
||||
|---|---|---|---|---|
|
||||
| 0 | Foundation and design system | Create the repo skeleton, local runtime, auth/RBAC baseline, audit baseline, frontend theme and component standards. | None | `docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md` |
|
||||
| 1 | Ticket workflow and reusable solutions | Implement ticket lifecycle, comments, attachments, events, export, solution library, and solution links. | Stage 0 | Create after Stage 0 passes. |
|
||||
| 1.5 | shadcn enterprise UI foundation | Formalize shadcn/ui initialization, add a project-owned App component layer, redesign current ticket and solution pages, and enforce Chinese frontend text. | Stage 1 | `docs/superpowers/specs/2026-07-01-stage-1-5-shadcn-ui-foundation-design.md` |
|
||||
| 2 | Knowledge base and vector retrieval | Implement knowledge bases, documents, parsing jobs, chunks, embeddings, and retrieval. | Stage 0, partial Stage 1 | Create after Stage 1 model contracts stabilize. |
|
||||
| 3 | Model gateway and Agent/Skill runtime | Implement provider configs, model configs, model testing, Skill configs, built-in Agents, runs, steps, AI artifacts. | Stage 0, Stage 1, Stage 2 retrieval interfaces | Create after Stage 2 retrieval contracts exist. |
|
||||
| 4 | MCP tools and trust boundary | Implement MCP server registration, tool sync, risk levels, Agent tool binding, tool calls, confirmation, audit. | Stage 3 | Create after Agent runtime exists. |
|
||||
@@ -96,4 +97,3 @@ The product contains multiple independent subsystems. Do not implement the entir
|
||||
- Every backend stage includes API tests.
|
||||
- Every frontend stage includes typecheck and build verification.
|
||||
- Commit after each coherent task.
|
||||
|
||||
|
||||
@@ -0,0 +1,240 @@
|
||||
# Stage 1.5 shadcn UI Foundation Design
|
||||
|
||||
## Background
|
||||
|
||||
Stage 0 established a basic frontend shell and local UI primitives. Stage 1 added ticket and solution pages. The current implementation is functional, but it is still closer to a demo workflow than an enterprise-grade workbench:
|
||||
|
||||
- The frontend has Tailwind CSS and local component primitives, but it has not been formally initialized as a shadcn/ui project.
|
||||
- `frontend/components.json` does not exist, and `npx shadcn@latest info` reports `config: null` and `components: []`.
|
||||
- Ticket list, ticket detail, ticket creation, and solution pages work, but the visual hierarchy, table capability, filtering, empty states, and operation layout are too thin for later enterprise modules.
|
||||
- Some user-facing frontend text is still English, while the product requirement is Chinese-first.
|
||||
|
||||
Stage 1.5 is therefore inserted between Stage 1 and Stage 2. Its purpose is to stabilize the UI base before adding knowledge base, model gateway, Agent, Skill, MCP, and governance-heavy screens.
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt option A from the UI direction discussion:
|
||||
|
||||
```text
|
||||
Formal shadcn/ui initialization
|
||||
↓
|
||||
Project-owned App component layer
|
||||
↓
|
||||
Chinese enterprise ticket workbench pages
|
||||
```
|
||||
|
||||
Use `satnaing/shadcn-admin` as an aesthetic and layout reference, not as a direct source transplant. The project keeps its current Vite React structure and npm package manager.
|
||||
|
||||
## Goals
|
||||
|
||||
1. Convert the frontend from "local shadcn-like primitives" to a real shadcn/ui-based project.
|
||||
2. Build a reusable enterprise admin UI layer for future modules.
|
||||
3. Redesign the current ticket and solution pages around a Chinese workbench experience.
|
||||
4. Make ticket tables feel production-ready with filtering, status/priority presentation, row actions, and pagination-ready structure.
|
||||
5. Make ticket detail feel like an operations workspace, not a field dump.
|
||||
6. Ensure all user-visible frontend text in this stage is Chinese.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not add Stage 2 knowledge base backend models.
|
||||
- Do not implement Agent, Skill, MCP, or model gateway behavior.
|
||||
- Do not replace Vite with Next.js.
|
||||
- Do not switch npm to pnpm.
|
||||
- Do not copy the shadcn-admin repository wholesale.
|
||||
- Do not implement real authentication screens unless required by existing routing.
|
||||
|
||||
## UI Style Direction
|
||||
|
||||
The target is a simple, modern, dense enterprise application:
|
||||
|
||||
- Quiet operational layout instead of marketing-style pages.
|
||||
- Left sidebar navigation with grouped Chinese modules.
|
||||
- Topbar focused on breadcrumb, global actions, and user/system status.
|
||||
- Clean card usage only for repeated items, metrics, or framed tools.
|
||||
- Data-heavy pages use tables, filters, compact toolbars, and clear status badges.
|
||||
- Detail pages use a workbench layout with primary content, timeline, and side panels.
|
||||
- Colors come from theme tokens and component variants, not one-off page colors.
|
||||
|
||||
## Required shadcn/ui Base
|
||||
|
||||
The frontend should be initialized with the shadcn CLI using npm:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npx shadcn@latest init
|
||||
```
|
||||
|
||||
The implementation plan may adjust exact CLI flags based on the current CLI prompt format, but it must preserve:
|
||||
|
||||
- Vite framework.
|
||||
- TypeScript.
|
||||
- Tailwind CSS v3.
|
||||
- `@` import alias.
|
||||
- Existing `frontend/src/styles/globals.css`.
|
||||
- Existing `frontend/tailwind.config.ts`.
|
||||
|
||||
Add only the components required by the first UI base pass. Expected components include:
|
||||
|
||||
- `button`
|
||||
- `badge`
|
||||
- `card`
|
||||
- `input`
|
||||
- `textarea`
|
||||
- `select`
|
||||
- `label`
|
||||
- `separator`
|
||||
- `sidebar`
|
||||
- `breadcrumb`
|
||||
- `dropdown-menu`
|
||||
- `table`
|
||||
- `tabs`
|
||||
- `sheet`
|
||||
- `dialog`
|
||||
- `tooltip`
|
||||
- `skeleton`
|
||||
- `sonner`
|
||||
|
||||
If a component is unavailable or named differently in the installed shadcn CLI version, use the current official equivalent and document the difference in the implementation notes.
|
||||
|
||||
## Product Component Layer
|
||||
|
||||
Create project-owned components under `frontend/src/components/app`. These components form the stable API for business pages.
|
||||
|
||||
Required components:
|
||||
|
||||
| Component | Purpose |
|
||||
|---|---|
|
||||
| `AppShell` | Overall application frame with sidebar, topbar, content area, and responsive behavior. |
|
||||
| `AppSidebar` | Chinese navigation groups for workbench, tickets, knowledge, solutions, agents, models/tools, and system management. |
|
||||
| `AppTopbar` | Breadcrumb, page context, quick actions, and system/user placeholder controls. |
|
||||
| `AppPageHeader` | Consistent title, description, actions, and optional metadata. |
|
||||
| `AppDataTable` | Reusable table wrapper with toolbar slot, empty state, row actions, and pagination-ready footer. |
|
||||
| `AppFilterBar` | Search, select filters, date/status placeholders, and reset action layout. |
|
||||
| `AppDetailLayout` | Workbench layout for detail pages with main column, timeline/content panels, and right side panel. |
|
||||
| `AppSection` | Lightweight section wrapper for grouped fields or activity blocks. |
|
||||
| `AppStatusBadge` | Unified Chinese status badge for ticket lifecycle. |
|
||||
| `AppPriorityBadge` | Unified Chinese priority badge. |
|
||||
| `AppEmptyState` | Chinese empty-state pattern with optional action. |
|
||||
|
||||
Business pages should use these App components instead of importing shadcn primitives directly for layout-level concerns.
|
||||
|
||||
## Page Redesign Scope
|
||||
|
||||
### 1. Workbench Home
|
||||
|
||||
The default application view should feel like an operations console:
|
||||
|
||||
- Key ticket counters.
|
||||
- Pending/high-priority/processing overview.
|
||||
- Recent ticket activity placeholder using current available ticket data.
|
||||
- Quick links to create ticket and solution library.
|
||||
|
||||
### 2. Ticket List
|
||||
|
||||
Redesign into an enterprise table page:
|
||||
|
||||
- Chinese page title and description.
|
||||
- Filter bar with keyword, status, priority, and owner placeholders.
|
||||
- Metric strip for ticket states.
|
||||
- Data table with stable columns:
|
||||
- 编号
|
||||
- 标题
|
||||
- 状态
|
||||
- 优先级
|
||||
- 分类
|
||||
- 负责人
|
||||
- 创建时间
|
||||
- 操作
|
||||
- Empty state in Chinese.
|
||||
- Row actions such as 查看详情 and 关联方案 where supported by current routes.
|
||||
|
||||
### 3. Ticket Create
|
||||
|
||||
Redesign into a guided creation surface:
|
||||
|
||||
- Chinese labels and helper text.
|
||||
- Clear sectioning for problem description, classification, priority, requester/contact, and attachments placeholder.
|
||||
- Right-side or inline "后续 AI 建单辅助" placeholder panel, clearly marked as upcoming capability without implying it works now.
|
||||
|
||||
### 4. Ticket Detail
|
||||
|
||||
Redesign into a workbench:
|
||||
|
||||
- Header with ticket title, status, priority, and primary actions.
|
||||
- Main problem summary and field sections.
|
||||
- Status timeline and comments as operational activity.
|
||||
- Side panel for linked solutions and future AI support analysis placeholder.
|
||||
- Use Chinese labels for all states, fields, actions, and empty states.
|
||||
|
||||
### 5. Solution List
|
||||
|
||||
Redesign as a knowledge asset list:
|
||||
|
||||
- Chinese title and description.
|
||||
- Search/filter toolbar.
|
||||
- Table or structured list with category, effectiveness/use count placeholder, update time, and actions.
|
||||
- Make the page visually aligned with ticket pages.
|
||||
|
||||
### 6. Design System Preview
|
||||
|
||||
Update preview page to show the new UI base:
|
||||
|
||||
- shadcn primitives.
|
||||
- App components.
|
||||
- Chinese status, priority, table, filters, section, and empty states.
|
||||
|
||||
## Chinese Localization Requirement
|
||||
|
||||
All frontend user-visible text touched by Stage 1.5 must be Chinese:
|
||||
|
||||
- Navigation labels.
|
||||
- Page titles and descriptions.
|
||||
- Button labels.
|
||||
- Empty states.
|
||||
- Form labels and placeholders.
|
||||
- Status and priority labels.
|
||||
- Table columns.
|
||||
- Toasts or inline feedback.
|
||||
|
||||
Internal variable names, file names, TypeScript types, API field names, and backend enum values may stay English.
|
||||
|
||||
## Compatibility Requirements
|
||||
|
||||
- Existing backend APIs remain unchanged.
|
||||
- Existing Stage 1 frontend routes remain reachable.
|
||||
- Existing tests and type checks must continue to pass.
|
||||
- Docker Compose deployment should still be compatible with the frontend build output.
|
||||
- The project must continue to use npm for frontend package management.
|
||||
|
||||
## Verification
|
||||
|
||||
Stage 1.5 is complete only when:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run typecheck
|
||||
npm run build
|
||||
```
|
||||
|
||||
both pass, and the local app visually shows:
|
||||
|
||||
- shadcn initialized with `components.json`.
|
||||
- Chinese sidebar/topbar navigation.
|
||||
- redesigned workbench, ticket list, ticket create, ticket detail, and solution list pages.
|
||||
|
||||
Backend tests are not required for Stage 1.5 unless backend code is modified. If backend code is changed unexpectedly, run:
|
||||
|
||||
```bash
|
||||
python -m pytest -v
|
||||
python -m ruff check .
|
||||
```
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `frontend/components.json` exists and matches the Vite/Tailwind/TypeScript project.
|
||||
- The frontend uses shadcn-generated primitives where applicable.
|
||||
- Business pages consume the project-owned App component layer for layout and repeated UI patterns.
|
||||
- The current crude ticket table is replaced by a denser, clearer enterprise table experience.
|
||||
- Ticket detail reads as an operational workbench.
|
||||
- User-facing frontend text touched in this stage is Chinese.
|
||||
- No new Stage 2/3/4 backend capability is introduced.
|
||||
Reference in New Issue
Block a user