npm package: @murex/murex
Description: Murex — Shared UI library and design system by Muse
Latest version: 0.3.2

# Murex

Shared UI component library and design system built by Muse. Ships as a TypeScript source package consumed by Scarlett, Cracked, and future Muse products.

---

## Quick Start

### 1. Install

```bash
npm install murex
```

> **Note:** Murex is currently distributed via GitHub Packages as `@museio/murex`. Configure your `.npmrc` accordingly.

### 2. Add the Tailwind preset

In your `tailwind.config.ts`:

```ts
import murexPreset from 'murex/preset';

export default {
  presets: [murexPreset],
  content: [
    // ... your app's content paths
    './node_modules/murex/src/**/*.{ts,tsx}',
  ],
  // ... rest of your config
};
```

### 3. Import styles

In your root layout (e.g. `app/layout.tsx`):

```ts
import 'murex/styles';
```

### 4. Configure Next.js

In your `next.config.ts`:

```ts
const nextConfig = {
  transpilePackages: ['murex'],
  // ...
};

export default nextConfig;
```

---

## Usage

Import components and utilities directly from `murex`:

```tsx
import { MxButton, MxInput, cn } from 'murex';
```

Example:

```tsx
import { MxButton } from 'murex';

export function SaveForm() {
  return (
    <MxButton variant="primary" onClick={() => save()}>
      Save Changes
    </MxButton>
  );
}
```

---

## What's Included

### Primitives (26 components)

Core UI building blocks.

| Component | Component | Component |
| --- | --- | --- |
| MxButton | MxInput | MxInputBase |
| MxTextareaBase | MxCheckbox | MxRadioButton |
| MxRadioBox | MxToggle | MxTab |
| MxTooltip | MxTooltipWrapper | MxLabel |
| MxBottomText | MxDropdown | MxDropdownBase |
| MxDropdownContainer | MxDropdownItem | MxLargePicker |
| NewSmallPicker | NewPickerCell | Card |
| Dialog | Select | Slider |

### Structure (18 components)

Generic structural and layout components.

| Component | Component | Component |
| --- | --- | --- |
| Toast | MxModal | ProgressBar |
| EmptyState | Titlebar | VideoThumbnail |
| ChecklistItem | ConnectionCard | TaskCard |
| FormSection | PageSectionCard | SectionCard |
| ActionHeader | PageHeader | MobilePageHeader |
| CenteredFlowShell | DesktopOnlyPageShell | ResponsivePageShell |

### Loading (3 components)

| Component | Description |
| --- | --- |
| LoadingSpinner | Inline spinner |
| LoadingSpinnerBlur | Full-area spinner with blur overlay |
| LottieLoading | Lottie-animated loading state |

### Design Tokens

- **180+** semantic color tokens
- **6** color scales
- Opacity scales
- All delivered as CSS custom properties (`--mx-*`, `--murex-*`)

### Typography

**48+** text style utilities covering heading, subheading, body, and subtitle variants.

### Shadows

**60+** box-shadow utilities for elevation and depth.

### Utilities

| Export | Description |
| --- | --- |
| `cn()` | Merges class names via `clsx` + `tailwind-merge` |
| Shared types | Common TypeScript types used across components |

---

## Project Structure

```
murex/
  src/
    components/
      primitives/          Core UI primitives
      structure/           Generic structural components
      content/             Loading states
    styles/                CSS tokens and global styles
    fonts/                 Circular XX font files
    lib/                   Utilities (cn)
    types/                 Shared TypeScript types
    index.ts               Main entry point
    preset.ts              Tailwind preset
  stories/                 Storybook stories
  tokens/                  Figma JSON token files
  scripts/                 Figma-to-code pipeline
  .storybook/              Storybook configuration
```

---

## Storybook

Storybook is the canonical design system documentation. Run it locally:

```bash
npm run storybook
```

Opens on [http://localhost:6006](http://localhost:6006). Every component should have a corresponding story in `stories/`.

To build a static Storybook site:

```bash
npm run build-storybook
```

---

## Design Tokens and Figma Pipeline

Design tokens originate in Figma and flow into code through an automated pipeline.

### Token files

Raw token data lives in `tokens/` as Figma Variables JSON exports.

### Regenerating tokens

```bash
npm run generate-colors
```

This compiles and runs the conversion script, producing `scripts/generated-colors.ts`. That generated file feeds directly into the Tailwind preset (`src/preset.ts`), which makes every token available as a Tailwind utility.

### Full workflow

1. Export variables from Figma as JSON (ZIP).
2. Drop the ZIP file(s) into `scripts/input/`.
3. Run `npm run generate-colors`.
4. Tokens propagate into the Tailwind preset and CSS custom properties automatically.

---

## Theming

Murex supports multiple themes via CSS custom properties defined in `src/styles/design-system-tokens.css`. The library currently ships a single purple theme.

### Adding a new theme

1. Create a new CSS file (e.g. `src/styles/theme-blue.css`).
2. Override the `--mx-*` and `--murex-*` custom properties with your theme's values.
3. Import the new theme file in place of (or in addition to) the default styles.

All components reference tokens through custom properties, so swapping values at the CSS layer updates the entire UI without touching component code.

---

## For Consumer Apps (Next.js)

Full setup checklist for integrating Murex into a Next.js application:

1. **Install the package**

   ```bash
   npm install murex
   ```

2. **Add `transpilePackages`** in `next.config.ts`:

   ```ts
   transpilePackages: ['murex']
   ```

3. **Add the Tailwind preset** in `tailwind.config.ts`:

   ```ts
   import murexPreset from 'murex/preset';

   export default {
     presets: [murexPreset],
     content: [
       './app/**/*.{ts,tsx}',
       './components/**/*.{ts,tsx}',
       './node_modules/murex/src/**/*.{ts,tsx}',
     ],
   };
   ```

4. **Import global styles** in your root layout:

   ```ts
   import 'murex/styles';
   ```

5. **Use components**:

   ```tsx
   import { MxButton } from 'murex';
   ```

After these five steps, all Murex components, tokens, and utilities are available throughout your app.

---

## Versioning

Murex follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PATCH):

| Change type | Version bump | Example |
| --- | --- | --- |
| Breaking API change (renamed prop, removed component) | **Major** | 1.0.0 -> 2.0.0 |
| New component or feature | **Minor** | 1.0.0 -> 1.1.0 |
| Bug fix or style tweak | **Patch** | 1.0.0 -> 1.0.1 |

---

## Development

### Scripts

| Script | Command | Description |
| --- | --- | --- |
| Storybook | `npm run storybook` | Start Storybook dev server on port 6006 |
| Type check | `npm run type-check` | Run `tsc --noEmit` across the project |
| Generate colors | `npm run generate-colors` | Regenerate tokens from Figma exports |
| Format | `npm run format` | Format source files with Prettier |
| Lint | `npm run lint` | Run ESLint |
| Lint (fix) | `npm run lint:fix` | Run ESLint with auto-fix |
| Format (check) | `npm run format:check` | Check formatting without writing |