agenta-ai / mobile-shadcn-conventions

Mobile shadcn conventions

web/mobile uses shadcn/ui on Tailwind v4 with CSS variables. No antd, ever.

Installing registry components

• Prefer the shared primitive first: if @agenta/ui/ui already exports it
  (Button, Input, Select, Dialog, Sheet, DropdownMenu, ...), import it
  from there. Do not install a local copy of a component the kit already has —
  button in particular lives ONLY in @agenta/ui (Nova preset on the shared
  control-* scale), so there is one button.

• Use Input, SkeletonBlock and Sheet from @agenta/ui/ui. A local
  src/components/ui/sheet.tsx still backs ChannelsPanelSheet only; do not import it
  anywhere else, and do not add other local duplicates of kit components.

• Otherwise install via the CLI from web/mobile/:
  pnpm dlx shadcn@latest add <component>.

• Components land in src/components/ui/ (aliases in components.json). They
  are owned code: you may adapt them, but keep diffs minimal and expressed in
  semantic tokens so upstream refreshes stay cheap.

• The CLI adds any peer deps (e.g. @radix-ui/react-slot) to
  web/mobile/package.json — commit the manifest and web/pnpm-lock.yaml
  changes together with the component.

• Never copy component source from the shadcn website by hand; the CLI resolves
  the Tailwind v4 variant correctly.

• Installing a shadcn component that references a NEW token (e.g. bg-sidebar,
  chart-*) requires extending VARS in scripts/generate-shadcn-tokens.ts +
  the @theme inline map in globals.css first — Tailwind v4 silently
  generates nothing for unmapped tokens.

Theming — the token bridge

• shadcn variables (--background, --primary, ...) are NOT hand-maintained.
  They are generated into src/styles/theme.generated.css from
  web/oss/src/styles/theme/palette.ts by scripts/generate-shadcn-tokens.ts.
  The script also reads controlScale.ts from the same folder. That theme
  folder is the one part of web/oss still in use: edit it for color changes,
  but touch nothing else in web/oss.

• To change a color: edit palette.ts (if the design-system value is wrong) or
  the ROLE MAP in the script (if the mapping is wrong), then run
  pnpm --filter @agenta/mobile generate:tokens and commit the regenerated CSS.

• Never edit theme.generated.css directly; never introduce raw hex values in
  components — if a needed role is missing, extend the bridge.

• Dark mode is the .dark class on <html> (@custom-variant dark in
  globals.css), set pre-paint by the _document.tsx init script from the
  shared agenta-theme localStorage key. Both themes must be checked for every
  new surface.

Extending components

• Wrap, don't fork: feature-specific variants live in src/features/* as thin
  wrappers over components/ui/* primitives (cva variants where appropriate).

• Use the cn util from @/lib/utils for all class merging.

Chat UI

• There are no Vercel AI Elements in the app and no src/components/ai-elements/.
  Chat lives in src/features/chat/ (ChatScreen, Composer,
  LiveConversation, TranscriptTurns, ...), built on @agenta/chat
  (state, model, hooks, components, ... subpaths) and the Lexical-based
  @agenta/ui/rich-chat-input. Markdown streams through streamdown.

• Behavior comes from @agenta/chat hooks — never re-implement orchestration
  inside a rendered component.

• Icons: both @phosphor-icons/react (most files) and lucide-react (older
  files and shadcn registry output) are in use. Match the surrounding feature.