TrueGrowth/docs/TRUEGROWTH_UI_SYSTEM.md

TrueGrowth UI System

TrueGrowth UI uses a local, free-to-use design system instead of a hosted or paid component dependency. New customer-facing UI must be built from apps/web/src/ui (@/ui) so Codex and human contributors reuse the same controls, spacing, focus states, and orange brand treatment.

The approved visual authority is the AI 图片生成 page at http://127.0.0.1:7200/image. Treat /image as the golden page for layout, surface colors, form density, media results, task batches, loading/failed states, hover actions, popovers, dialogs, and browser QA. The detailed standard is docs/TRUEGROWTH_GOLDEN_IMAGE_PAGE_UI.md.

Stack

• Base components: local shadcn-style React components in @/ui
• Interaction target: Radix primitives as the future implementation layer for complex overlays and menus
• Styling: Tailwind 4 plus TrueGrowth CSS tokens
• Icons: lucide-react only
• Data views: Tremor-style patterns may be copied locally and tokenized for dashboards only
• Motion/empty states: Magic UI-style patterns may be copied locally and tokenized for limited non-form surfaces

Rules

• Import app UI primitives from @/ui; do not create page-local buttons, inputs, dialogs, cards, tabs, badges, or progress controls.
• Do not add new imports from tdesign-react or tdesign-icons-react in apps/web/src.
• Use lucide-react for every new icon.
• Use #ff5b00 only through tokens such as --aitu-ui-brand, --tg-ui-primary, or existing --tg-brand aliases.
• Primary actions must be orange; blue primary actions are not allowed.
• Controls should be 40-42px tall, use 8-10px radius, visible labels, orange focus rings, and non-wrapping button labels.
• Keep light and dark mode support for every new surface. Any custom page CSS must define both light and :root[data-tg-theme='dark'] states for surfaces, text, borders, overlays, hover states, and focus rings before the page is considered complete.
• The workbench shell is a two-area layout: fixed left navigation and content. Do not add a global top search/header bar; route titles, filters, and actions must live inside the page flow. The global task summary and theme toggle live in the lower-left navigation utility area.
• Generator pages must follow the /image split layout: full-height left creation/configuration panel and soft right result feed, with batch-based horizontal media rails.
• Libraries, asset pages, and publishing pages must be media-first, with full-ratio thumbnails, quiet surfaces, and hover/compact actions instead of always-visible button clutter.
• Dialogs, drawers, popovers, and settings panels must match /image radius, surface, input, and orange focus behavior. Nested white inputs inside bordered white wrappers are not allowed.
• Visual UI changes must be verified in the browser against the golden page standard, including screenshots and at least one primary interaction.

Page Templates

Start from the templates in docs/page-templates/ or the React helpers in @/ui:

• PageShell for page-level title, description, and actions
• Section for bordered white/near-black bands
• FormGrid for compact SaaS form layouts
• Card for repeated items, not nested page sections
• EmptyState for directional empty surfaces
• generator-page.tsx for /image-style generator surfaces
• media-library-page.tsx for assets, finished work, digital-human image/video grids, and result libraries
• status-page.tsx for task center, model center, runtime state, and publishing status lists

Migration Policy

TDesign remains as a compatibility boundary for old Drawnix/opentu surfaces while they are migrated. New work should not expand that dependency. When touching a legacy page, prefer replacing visible shell controls with @/ui and leaving business logic intact.

Migration order should start with navigation-entered first-level pages, then their primary dialogs and popovers, then deeper secondary flows. Each route needs screenshot evidence before it is treated as migrated.