Theming with Agents

Let coding agents customize HeroUI globally and author complete themes with CSS

The heroui-theming skill teaches your coding agent to restyle HeroUI across your whole app, or to build a complete light and dark theme from a description of the look you want.

Prefer a visual tool? The Theme Builder lets you tune colors, radius, and fonts by hand and export the CSS. Use an agent when you want to go further: reshaped components, new variants, or a full visual identity.

Why It Works

HeroUI keeps its look and its behavior in separate packages. @heroui/react handles behavior and accessibility; everything visual lives in @heroui/styles as plain CSS:

  • Theme tokens: CSS variables such as --accent, --radius, and --surface-shadow
  • Component classes: readable BEM names such as .button, .button--primary, and .card__header
  • Cascade layers: theme, base, components, utilities, so overrides land in a predictable place

An agent can read that CSS from your node_modules, see exactly which tokens and selectors exist, and change them globally. There are no component wrappers to write, nothing to fork, and no JavaScript to touch. Because it is only CSS, the same theme also works on plain HTML and other frameworks.

Install the Skill

curl -fsSL https://heroui.com/install | bash -s heroui-theming

To install it for a single project, run this from the project root:

curl -fsSL https://heroui.com/install | HEROUI_SKILL_SCOPE=project bash -s heroui-theming

Your agent discovers the skill automatically, or you can call it with /heroui-theming. See Agent Skills for supported tools and the heroui-react skill, which covers building UIs with the components.

Prompts to Try

Customize globally

Globally make all HeroUI buttons uppercase with wider letter spacing, and give every card a 1px border. Keep hover, pressed, focus, and disabled states working in light and dark mode.
Change the HeroUI brand color to a deep violet, make everything less rounded, and flatten the shadows. Use theme tokens only.
Add a "brand" button variant with a green background that I can use next to the existing variants.

Create a theme

Create a HeroUI theme called "arcade": chunky and playful, thick dark outlines, hard offset shadows instead of soft ones, saturated candy colors, and buttons that press down like keys. Include light and dark variants.
Create a HeroUI theme called "ledger" for a finance dashboard: calm, dense, low contrast surfaces, hairline borders, almost no shadows, a single navy accent. Light and dark.
Give our theme a tactile feel: everything that is on (primary buttons, checked switches, slider fills, selected days) looks raised and lit from above, and secondary buttons press in. Keep our current colors, in light and dark.
We use the "<preset>" theme. Keep how its controls look, but switch it to our palette: neutral grays instead of its tint, #6466E9 as the accent, 8px corners.

The more you say about the feel (shape, depth, color, motion), the better the result. Screenshots and brand guidelines work as input too.

Without React

Style this plain HTML page with HeroUI's CSS from the CDN. Use the button, card, input, and switch classes, and theme it with our brand color.

What the Agent Produces

Small changes go straight into your main CSS file, after the HeroUI import:

app/globals.css
@import "tailwindcss";
@import "@heroui/styles";

@layer theme {
  :root {
    --accent: oklch(0.55 0.2 300);
    --radius: 0.375rem;
  }
}

@layer components {
  .button {
    @apply font-semibold tracking-wide uppercase;
  }
}

A named theme becomes a folder with one fixed structure:

src/themes/arcade/
├── index.css             # Imports the two parts into the right layers
├── variables.css         # Light and dark tokens
└── components/
    ├── index.css         # Imports each override file
    ├── button.css        # One file per restyled component
    ├── card.css
    └── switch.css

Themes can also define their own tokens, prefixed with the theme name (--arcade-outline, --arcade-depth), and reuse them across component files.

Apply the Theme

Import the theme after HeroUI:

app/globals.css
@import "tailwindcss";
@import "@heroui/styles";
@import "../themes/arcade/index.css";

Then activate it on the <html> element:

<html data-theme="arcade-light">
  <body class="bg-background text-foreground">
    <!-- Your app -->
  </body>
</html>

Switch to the dark variant with data-theme="arcade-dark". To wire the switch to a toggle or the system preference, see Using custom theme names in the Dark Mode guide.

Apply themes on <html>, not on a nested element. Overlays such as modals, popovers, and tooltips render outside your app's root, and hover and soft colors are calculated on the root element.

What the Skill Teaches

The agent picks the smallest change that solves your request:

RequestWhat the agent changes
"Change the brand color", "make everything rounder"Theme tokens
"Primary buttons should be black"That component's CSS variables, such as --button-bg
"All buttons uppercase", "cards get a border"BEM classes in @layer components
"Add a gradient button"A new modifier class, such as .button--brand
"Create a theme called X"A named theme folder with light and dark variants
"Use preset X in our colors"A brand palette layered over the preset, keeping its look

It also carries the rules that keep a theme solid: read tokens and selectors from the installed version instead of guessing, define both color modes, keep foreground pairs readable, style every state, give every "on" state the same look, and never break focus rings or reduced-motion handling.

Structure

skills/heroui-theming/
├── SKILL.md              # Mental model, decision ladder, rules
├── LICENSE.txt           # Apache License 2.0
├── references/
│   ├── tokens.md         # Every theme token and what it affects
│   ├── components.md     # BEM conventions, states, component variables
│   ├── theme-recipe.md   # Step-by-step theme process and a full example
│   └── any-framework.md  # Plain HTML, Vue, Svelte, CDN
└── scripts/              # Read tokens and classes from your installed version
    ├── list_tokens.mjs
    └── list_component_classes.mjs
  • Theming - Theme variables, custom themes, and the full token reference
  • Colors - The semantic color palette
  • Styling - Ways to style individual components
  • Dark Mode - Theme switching setup
  • DESIGN.md - Give agents HeroUI's default visual language
  • Agent Skills - The heroui-react skill for building UIs

On this page

Build faster with HeroUI ProComponents, templates & AI toolingExplore Pro