just-works: Skill for Claude Code

shadcn/ui coding

Project conventions override these defaults. Read components.json first: style (its prefix names the primitive library), tailwind, aliases, rsc. Then read the local source in components/ui/ and package.json for the React version; the local source is the truth for props and structure.

Primitive library

The style prefix in components.json tells you which primitives the components wrap: base-* is Base UI, radix-* and the older new-york are Radix UI, aria-* is React Aria. This changes the API:

Both libraries use onValueChange for Select-like inputs and onCheckedChange for Checkbox and Switch. React Aria projects: read the local source before composing. For any component, npx shadcn@latest docs <component> prints its usage and its Composition tree (what wraps what).

Never rules

• Never import shadcn components from npm. shadcn is not a package. Import from the alias in components.json: import { Button } from "@/components/ui/button".
• Never flatten compound components. Dialog, DropdownMenu, Select, AlertDialog, Menubar, NavigationMenu, ContextMenu, and Tabs need their nested structure (for example Dialog > DialogContent > DialogHeader > DialogTitle); removing wrappers breaks ARIA roles and keyboard navigation.
• Never nest a <Button> inside a Trigger. Triggers render their own <button>, so nesting produces invalid HTML. Use asChild (Radix) or render (Base UI) to render your element instead.

// Radix
<DialogTrigger asChild><Button variant="outline">Open</Button></DialogTrigger>
// Base UI
<DialogTrigger render={<Button variant="outline" />}>Open</DialogTrigger>

• Never hardcode colors or compose className with template literals. Use semantic tokens (bg-primary text-primary-foreground) and cn(); the rules live in tailwind-css-coding.
• Never spread {...field} on Select, Checkbox, or Switch. They take onValueChange / onCheckedChange, not onChange, so the spread's onChange is silently ignored. Wire value and the handler explicitly.
• Never define DataTable columns inside the component. A new array every render triggers TanStack Table's referential-equality checks and loops. Define them at module level.
• Never build custom modals, dropdowns, or tooltips. Use Dialog, DropdownMenu, Tooltip, Popover, or Sheet; hand-built versions lack focus trapping, keyboard navigation, and portals.
• Never nest TooltipProvider. Mount it once at the app root.
• Never invent props. Components only have the props in their local source.
• Never use npx shadcn-ui@latest. The CLI is npx shadcn@latest.
• Never use the old Radix toast component (deprecated in favor of Sonner). Use the toast library the project already has (Sonner, or the newer toast component on Base UI styles), and add one with npx shadcn@latest add sonner only if none exists.