# @heroui/styles
The core HeroUI styles package containing CSS files for components, themes, and utilities. This package provides the foundation for HeroUI's design system using Tailwind CSS v4 and is framework-agnostic.
## Documentation
It's the [heroui.com](https://heroui.com) website for the latest version of HeroUI.
- **Latest (v3)**: [https://heroui.com](https://heroui.com)
- **v2**: [https://v2.heroui.com](https://v2.heroui.com)
## Installation
```bash
npm install @heroui/styles
# or
pnpm add @heroui/styles
# or
yarn add @heroui/styles
```
## Usage
### Basic Setup
Import the HeroUI styles in your main CSS file:
```css
@import "@heroui/styles";
```
This will import:
- Tailwind CSS base styles
- HeroUI component styles
- HeroUI utilities
- Default theme variables
- Animation utilities from tw-animate-css
### Package Structure
The package exports CSS files organized into:
```
@heroui/styles/
├── index.css # Main entry point
├── base/ # Base styles and CSS variables
│ └── base.css # Layout tokens, typography, scrollbar
├── components/ # Component-specific styles
│ ├── accordion.css
│ ├── avatar.css
│ ├── button.css
│ ├── chip.css
│ ├── link.css
│ ├── popover.css
│ └── tooltip.css
├── themes/ # Theme definitions
│ ├── default/ # Default theme
│ │ ├── index.css # Theme entry point
│ │ └── variables.css # Theme variables (light/dark)
│ └── shared/ # Shared theme utilities
│ └── theme.css # Calculated variables and utilities
└── utilities/ # Utility classes
├── backdrop.css
└── index.css
```
### Importing Specific Components
Instead of importing everything, you can import only what you need:
```css
/* Import Tailwind CSS base */
@import "tailwindcss";
/* Import only specific components */
@import "@heroui/styles/components/button.css" layer(components);
@import "@heroui/styles/components/chip.css" layer(components);
/* Import theme */
@import "@heroui/styles/themes/default" layer(base);
```
### Component Classes
Components use a BEM-like naming convention:
- Base: `.button`
- Variants: `.button--primary`, `.button--danger`
- Sizes: `.button--sm`, `.button--lg`
- Modifiers: `.button--icon-only`
#### Button Example
```html
```
### Themes
The default theme provides automatic light/dark mode support:
- **Light mode**: Applied by default to `:root`
- **Dark mode**: Applied with `.dark` class or `[data-theme="dark"]` attribute
```html
```
### CSS Variables
The package provides a comprehensive set of CSS variables for customization:
#### Layout Tokens
```css
:root {
/* Spacing */
--spacing: 0.25rem;
/* Border */
--border-width: 0px; /* no border by default */
--field-border-width: var(--border-width);
--disabled-opacity: 0.5;
/* Radius */
--radius: 0.5rem;
--field-radius: calc(var(--radius) * 1.5);
/* Ring offset - Used for focus ring */
--ring-offset-width: 2px;
/* Cursor */
--cursor-interactive: pointer;
--cursor-disabled: not-allowed;
}
```
#### Theme Colors
```css
:root {
/* Primitive Colors (Do not change between light and dark) */
--white: oklch(100% 0 0);
--black: oklch(0% 0 0);
--snow: oklch(0.9911 0 0);
--eclipse: oklch(0.2103 0.0059 285.89);
/* Base Colors */
--background: oklch(0.9702 0 0);
--foreground: var(--eclipse);
/* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
--surface: var(--white);
--surface-foreground: var(--foreground);
/* Overlay: Used for floating/overlay components (tooltips, popovers, modals, menus) */
--overlay: var(--white);
--overlay-foreground: var(--foreground);
--muted: oklch(0.5517 0.0138 285.94);
--scrollbar: oklch(87.1% 0.006 286.286);
--default: oklch(94% 0.001 286.375);
--default-foreground: var(--eclipse);
/* Interactive Colors */
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
/* Status Colors */
--success: oklch(0.7329 0.1935 150.81);
--success-foreground: var(--eclipse);
--warning: oklch(0.7819 0.1585 72.33);
--warning-foreground: var(--eclipse);
--danger: oklch(0.6532 0.2328 25.74);
--danger-foreground: var(--snow);
/* Component Colors */
--segment: var(--white);
--segment-foreground: var(--eclipse);
/* UI Colors */
--border: oklch(0 0 0 / 0%);
--separator: oklch(92% 0.004 286.32);
--focus: var(--accent);
--link: var(--foreground);
/* Shadows */
--surface-shadow:
0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
--overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
--field-shadow:
0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
}
```
**Note**: Dark mode overrides specific variables (like `--background`, `--surface`, `--overlay`, `--muted`, `--scrollbar`, `--default`, `--warning`, `--danger`, `--segment`, `--separator`, and shadow values) when `.dark` class or `[data-theme="dark"]` attribute is applied.
#### Field Tokens
```css
:root {
/* Form field defaults */
--field-background: var(--white);
--field-foreground: oklch(0.2103 0.0059 285.89);
--field-placeholder: var(--muted);
--field-border: transparent; /* no border by default on form fields */
--field-border-width: var(--border-width);
--field-radius: calc(var(--radius) * 1.5);
}
```
Providing any of these knobs automatically updates the generated utilities (`bg-field`, `placeholder:text-field-placeholder`, `rounded-field`, etc.) along with the calculated hover/focus variants.
#### Calculated Variables
The theme also provides calculated variables for hover states, soft colors, and surface levels (defined in `themes/shared/theme.css`):
- **Hover states**: `--color-accent-hover`, `--color-success-hover`, `--color-warning-hover`, `--color-danger-hover`, `--color-default-hover`
- **Soft colors**: `--color-accent-soft`, `--color-danger-soft`, `--color-warning-soft`, `--color-success-soft` (with their foreground and hover variants)
- **Surface levels**: `--color-surface-secondary`, `--color-surface-tertiary`
- **Radius scale**: `--radius-xs` through `--radius-4xl` (calculated from `--radius`)
- **Transition timing functions**: Various easing curves like `--ease-smooth`, `--ease-out-fuild`, etc.
## Dependencies
- **Tailwind CSS v4+**: Required peer dependency
- **tw-animate-css**: Provides animation utilities
## Build Output
The package provides:
- `index.css`: Main unminified CSS file
- `heroui.min.css`: Minified production-ready CSS (generated during build)
## Framework Integration
This package is designed to work with any framework. For React-specific components, use `@heroui/react` which builds on top of these core styles.
## License
MIT