Getting Started

Puzzle is a TypeScript and React UI component library built around reusable components and shared design tokens. Its components are composable and router-independent, with styling supplied by @puzzle-ui/theme.

PrerequisitesCopy Anchor Link

• A package manager: npm, Bun, pnpm, or Yarn.
• An existing React application with a bundler that supports CSS imports, such as Vite.
• React and React DOM 19.

Install PuzzleCopy Anchor Link

Install the UI and theme packages in your application's directory.

npm install @puzzle-ui/ui @puzzle-ui/theme

These commands install published packages. They do not clone the repository or build its workspaces. Puzzle does not require Bun in your application.

Your first interfaceCopy Anchor Link

Import components from @puzzle-ui/ui and wrap your application in Theme from @puzzle-ui/theme.

import { Theme } from "@puzzle-ui/theme";
import { Button } from "@puzzle-ui/ui";

export const App = () => (
  <Theme theme="system">
    <main>
      <h1>Hello, Puzzle</h1>
      <p>Build your interface with reusable components and shared tokens.</p>
      <Button onClick={() => window.alert("Welcome to Puzzle!")}>
        Get started
      </Button>
    </main>
  </Theme>
);

Theme applies the default tokens and global styles, and follows the user's system light/dark preference. Use one root theme for your application.

Component styles are imported by the components themselves. Your application bundler must support CSS imports.

See Button for variants, sizes, and API details.

Customize your themeCopy Anchor Link

Set the color mode, choose a color palette, load fonts, or override individual tokens.

<Theme
  theme="system"
  colorTheme="cobalt-sky"
  fonts={{
    heading: { family: "Inter" },
    body: { family: "Inter" },
  }}
  tokens={{
    radius: { md: "0.5rem" },
  }}
>
  <AppContent />
</Theme>

Font configuration can load stylesheets from Google Fonts. Omit fonts if you do not want external font requests.

In your own CSS, use the same semantic tokens as Puzzle components.

.welcome-panel {
  color: var(--puzzle-color-text);
  background: var(--puzzle-color-surface);
  padding: var(--puzzle-space-4);
  border-radius: var(--puzzle-radius-md);
}

Read the Theme overview, Theme Provider, and Design Tokens guides for configuration details.

Build your applicationCopy Anchor Link

Puzzle ships compiled JavaScript and CSS, so you do not need to build the library yourself. Use your application's existing build script.

npm run build

Your application must retain CSS imports when bundling Puzzle. No separate Puzzle stylesheet import or Tailwind setup is required.

Framework and server-rendering compatibility is still being evaluated. Test your chosen components in your application's environment.

Next stepsCopy Anchor Link

• Explore Buttons, Cards, and Text Inputs.
• Learn how to configure colors and typography and fonts.
• Try the interactive documentation examples before composing a larger interface.
• Use the project generator to scaffold a new application.