aural-ui

🎨 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:

• Build: npm run build-storybook
• Deploy: npm run deploy-storybook
• 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