81 lines
3.9 KiB
Markdown
81 lines
3.9 KiB
Markdown
# Frontend Design System
|
|
|
|
## Principles
|
|
|
|
- Build product screens from shadcn/ui primitives and project-owned App components.
|
|
- Keep operational pages dense, quiet, and optimized for repeated use.
|
|
- Use semantic status colors for ticket state, priority, audit, AI, and system feedback.
|
|
- User-facing frontend text must be Chinese-first. Internal TypeScript names and API field names may stay English.
|
|
- Business pages must not create one-off table, filter, detail, status, or priority patterns.
|
|
- Admin UI should feel calm and enterprise-grade: clear hierarchy, restrained surfaces, compact actions, and no decorative marketing-style layout.
|
|
|
|
## Tokens
|
|
|
|
Theme tokens live in `frontend/src/styles/globals.css` and are exposed through Tailwind in
|
|
`frontend/tailwind.config.ts`.
|
|
|
|
Core tokens:
|
|
|
|
- `background`, `foreground`, `surface`, `border`
|
|
- `muted`, `muted-foreground`
|
|
- `primary`, `success`, `warning`, `danger`, `info`, `ai`
|
|
- `sidebar`, `sidebar-foreground`, `sidebar-primary`, `sidebar-accent`, `sidebar-border`
|
|
|
|
Theme behavior:
|
|
|
|
- `AppThemeProvider` uses `next-themes` with `light`, `dark`, and `system`.
|
|
- `AppThemeToggle` is rendered in `AppTopbar` and exposes Chinese options: `亮色`, `暗色`, `跟随系统`.
|
|
- Light and dark mode values must both be defined in `frontend/src/styles/globals.css`; do not add one-off `dark:` color overrides in business pages.
|
|
- Sidebar colors must come from `sidebar*` tokens so the sidebar follows theme switching.
|
|
|
|
## Components
|
|
|
|
shadcn/ui primitives live in `frontend/src/components/ui` and should remain close to generated shadcn APIs:
|
|
|
|
- `Button`
|
|
- `Badge`
|
|
- `Card`, `CardHeader`, `CardContent`, `CardTitle`, `CardDescription`
|
|
- `Input`, `Textarea`, `Select`
|
|
- `Table`
|
|
- `Dialog`, `Sheet`, `DropdownMenu`, `Tabs`, `Tooltip`, `Skeleton`, `Sonner`
|
|
|
|
Product App components live in `frontend/src/components/app` and are the preferred page-level API:
|
|
|
|
- `AppSidebar`
|
|
- `AppTopbar`
|
|
- `AppThemeProvider`
|
|
- `AppThemeToggle`
|
|
- `AppPage`
|
|
- `AppPageHeader`
|
|
- `AppDataTable`
|
|
- `AppFilterBar`
|
|
- `AppDetailLayout`
|
|
- `AppSection`
|
|
- `AppEmptyState`
|
|
- `AppStatusBadge`
|
|
- `AppPriorityBadge`
|
|
|
|
Business pages should use:
|
|
|
|
- `AppDataTable` for repeated table/list surfaces.
|
|
- `AppFilterBar` for search and filter controls.
|
|
- `AppDetailLayout` for detail pages with main content and side panels.
|
|
- `AppStatusBadge` and `AppPriorityBadge` for ticket lifecycle and priority presentation.
|
|
- `AppField` for form labels and required state; direct page-level `Label` usage should be avoided.
|
|
- `SelectContent > SelectGroup > SelectItem` for every select menu.
|
|
|
|
## Current Core Screens
|
|
|
|
- Ticket center uses an operations-table layout: the first column combines ticket number, title, requester, and description; workflow state and priority are grouped together.
|
|
- Ticket detail uses `AppDetailLayout`, a ticket overview card, a real event timeline, and a side column for handling context, linked solutions, and AI analysis placeholder. Avoid repeating overview-card fields in the side column.
|
|
- Ticket status transitions use `TicketTransitionDialog`. Resolution and closure actions can carry a solution summary; non-resolution workflow actions still require a handling note.
|
|
- Ticket workflows are category-driven: business and operation issues support short closure paths, data issues use a medium path, and technical issues keep the standard support workflow.
|
|
- Linked solutions support search, recommendation-only linking, adoption with automatic ticket closure, and prefilled resolution text during later resolve/close actions.
|
|
- Knowledge pages use the same `AppPage`, `AppSection`, `AppDataTable`, `AppField`, and shadcn form primitives as ticket and system pages.
|
|
- Knowledge search results must show source type, title, score, and citable content snippets.
|
|
- System governance quick-create forms use `AppSection`, `FieldGroup`, and `AppField`.
|
|
|
|
Preview page:
|
|
|
|
- `frontend/src/features/design-system/DesignSystemPreview.tsx`
|