HeroUI Component Recommender Skill

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