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

2. Add the Tailwind preset

In your tailwind.config.ts:

import murexPreset from "@murex/murex/preset";

export default {
  presets: [murexPreset],
};

3. Wire Tailwind v4 source detection

In your app CSS entry point:

@import "tailwindcss";
@import "tw-animate-css";
@config '../tailwind.config.ts';
@source '../node_modules/@murex/murex/src';

Adjust the relative paths for your project layout. The @config line loads the Murex preset; the @source line tells Tailwind v4 to scan Murex component source in node_modules, which Tailwind ignores by default.

4. Import styles

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

import "@murex/murex/styles";

5. Configure Next.js

In your next.config.ts:

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

export default nextConfig;

Usage

Import components and utilities directly from @murex/murex:

import { MxButton, MxInput, cn } from "@murex/murex";

Example:

import { MxButton } from "@murex/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 |

Corner geometry

Murex surfaces use Lisse's Figma curve with the explicit 0.6 smoothing preset. Their shadows are generated from the same path and remain synchronized with light/dark shadow tokens.

For progressive CSS-only geometry, use .superellipse with a rounded-* utility. The older .squircle class remains as a compatibility alias, but is deprecated because CSS corner-shape: superellipse(...) does not reproduce the Figma/Lisse curve exactly.

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

MxThemeProvider manages light/dark appearance and a separate color theme. In addition to the default Murex palette, the library ships the 24 traditional Chinese solar-term palettes from Colors of China.

import {
  MxThemeProvider,
  mxSolarTermThemes,
  useTheme,
  type MxColorTheme,
} from "@murex/murex";

export function Root({ children }: { children: React.ReactNode }) {
  return (
    <MxThemeProvider defaultTheme="system" defaultColorTheme="start-of-autumn">
      {children}
    </MxThemeProvider>
  );
}

function ThemePicker() {
  const { colorTheme, setColorTheme } = useTheme();
  return (
    <select
      value={colorTheme}
      onChange={(event) => setColorTheme(event.target.value as MxColorTheme)}
    >
      {mxSolarTermThemes.map(({ id, name, nameZh }) => (
        <option key={id} value={id}>
          {nameZh} · {name}
        </option>
      ))}
    </select>
  );
}

Color-theme selection is stored under mx-color-theme by default and exposed as data-mx-color-theme on the provider target. Each solar theme publishes its 16 source colors as --mx-theme-color-1 through --mx-theme-color-16, alongside accessible derived --ds-* component tokens. Use applyMxColorTheme() when a theme needs to be scoped to an element without React context.

For Consumer Apps (Next.js)

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

1. Install the package

   npm install @murex/murex

2. Add transpilePackages in next.config.ts:

   transpilePackages: ["@murex/murex"];

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

   import murexPreset from "@murex/murex/preset";
   
   export default {
     presets: [murexPreset],
   };

4. Update your Tailwind v4 CSS entry point:

   @import "tailwindcss";
   @import "tw-animate-css";
   @config '../tailwind.config.ts';
   @source '../node_modules/@murex/murex/src';

   @config replaces v3's automatic tailwind.config.ts discovery. @source replaces the old content path for Murex because Tailwind v4 skips node_modules unless a package is explicitly registered.

5. Import global styles in your root layout:

   import "@murex/murex/styles";

6. Use components:

   import { MxButton } from "@murex/murex";

After these six 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 |