shadcn/ui in this repo
A router: the house contract and a map. The catalogue, the long examples and the vendored upstream
docs are in references/ — read the one you need.
House rules — these win over anything in references/
- Never
--overwrite. npx shadcn@latest add <name> --overwrite is denied in
.foundry/settings.json. Answer N to any overwrite prompt. The 63 files in
webapp/components/ui/ are owned and customised; a component that depends on an existing one
gets only its own new files installed.
- Tailwind v4, CSS-first. There is no
tailwind.config.js; webapp/components.json sets
"tailwind": { "config": "", "css": "app/globals.css" }. Tokens are oklch custom properties in
webapp/app/globals.css, exposed as utilities by @theme inline. Use the semantic class
(bg-background, text-muted-foreground, border-border, ring-ring) — never a raw palette
class such as bg-slate-900, and never an hsl(var(--x)) wrapper. globals.css is marked
PROTECTED — APPEND ONLY: add tokens, do not edit existing ones.
- Server components by default.
"use client" goes on the lowest leaf that needs state, an
event handler or a Radix primitive — not on the page.
- No
useEffect data fetching. Reads are TanStack Query over oRPC
(useQuery(orpc.<router>.<procedure>.queryOptions({ input }))); writes are .actionable()
server actions followed by router.refresh(). Never queryClient.invalidateQueries() for a
mutation — the cache is busted server-side by updateTag(). See library/skills/orpc-fullstack/
and docs/orpc/client.md.
- Forms are react-hook-form +
zodResolver + Zod v4 (zod ^4.3.6, import from "zod", never
"zod/v4"). Field errors render through <FormMessage />, not a toast.
- Toasts come from
@/components/ui/sonner (import { Toaster } from "@/components/ui/sonner",
already mounted in webapp/app/layout.tsx). There is no components/ui/toaster.tsx here.
- Loading, empty and error states follow
.foundry/philosophy/async-state.md; layout, hierarchy
and both-mode design follow .foundry/philosophy/visual.md. A skeleton belongs to first paint
only; after that dim the content in place.
Where things are
| Path |
What |
webapp/components.json |
style new-york, rsc: true, aliases, and five extra registries |
webapp/components/ui/ |
the 63 installed components — read one before inventing a pattern |
webapp/app/globals.css |
tokens (:root, .dark), @theme inline mapping, @custom-variant dark |
webapp/lib/utils.ts |
cn() — clsx + tailwind-merge |
webapp/app/layout.tsx |
<Toaster richColors closeButton /> mount point |
Installing
cd webapp
npx shadcn@latest add dialog # answer N to any overwrite prompt
npx shadcn@latest add @magicui/marquee # extra registries are configured in components.json
Registries in components.json: @magicui, @aceternity, @react-bits, @shadcn-space, @diceui.
The one pattern to copy — a validated form
"use client"
import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import { z } from "zod"
import { Button } from "@/components/ui/button"
import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"
const formSchema = z.object({
email: z.string().trim().max(254).email("Invalid email format"),
password: z.string().min(8, "Password must be at least 8 characters"),
})
type FormValues = z.infer<typeof formSchema>
export function LoginForm({ action }: { action: (input: FormValues) => Promise<void> }) {
const form = useForm<FormValues>({
resolver: zodResolver(formSchema),
defaultValues: { email: "", password: "" },
})
return (
<Form {...form}>
<form className="space-y-4">
<FormField
control={form.control}
name="email"
render={({ field }) => (
<FormItem>
<FormLabel>Email</FormLabel>
<FormControl><Input type="email" autoComplete="email" {...field} /></FormControl>
<FormMessage />
</FormItem>
)}
/>
<Button type="submit" disabled={form.formState.isSubmitting}>
{form.formState.isSubmitting ? "Signing in..." : "Sign in"}
</Button>
</form>
</Form>
)
}
action is the .actionable() server action. The button blocks a second submit while pending and
returns to its label so a failure can be retried (.foundry/philosophy/async-state.md).
References
| File |
Holds |
Load when |
references/setup.md |
init, install, components.json, tsconfig alias, Tailwind v4 config, tokens, theming |
setting up, re-theming, changing a variant |
references/components.md |
Button, Input, Form, Card, Dialog, Sheet, Menubar, Select, Toast, Table — props + examples |
using a component you have not used here before |
references/charts.md |
ChartContainer, ChartConfig, line / area / pie examples, tooltip props, a11y |
building a chart |
references/nextjs.md |
App Router wiring, layout, client boundary, server actions, metadata, fonts, longer forms |
wiring a component into a route |
references/chart.md |
upstream ui.shadcn.com chart docs, scraped |
you need the exact upstream chart API |
references/ui-reference.md |
upstream component docs, scraped |
you need the exact upstream component API |
references/official-ui-reference.md |
upstream installation and CLI docs, scraped |
resolving a CLI or registry question |
references/reference.md |
shadcn.io extras — hooks, animation components |
you are evaluating a third-party shadcn-style component |
references/learn.md |
a learning path through the above, plus the upstream links |
onboarding someone |
1---2name: shadcn-ui3description: >4 shadcn/ui component patterns — installation, configuration, accessible React components,5 forms with React Hook Form and Zod, Tailwind v4 theming. Use for "shadcn", "shadcn/ui",6 "add a component", "build a form", "dialog", "data table", "theme the components".7 Never install with `--overwrite`.8allowed-tools: Read, Write, Bash, Edit, Glob9metadata:10 source: https://skillmd.com/skills/dabhiram13/shadcn-ui11---1213# shadcn/ui in this repo1415A router: the house contract and a map. The catalogue, the long examples and the vendored upstream16docs are in `references/` — read the one you need.1718## House rules — these win over anything in `references/`19201. **Never `--overwrite`.** `npx shadcn@latest add <name> --overwrite` is denied in21 `.foundry/settings.json`. Answer `N` to any overwrite prompt. The 63 files in22 `webapp/components/ui/` are owned and customised; a component that depends on an existing one23 gets only its own new files installed.242. **Tailwind v4, CSS-first.** There is no `tailwind.config.js`; `webapp/components.json` sets25 `"tailwind": { "config": "", "css": "app/globals.css" }`. Tokens are oklch custom properties in26 `webapp/app/globals.css`, exposed as utilities by `@theme inline`. Use the semantic class27 (`bg-background`, `text-muted-foreground`, `border-border`, `ring-ring`) — never a raw palette28 class such as `bg-slate-900`, and never an `hsl(var(--x))` wrapper. `globals.css` is marked29 **PROTECTED — APPEND ONLY**: add tokens, do not edit existing ones.303. **Server components by default.** `"use client"` goes on the lowest leaf that needs state, an31 event handler or a Radix primitive — not on the page.324. **No `useEffect` data fetching.** Reads are TanStack Query over oRPC33 (`useQuery(orpc.<router>.<procedure>.queryOptions({ input }))`); writes are `.actionable()`34 server actions followed by `router.refresh()`. Never `queryClient.invalidateQueries()` for a35 mutation — the cache is busted server-side by `updateTag()`. See `library/skills/orpc-fullstack/`36 and `docs/orpc/client.md`.375. **Forms are react-hook-form + `zodResolver` + Zod v4** (`zod` ^4.3.6, import from `"zod"`, never38 `"zod/v4"`). Field errors render through `<FormMessage />`, not a toast.396. **Toasts come from `@/components/ui/sonner`** (`import { Toaster } from "@/components/ui/sonner"`,40 already mounted in `webapp/app/layout.tsx`). There is no `components/ui/toaster.tsx` here.417. **Loading, empty and error states follow `.foundry/philosophy/async-state.md`**; layout, hierarchy42 and both-mode design follow `.foundry/philosophy/visual.md`. A skeleton belongs to first paint43 only; after that dim the content in place.4445## Where things are4647| Path | What |48|------|------|49| `webapp/components.json` | style `new-york`, `rsc: true`, aliases, and five extra registries |50| `webapp/components/ui/` | the 63 installed components — read one before inventing a pattern |51| `webapp/app/globals.css` | tokens (`:root`, `.dark`), `@theme inline` mapping, `@custom-variant dark` |52| `webapp/lib/utils.ts` | `cn()` — `clsx` + `tailwind-merge` |53| `webapp/app/layout.tsx` | `<Toaster richColors closeButton />` mount point |5455## Installing5657```bash58cd webapp59npx shadcn@latest add dialog # answer N to any overwrite prompt60npx shadcn@latest add @magicui/marquee # extra registries are configured in components.json61```6263Registries in `components.json`: `@magicui`, `@aceternity`, `@react-bits`, `@shadcn-space`, `@diceui`.6465## The one pattern to copy — a validated form6667```tsx68"use client"6970import { zodResolver } from "@hookform/resolvers/zod"71import { useForm } from "react-hook-form"72import { z } from "zod"73import { Button } from "@/components/ui/button"74import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"75import { Input } from "@/components/ui/input"7677const formSchema = z.object({78 email: z.string().trim().max(254).email("Invalid email format"),79 password: z.string().min(8, "Password must be at least 8 characters"),80})8182type FormValues = z.infer<typeof formSchema>8384export function LoginForm({ action }: { action: (input: FormValues) => Promise<void> }) {85 const form = useForm<FormValues>({86 resolver: zodResolver(formSchema),87 defaultValues: { email: "", password: "" },88 })8990 return (91 <Form {...form}>92 <form onSubmit={form.handleSubmit(action)} className="space-y-4">93 <FormField94 control={form.control}95 name="email"96 render={({ field }) => (97 <FormItem>98 <FormLabel>Email</FormLabel>99 <FormControl><Input type="email" autoComplete="email" {...field} /></FormControl>100 <FormMessage />101 </FormItem>102 )}103 />104 <Button type="submit" disabled={form.formState.isSubmitting}>105 {form.formState.isSubmitting ? "Signing in..." : "Sign in"}106 </Button>107 </form>108 </Form>109 )110}111```112113`action` is the `.actionable()` server action. The button blocks a second submit while pending and114returns to its label so a failure can be retried (`.foundry/philosophy/async-state.md`).115116## References117118| File | Holds | Load when |119|------|-------|-----------|120| `references/setup.md` | init, install, `components.json`, tsconfig alias, Tailwind v4 config, tokens, theming | setting up, re-theming, changing a variant |121| `references/components.md` | Button, Input, Form, Card, Dialog, Sheet, Menubar, Select, Toast, Table — props + examples | using a component you have not used here before |122| `references/charts.md` | `ChartContainer`, `ChartConfig`, line / area / pie examples, tooltip props, a11y | building a chart |123| `references/nextjs.md` | App Router wiring, layout, client boundary, server actions, metadata, fonts, longer forms | wiring a component into a route |124| `references/chart.md` | upstream ui.shadcn.com chart docs, scraped | you need the exact upstream chart API |125| `references/ui-reference.md` | upstream component docs, scraped | you need the exact upstream component API |126| `references/official-ui-reference.md` | upstream installation and CLI docs, scraped | resolving a CLI or registry question |127| `references/reference.md` | shadcn.io extras — hooks, animation components | you are evaluating a third-party shadcn-style component |128| `references/learn.md` | a learning path through the above, plus the upstream links | onboarding someone |