```
**Mapping:**
| v2 Class | Width | v3 Class | Width |
|----------|-------|----------|-------|
| `border-small` | 1px | `border` | 1px |
| `border-medium` | 2px | `border-2` | 2px |
| `border-large` | 3px | `border-[3px]` | 3px (arbitrary) |
### Transition Utilities
v2 provided custom transition utilities for common animation patterns with a default duration of 250ms. v3 removes these utilities in favor of standard Tailwind `transition-*` utilities, where you specify which properties to transition.
**v2 Transition Utilities:**
v2 provided custom transition utilities with a default duration of 250ms and `ease` timing function. The following table shows which CSS properties each utility transitions:
| v2 Utility | Transition Properties |
|-----------|----------------------|
| `.transition-background` | `background` |
| `.transition-colors-opacity` | `color, background-color, border-color, text-decoration-color, fill, stroke, opacity` |
| `.transition-width` | `width` |
| `.transition-height` | `height` |
| `.transition-size` | `width, height` |
| `.transition-left` | `left` |
| `.transition-transform-opacity` | `transform, scale, opacity rotate` |
| `.transition-transform-background` | `transform, scale, background` |
| `.transition-transform-colors` | `transform, scale, color, background, background-color, border-color, text-decoration-color, fill, stroke` |
| `.transition-transform-colors-opacity` | `transform, scale, color, background, background-color, border-color, text-decoration-color, fill, stroke, opacity` |
**Note:** These utilities are no longer available in v3. Use Tailwind's standard `transition-*` utilities to specify which properties to transition.
### Other Utilities
**Scrollbar Utilities:**
v2 provided `.scrollbar-hide` and `.scrollbar-default` utilities. These are not included in v3 by default, but you can use Tailwind's scrollbar plugin or custom CSS.
**Animation Utilities:**
v2 provided spinner animation utilities (`.spinner-bar-animation`, `.spinner-dot-animation`, etc.). These are handled internally by v3 components and are not exposed as utilities.
**Custom Utilities:**
v2 included utilities like:
- `.leading-inherit` → Use `leading-[inherit]`
- `.tap-highlight-transparent` → Use `[-webkit-tap-highlight-color:transparent]`
- `.input-search-cancel-button-none` → Use custom CSS if needed
## Theme System Architecture
### v2: Plugin-Based System
v2 used a Tailwind CSS plugin that:
1. **Generated Utilities**: Created custom utility classes via JavaScript
2. **CSS Variables**: Injected CSS variables through the plugin
3. **Theme Configuration**: Required configuration in `tailwind.config.js`
4. **Runtime Generation**: Utilities generated at build time
**v2 Configuration:**
```js
// tailwind.config.js
const {heroui} = require("@heroui/react");
module.exports = {
plugins: [
heroui({
layout: {
fontSize: {
tiny: "0.75rem",
small: "0.875rem",
medium: "1rem",
large: "1.125rem",
},
radius: {
small: "8px",
medium: "12px",
large: "14px",
},
},
themes: {
light: {
colors: {
primary: {
// color definitions
},
},
},
},
}),
],
};
```
### v3: CSS-First System
v3 uses a pure CSS approach:
1. **CSS Files**: Styles defined in CSS files (`packages/styles/`)
2. **CSS Variables**: Variables defined in CSS, not generated
3. **No Plugin**: No Tailwind plugin required
4. **Import-Based**: Styles imported via CSS imports
**v3 Configuration:**
```css
/* globals.css */
@import "tailwindcss";
@import "@heroui/styles";
```
**No Tailwind Config Required:**
If you only use HeroUI, you can remove `tailwind.config.js` entirely. If you have custom Tailwind config, keep it but remove the HeroUI plugin.
### Architecture Comparison
| Aspect | v2 | v3 |
|--------|----|----|
| **Styling Method** | Tailwind plugin (JavaScript) | CSS files |
| **Utility Generation** | Runtime via plugin | Pre-defined CSS |
| **CSS Variables** | Generated by plugin | Defined in CSS |
| **Configuration** | `tailwind.config.js` | CSS imports |
| **Customization** | Plugin config | CSS variable overrides |
| **Build Dependency** | Requires plugin | No plugin needed |
## CSS Variables & Design Tokens
### Variable Naming Changes
v2 used the pattern `--heroui-{property}-{scale}` while v3 uses `--{property}` or `--color-{property}`.
**v2 CSS Variables:**
```css
--heroui-font-size-tiny: 0.75rem;
--heroui-font-size-small: 0.875rem;
--heroui-radius-small: 8px;
--heroui-radius-medium: 12px;
--heroui-border-width-medium: 2px;
--heroui-disabled-opacity: 0.5;
```
**v3 CSS Variables:**
```css
/* Typography - handled by Tailwind */
/* No custom font-size variables */
/* Radius */
--radius-xs: calc(var(--radius) * 0.25);
--radius-sm: calc(var(--radius) * 0.5);
--radius-md: calc(var(--radius) * 0.75);
--radius-lg: calc(var(--radius) * 1);
--radius-xl: calc(var(--radius) * 1.5);
/* Colors */
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-accent: var(--accent);
--color-muted: var(--muted);
/* Opacity */
--disabled-opacity: 0.5;
```
### Color System Changes
**v2 Color Structure:**
```css
--heroui-primary: 210 100% 50%;
--heroui-primary-50: 210 100% 95%;
--heroui-primary-100: 210 100% 90%;
/* ... more shades ... */
```
**v3 Color Structure:**
```css
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
--accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);
```
**Key Differences:**
1. **Color Format**: v2 used HSL, v3 uses OKLCH
2. **Naming**: v2 used numbered shades (50-900), v3 uses semantic names
3. **Calculated Colors**: v3 uses `color-mix()` for hover states
4. **Foreground Colors**: v3 explicitly defines foreground colors
5. **Primary → Accent**: `primary` color renamed to `accent`
6. **Secondary Color Removed**: `secondary` semantic color removed (was purple in v2)
7. **Numbered Scales Removed**: Color scales like `primary-50`, `primary-100`, etc. no longer exist
### Primary → Accent Rename
v2 used `primary` as the main brand color. v3 renamed it to `accent` for better semantic clarity.
**v2 Primary Color:**
```tsx
// v2 - Primary color with numbered scales
Primary background
Light primary
Lighter primary
Primary text
```
**v3 Accent Color:**
```tsx
// v3 - Accent color (no numbered scales)
Accent background
Soft accent
Accent text
```
**Migration:**
| v2 Class | v3 Equivalent | Notes |
|----------|---------------|-------|
| `bg-primary` | `bg-accent` | Base accent color |
| `text-primary` | `text-accent` | Accent text color |
| `bg-primary-50` | `bg-accent-soft` | Light accent variant |
| `bg-primary-100` | `bg-accent-soft` | Light accent variant |
| `bg-primary-500` | `bg-accent` | Base accent color |
| `text-primary-600` | `text-accent` | Accent text color |
| `border-primary` | `border-accent` | Accent border |
**Note:** v3 doesn't have numbered color scales (`-50`, `-100`, `-200`, etc.). Use semantic variants like `-soft`, `-hover`, or custom Tailwind classes.
### Secondary Color Removed
v2 provided a `secondary` semantic color (purple). This has been removed in v3. Component variants named "secondary" now use different colors.
**v2 Secondary Color:**
```tsx
// v2 - Secondary as a semantic color (purple)
Secondary background
Light secondary
Secondary text
```
**v3 Secondary Variant:**
```tsx
// v3 - Secondary is a variant, not a color
Default background (used by secondary variant)
Accent text
```
**Migration:**
| v2 Class | v3 Equivalent | Notes |
|----------|---------------|-------|
| `bg-secondary` | `bg-default` | Secondary variant uses default color |
| `text-secondary` | `text-accent` | Use accent for emphasis |
| `bg-secondary-50` | `bg-default` | Use default color |
| `border-secondary` | `border-accent` | Use accent border |
**Note:** In v3, "secondary" refers to a component variant style (like `button--secondary`), not a color token. The secondary variant typically uses `bg-default` and `text-accent`.
### Numbered Color Scales Removed
v2 provided numbered color scales (50-900) for all semantic colors. v3 removed these in favor of semantic variants and calculated colors.
**v2 Numbered Scales:**
```tsx
// v2 - Numbered color scales
```
**Migration:**
- **Light shades** (`-50`, `-100`, `-200`): Use `-soft` variants or custom Tailwind opacity classes
- **Base color** (`-500`): Use base color name (`bg-accent`, `bg-danger`, etc.)
- **Dark shades** (`-600`, `-700`, `-800`, `-900`): Use hover variants or custom Tailwind classes
### Content Colors Removed
v2 provided `content1`, `content2`, `content3`, and `content4` colors for layered backgrounds. These have been removed in v3 and replaced with semantic surface colors.
**v2 Content Colors:**
```tsx
// v2 - Content colors for layered backgrounds