npm package: @music-vine/cadence
Description: Cadence Design System - UI components and icons for Uppbeat
Latest version: 2.5.1

# @music-vine/cadence

> [**View full documentation →**](https://music-vine.github.io/uppbeat-frontend/)

Cadence Design System - UI components and icons for Uppbeat applications.

## Installation

```bash
pnpm add @music-vine/cadence
```

## Usage

### Components

```tsx
import { Button, Text, Heading } from '@music-vine/cadence/ui';

function App() {
  return (
    <div>
      <Heading>Welcome</Heading>
      <Text>Hello world</Text>
      <Button>Click me</Button>
    </div>
  );
}
```

### Icons

```tsx
import { Play, Pause, Music } from '@music-vine/cadence/icons';

function Player() {
  return (
    <button>
      <Play />
    </button>
  );
}
```

### Toast Notifications

```tsx
import { toast, Toaster } from '@music-vine/cadence/ui';

function App() {
  return (
    <>
      <button onClick={() => toast.success('Success!')}>Show Toast</button>
      <Toaster />
    </>
  );
}
```

## Tailwind Configuration

Cadence supports both Tailwind CSS v3 and v4. Choose the version that matches your project.

### Tailwind v3 (JavaScript config)

Extend your Tailwind config with the Cadence preset:

```js
// tailwind.config.js
import cadenceConfig from '@music-vine/cadence/tailwind.config';

export default {
  presets: [cadenceConfig],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@music-vine/cadence/dist/**/*.js',
  ],
};
```

Then import the v3 styles:

```css
/* app.css */
@import '@music-vine/cadence/styles';
```

### Tailwind v4 (CSS-first config)

For Tailwind v4, use the CSS-first configuration:

```css
/* app.css */
@import "tailwindcss";
@import "@music-vine/cadence/tailwind.config.v4";
@import "@music-vine/cadence/styles.v4";

@source "./src/**/*.{js,ts,jsx,tsx}";
@source "./node_modules/@music-vine/cadence/dist/**/*.js";
```

**Benefits of v4:**
- 3-10x faster builds
- 100x faster incremental rebuilds
- Built-in container queries
- Native CSS variable support
- Smaller bundle size

See the [Migration Guide](./src/docs/02-guides/tailwind-v4-migration.mdx) for detailed instructions.

## Available Exports

| Export | Description |
|--------|-------------|
| `@music-vine/cadence/ui` | React UI components (Button, Text, Card, etc.) |
| `@music-vine/cadence/icons` | Lucide icons + custom Uppbeat icons |
| `@music-vine/cadence/theme` | Theme customization API (`createTheme`, presets) |
| `@music-vine/cadence/styles` | Base CSS styles (Tailwind v3) |
| `@music-vine/cadence/styles.v4` | Base CSS styles (Tailwind v4) |
| `@music-vine/cadence/tailwind.config` | Tailwind v3 preset (JavaScript) |
| `@music-vine/cadence/tailwind.config.v4` | Tailwind v4 config (CSS) |

## Components

The following components are available:

- **Layout**: Card, Separator, ScrollArea
- **Typography**: Text, Heading
- **Forms**: Button, Input, Textarea, Checkbox, RadioGroup, Select, Slider, Label
- **Feedback**: Toast, Badge, Skeleton
- **Overlay**: Dialog, Drawer, Popover, ContextMenu
- **Navigation**: Tabs, Accordion, Carousel, Breadcrumb

## Peer Dependencies

This package requires React 19+:

```json
{
  "react": "^19.0.0",
  "react-dom": "^19.0.0"
}
```

## Development

### Local Development

For local development within the monorepo, the package is automatically linked via pnpm workspaces.

```bash
# Build the package
pnpm build:packages

# Watch mode for development
pnpm dev:packages
```

### Storybook

View and develop components in isolation:

```bash
cd packages/cadence
pnpm storybook
```

### Creating a Release

1. Create a changeset when making changes:
   ```bash
   npx changeset
   ```

2. Select `@music-vine/cadence`, choose semver bump, write summary

3. Commit the changeset file with your changes

4. When merged to develop/main, GitHub Actions will create a release PR

5. Merging the release PR publishes to npm automatically

## License

Private package for Music Vine applications.