wehub-resource-sync
266 lines
7.4 KiB
Markdown
266 lines
7.4 KiB
Markdown
# @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
|
|
<!-- Basic button -->
|
|
<button class="button">Click me</button>
|
|
|
|
<!-- Primary variant -->
|
|
<button class="button button--primary">Save</button>
|
|
|
|
<!-- Small size -->
|
|
<button class="button button--sm">Small</button>
|
|
|
|
<!-- Icon-only button -->
|
|
<button class="button button--icon-only">
|
|
<svg>...</svg>
|
|
</button>
|
|
|
|
<!-- Combining classes -->
|
|
<button class="button button--primary button--sm">Small Primary</button>
|
|
```
|
|
|
|
### 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
|
|
<!-- Dark mode with class -->
|
|
<html class="dark">
|
|
<!-- Dark mode with data attribute -->
|
|
<html data-theme="dark"></html>
|
|
</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
|