Better Auth

Overview

Better Auth is a developer-centric authentication framework that prioritizes clarity, precision, and technical accessibility. The design system embodies a "Functional Minimalism" aesthetic—one that strips away ornament in favor of pure information hierarchy, using a neutral grayscale palette anchored by deep black (#0a0a0a) and pure white (#ffffff) to create maximum contrast and readability. The UI speaks to developers through clean typography, generous whitespace, and a grid-based layout that feels both structured and approachable. The brand personality is direct, unambiguous, and respectful of the user's time: every pixel serves a function, every color choice communicates intent. Example sentence in voice: "Install the 2FA plugin, configure your schema, and ship secure authentication in minutes."

Colors

The color system is built on a neutral foundation with strategic accent deployment. Primary (#0a0a0a) is the deep black used for primary CTAs, navigation, and text hierarchy—it commands attention without aggression. On-primary (#ffffff) ensures maximum contrast (WCAG AAA) for accessibility. The surface stack ranges from pure white (#ffffff) at the brightest to #e0e0e0 at the container-highest level, providing subtle visual separation without introducing color noise. On-surface (#090909) and on-surface-variant (#6a6a6a) establish the text hierarchy: primary content uses #090909 at 16px body-md weight, secondary content uses #6a6a6a at the same size. Tertiary (#0066cc) is reserved for interactive elements like links and secondary CTAs—a technical blue that signals interactivity without compe

Typography

The type system uses Geist as the primary typeface—a geometric sans-serif that balances technical precision with approachability. Display (56px, 700 weight, -0.02em tracking) anchors hero sections and major page titles; headline-lg (32px, 600 weight) is used for section headings and prominent content blocks. Body-md (16px, 400 weight) is the baseline for all body copy and maintains 24px line-height for comfortable reading. Label-md (14px, 500 weight, 0.02em tracking) is applied to buttons, form labels, and UI chrome. On small labels over busy backgrounds or code blocks, apply text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1) to ensure legibility. Headlines use -0.01em to -0.02em letter-spacing to create visual compression and authority; body text uses 0em tracking to maintain neutrality. All inter

Layout

The page layout uses a 12-column grid with a max-width of 1280px, centered on the viewport. The gutter is 24px between columns, providing breathing room without excessive whitespace. The left sidebar navigation occupies 280px (fixed width) on desktop, collapsing to a hamburger menu below 768px. Main content area uses 8–12 columns depending on context: full-width for hero sections, 8 columns for documentation prose, 6 columns for narrow forms. Vertical rhythm is maintained through the spacing scale: lg (40px) separates major sections, md (24px) separates subsections and card groups, sm (12px) separates list items and inline elements. Container-max-width (1280px) prevents line lengths from exceeding 75–80 characters, maintaining readability. Padding inside cards and containers uses md (24px)

Elevation & Depth

Depth is conveyed through subtle shadows and border treatments rather than color shifts. Level 1 (Base): flat surfaces with no shadow, using 1px solid borders at outline-variant (#c4c4c4) to define edges. Level 2 (Cards, Modals): box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08) with 1px solid outline (#8e8e8e) border, creating a soft lift. Level 3 (Dropdowns, Popovers): box-shadow: 0 16px 40px rgba(0, 0, 0, 0.12) with 1px solid outline border, reserved for overlays that must float above all content. On hover, cards transition from Level 1 to Level 2 over 200ms ease. Focus states use a 3px inset box-

Shapes

The shape philosophy is "Technical Precision"—minimal rounding that signals modernity without sacrificing clarity. Buttons and form inputs use rounded: DEFAULT (0.5rem / 8px) for a subtle, professional appearance. Cards and larger containers use rounded: md (0.75rem / 12px) to create visual softness while maintaining structure. Modals and overlays use rounded: lg (1rem / 16px) to emphasize their floating nature. The full (9999px) radius is reserved for badges and pill-shaped elements. Avoid rounded: sm (4px) in new components—it reads as dated. The rationale: 8px rounding feels contemporary an

Components

Action Elements Buttons use a consistent 40px height with 10px vertical / 16px horizontal padding. Primary buttons (#0a0a0a background, white text) are the default CTA; secondary buttons (transparent background, black text, 1px outline) are for alternative actions. On hover, primary buttons transition to primary-container (#2a2a2a) over 150ms ease; secondary buttons shift to surface-container-high (#e8e8e8). Active/pressed state uses #000000 (pure black) for maximum contrast. Ghost buttons (no background, no border) are used for tertiary actions and navigation links; they shift to surface-container-low (#f5f5f5) on hover. All buttons use label-md typography (14px, 500 weight) and rounded: DEFAULT (8px).

Containers & Surfaces Cards are the primary container for grouped content. Bas

Do's and Don'ts

**Do**

• Do use primary (#0a0a0a) for primary CTAs and main navigation—it commands attention and ensures WCAG AAA contrast.
• Do maintain 24px line-height on body text (16px) for comfortable reading; never compress below 1.5x font size.
• Do apply box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08) to cards and containers to create subtle depth without visual noise.
• Do use label-md (14px, 500 weight) for all button text and form labels to signal interactivity.
• Do reserve tertiary (#0066cc) for links and secondary interactive elements; never use it for primary CTAs.
• Do apply 150ms ease transitions to hover states on buttons and interactive elements for smooth, responsive feedback.

**Don't**

• Don't use colors outside the defined palette—the system is intentionally constrained to prevent visual chaos.
• Don't apply shadows to text, small icons, or elements smaller than 120px × 120px; shadows are for containers only.
• Don't mix rounded radii inconsistently (e.g., 4px on buttons and 12px on cards in the same section); use 8px for buttons, 12px for cards.
• Don't use primary-container (#2a2a2a) for large background surfaces; it's reserved for hover states and secondary navigation.
• Don't compress line-height below 1.4x font size; readability suffers and accessibility scores drop.
• Don't apply focus states with outline: 2px solid; use inset box-shadow: 0 0 0 3px rgba(10, 10, 10, 0.08) instead for better visual clarity.