Design System Diagnosis

## Design system rules

<!-- Generated by roast-my-design-system from a scan of vercel/ai-chatbot on 2026-08-22.
     Paste into CLAUDE.md, .cursor/rules or AGENTS.md. Regenerate after big refactors:
     npx roast-my-design-system --rules -->

Follow these rules when writing or editing UI in this repo. Every rule below was derived from a scan of this codebase, with real paths and usage counts.

### Colours and tokens

- Design tokens live in `app/globals.css`. Reach for an existing token before inventing any value.
- Never hardcode colour values in components. The palette already has 49 tokens; the scan still found 12 hardcoded colours sitting next to them. Do not add more.
- This repo uses shadcn/ui; its components live in `components/ui`. Prefer extending it over building parallel pieces.

### Canonical components

- Use these existing components instead of writing new ones, the way this repo already uses them:
  - `<Button>` from `components/ui/button.tsx` (used 25x · props: variant, size, asChild)
  - `<Tooltip>` from `components/ui/tooltip.tsx` (used 10x)
    - most common usage, as in `components/ai-elements/message.tsx` (matching 8 of 10 usages): `<Tooltip>…</Tooltip>`
  - `<TooltipContent>` from `components/ui/tooltip.tsx` (used 10x · props: sideOffset)
  - `<TooltipTrigger>` from `components/ui/tooltip.tsx` (used 10x)
    - most common usage, as in `components/ai-elements/message.tsx` (matching 10 of 10 usages): `<TooltipTrigger asChild>…</TooltipTrigger>`
  - `<DropdownMenuItem>` from `components/ui/dropdown-menu.tsx` (used 8x · props: inset, variant)
  - `<LoaderIcon>` from `components/chat/icons.tsx` (used 8x · props: size)
    - most common usage, as in `components/chat/document.tsx` (matching 5 of 8 usages): `<LoaderIcon />`
  - `<SidebarMenuButton>` from `components/ui/sidebar.tsx` (used 7x · props: asChild, isActive, variant, size)
  - `<CopyIcon>` from `components/chat/icons.tsx` (used 6x · props: size)
    - most common usage, as in `artifacts/code/client.tsx` (matching 3 of 6 usages): `<CopyIcon size={18} />`

### Known duplicates: do not make it worse

- `<MessageActions>` is defined twice and one wraps the other; do not create a third.

### Spacing and sizing

- Stay on the Tailwind spacing scale. If a gap looks wrong on a scale step, flag it instead of nudging by a pixel.
- No new arbitrary bracket values (`p-[13px]`, `text-[10px]`). The scan found 103 already. If a value repeats, it is a decision: name it as a token instead of writing the bracket again.
- Avoid new one-off CSS spacing values; 2 off-scale values are already in play.

### Typography

- The repo uses 3 typefaces: SF Mono, Geist, Geist Mono. Do not introduce another, and do not re-declare font stacks by hand; use the existing setup.

### Styling discipline

- Never write `style={{ ... }}` for static values; styling belongs to classes and tokens where the system can see it.
  (7 static inline blocks already exist; do not add to them.)
- Never write !important; the scan found 9 declarations already. When a style does not apply, fix the selector or the source of the conflict instead of shouting over it.
- Before styling anything new, look at a neighbouring component and match how it does it. Consistency with the repo beats personal preference.

---
*Generated by [roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system) ver. 5.2.1. Rescan after refactors to keep these rules honest.*