mobile-shadcn-conventions

How the Agenta mobile app (web/mobile) installs and extends shadcn/ui registry components, themes them via the palette token bridge, and uses Vercel AI Elements. Use when adding UI components under web/mobile, changing theme colors, editing components.json or globals.css, or building chat UI with AI Elements.

Jump to install

Repository: Agenta-AI/agenta
Last source activity: August 5, 2026 at 23:04
Detected SKILL.md language: English
Stars: 4,719
Forks: 664

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	mobile-shadcn-conventions
description	How the Agenta mobile app (web/mobile) installs and extends shadcn/ui registry components, themes them via the palette token bridge, and uses Vercel AI Elements. Use when adding UI components under web/mobile, changing theme colors, editing components.json or globals.css, or building chat UI with AI Elements.

Mobile shadcn conventions

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

Installing registry components

Always install via the CLI from web/mobile/: pnpm dlx shadcn@latest add <component> (e.g. button, sheet, dialog, command, skeleton, input).
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.
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.

Vercel AI Elements (chat render layer, WP3b+)

AI Elements are shadcn registry components; install them the same way (pnpm dlx shadcn@latest add <ai-elements registry item>), landing in src/components/ui/ / src/components/ai-elements/ per the registry config.
They are the base of the chat skin (Conversation, Message, Response, Reasoning, Tool, PromptInput); behavior comes from @agenta/chat hooks — never re-implement orchestration inside a rendered component.