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

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:

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

import 'murex/styles';

4. Configure Next.js

In your next.config.ts:

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

export default nextConfig;

Usage

Import components and utilities directly from murex:

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

Example:

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:

npm run storybook

Opens on http://localhost:6006. Every component should have a corresponding story in stories/.

To build a static Storybook site:

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

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

   npm install murex

2. Add transpilePackages in next.config.ts:

   transpilePackages: ['murex']

3. Add the Tailwind preset in tailwind.config.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:

   import 'murex/styles';

5. Use components:

   import { MxButton } from 'murex';

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

Versioning

Murex follows Semantic Versioning (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 |