Installation

Get started with Mordecai Design System in your React application.

ImportantPackage vs Copy-Paste

Mordecai is distributed as an NPM package, not a copy-paste CLI like shadcn/ui. You install components via npm install, not npx shadcn add.

Install the package

Install @corew500/ui and its peer dependencies.

npm install @corew500/ui react react-dom

Or with your preferred package manager:

pnpm add @corew500/ui

yarn add @corew500/ui

Import the styles

Import the CSS file in your app's entry point. This includes all design tokens, Tailwind utilities, and component styles.

// app/layout.tsx or _app.tsx
import '@corew500/ui/styles.css'

What's included?

Design tokens (colors, spacing, typography, etc.)
Tailwind CSS v4 base, components, and utilities
Custom component utilities (button sizes, input heights, etc.)
Light/dark theme support

Use components

Import and use components directly from the package.

import { Button, Card, CardContent, CardHeader } from '@corew500/ui'

export function MyComponent() {
  return (
    <Card>
      <CardHeader>Welcome</CardHeader>
      <CardContent>
        <Button variant="primary">Get Started</Button>
      </CardContent>
    </Card>
  )
}

Framework Setup

Next.js (App Router)

For Next.js 13+ with the App Router, add the styles import to your root layout:

// app/layout.tsx
import '@corew500/ui/styles.css'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

Next.js (Pages Router)

For Next.js with the Pages Router, add the styles import to _app.tsx:

// pages/_app.tsx
import '@corew500/ui/styles.css'
import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

Vite / Create React App

Add the styles import to your main entry file:

// main.tsx or index.tsx
import '@corew500/ui/styles.css'
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
)

Dark Mode

The design system supports dark mode out of the box. Add the dark class to your HTML element or use a theme provider like next-themes.

// With next-themes
import { ThemeProvider } from 'next-themes'

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system">
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

TypeScript Support

The package includes full TypeScript definitions. All components, props, and utilities are fully typed.

import type { ButtonProps } from '@corew500/ui'

// Component props are fully typed
const props: ButtonProps = {
  variant: 'primary',
  size: 'lg',
  loading: false,
}

CMS Integration (Optional)

For Payload CMS integration, install the CMS adapter package:

npm install @corew500/cms-payload

See the CMS Integration guide for detailed setup instructions.

Direct Token Access (Optional)

If you need programmatic access to design token values (e.g., for runtime calculations), import from the tokens package:

import { colors, spacing, breakpoints } from '@corew500/tokens'

// Access token values in JavaScript
console.log(spacing[4]) // "1rem"
console.log(breakpoints.md) // 768

Note: The tokens package is automatically installed with @corew500/ui.

Troubleshooting

Styles not loading?

Make sure you've imported @corew500/ui/styles.css in your app's entry point. The import must be at the top level, not inside a component.

TypeScript errors?

Ensure you're using TypeScript 5.0 or later. The package uses modern TypeScript features for better type inference.

Using Tailwind in your app?

See the Tailwind Setup guide for configuring Tailwind CSS v4 alongside the design system.