Component library
HeroUI
AI-nativemarkdown record for HeroUI json record for HeroUI
HeroUI (formerly NextUI) is a 30k-star React component library, now shipping v3 on Tailwind CSS v4 + React Aria Components. It is one of the most thoroughly AI-instrumented open-source component libraries in the study: the v3 monorepo ships a top-level skills/ directory with three installable Agent Skills, a prompts/ directory of vendor-specific system prompts (v0.dev, bolt.new, universal), four llms.txt variants per platform sliced by context-window budget, an official stdio MCP server (@heroui/react-mcp) auto-refreshed from docs deploys via repository_dispatch, and a curl | bash installer that writes skills into Claude Code, Cursor, OpenCode and Codex config dirs. On the builder side the repo carries both AGENTS.md and CLAUDE.md, five .claude/agents/* subagent definitions, a .claude/guides/ reference, and a .claude/hooks.mjs pre/post-edit hook running prettier, eslint --fix and tsc on every agent edit. The coercion language is unusually blunt: the CLI-injected index literally opens with “STOP. What you remember about HeroUI React v3 is WRONG for this project.”
For consumers — building with it
Exceptionally well served, and deliberately multi-modal so the same guidance lands whatever harness the developer uses: Agent Skills (Claude Code / Cursor / OpenCode / Codex, installed by a one-line curl or npx skills add heroui-inc/heroui), an official MCP server with six retrieval tools and copy-paste config for seven clients plus a one-click Cursor deeplink, four tiers of llms.txt per platform, .mdx suffix retrieval on every docs page, a heroui-cli agents-md command that vendors the docs into the consumer’s repo and rewrites their AGENTS.md/CLAUDE.md, and vendor-tuned prompt packs for v0.dev and bolt.new. The unifying strategy is anti-memory: because v3 broke nearly every v2/NextUI API models were trained on, almost every artefact’s first move is to invalidate the model’s priors and force a live fetch.
For builders — maintaining it
Also unusually mature for an OSS component library. The repo root carries both AGENTS.md and CLAUDE.md (overlapping; AGENTS.md is the fuller spec), plus .claude/ with five committed subagent definitions (docs-curator on opus, heroui-docs-writer, style-migrator, tailwind-v4-css-expert, storybook-debugger), a curated .claude/guides/tailwindcss-v4-css-guide.md, and hooks.mjs enforcing lint/typecheck/protected-file rules on every agent edit. The style-migrator subagent is a genuine AI-assisted migration tool (tailwind-variants .styles.ts → BEM CSS) built for the v2→v3 restyle. Notably absent: any .cursorrules, .cursor/rules/, or .github/copilot-instructions.md, and CONTRIBUTING.md contains zero mentions of AI, agents, Claude, Copilot or skills, so the agent tooling is entirely undocumented for outside contributors.
Affordances · 10
Concrete AI-facing artifacts this system ships. Expand for snippets and links.
Agent skillheroui-react Agent Skill (+ heroui-migration, heroui-native)officialconsumers
Three first-party Agent Skills versioned in the main repo under skills/. Each has SKILL.md plus a scripts/ dir of .mjs fetchers (list_components, get_component_docs, get_source, get_styles, get_theme, get_docs) so the agent pulls live docs rather than relying on weights. Installed via
curl -fsSL https://heroui.com/install | bash -s heroui-reactornpx skills add heroui-inc/heroui; auto-discovered, or invoked as /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>` | ```tsx // DO NOT DO THIS - v2 pattern import { HeroUIProvider } from "@heroui/react"; import { motion } from "framer-motion"; ``` **Always fetch v3 docs before implementing.**Skill frontmatter is keyword-stuffed (“Keywords: HeroUI, Hero UI, heroui, @heroui/react, @heroui/styles”) to force autodiscovery; metadata.version pinned to 3.0.1.
MCP server@heroui/react-mcp (and @heroui/native-mcp)officialconsumers
Official stdio MCP server exposing 6 tools. Docs ship copy-paste config for Cursor (plus one-click deeplink link.heroui.com/mcp-cursor-install), Claude Code, Windsurf, Zed, VS Code/Copilot, Codex (TOML) and OpenCode. Also pitched as an upgrade agent: ‘Hey Cursor, update HeroUI to the latest version’ → compares versions, reads changelog, applies updates.
claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest { "mcpServers": { "heroui-react": { "command": "npx", "args": ["-y", "@heroui/react-mcp@latest"] } } } | Tool | Description | | `list_components` | List all available HeroUI v3 components | | `get_component_docs` | Get complete component documentation including anatomy, props, examples, and usage patterns | | `get_component_source_code` | Access the React/TypeScript source code (.tsx files) for components | | `get_component_source_styles` | View the CSS styles (.css files) for components | | `get_theme_variables` | Access theme variables for colors, typography, spacing with light/dark mode support | | `get_docs` | Browse the full HeroUI v3 documentation including guides and principles |v3-only, stdio-only. Requires Node 22+.
llms.txtllms.txt family (8 files, sliced by context budget)officialconsumers
Eight files: /llms.txt (517 lines, 76 KB index), /llms-full.txt (~7 MB), /llms-components.txt and /llms-patterns.txt, each also namespaced per platform under /react/ and /native/. Explicitly tiered ‘For limited context windows’. Every docs page is also retrievable as raw MDX by appending .mdx, with a header naming the upstream GitHub source file.
**Core documentation:** - [/react/llms.txt](/react/llms.txt) — Quick reference index for React documentation - [/react/llms-full.txt](/react/llms-full.txt) — Complete HeroUI React documentation **For limited context windows:** - [/react/llms-components.txt](/react/llms-components.txt) — Component documentation only - [/react/llms-patterns.txt](/react/llms-patterns.txt) — Common patterns and recipes **Windsurf:** Add to your `.windsurfrules` file: ``` #docs https://heroui.com/react/llms-full.txt ``` ## Contributing Found an issue with AI-generated code? Help us improve our LLMs.txt files on [GitHub](https://github.com/heroui-inc/heroui).CLI scaffoldingheroui-cli agents-mdofficialconsumers
npx heroui-cli@latest agents-md --react [--output AGENTS.md CLAUDE.md]git-sparse-checkouts the v3 docs branch into.heroui-docs/react/, builds a compact index, injects it into AGENTS.md/CLAUDE.md, and auto-appends.heroui-docs/to .gitignore. Explicitly adapted from Vercel’s next-codemod agents-md tool; the docs page links Vercel’s ‘AGENTS.md outperforms Skills in our agent evals’ post as justification.if (library === 'react') { parts.push('[HeroUI React v3 Docs Index]'); if (reactDocsPath) parts.push(`root: ${reactDocsPath}`); parts.push( 'STOP. What you remember about HeroUI React v3 is WRONG for this project. Always search docs and read before any task.' ); const targetFile = outputFile || 'AGENTS.md'; parts.push( `If docs missing, run this command first: heroui agents-md --react --output ${targetFile}` );Split-brain: agents-md is v3-only while the CLI’s add/init/upgrade commands still target v2.
Prompt libraryprompts/ — vendor-specific system prompt packsofficialconsumers
Three maintained prompt packs in-repo: heroui-system-prompt.md (universal, usable as .cursorrules), v0-heroui.md (v0.dev, App Router + RSC), bolt-heroui.md (bolt.new/StackBlitz, full runnable Vite setup). README names Lovable, Replit Agent and Windsurf as further targets and tells contributors to diff prompts against real v3 source to catch drift.
# HeroUI v3 — AI Integration Prompt Packs System prompts that teach AI code-generation tools to produce correct, idiomatic HeroUI v3 code. | File | Purpose | | `heroui-system-prompt.md` | Universal prompt — works with any LLM or AI coding tool (Claude, ChatGPT, Cursor, Copilot, etc.) | | `v0-heroui.md` | Tailored for [v0.dev](https://v0.dev) — emphasizes Next.js App Router, RSC patterns, and Tailwind v4 | | `bolt-heroui.md` | Tailored for [bolt.new](https://bolt.new) / StackBlitz — includes full Vite setup and runnable single-file examples | ## Contributing When updating these prompts, verify that the component names, APIs, and import patterns match the actual v3 source code in this repo. Run a quick check against the component docs in `apps/docs/content/docs/react/components/` to catch any drift.CLI scaffoldingheroui.com/install — multi-harness skill installerofficialconsumers
A bash script served from the docs domain that detects installed agent harnesses and drops the requested skill tarball into each: ~/.claude/skills/, ~/.cursor/skills/, ~/.config/opencode/skill/, and $CODEX_HOME. It also garbage-collects the previous-generation
herouiskill and its /heroui slash command. Distribution-as-coercion: the skill lands in the agent’s global config without the user editing anything.#!/bin/bash # HeroUI Skill Installer # Usage: curl -sSL https://heroui.com/install | bash -s [skill-name] # Default: heroui-react # Available skills: heroui-react, heroui-native, heroui-migration SKILL_NAME="${1:-heroui-react}" SKILL_URL="${BASE_URL}/skills/${SKILL_NAME}.tar.gz" CODEX_HOME="${CODEX_HOME:-$HOME/.codex}" # Claude Code - Skill only (skills are auto-discovered, no command needed) if [ -d "$HOME/.claude" ]; then mkdir -p "$HOME/.claude/skills/${SKILL_NAME}" curl -sL "$SKILL_URL" | tar xz -C "$HOME/.claude/skills/${SKILL_NAME}" echo "✓ Installed ${SKILL_NAME} skill for Claude Code" fi # Cursor - Install skill if [ -d "$HOME/.cursor" ]; then mkdir -p "$HOME/.cursor/skills/${SKILL_NAME}" curl -sL "$SKILL_URL" | tar xz -C "$HOME/.cursor/skills/${SKILL_NAME}" fiAGENTS.mdAGENTS.md + CLAUDE.md (contributor-facing)officialbuilders
Both at repo root, largely mirroring each other (AGENTS.md is richer, ~220 lines). They encode the monorepo map, an exact command table, conventional-commit rules enforced by husky+commitlint, and hard styling prohibitions that constrain what an agent may write.
### Creating a New Component Always use the scaffold script: ```bash cd packages/react pnpm add:component ComponentName ``` ### Styling Rules 1. **Styles go in `.styles.ts` files**, never in `.tsx` files. Use `tv()` from `tailwind-variants`. 2. **Import from `tailwind-variants`**, never from `@heroui/standard`. 3. **Never use `twMerge` manually** — `tailwind-variants` already includes it. 4. **Add `"use client"` directive** at the top of every component `.tsx` file. 5. **Display names** follow: `HeroUI.ComponentName` or `HeroUI.Component.SubPart`.Agent skill.claude/agents/ — five specialised subagents + .claude/guides/officialbuilders
Checked-in Claude Code subagent definitions: docs-curator.md (13 KB, model: opus), heroui-docs-writer.md (16 KB), style-migrator.md (11 KB, .styles.ts → BEM CSS migration), tailwind-v4-css-expert.md, storybook-debugger.md, plus .claude/guides/tailwindcss-v4-css-guide.md as shared curated context. They chain: style-migrator is told to delegate to tailwind-v4-css-expert for validation.
**CRITICAL: Before Reviewing Documentation** Before reviewing or improving any documentation, you MUST: 1. **Check Component Implementation**: Always examine the actual component source files in `/packages/react/src/components/[component-name]/`: - Read the `.tsx` file to understand the component structure and compound parts - **MANDATORY: Read the `.stories.tsx` file thoroughly** - This is your PRIMARY reference for validating demos - Verify demos match Storybook story patterns and structures 4. **Verify Component APIs**: Never assume component structure - always verify: - Compound parts match actual implementationOther.claude/hooks.mjs — pre/post-edit validation loopofficialbuilders
Programmatic guardrails around every agent file edit: preEdit hard-throws on a protected-files denylist (lockfiles, .env.production, firebase.json) and warns on formatting; postEdit runs
pnpm lint --fixandtsc --noEmiton the edited file and surfaces failures back to the agent. Enforcement in code rather than prose.// Hook that runs before editing files export async function preEdit({filePath}) { // Prevent editing of certain protected files const protectedFiles = ["yarn.lock", "package-lock.json", ".env.production", "firebase.json"]; const fileName = path.basename(filePath); if (protectedFiles.includes(fileName)) { throw new Error(`❌ Cannot edit protected file: ${fileName}`); } return {proceed: true}; } // Hook that runs after editing files export async function postEdit({filePath, success}) { if (!success) return; if (filePath.match(/\.(ts|tsx|js|jsx)$/)) { try { execSync(`pnpm lint --fix "${filePath}"`, {stdio: "pipe"}); console.log("✅ Lint fixes applied"); } catch (e) { console.log("⚠️ Lint errors detected - please review"); } }MCP serverT-hash06/heroui-mcp (community)communityconsumers
Independent community MCP server for HeroUI component context, predating the official one. 17 stars, last pushed 2025-07-20, effectively dormant and superseded by @heroui/react-mcp.
Listed for completeness; not recommended.
Coercion techniques · 8
How this system keeps models on-system instead of inventing components.
Prohibition“STOP. What you remember is WRONG” — weight-invalidation preamble
The strongest coercion artefact in the corpus. Every AGENTS.md/CLAUDE.md index the CLI writes into a consumer project opens by asserting the model’s parametric memory of HeroUI is invalid, mandates doc retrieval before any task, and gives a recovery command if the docs directory is missing. It directly targets v2/NextUI contamination: ~30k stars of v2 code in training data against a v3 API that broke almost everything.
parts.push('[HeroUI React v3 Docs Index]'); if (reactDocsPath) parts.push(`root: ${reactDocsPath}`); parts.push( 'STOP. What you remember about HeroUI React v3 is WRONG for this project. Always search docs and read before any task.' ); const targetFile = outputFile || 'AGENTS.md'; parts.push( `If docs missing, run this command first: heroui agents-md --react --output ${targetFile}` );ExemplarsNegative exemplars — a labelled “DO NOT DO THIS” code block
The heroui-react skill pairs a v2/v3 contrast table with an explicitly labelled wrong-answer sample followed by the corrected one. Rather than only describing the target API, it shows the exact hallucination it expects (HeroUIProvider + framer-motion + flat Card props) and marks it forbidden.
```tsx // 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) ```tsx // 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>; ```Tool-gatingForced retrieval — the skill ships executable fetchers, not prose
heroui-react deliberately withholds component API detail from SKILL.md and instead hands the agent six node scripts plus a deterministic MDX URL scheme, repeating “Always fetch component docs before implementing.” The skill body stays small (6.5 KB) while every concrete answer must come from a live fetch, the same discipline the MCP server enforces via tools.
**For component details, examples, props, and implementation patterns, always fetch documentation:** # List all available components node scripts/list_components.mjs # Get component documentation (MDX) node scripts/get_component_docs.mjs Button # 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 Component docs: `https://heroui.com/docs/react/components/{component-name}.mdx` **Important:** Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.Token enforcementSemantic-token enforcement — “Don’t use raw colors”
The skill supplies a variant-intent table (primary = 1 per context, tertiary = dismissive, danger = destructive) and forbids raw/visual color choices, pushing the agent toward semantic variants and oklch CSS variables that adapt to theme and contrast. The naming convention is machine-checkable: bare var = background,
-foregroundsuffix = text.## Semantic Variants | 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 | **Don't use raw colors** - semantic variants adapt to themes and accessibility. **Color naming:** - Without suffix = background (e.g., `--accent`) - With `-foreground` = text color (e.g., `--accent-foreground`)ScaffoldingScaffold-only component creation (builders)
Contributor agents are forbidden from hand-rolling a new component directory; AGENTS.md mandates
pnpm add:component ComponentNamethen a build to regenerate package.json exports. Combined with the enumerated prohibitions (never twMerge, never styles in .tsx, never import tv from @heroui/standard) this narrows the agent to filling in a generated skeleton.### Creating a New Component Always use the scaffold script: ```bash cd packages/react pnpm add:component ComponentName ``` Then build to update package.json exports: ```bash pnpm build ```Validation loopHook-enforced validation loop on every edit
Rather than asking the agent to remember to lint, .claude/hooks.mjs runs prettier check pre-edit and
pnpm lint --fix+tsc --noEmit --skipLibCheckpost-edit, feeding results back into the transcript; a denylist throws outright for protected files. Deterministic enforcement outside the model’s discretion.// Run type checking on TypeScript files if (filePath.match(/\.(ts|tsx)$/)) { try { execSync(`npx tsc --noEmit --skipLibCheck "${filePath}"`, {stdio: "pipe"}); } catch (e) { console.log("⚠️ TypeScript errors detected - please review"); } }Curated contextGround-truth-first subagents (“never assume, always verify”)
The docs-curator subagent is barred from writing docs off memory: it must first read the component .tsx, its .stories.tsx (declared the PRIMARY reference), .styles.ts and BEM CSS, and verify React Aria
links.racfrontmatter. Storybook stories are promoted to the executable spec docs are validated against. Sibling agents are pointed at .claude/guides/tailwindcss-v4-css-guide.md as shared curated context, with explicit CSS prohibitions.**IMPORTANT**: Always refer to the comprehensive Tailwind CSS v4 guide at `.claude/guides/tailwindcss-v4-css-guide.md` for: - Proper @apply directive usage and v4-specific changes - CSS nesting syntax with & symbol - **DO NOT add any @utility directives** - the plugin handles CSS injection - Proper use of `@apply` directives for Tailwind utilities (IMPORTANT: Only ONE @apply per CSS rule block - combine all utilities into a single @apply statement) **IMPORTANT**: When creating or analyzing CSS files, use the tailwind-v4-css-expert agent to ensure proper Tailwind CSS v4 syntax and patterns.Registry metadataAuto-refresh pipeline: docs deploy → MCP re-extraction
A GitHub Actions workflow listens for Vercel deployment webhooks on the v3 branch and repository_dispatches
react-docs-deployed/native-docs-deployedinto heroui-inc/heroui-mcp, so the MCP server’s corpus is re-extracted from the freshly deployed docs. Infrastructure that keeps the agent-facing surface from drifting from the docs.name: Trigger MCP Extraction on Vercel Deployment on: repository_dispatch: types: - vercel.deployment.success - vercel.deployment.promoted jobs: trigger-extraction: steps: - name: Trigger React MCP Extraction if: | github.event.client_payload.git.ref == 'v3' || github.event.client_payload.git.ref == 'refs/heads/v3' uses: peter-evans/repository-dispatch@v3 with: token: ${{ secrets.MCP_DISPATCH_TOKEN }} repository: heroui-inc/heroui-mcp event-type: react-docs-deployed
Platform integrations
Figma
Official HeroUI Figma Kit V3 on Figma Community, marketed as a 1:1 match with v3 code (same variants, naming, structure) using Figma variables mapped to code tokens (--accent, --surface, --radius) and Figma slots for composition. No Code Connect (*.figma.tsx) files exist anywhere in the heroui-inc org; code search returned only prose mentions in blog/docs MDX. Figma Dev Mode MCP is not documented as supported.
Storybook
Storybook is the internal component-development environment (pnpm dev, port 6006); every component ships a .stories.tsx. It is used as an AI substrate on the builder side: docs-curator treats stories as the primary source of truth for docs demos, and a dedicated storybook-debugger subagent exists. No public Storybook-based MCP or addon for consumers.
Other
HeroUI Pro (commercial block library) ships its own agent-skills and Figma docs pages; not verified in depth here. No Supernova / Knapsack / zeroheight presence found.
Gaps & open questions
1) No Figma Code Connect: despite a 1:1 Figma Kit V3, a GitHub code search across heroui-inc found no *.figma.tsx or Code Connect configuration, only prose mentions in blog/docs MDX. No Figma Dev Mode MCP integration documented. 2) No shadcn-style machine-readable component registry (registry.json returned 0 results org-wide); agents get docs and source via MCP/scripts, not an installable registry. 3) MCP staleness: @heroui/react-mcp last published 2026-02-12 and heroui-inc/heroui-mcp last pushed 2026-04-16 while the library shipped v3.2.2 in July 2026. The auto-extraction workflow keeps the docs corpus fresh, but the server package lags. Legacy @heroui/mcp is stuck at 1.0.0-alpha.17 (Sept 2025) and still surfaces in search. 4) Tooling split-brain: heroui-cli’s agents-md is v3-only while add/init/upgrade still target v2, flagged in a docs Callout. 5) The migration skill points at a preview Vercel URL (heroui-git-docs-migration-heroui.vercel.app) rather than a stable domain, and is marked status: preview. 6) No Supernova / Knapsack / zeroheight presence found. 7) /llms-full.txt is ~7 MB, far beyond most context windows despite the ‘full’ framing; heroui.com/llms.txt serves a JS redirect shell to some clients before resolving to the 76 KB / 517-line index. 8) No AI guidance for external contributors: CONTRIBUTING.md never mentions the .claude/ tooling. 9) No evidence found of AI review bots on PRs or AI-authored codemods beyond the style-migrator subagent. 10) AGENTS.md and CLAUDE.md substantially duplicate each other, a drift risk.
Sources
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/AGENTS.md (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/CLAUDE.md (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/.claude/hooks.mjs (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/.claude/agents/docs-curator.md (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/.claude/agents/style-migrator.md (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/skills/heroui-react/SKILL.md (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/skills/heroui-migration/SKILL.md (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/prompts/README.md (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/prompts/heroui-system-prompt.md (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/HEAD/.github/workflows/trigger-mcp-extraction.yml (opens in new tab)
- heroui.com/install (opens in new tab)
- heroui.com/docs/react/getting-started/mcp-server.mdx (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui/v3/apps/docs/content/docs/en/react/getting-started/(ui-for-agents)/llms-txt.mdx (opens in new tab)
- raw.githubusercontent.com/heroui-inc/heroui-cli/HEAD/src/helpers/agents-docs/index-and-inject.ts (opens in new tab)
- www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3 (opens in new tab)