# 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`