🎨 Aural UI

A modern CLI toolkit for seamlessly integrating customizable UI components into React projects. Quickly scaffold, add, and manage production-ready components with minimal configuration.

📚 Documentation • 🎨 Storybook • 📦 NPM • 🐛 Issues

✨ Features

• 🚀 CLI-First Approach - Scaffold and manage components via intuitive CLI commands
• 🎯 Production Ready - Battle-tested components used in production applications
• 🎨 Highly Customizable - Full theming support with CSS variables and Tailwind CSS
• 📱 Accessible - Built on Radix UI primitives for maximum accessibility
• 🔧 Type Safe - Written in TypeScript with comprehensive type definitions
• 📖 Storybook Integration - Interactive component documentation and testing
• 🌙 Dark Mode Support - Built-in dark mode with easy theme switching
• ⚡ Performance Optimized - Tree-shakeable components with minimal bundle impact
• 🔄 Hot Reloading - Development experience with instant updates
• 📦 Zero Config - Works out of the box with sensible defaults

🛠️ Tech Stack

Core Technologies

• React - Component library foundation
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first styling
• Radix UI - Accessible component primitives
• Class Variance Authority - Component variant management

Build & Development

• Vite - Fast build tool and dev server
• Tsup - TypeScript bundler
• Storybook - Component documentation and testing
• Vitest - Unit testing framework
• Playwright - End-to-end testing

CLI & Tooling

• Commander.js - CLI framework
• Inquirer.js - Interactive command line prompts
• Chalk - Terminal string styling
• Handlebars - Template engine for code generation
• ESLint & Prettier - Code quality and formatting

📦 Installation

npm

npm install -g aural-ui

yarn

yarn global add aural-ui

pnpm

pnpm add -g aural-ui

🚀 Quick Start

1. Initialize your project

# Create a new React project (if you don't have one)
npx create-react-app my-app --template typescript
cd my-app

# Initialize aural-ui
aural-ui init

2. Add components

# Add individual components
aural-ui add button
aural-ui add card
aural-ui add dialog

# Add multiple components
aural-ui add button card dialog avatar

3. Configure themes

# Set up custom theme
aural-ui theme

# Update existing components
aural-ui update

📋 Available Commands

| Command | Description | Example | |---------|-------------|---------| | init | Initialize aural-ui in your project | aural-ui init | | add <components> | Add one or more components | aural-ui add button card | | remove <components> | Remove components from project | aural-ui remove button | | update [components] | Update components to latest version | aural-ui update | | theme | Configure theme and design tokens | aural-ui theme |

🧩 Available Components

Layout & Structure

• AspectRatio - Maintain consistent aspect ratios
• Card - Flexible content containers
• Divider - Visual content separation
• Resizable - Resizable panel layouts
• ScrollArea - Custom scrollable areas

Form Controls

• Button - Interactive buttons with variants
• Input - Text input fields
• Textarea - Multi-line text input
• Checkbox - Binary choice inputs
• Radio - Single choice from multiple options
• Select - Dropdown selection menus
• Slider - Range value selection
• Switch - Toggle controls

Navigation

• Tabs - Tabbed content organization
• Pagination - Page navigation controls
• Command - Command palette interface

Feedback

• Toast - Notification messages
• Dialog - Modal dialogs
• Banner - Important announcements
• Badge - Status indicators
• Tooltip - Contextual information

Data Display

• Avatar - User profile images
• Table - Data tables
• Typography - Text styling components
• Chip - Compact information display
• Tag - Categorization labels

Utilities

• If-Else - Conditional rendering helper
• Switch-Case - Multi-condition rendering
• Overlay - Modal overlays
• Skelton - Loading placeholders

🎨 Theming

Aural UI provides a powerful theming system built on CSS variables and Tailwind CSS:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  /* ... more variables */
}

Custom Theme Configuration

# Interactive theme setup
aural-ui theme

# This will:
# 1. Generate CSS variables
# 2. Create Tailwind config
# 3. Set up component styles
# 4. Configure Storybook themes

📖 Storybook

Interactive component documentation is available at: https://aural-ui.netlify.app

Local Development

# Install dependencies
npm install

# Start Storybook
npm run storybook

Building Storybook

# Build static Storybook
npm run build-storybook

# Deploy to Netlify
npm run deploy-storybook

📁 Project Structure

aural-ui/
├── 📁 src/
│   ├── 📁 cli/               # CLI commands and utilities
│   │   ├── 📁 commands/      # Individual command implementations
│   │   │   ├── add.ts        # Add components command
│   │   │   ├── init.ts       # Initialize project command
│   │   │   ├── remove.ts     # Remove components command
│   │   │   ├── theme.ts      # Theme configuration command
│   │   │   └── update.ts     # Update components command
│   │   └── index.ts          # CLI entry point
│   ├── 📁 core/              # Core utilities and services
│   │   ├── 📁 services/      # Business logic services
│   │   ├── 📁 templates/     # Code generation templates
│   │   ├── 📁 utils/         # Utility functions
│   │   ├── 📁 validation/    # Input validation
│   │   └── constants.ts      # Global constants
│   ├── 📁 ui/                # UI components and assets
│   │   ├── 📁 components/    # React components
│   │   ├── 📁 hooks/         # Custom React hooks
│   │   ├── 📁 lib/           # Utility libraries
│   │   ├── 📁 styles/        # Global styles and themes
│   │   ├── 📁 icons/         # Icon components
│   │   └── 📁 fonts/         # Font assets
│   └── 📁 stories/           # Storybook stories
├── 📁 aural-ui-example/      # Example implementation
├── 📁 storybook-static/      # Built Storybook output
├── 📄 package.json           # Package configuration
├── 📄 tsconfig.json          # TypeScript configuration
├── 📄 vite.config.mts        # Vite configuration
└── 📄 README.md              # This file

🌍 Deployment

Storybook Deployment

The component documentation is automatically deployed to Netlify:

1. Build: npm run build-storybook
2. Deploy: npm run deploy-storybook
3. Live URL: https://aural-ui.netlify.app

NPM Package

# Build for production
npm run build

# Publish to NPM
npm run release

💡 Benefits

For Developers

• Rapid Development - Add production-ready components in seconds
• Consistent Design - Maintain design system consistency across projects
• Type Safety - Full TypeScript support with IntelliSense
• Customization - Easy theming and component customization
• Documentation - Interactive Storybook documentation

For Teams

• Standardization - Consistent component library across projects
• Productivity - Reduce time spent building common UI components
• Maintainability - Centralized component updates and bug fixes
• Accessibility - Built-in accessibility best practices
• Scalability - Modular architecture for large applications

For Projects

• Performance - Optimized bundle size with tree-shaking
• Modern Stack - Latest React, TypeScript, and tooling
• Cross-Platform - Works with any React framework (Next.js, Vite, CRA)
• Future-Proof - Regular updates and modern development practices

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/Pocket-Fm/fm-ui.git
cd aural-ui

# Install dependencies
npm install

# Start development
npm run dev

# Run tests
npm test

# Start Storybook
npm run storybook

Development Scripts

| Script | Description | |--------|-------------| | npm run dev | Start development build with watch mode | | npm run build | Build for production | | npm run test | Run unit tests | | npm run lint | Lint code with ESLint | | npm run format | Format code with Prettier | | npm run storybook | Start Storybook development server |

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Radix UI - For accessible component primitives
• Tailwind CSS - For utility-first CSS framework
• Shadcn/ui - For design inspiration
• Storybook - For component documentation

Built with ❤️ by the Pocket FM team

Website • GitHub • NPM