ai-ticket-platform/docs/frontend/design-system.md

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 metadata, linked solutions, and AI analysis placeholder.
• Ticket status transitions require a handling note through TicketTransitionDialog.
• System governance quick-create forms use AppSection, FieldGroup, and AppField.

Preview page:

• frontend/src/features/design-system/DesignSystemPreview.tsx