@vx-oss/heroui-v3-styles
v3.0.0-beta.7
Published
HeroUI core styles and Tailwind plugin
Readme
@vx-oss/heroui-v3-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.
Installation
npm install @vx-oss/heroui-v3-styles
# or
pnpm add @vx-oss/heroui-v3-styles
# or
yarn add @vx-oss/heroui-v3-stylesUsage
Basic Setup
Import the HeroUI styles in your main CSS file:
@import "@vx-oss/heroui-v3-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:
@vx-oss/heroui-v3-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.cssImporting Specific Components
Instead of importing everything, you can import only what you need:
/* Import Tailwind CSS base */
@import "tailwindcss";
/* Import only specific components */
@import "@vx-oss/heroui-v3-styles/components/button.css" layer(components);
@import "@vx-oss/heroui-v3-styles/components/chip.css" layer(components);
/* Import theme */
@import "@vx-oss/heroui-v3-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
<!-- 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
.darkclass or[data-theme="dark"]attribute
<!-- 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
: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
: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
: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-xsthrough--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 fileheroui.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 @vx-oss/heroui-v3-react which builds on top of these core styles.
License
MIT