React Email Design System

Overview

React Email is a developer-centric design system built for transactional email components and code-first workflows. The brand embodies 'Technical Minimalism'—a philosophy that strips away decorative elements to expose pure functional design, where every pixel serves the developer's intent. The aesthetic is intentionally austere: pure black (#000000) backgrounds, high-contrast light text (#ededed), and surgical accent colors (hot pink #ffb1ee, electric cyan #00c4cc, warm gold #f5a623) that punctuate CTAs and interactive states. The UI evokes the precision of a terminal interface merged with modern component design, creating an environment where complex email logic feels approachable and modular.

The brand voice is direct, technical, and unapologetically developer-focused. Sentences are short, imperative, and action-oriented: 'Explore components. Build faster. Ship production-ready emails.' The vocabulary favors concrete terms (component, template, props, render) over marketing abstractions. Personality is confident without being arrogant—the system assumes the user is competent and values their time. Example sentence in brand voice: 'React Email gives you the component primitives; you control the output.'

Colors

The color system is built on a high-contrast dark foundation optimized for sustained developer focus and accessibility. Surface (#000000) and surface-container (#1a1a1a) form the base, with a carefully calibrated gray stack (surface-container-low #111111 through surface-container-highest #2e2e2e) providing subtle depth without visual noise. On-surface (#ededed) ensures WCAG AAA contrast (ratio 15.8:1) for body text, while on-surface-variant (#878787) is reserved for secondary information and disabled states.

Primary (#ffb1ee) is the brand's signature accent—a hot pink deployed exclusively on primary CTAs, active navigation states, and focus indicators. It appears in the 'Request private DESIGN.md' button and all interactive highlights, creating visual urgency without aggression. Secondary

Typography

The type system balances technical precision with readability through a dual-font strategy. Display and headline levels use GeistPixel-Square (a monospace pixel font) at 56px and 32px respectively, reinforcing the developer-tool aesthetic and creating visual hierarchy through geometric form rather than weight variation. Body text (Geist, 16px–18px, 400 weight, 24–28px line-height) prioritizes legibility at sustained reading distances, with generous line-height (1.5) to reduce eye strain during long coding sessions. Labels and UI text use Geist at 12–14px with letter-spacing of 0.01–0.05em to enhance scannability in dense component lists. Monospace (Geist Mono) is reserved for code snippets and technical metadata. Font weights are minimal: 400 for body, 500–600 for labels and buttons. Apply

Layout

The layout system uses a 12-column grid with a 1280px max-width container, centered on screens ≥2200px. Horizontal padding is 24px on desktop (lg breakpoint 64px+) and 16px on mobile, creating breathing room without excessive margins. Vertical rhythm is governed by the spacing scale: section separation uses lg spacing (40px), component internal padding uses md spacing (24px), and element-to-element gaps use sm spacing (12px). The gutter (24px) is applied consistently between grid columns and major content blocks. White-space is aggressive—empty space is treated as a design material, not wasted real estate. Cards and containers use 24px internal padding (md) with 12px gaps between child elements. The sticky header (height 68px) uses 12px backdrop blur and rgba(0, 0, 0, 0.85) background to m

Elevation & Depth

Depth is conveyed through a restrained shadow and backdrop-filter system that avoids the 'floating card' cliché. Level 1 (Base): no shadow; surface is the ground truth. Level 2 (Standard Card): box-shadow 0 4px 12px rgba(0, 0, 0, 0.4) with 1px solid border at {colors.outline} (#2e2e2e). Level 3 (Elevated/Modal): box-shadow 0 16px 40px rgba(0, 0, 0, 0.5) with backdrop-filter blur(12px) and rgba(0, 0, 0, 0.85) background. The header uses backdrop-filter blur(12px) with -webkit-backdrop-filter for cross-browser support, creating a frosted-glass effect that separates navigation from content withou

Shapes

The shape philosophy is 'Functional Geometry'—rounded corners are applied with surgical precision to guide visual flow without introducing softness. Buttons and interactive elements use rounded-md (0.75rem / 12px) to signal clickability while maintaining a technical edge. Cards and containers use rounded-lg (1rem / 16px) to create subtle visual separation. Input fields use rounded-DEFAULT (0.5rem / 8px) for a compact, utilitarian appearance. Badges and pills use rounded-full (9999px) to emphasize their role as discrete, self-contained labels. The header and modals use rounded-lg (1rem) at corn

Components

Action Elements Buttons are the primary interaction primitive. Button-primary uses {colors.primary} (#ffb1ee) background with {colors.on-primary} (#1a0a16) text, 16px padding horizontal, 44px height, and rounded-md (12px). On hover, shift background to #e89fd9 (primary-fixed-dim) with a 150ms cubic-bezier(0.4, 0, 0.2, 1) transition. Button-secondary is transparent with a 1px border at {colors.outline} (#2e2e2e), text color {colors.on-surface} (#ededed), and on hover shifts background to {colors.surface-container-high} (#292929) and text to {colors.primary}. Button-accent uses {colors.tertiary} (#f5a623) for promotional CTAs (e.g., 'Request a DESIGN.md analysis'); on hover, shift to #d98a1a. All buttons must have a minimum touch target of 44px height and 48px width. Apply focus-ring: 0

Do's and Don'ts

**Do**

• Do use {colors.primary} (#ffb1ee) exclusively for primary CTAs and active states; it's the brand's signature accent and must never be diluted or overused.
• Do maintain minimum 44px height and 48px width for all interactive elements to ensure touch accessibility on mobile devices.
• Do apply backdrop-filter blur(12px) on sticky headers and modals to create visual separation without hard borders; always include -webkit-backdrop-filter for Safari support.
• Do use GeistPixel-Square for display and headline levels to reinforce the developer-tool aesthetic; reserve Geist for body and UI text.
• Do apply box-shadow 0 4px 12px rgba(0, 0, 0, 0.4) on cards and elevated surfaces; avoid drop-shadows on text.
• Do use cubic-bezier(0.4, 0, 0.2, 1) timing function for all transitions; keep duration at 150ms for UI interactions and 300ms for page-level animations.

**Don't**

• Don't use rounded-xl (1.5rem) or rounded-full on buttons or standard containers; reserve full rounding for badges and pills only.
• Don't apply text-shadow on body text or large headlines; use it sparingly (0 1px 2px rgba(0, 0, 0, 0.3)) only on small labels over busy backgrounds.
• Don't mix accent colors within a single CTA; if using {colors.tertiary} (#f5a623) for a button, don't add {colors.secondary} (#00c4cc) as a border or icon.
• Don't use opacity below 0.5 for interactive elements; low opacity signals disabled state, not visual hierarchy.
• Don't exceed 24px padding (md) on standard cards; excessive padding dilutes the technical aesthetic and wastes screen real estate.
• Don't apply box-shadow to more than one elevation level simultaneously; use either shadow OR backdrop-filter, not both, to maintain visual clarity.