# Studio Design Architecture
<!-- wiki:featured -->
**Package:** `@studio/ui`  
**Version:** v3.2.3  
**Source:** `packages/studio-design-kit/`  
**Track:** studio-design  
**Status:** Production — sole design system for new UI

## Overview

`@studio/ui` is the app-factory design kit: shadcn semantic tokens, layered components, forms, agent UI, and layout scaffolds. Apps import from `@studio/ui` only. Legacy `studio_platform/ui` (and `platform/ui`) is **frozen** — do not extend or re-import it.

## Package layout

| Path | Role |
|------|------|
| `src/index.ts` | Public exports (SSOT for MCP `list_components`) |
| `src/components/ui/` | Layer 1 — shadcn/Radix primitives |
| `src/components/` (Magic UI) | Layer 2 — motion / pattern components |
| `src/components/agent-elements/` | Layer 3 — streaming agent chat + tools |
| `src/studio/` | Layers 4–5 — app shells, KPIs, ANDI widgets |
| `src/form/` | `useStudioForm`, `StudioForm`, `StudioFormField` |
| `src/tokens/` | `tokens.css`, `tokens.dark.css`, `tokens.products.css` |
| `src/llms.txt` | Recipes for MCP `get_recipe` |
| `src/lib/utils.ts` | `cn()` |

**Exports** (from `package.json`): `.`, `./tokens`, `./tokens-dark`, `./tokens-products`, `./globals`, `./components/*`, `./form/*`, `./studio/*`, `./lib/*`, `./hooks/*`, `./templates` → product-kit.

## Component layers

1. **Primitives** — Button, Input, Dialog, Select, Table, Chart, Sonner, etc. (shadcn via `npx shadcn@latest add`; never hand-roll).
2. **Magic UI** — ShimmerButton, NumberTicker, TextReveal, GridPattern, BlurFade, BorderBeam, etc.
3. **Agent elements** — AgentChat, InputBar, StreamingMarkdown, ThinkingTool, tool rows (edit/plan/todo/MCP/bash).
4. **Layout scaffolds** (3.2.0+) — StudioAppShell, StudioAppLayout, StudioPageHeader, StudioSidebar, StudioMobileNav, StudioNavTabs, StudioFilterSidebar, StudioKpiGrid / StudioStatusPage.
5. **ANDI / domain** — EvidenceTierBadge, ConfidenceInterval, JevFactorBreakdown, ANDIDecisionCard, PropertyCard, RiskMeter, StatusDot, HealthPill.

Async views always ship **empty + loading (skeleton) + error + success** (`EmptyState` / `ErrorState` / Skeleton).

## Token system

Semantic CSS variables only (light + `.dark` + `[data-product='…']` overrides):

| Category | Tokens |
|----------|--------|
| Surfaces | `--background`, `--foreground`, `--card`, `--popover`, `--muted`, `--accent`, `--border`, `--input`, `--ring` |
| Actions | `--primary`, `--secondary`, `--destructive`, `--success`, `--warning` (+ `-foreground` variants) |
| Radius | `--radius`, `--radius-sm/md/lg/xl` |
| State / brand (v5.1+) | `--success`, `--warning`, `--info`, `--error` (→ destructive), `--brand-primary` (→ primary) |

**Banned semantic names:** `--studio-canvas`, `--studio-ink`, `--studio-accent` (legacy). Map old `--studio-*` colours to shadcn semantic tokens.

Dark mode: `dark` class on `html`. Product theme: `data-product` on root.

## Kit conventions

- No hardcoded hex / rgb / Tailwind palette utilities (`bg-blue-500`, etc.).
- No MUI, Ant Design, styled-components, emotion, Chakra, Mantine.
- Icons: `lucide-react` named imports only (no second icon set in app code).
- Relative imports **inside** the kit; consumers import from `@studio/ui`.
- Forms: `useStudioForm` + Zod together — always.
- Prefer kit Magic UI / motion wrappers; do not import `motion/react` directly in app code.
- Mobile-first, ≥44px touch targets, WCAG AA, 8px spacing grid.
- Validate with MCP `validate_ui` + `bash scripts/validate-design-system-contract.sh`.

## Allowed / expected dependencies

| Concern | Library |
|---------|---------|
| UI primitives | Radix / Base UI, CVA, `clsx` + `tailwind-merge` |
| Forms | react-hook-form + Zod |
| State / data (per product) | Zustand, TanStack Query / Table / Virtual |
| Charts | recharts (via kit Chart*) |
| Toasts / drawers / cmd | sonner, vaul, cmdk |
| Streaming | Vercel AI SDK, streamdown |
| Animation | framer-motion / motion (kit-wrapped) |
| Icons | lucide-react (primary) |
| Tooling | TypeScript, Biome, Vitest |

**Peers:** `react` / `react-dom` `^18.3 \|\| ^19` — consumers match monorepo (kit dev: React 19.3).

**Version authority:** kit `package.json` owns shared React/Next/Tailwind pins; apps must not independently override or alias React/Next.

## Migrated from `studio_platform/ui`

| Legacy | Status |
|--------|--------|
| `studio_platform/ui` / `platform/ui` | **FROZEN** — `FROZEN.md`; reference only; do not import |
| shadcn primitives + Studio* surfaces | Re-homed under kit `components/ui` + `studio/` |
| Agent widgets (TraceCard, PipelineRail, StreamingText, …) | Kit `components/agent*` + studio exports |
| Tokens (`platform/design/tokens.css` style) | Kit `src/tokens/*` on shadcn semantic names |
| Form kit gaps (no RHF/Zod in legacy) | Closed with `useStudioForm` + Zod |
| Deleted Phase A motion/decorative files | Do **not** recreate (AnimatedNumber, BentoGrid, Cult*, etc.) |

New work: kit + `docs/studio-design/APP_FACTORY.md` Craft Pack → MCP recipes → optional 21st.dev inspiration only after kit miss.

## Related docs

- `docs/studio-design/` — track VERSION, TECH_STACK, APP_FACTORY, CHANGELOG  
- `packages/studio-design-kit/src/llms.txt` — recipes  
- `AGENTS.md` — agent law for all coding tools