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