Resend Design System

Use primitives from src/ui/ for all UI work. Never create custom components when a primitive exists. Check /design/components pages for live examples.

Quick Reference

All primitives use @/ui/{name} imports. Icons in @/ui/icons/icon-{name}.

Core Components

Sizing Scale

Color Conventions

• Primary action: appearance="white" (inverted black/white, flips in dark mode)
• Secondary: appearance="gray"
• Subtle/ghost: appearance="fade" or appearance="fade-gray"
• Destructive: appearance="red" or appearance="fade-red"

Key Rules

1. Use cn() from @/lib/cn for class merging
2. Use @/ absolute imports everywhere
3. Prefer Server Components; 'use client' only at lowest interactive leaf — extract the interactive part into a small leaf component, don't mark the whole page client
4. Use sentence case for all UI copy
5. State via state prop, not booleans — state="loading", state="disabled", state="invalid", state="read-only". Each value is self-sufficient: state="loading" already prevents interaction, so don't also add disabled={}
6. Compound TextField: TextField.Root > TextField.Slot? + TextField.Input + TextField.Slot? — state and size go on TextField.Input, not Root. Use <TextField.Error message={msg} id="x" /> inside a trailing Slot for validation errors — it auto-wires aria-describedby. Don't also pass error= on Input or set aria-describedby manually.
7. Radix namespaces: import * as Select from '@/ui/select'
8. asChild for links: <Button asChild><Link href="/x">Label</Link></Button> — also works on Dialog.Trigger, Tooltip.Trigger

Server vs Client

Already client (built-in, no extra 'use client' needed on your part): TextField, Checkbox, Dialog, Drawer, Collapsible, Calendar, BulkActions.

Server-safe: Button, Heading, Text, Tag, Banner, Card, EmptyState, Kbd, IconButton.

Correct pattern — extract only the interactive leaf:

// page.tsx — Server Component
export default function Page() {
  return <Card><Heading>Title</Heading><DeleteDialog /></Card>;
}

// delete-dialog.tsx — small Client Component
'use client';
export function DeleteDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild><Button appearance="fade-red">Delete</Button></Dialog.Trigger>
      <Dialog.Content size="1"><Dialog.Title>Confirm delete</Dialog.Title></Dialog.Content>
    </Dialog.Root>
  );
}

Patterns

Documented UI patterns live in design-system/references/patterns/. A pattern is a composition of src/ui/ primitives repeated across ≥ 3 dashboard files. When asked "what pattern applies to X?", load design-system/references/patterns/README.md first, then check src/app/(internal)/design/_common/documented-patterns.json to see what is currently documented.

The design-audit skill (see design-audit/SKILL.md) uses this directory when deciding whether a detected composition is already a documented pattern or a new candidate.

Heuristics

Resend's UX heuristics live in design-system/references/heuristics.md and the files under heuristics/. They cover decisions — which pattern fits this task — rather than how to build a primitive. Load them when choosing between dialog/stepper/full-screen/drawer, deciding whether to disable or hide a control, picking an error surface, etc.

Heuristics are guidelines, not strict rules. If a screen has a real reason to deviate, that's allowed; escalate to @design when unsure.

References

For detailed documentation, load these as needed:

• design-system/references/components.md — Full component catalog with all props and usage
• design-system/references/design-tokens.md — Colors, typography, shadows, animations
• design-system/references/patterns.md — Component patterns: CVA variants, compound components, asChild / slot system
• design-system/references/patterns/README.md — Documented UI composition patterns and scaffolding guide
• design-system/references/heuristics.md — Index of Resend's UX heuristics (dialog-vs-stepper, disable-vs-hide, API-first, etc.)