placidovenegas/heroui-react
.agents/skills/heroui-react/SKILL.md
HeroUI v3 React component library (Tailwind CSS v4 + React Aria). Use when building UIs with HeroUI — creating Buttons, Modals, Forms, Cards; installing @heroui/react; configuring dark/light themes with oklch variables; or fetching component docs. Keywords: HeroUI, Hero UI, heroui, @heroui/react, @heroui/styles.
development
Updated Apr 17, 2026
$ install --global
skillsauthnpx skillsauth add placidovenegas/kiyoko-AI heroui-reactInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 24, 2026, 8:59 PM2.1s1 file scanned
SKILL.md
- name:
- heroui-react
- description:
- HeroUI v3 React component library (Tailwind CSS v4 + React Aria). Use when building UIs with HeroUI — creating Buttons, Modals, Forms, Cards; installing @heroui/react; configuring dark/light themes with oklch variables; or fetching component docs. Keywords: HeroUI, Hero UI, heroui, @heroui/react, @heroui/styles.
- author:
- heroui
- version:
- 3.0.1
HeroUI v3 React Development Guide
HeroUI v3 is a component library built on Tailwind CSS v4 and React Aria Components, providing accessible, customizable UI components for React applications.
Installation
curl -fsSL https://heroui.com/install | bash -s heroui-react
CRITICAL: v3 Only - Ignore v2 Knowledge
This guide is for HeroUI v3 ONLY. Do NOT apply v2 patterns — the provider, styling, and component API all changed:
| Feature | v2 (DO NOT USE) | v3 (USE THIS) |
| ------------- | --------------------------------- | ------------------------------------------- |
| Provider | <HeroUIProvider> required | No Provider needed |
| Animations | framer-motion package | CSS-based, no extra deps |
| Component API | Flat props: <Card title="x"> | Compound: <Card><Card.Header> |
| Styling | Tailwind v3 + @heroui/theme | Tailwind v4 + @heroui/styles |
| Packages | @heroui/system, @heroui/theme | @heroui/react, @heroui/styles |
// DO NOT DO THIS - v2 pattern
import { HeroUIProvider } from "@heroui/react";
import { motion } from "framer-motion";
<HeroUIProvider>
<Card title="Product" description="A great product" />
</HeroUIProvider>;
CORRECT (v3 patterns)
// DO THIS - v3 pattern (no provider, compound components)
import { Card } from "@heroui/react";
<Card>
<Card.Header>
<Card.Title>Product</Card.Title>
<Card.Description>A great product</Card.Description>
</Card.Header>
</Card>;
Always fetch v3 docs before implementing.
Core Principles
- Semantic variants (
primary,secondary,tertiary) over visual descriptions - Composition over configuration (compound components)
- CSS variable-based theming with
oklchcolor space - BEM naming convention for predictable styling
Accessing Documentation & Component Information
For component details, examples, props, and implementation patterns, always fetch documentation:
Using Scripts
# List all available components
node scripts/list_components.mjs
# Get component documentation (MDX)
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField
# Get component source code
node scripts/get_source.mjs Button
# Get component CSS styles (BEM classes)
node scripts/get_styles.mjs Button
# Get theme variables
node scripts/get_theme.mjs
# Get non-component docs (guides, releases)
node scripts/get_docs.mjs /docs/react/getting-started/theming
Direct MDX URLs
Component docs: https://heroui.com/docs/react/components/{component-name}.mdx
Examples:
- Button:
https://heroui.com/docs/react/components/button.mdx - Modal:
https://heroui.com/docs/react/components/modal.mdx - Form:
https://heroui.com/docs/react/components/form.mdx
Getting started guides: https://heroui.com/docs/react/getting-started/{topic}.mdx
Important: Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.
Installation Essentials
Quick Install
npm i @heroui/styles @heroui/react tailwind-variants
Framework Setup (Next.js App Router - Recommended)
- Install dependencies:
npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss
- Create/update
app/globals.css:
/* Tailwind CSS v4 - Must be first */
@import "tailwindcss";
/* HeroUI v3 styles - Must be after Tailwind */
@import "@heroui/styles";
- Import in
app/layout.tsx:
import "./globals.css";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en" suppressHydrationWarning>
<body>
{/* No Provider needed in HeroUI v3! */}
{children}
</body>
</html>
);
}
- Configure PostCSS (
postcss.config.mjs):
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};
Critical Setup Requirements
- Tailwind CSS v4 is MANDATORY - HeroUI v3 will NOT work with Tailwind CSS v3
- Use Compound Components - Components use compound structure (e.g.,
Card.Header,Card.Content) - Use onPress, not onClick - For better accessibility, use
onPressevent handlers - Import Order Matters - Always import Tailwind CSS before HeroUI styles
Component Patterns
All components use the compound pattern shown above (dot-notation subcomponents like Card.Header, Card.Content). Don't flatten to props — always compose with subcomponents. Fetch component docs for complete anatomy and examples.
Semantic Variants
HeroUI uses semantic naming to communicate functional intent:
| Variant | Purpose | Usage |
| ----------- | --------------------------------- | -------------- |
| primary | Main action to move forward | 1 per context |
| secondary | Alternative actions | Multiple |
| tertiary | Dismissive actions (cancel, skip) | Sparingly |
| danger | Destructive actions | When needed |
| ghost | Low-emphasis actions | Minimal weight |
| outline | Secondary actions | Bordered style |
Don't use raw colors - semantic variants adapt to themes and accessibility.
Theming
HeroUI v3 uses CSS variables with oklch color space:
:root {
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
--background: oklch(0.9702 0 0);
--foreground: var(--eclipse);
}
Get current theme variables:
node scripts/get_theme.mjs
Color naming:
- Without suffix = background (e.g.,
--accent) - With
-foreground= text color (e.g.,--accent-foreground)
Theme switching:
<html class="dark" data-theme="dark"></html>
For detailed theming, fetch: https://heroui.com/docs/react/getting-started/theming.mdx
Related Skills
placidovenegas/ui-audit
testing
VerifiedTrustedCommunity
Auditar componentes UI para consistencia visual, compliance con design system, accesibilidad y patrones Notion/Supabase. Usar cuando se quiera verificar calidad visual del proyecto.
SKILL.mdUpdated Apr 17, 2026
placidovenegas/supabase-postgres-best-practices
data-ai
VerifiedTrustedCommunity
Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
SKILL.mdUpdated Apr 17, 2026
placidovenegas/supabase-migration
tools
VerifiedTrustedCommunity
Cuando necesites crear, modificar o borrar tablas, enums, indices, RLS policies o seeds en Supabase. También para ejecutar SQL vía MCP.
SKILL.mdUpdated Apr 17, 2026
placidovenegas/scene-engine
testing
VerifiedTrustedCommunity
Motor de escenas de Kiyoko AI. Usar cuando se trabaje con escenas, prompts de imagen/video, timeline, camara, o generacion de contenido audiovisual. Referencia completa en docs/v6/MY DOCUMENT/kiyoko-motor-escenas-spec.md
SKILL.mdUpdated Apr 17, 2026