HeroUI v3

Overview

HeroUI v3 is a production-ready React component library built on React Aria and Tailwind CSS v4, designed for teams building accessible, scalable applications. The brand embodies "Accessible Minimalism"—a design philosophy that prioritizes clarity and usability without sacrificing visual refinement. The aesthetic is clean, intentional, and token-driven: every color, radius, and spacing value is customizable through a unified theming system, enabling rapid brand adaptation while maintaining consistency across all components. The UI evokes trust and professionalism through precise typography (Inter at 16px base, 14px labels), subtle shadows (0 4px 12px rgba(0,0,0,0.08) for elevated surfaces), and a neutral surface palette anchored by pure white (#ffffff) and near-black text (#1a1a1a). Voice: direct, technical, and empowering. Example: "Customize colors, radius, and typography using a token system that keeps every component consistent and production-ready."

Colors

HeroUI's color system is built on a semantic, light-first foundation with full dark-mode support via oklch() color space. Primary (#0066ff) is the signature accent—used exclusively on primary CTAs, focus states, and brand-critical interactions. It commands attention without aggression, sitting at 54.5% lightness in oklch space. Secondary (#fe6e00, a vibrant orange) provides energetic contrast for secondary actions and highlights, while tertiary (#00bb7f, emerald green) signals success states and positive feedback. The surface stack progresses from pure white (surface: #ffffff) through carefully calibrated grays (surface-container-low: #f5f5f5, surface-container: #f0f0f0, surface-container-high: #ebebeb) to enable subtle layering without visual noise. Error (#fb2c36) is reserved for destruc

Typography

The type system uses Inter exclusively across all weights (400, 500, 600, 700), scaled from 12px labels to 60px display headlines. Display (60px, 700 weight, -0.04em letter-spacing) is reserved for hero statements and major page titles, commanding visual hierarchy through size and negative letter-spacing that tightens the letterforms. Headline-lg (40px, 600 weight, -0.02em) anchors section headings and modal titles, while headline-md (28px, 600 weight) serves subsections. Body-lg (18px, 400 weight) is used for introductory paragraphs and prominent descriptions; body-md (16px, 400 weight) is the default paragraph text and input field content. Label-md (14px, 500 weight, 0.01em letter-spacing) is applied to button text, form labels, and UI microcopy; label-sm (12px, 500 weight, 0.02em letter

Layout

HeroUI uses a 12-column fluid grid with a max-width of 1280px, centered with symmetric gutters of 24px on desktop and 16px on mobile. The spacing scale is semantic: unit (8px) is the base increment, with xs (4px) for micro-spacing, sm (12px) for compact grouping, md (24px) for standard section separation, lg (40px) for major section breaks, and xl (64px) for page-level spacing. Container padding follows the gutter value (24px) to maintain visual rhythm. White-space is generous but purposeful—cards and modals use md (24px) padding internally, while section separators use lg (40px) vertical spacing. The layout philosophy prioritizes breathing room: avoid stacking elements closer than sm (12px) unless they form a tight logical group (e.g., label + input field at 8px). Responsive breakpoints a

Elevation & Depth

Depth is conveyed through a three-tier shadow system that avoids excessive blur or spread. Level 1 (sm: 0 1px 2px rgba(0,0,0,0.06)) is applied to subtle interactive elements like hover states on list items and secondary cards—barely perceptible but present. Level 2 (md: 0 4px 12px rgba(0,0,0,0.08)) is the standard for elevated surfaces: cards, input fields, and dropdown panels. Level 3 (lg: 0 16px 40px rgba(0,0,0,0.12)) is reserved for modals, popovers, and top-level overlays that demand visual separation. All shadows use a 0-offset vertical blur to simulate light from above, with opacity valu

Shapes

HeroUI employs "Precise Softness"—a shape philosophy that balances technical clarity with approachability through carefully calibrated border-radius values. Buttons and chips use lg (1rem / 16px) radius, creating a distinctly rounded but not pill-shaped appearance that feels modern and friendly. Cards and modals use xl (1.5rem / 24px) radius for a softer, more inviting container aesthetic. Input fields and smaller interactive elements use DEFAULT (0.5rem / 8px) radius, maintaining visual distinction from larger surfaces. Badges and tags use full (9999px) radius for a true pill shape, signaling

Components

Action Elements Buttons are the primary interaction pattern, with three variants: primary (background: #0066ff, text: white, height: 40px, padding: 0 16px, radius: 1rem), secondary (background: #fe6e00, text: white, same dimensions), and ghost (background: transparent, border: 1px solid #c0c0c0, text: #0066ff). All buttons use label-md typography (14px, 500 weight) and transition background-color over 150ms cubic-bezier(0.4, 0, 0.2, 1) on hover. Primary buttons darken to #0052cc on hover, secondary to #e55c00, and ghost to surface-container (#f0f0f0). Disabled buttons reduce opacity to 0.5 and set cursor: not-allowed. Chips and badges are compact action elements: chips (height: 32px, padding: 6px 16px, radius: full) are selectable toggles with border: 1px solid outline-variant; badges

Do's and Don'ts

**Do**

• Do use primary (#0066ff) exclusively for high-emphasis CTAs and focus states—never for secondary UI or decorative elements.
• Do maintain consistent spacing using the semantic scale (sm: 12px for grouping, md: 24px for sections, lg: 40px for major breaks).
• Do apply transitions over 150–200ms using cubic-bezier(0.4, 0, 0.2, 1) for all interactive state changes (hover, focus, active).
• Do use the three-tier shadow system (sm, md, lg) to convey depth; never stack multiple shadows or use custom blur values.
• Do ensure all interactive elements have a visible focus state (border color, ring, or background change) for keyboard accessibility.
• Do use Inter at 400 weight for body text, 500 for labels, and 600+ for headlines—never mix weights within a single text element.
• Do apply label-sm (12px) with text-shadow 0 2px 4px rgba(0,0,0,0.08) when placing text over busy backgrounds.

**Don't**

• Don't use secondary (#fe6e00) or tertiary (#00bb7f) for primary CTAs—reserve them for secondary actions and status messaging.
• Don't apply border-radius values inconsistently within a component family (e.g., all buttons must share the same radius).
• Don't create custom shadows; use only the three defined levels (sm, md, lg) with their exact blur and opacity values.
• Don't exceed 1280px container width or use gutters smaller than 16px on mobile—maintain readability and touch targets.
• Don't mix oklch() and hex color values in the same component; use hex for consistency with the token system.
• Don't apply transitions longer than 300ms or use easing functions other than cubic-bezier(0.4, 0, 0.2, 1) for UI interactions.
• Don't omit focus states or rely on color alone to indicate interactivity—always include a visible border, ring, or background change.