Add a shadcn component

The rules are in docs/standards/frontend-architecture.md, in the sections "The only-shadcn rule" and "Shared tiers".

<component> is the registry name of the component. Example: dropdown-menu.

Procedure

1. Run the shadcn CLI:

   env -u NODE_ENV npx shadcn@latest add <component> -y

2. Run git status --short. Record each file that the CLI created or changed.

3. Format the new files. The CLI writes files without semicolons, so format:check fails on them before this step.

   env -u NODE_ENV npx oxfmt <each new file>

4. Do not write a new primitive by hand. Do not change a generated file, except with the edits in steps 5 to 17 or with a cva variant.

Packages

5. Open package.json. The CLI adds packages to dependencies, for example radix-ui, cn, cmdk and sonner.
   1. Move each web package that the CLI added to devDependencies.
   2. Pin each moved package to an exact version. Remove each ^ and ~.
   3. Do not move zod or a server package.
   4. Do not install next-themes, react-hook-form or @hookform/resolvers.
   5. Run env -u NODE_ENV npm install to update package-lock.json.

Focus outline

6. In each generated file, replace each of these classes with focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring:

   • focus-visible:ring-*
   • focus-visible:border-ring
   • ring-offset-*
   • aria-invalid:ring-* and dark:aria-invalid:ring-*

   If the class string also has outline-hidden or outline-none, add focus-visible:outline-solid; focus-outline.test.ts enforces it.

7. Keep aria-invalid:border-destructive.
8. If an ancestor with overflow: hidden cuts the outline, use focus-visible:outline-offset-0 at that element. Menu and select items use the inset form focus-visible:-outline-offset-2.
9. Run grep -nE '(^|[^a-z-])ring-' <file> on each generated file. The command must show no line.

Colours

10. Replace each Tailwind default palette class with a token class. Examples: text-white becomes text-on-accent or text-on-danger, and bg-black/50 becomes bg-scrim.
11. Replace a raw colour variable in a class, for example hsl(var(--x)), with var(--x).
12. Open src/web/styles/globals.css. Remove each colour value that the CLI added, for example an oklch() value.
13. Map each new shadcn colour name to a token that src/web/styles/tokens.css defines. Do not add a shadcn name to tokens.css.
    1. In the :root block of src/web/styles/globals.css, add one custom property for the name. Its value is var() of the token. Example: --card: var(--surface-card);.
    2. In the @theme inline block of src/web/styles/globals.css, add the colour name. Example: --color-card: var(--card);.
    3. tokens.css already defines some names. Do not add a :root line for these names. Map each one in the @theme inline block of src/web/styles/globals.css:
       • accent: --color-accent: var(--surface-card-hover);
       • destructive: --color-destructive: var(--destructive);
       • border: --color-border: var(--border);
       • radius: --radius-md: var(--radius);. The --radius-sm and --radius-lg tokens in tokens.css set the other sizes.
14. If a token class does not exist in the @theme inline block of src/web/styles/globals.css, add its mapping there. Do not write a colour value.
15. Keep the @custom-variant dark line in src/web/styles/globals.css.

Sonner

16. If the component is sonner, remove the next-themes import from sonner.tsx. Give the Toaster a theme prop that its consumer sets. Do not import a hook from outside src/web/components/ui/.

Gallery

17. Add the component to src/web/gallery-main.tsx, in the group of its family. If this file does not exist, skip this step and tell the user.

Checks

18. Run env -u NODE_ENV npm run check:static. It must pass.
19. Tell the user the new files, the moved packages and their versions.