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.

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

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
• 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.

Preview page:

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