🎨 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 | | init --yes | Non-interactive init with defaults | aural-ui init --yes | | 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 |

🔌 MCP (Cursor / AI assistant)

The aural-ui MCP server exposes the design system by reading from aural-ui source (components, icons, source and story files). No Storybook process is required.

Run the MCP server locally

1. Copy mcp/.env.example to mcp/.env and fill in the values (Google OAuth client, redirect URL, issuer base URL, JWT secret). That file is the canonical list of variables; it stays next to the server code so it does not drift.
2. From the repo root: npx tsx mcp/src/index.ts (listens on port 3000 by default).

For OAuth flow details, see mcp/docs/auth.md.

Setup in Cursor

Add the server in .cursor/mcp.json (or Cursor Settings → MCP). Start the MCP server first (e.g. npx tsx mcp/src/index.ts from the aural-ui repo root, or run the Docker image), then point Cursor at the streamable HTTP endpoint:

{
  "mcpServers": {
    "aural-ui": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp"
    }
  }
}

The server identifies as aural-ui so agents match user phrases like "add aural-ui btn". Use the same URL when the server runs in Docker or elsewhere (e.g. http://your-host:3000/mcp).

• Config: Non-secret defaults and limits live in mcp/src/lib/env.ts. OAuth and JWT values must come from the environment; for local dev, use mcp/.env (start from mcp/.env.example).

HTTP / Docker: When running the MCP server over HTTP (e.g. in Docker):

• GET /health — Returns 200 and { "ok": true, "server": "aural-ui" } for load balancers and orchestrators (no MCP session required).
• GET /metrics — Returns Prometheus-format metrics: mcp_sessions_active, mcp_sessions_max, mcp_tool_calls_total{tool="..."} (no MCP session required).
• Settings (in mcp/src/lib/env.ts): PORT (default 3000), MCP_MAX_SESSIONS (default 100; 0 = unlimited), MCP_SESSION_IDLE_TIMEOUT_MS (default 15 min), MCP_LIST_CACHE_TTL_MS (list cache TTL).

To have Cursor install Aural UI components in your project (instead of writing code manually), ask it to use add_aural_components with the component names (e.g. ["button", "card", "dialog"]). The agent must run the returned CLI steps first on the user machine; use componentSources only if the CLI fails. Do not pass --yes to add; only init supports it.

MCP tools

| Tool | Description | |------|-------------| | add_aural_components | Returns instructions: run the returned CLI steps first on the user machine (init if needed, then npx aural-ui add <components>); use componentSources only if CLI fails. Only use component names that exist; call list_components first if unclear. The MCP does not run the CLI. | | init_aural_ui | Returns instructions: step to run npx aural-ui init --yes in the project root on the user machine. Use when the project has no aural-ui.json yet. The MCP does not run the CLI. | | ensure_aural_components | Returns instructions: run the returned CLI steps first (init if needed, then add); use componentSources only if CLI fails. Only missing components are added by the CLI. The MCP does not run the CLI. | | get_aural_ui_status | Where aural-ui source is resolved (env, repo, node_modules). | | get_aural_ui_version | Returns the aural-ui design system version from the resolved source (package.json). | | list_components / list_icons / list_hooks | Call first when unsure: returns available component, icon, or hook names. Use when the user asks for a component/hook that might not exist so you can show the list instead of guessing. | | get_component_source / get_component_story / get_component_docs | Component source and story file content (read from repo). get_component_docs includes metadata (tokens, internal deps) when available. | | get_component_meta | Component metadata: dependencies, internalDependencies, and design tokens. | | get_icon_source | Icon component source. | | get_theme_source | Theme CSS (design tokens) from aural-theme.css. Use for correct token names when implementing UI. | | get_hook_source | Hook source code. Use list_hooks for available hook names. | | search_components | Search components, icons, and hooks by name (substring). Use when the user describes something vaguely (e.g. "dropdown"). |

Prompts: The server exposes guided-flow prompts: "Add aural-ui components" and "Implement UI from Figma". When the user pastes a Figma link, frame, or URL, use "Implement UI from Figma" (or the aural-ui MCP tools): get design via Figma MCP, add missing components with ensure_aural_components, then build the UI with aural-ui only. In Cursor you can invoke these via the prompts UI for step-by-step instructions.

Design system docs and Storybook: aural-ui.pocketfm.com (built on Radix UI).

🧩 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.pocketfm.com/

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
├── 📁 mcp/                   # MCP server (Cursor / HTTP)
│   ├── 📁 docs/              # MCP docs (guidelines, figma-workflow, etc.)
│   └── 📁 src/
│       ├── 📁 lib/           # env, logger, constants
│       ├── 📁 transport/     # HTTP transport (sessions, /mcp, /health, /metrics)
│       ├── 📁 tools/         # MCP tool handlers
│       ├── 📁 resources/     # MCP resource providers
│       ├── 📁 prompts/        # MCP prompts
│       ├── design-system.ts  # Resolve aural-ui source, list/get components
│       ├── consumer-project.ts # Consumer detection, get_consumer_setup
│       └── index.ts          # Entry (runHttp)
├── 📁 .storybook/            # Storybook config and manager
├── 📁 aural-ui-example/      # Example implementation
├── 📁 .github/               # CI/CD (e.g. deploy-storybook)
├── 📄 Dockerfile             # Build MCP HTTP server image (port 3000)
├── 📄 .dockerignore          # Docker build exclusions
├── 📄 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.pocketfm.com/

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/aural-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