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>
  );
}

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/component-conventions.md — Code conventions: CVA variants, compound components, asChild / slot system
• design-system/references/patterns/README.md — Documented UI composition patterns (compositions of primitives, not code conventions). Load when asked "what pattern applies to X?"
• design-system/references/heuristics.md — Index of UX heuristics: which pattern fits a task (dialog vs stepper, disable vs hide, error surfaces, etc.). Guidelines, not rules — escalate to @design when a screen has reason to deviate