Muza UI

A modern React component library built with Vite, shadcn/ui, and Tailwind CSS 4.

View Figma Design System

Prerequisites

• Node.js 22 or higher
• npm or yarn

Quick Start

1. Clone and install dependencies:

   npm install

2. Start development server:

   npm run dev

   This starts Storybook at http://localhost:6006

Development

Node.js Version Management

This project requires Node.js 22+. If you're using nvm:

nvm use

Available Scripts

| Script | Description | | ---------------------------------- | ----------------------------------------------- | | npm run dev | Start Storybook development server on port 6006 | | npm run build | Build the component library for production | | npm run build-storybook | Build Storybook for deployment | | npm run typecheck | Run TypeScript type checking | | npm run lint | Run ESLint | | npm run lint:fix | Run ESLint with auto-fix | | npm run add-component <name> | Add shadcn/ui component (macOS/Linux) | | npm run add-component:win <name> | Add shadcn/ui component (Windows) | | npm run format | Run Prettier | | npm run chromatic | Run Chromatic visual regression tests |

Project Structure

src/
├── components/          # React components
│   ├── Button/         # Example component
│   │   ├── Button.tsx
│   │   ├── Button.stories.tsx
│   │   └── index.ts
│   └── index.ts        # Component exports
├── utils/              # Utility functions
│   ├── cn.ts          # Class name utility
│   └── index.ts       # Utility exports
├── globals.css        # Global Tailwind styles
└── index.ts          # Main library export

Adding Components

For automated component installation using shadcn/ui, see: Component Installation Guide

Manual Component Creation

1. Create component directory:

   mkdir src/components/YourComponent

2. Create component files:

   • YourComponent.tsx - Main component
   • YourComponent.stories.tsx - Storybook stories
   • index.ts - Export file

3. Export from main index: Add to src/components/index.ts:

   export * from './YourComponent'

Storybook Development

Components are showcased and developed using Storybook:

• View components: npm run dev → http://localhost:6006
• Create stories: Follow the pattern in Button.stories.tsx
• Auto-docs: Stories are automatically documented

Build Process

Library Build

npm run build

This creates:

• dist/index.js - ES module bundle
• dist/index.d.ts - TypeScript declarations
• dist/muza-ui.css - Compiled CSS with all design tokens
• dist/components/ - Individual component modules
• dist/styles/ - Design system token files

Storybook Build

npm run build-storybook

Creates storybook-static/ directory for deployment.

Technologies

• React 18 - UI framework
• Vite - Build tool and dev server
• TypeScript - Type safety
• Tailwind CSS 4 - Utility-first CSS framework
• shadcn/ui - Component patterns and utilities
• Storybook - Component development and documentation
• class-variance-authority - Component variant management

Library Usage

Install the package:

npm install @vkzstudio/muza-ui

⚠️ Pin with tilde, not caret. muza-ui uses a non-standard version scheme where breaking changes ship in the minor (y) position, not the major (x). Use "~1.1.0" so breaking releases don't auto-install; "^1.1.0" (caret) will silently pull in breaking changes. If you use Renovate/Dependabot, don't auto-merge minor updates of this package. See docs/releasing.md.

Important: This library requires Tailwind CSS 4 to be configured in your project.

import { Button } from '@vkzstudio/muza-ui'
import '@vkzstudio/muza-ui/styles'

function App() {
  return <Button variant="primary">Click me</Button>
}

Styling

• Uses Tailwind CSS 4 with CSS variables
• Follows shadcn/ui design system patterns
• Custom utility function cn() for class merging
• Dark mode support built-in

Quality Assurance

• TypeScript - Static type checking
• ESLint - Code linting
• Prettier - Code formatting
• Storybook - Visual testing and documentation

Contributing

1. Create components following the established patterns
2. Include comprehensive Storybook stories
3. Run type checking and linting before committing
4. Test components in Storybook