Design System Diagnosis

## Design system rules

<!-- Generated by roast-my-design-system from a scan of dubinc/dub 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 `packages/tailwind-config/themes.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 55 hardcoded colours sitting next to them. Do not add more.
- Never eyeball a colour from memory: the scan found 14 nearly identical pairs (like #ffffff next to #fafafa). Look the exact value up, or better, use its token.

### Canonical components

- Use these existing components instead of writing new ones, the way this repo already uses them:
  - `<Button>` from `packages/ui/src/button.tsx` (used 988x · props: text, variant, textWrapperClassName, shortcutClassName)
  - `<Modal>` from `packages/ui/src/modal.tsx` (used 185x · props: showModal, setShowModal, onClose, desktopOnly)
    - most common usage, as in `apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/groups/[groupSlug]/links/add-edit-group-additional-link-modal.tsx` (matching 98 of 182 usages): `<Modal showModal={isOpen} setShowModal={setIsOpen}>…</Modal>`
  - `<Tooltip>` from `packages/ui/src/tooltip.tsx` (used 144x · props: content, contentClassName, disabled, side)
    - most common usage, as in `apps/web/ui/support/chat-bubble.tsx` (matching 50 of 68 usages): `<Tooltip content="Close">…</Tooltip>`
  - `<LoadingSpinner>` from `packages/ui/src/icons/loading-spinner.tsx` (used 113x)
    - most common usage, as in `apps/web/app/(ee)/admin.dub.co/(dashboard)/programs/page.tsx` (matching 58 of 113 usages): `<LoadingSpinner className="size-4" />`
  - `<Popover>` from `packages/ui/src/popover.tsx` (used 100x · props: content, align, side, openPopover)
  - `<InfoTooltip>` from `packages/ui/src/tooltip.tsx` (used 97x)
    - most common usage, as in `apps/web/ui/modals/qr-code-design-fields.tsx` (matching 76 of 78 usages): `<InfoTooltip content={tooltip} />`
  - `<X>` from `apps/web/ui/shared/icons/x.tsx` (used 90x)
    - most common usage, as in `apps/web/app/(ee)/admin.dub.co/(dashboard)/partners/network/network-partner-application-sheet.tsx` (matching 86 of 90 usages): `<X className="size-5" />`
  - `<AnimatedSizeContainer>` from `packages/ui/src/animated-size-container.tsx` (used 89x)
    - most common usage, as in `apps/web/app/(ee)/app.dub.co/embed/referrals/settings.tsx` (matching 38 of 85 usages): `<AnimatedSizeContainer height>…</AnimatedSizeContainer>`

### Known duplicates: do not make it worse

- `<PayoutStats>` exists in 3 places. Treat `apps/web/ui/layout/sidebar/payout-stats.tsx` as canonical; do not import the other copies, and never create another.
- `<Logo>` exists in 2 places. Treat `packages/ui/src/logo.tsx` as canonical; do not import the other copy, and never create another.
- `<EmptyState>` is defined twice and one wraps the other. Import `packages/ui/src/empty-state.tsx`; do not create a third.
- `<FormControl>` exists in 2 places (`apps/web/ui/partners/groups/design/application-form/fields/form-control.tsx`, `apps/web/ui/submitted-leads/form-fields/form-control.tsx`). Match whichever the surrounding code already imports, and never create another.
- `<SettingsRow>` exists in 2 places (`apps/web/app/(ee)/partners.dub.co/(dashboard)/profile/settings-row.tsx`, `apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/program-settings-row.tsx`). Match whichever the surrounding code already imports, and never create another.
- `<Hero>` exists in 2 places (`apps/web/ui/placeholders/hero.tsx`, `apps/web/ui/modals/dot-link-offer-modal.tsx`). Match whichever the surrounding code already imports, and never create another.
- Two icon sets collide on 11 names. Before adding any icon, check which set the surrounding file already imports and stay with it.

### Components nobody imports

- 16 components are defined but never imported (`<Alert>`, `<AlertDescription>`, `<AlertTitle>`…). Before writing any new component, check this list first; adopt one or flag it for deletion instead of adding another.

### 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 632 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; 33 off-scale values are already in play.

### Typography

- The repo uses 3 typefaces: Inter, satoshi, Geist. 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.
  (48 static inline blocks already exist; do not add to them.)
- 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.*