HeroUI Component Recommender Skill

This Skill helps developers select and implement the right HeroUI components for features, ensuring consistent UI/UX across the application.

When to Activate

• Starting implementation of new UI features
• Migrating components from shadcn/ui to HeroUI
• Uncertain which HeroUI component fits requirements
• Need usage examples with TypeScript types
• Want to verify proper HeroUI patterns

Available HeroUI Components

The project uses these HeroUI components (from package.json):

Interactive Components

• Button (@heroui/button) - Actions, CTAs, form submissions
• Tabs (@heroui/tabs) - Section navigation, category switching
• Pagination (@heroui/pagination) - List navigation, data tables
• Input (@heroui/input) - Form fields, search boxes
• Popover (@heroui/popover) - Contextual information, tooltips
• Tooltip (@heroui/tooltip) - Hover hints, icon explanations

Display Components

• Card (@heroui/card) - Content containers, dashboard widgets
• Table (@heroui/table) - Data grids, listings
• Chip (@heroui/chip) - Tags, badges, status indicators
• Alert (@heroui/alert) - Notifications, warnings, info messages
• Toast (@heroui/toast) - Temporary notifications, success messages

Layout Components

• Spacer (@heroui/spacer) - Flexible spacing between elements
• Spinner (@heroui/spinner) - Loading states, async operations

Complete Suite

• @heroui/react - Full HeroUI component library

Actions Performed

1. Analyze Requirements: Understand the feature/UI needs
2. Recommend Components: Suggest appropriate HeroUI components
3. Provide Examples: Show TypeScript usage with proper types
4. Fetch Latest Docs: Use Context7 MCP to get up-to-date HeroUI documentation
5. Check Patterns: Ensure semantic colors and accessibility best practices
6. Migration Guide: If replacing shadcn/ui, provide migration steps

Example Recommendations

Feature: Data Table with Pagination

Recommended Components:

• Table from @heroui/table - Main data display
• Pagination from @heroui/pagination - Navigation controls
• Chip from @heroui/chip - Status badges
• Spinner from @heroui/spinner - Loading state

Usage Example:

import { Table, TableHeader, TableColumn, TableBody, TableRow, TableCell } from "@heroui/table";
import { Pagination } from "@heroui/pagination";
import { Chip } from "@heroui/chip";

export function DataTable() {
  return (
    <div className="flex flex-col gap-4">
      <Table aria-label="Car registrations">
        <TableHeader>
          <TableColumn>Make</TableColumn>
          <TableColumn>Model</TableColumn>
          <TableColumn>Status</TableColumn>
        </TableHeader>
        <TableBody>
          <TableRow key="1">
            <TableCell>Toyota</TableCell>
            <TableCell>Camry</TableCell>
            <TableCell>
              <Chip color="success" variant="flat">Active</Chip>
            </TableCell>
          </TableRow>
        </TableBody>
      </Table>
      <Pagination total={10} initialPage={1} />
    </div>
  );
}

Feature: Form with Validation

Recommended Components:

• Input from @heroui/input - Form fields
• Button from @heroui/button - Submit action
• Alert from @heroui/alert - Error messages

Feature: Dashboard Cards

Recommended Components:

• Card from @heroui/card - Container
• Chip from @heroui/chip - Metrics, trends
• Spinner from @heroui/spinner - Loading state

Semantic Color System

All HeroUI components support semantic colors:

Text Colors:

• text-foreground - Primary text (auto-adjusts for light/dark mode)
• text-default-900 - Strong emphasis
• text-default-600 - Secondary text
• text-muted-foreground - Metadata, captions

Component Colors:

• color="default" - Neutral, standard UI
• color="primary" - Main actions, CTAs
• color="secondary" - Supporting actions
• color="success" - Positive states, confirmations
• color="warning" - Caution, important notices
• color="danger" - Errors, destructive actions

Accessibility Guidelines

Ensure all HeroUI components include:

• aria-label attributes for screen readers
• Keyboard navigation support
• Focus indicators
• Semantic HTML structure
• Proper heading hierarchy

Migration from shadcn/ui

Common Mappings:

• shadcn Button → @heroui/button
• shadcn Card → @heroui/card
• shadcn Badge → @heroui/chip
• shadcn Table → @heroui/table
• shadcn Tabs → @heroui/tabs
• shadcn Tooltip → @heroui/tooltip

Note: Do NOT modify files in src/components/ui/ (shadcn/ui). Create new HeroUI components in appropriate directories.

Tools Used

• Context7 MCP: Fetch latest HeroUI documentation
  • mcp__context7__resolve-library-id - Find HeroUI library ID
  • mcp__context7__get-library-docs - Get component documentation
• Read: Examine existing component implementations
• Grep: Find similar patterns in codebase

Documentation Resources

When fetching HeroUI docs via Context7:

• Library ID: /heroui/react or component-specific packages
• Focus on: TypeScript types, props, variants, colors, accessibility

Project-Specific Guidelines

From apps/web/CLAUDE.md:

• New Features: Use HeroUI components with TypeScript-first approach
• Component Selection: Leverage HeroUI's professional design system
• Data Visualisation: Use HeroUI's table and chart components for market data
• Customisation: Apply HeroUI theming to match Singapore car market branding
• Performance: Take advantage of tree-shakeable, optimized components
• Legacy Code: Gradually migrate shadcn/ui to HeroUI equivalents