puzzle / playgroundInteractive
Component showcase

Everything in its place.

A glimpse into what you can build.
PreferencesSwitch
Use dark appearance
Receive updates
TasksCheckbox
Project settingsInput
A modern React design system

A TypeScript-first
React design system.

Build accessible React interfaces with a carefully designed component system. Compose predictable building blocks, establish a consistent visual language and focus on creating great products.
✓TypeScript first✓Accessibility informed✓Open source
  • React

    Built for

    Modern React applications

  • TypeScript

    Designed with

    Typed, predictable APIs

  • MIT

    Licensed under

    Open-source ecosystem

  • Composable

    Built around

    Reusable building blocks

Why Puzzle

Less boilerplate.
More building.

The foundations of a great interface, thoughtfully implemented so you can focus on creating great products.
  • Designed to compose

    Build interfaces from small, predictable building blocks. Compose complex experiences without fighting the framework.

  • Accessibility informed

    Semantic markup, keyboard navigation, focus management and screen reader behavior are considered in the component design.

  • Developer experience

    TypeScript-first APIs, predictable behavior and a consistent design system make development enjoyable.

  • Flexible by design

    Use the pieces you need, customize the visual language and compose components around your own product requirements.

Reusable page sections

Go beyond components.
Compose the whole page.

Pieces brings responsive, theme-aware sections together into complete marketing pages, product experiences, and application layouts.
  • Marketing pages

    Compose heroes, feature grids, social proof, FAQs, and calls to action into a cohesive landing page.

  • Product experiences

    Bring product showcases, pricing, comparisons, and customer stories into a consistent visual system.

  • Application layouts

    Use reusable sections across content, commerce, business, and dashboard experiences.

Getting started

From installation to implementation.

Start with the foundation you need. Add more of the Puzzle ecosystem whenever your application calls for it.
  1. Install the packages

    Add the UI and theme packages to an existing React application, or generate a new project with the Puzzle CLI.

  2. Set up your design system

    Configure your theme, design tokens and application-wide styling to establish a consistent foundation.

  3. Compose your interface

    Combine accessible components and reusable pieces to build the experiences your product needs.

  4. Expand when you need to

    Explore additional packages for icons, hooks, SEO, authentication, storage and more.

A familiar React experience

Simple APIs. Composable interfaces.

Use Puzzle components directly in your React application. Start small and compose more complex interfaces as your product grows.
A simple componenttsxWelcome.tsx
import {  Button,  Card,  Heading,  Text,} from "@puzzle-ui/ui"; export function Welcome() {  return (    <Card>      <Heading level="headline2">        Welcome to Puzzle      </Heading>       <Text>        Build something wonderful.      </Text>       <Button variant="primary">        Get started      </Button>    </Card>  );}
Start building

Your project.
Your choice.

Whether you are starting from scratch or integrating Puzzle into an existing React application, there is a straightforward way to get started.
  • New projects

    Create a project with Puzzle

    Generate a new React application with the Puzzle ecosystem configured. Supports Next.js, TanStack Start and standard React with Vite.

    • Choose your preferred framework
    • Start with a configured project
    • Add the packages you need
  • Existing projects

    Add Puzzle to your application

    Install the UI and theme packages independently and start using components in your existing React project.

    • Install packages independently
    • Keep your existing application structure
    • Adopt Puzzle incrementally
Made for developers

Your ideas.
Without the friction.

Predictable APIs, powerful composition and a consistent design language. Puzzle gives you the building blocks to turn ideas into polished experiences.
  • TypeScript-first

    Excellent types and predictable APIs help you understand how components behave and how to compose them.

  • Flexible by design

    Customize and compose components to fit your product instead of adapting your product to a rigid component library.

  • Accessibility matters

    Thoughtful interaction patterns and semantic foundations are part of the component design process.

  • A consistent design language

    Shared theme tokens and reusable building blocks help keep your application visually coherent.

AI-READY DEVELOPMENT

Built for developers.
Ready for AI.

Puzzle is a TypeScript-first React design system for developers using AI coding agents. Its CLI reads guidance published with the Puzzle packages in your project, giving agents context for documented APIs and patterns. Keep your preferred agent; Puzzle provides context, not a replacement.

Explore the project generator
Installed Puzzle packages provide published instructions for your selected coding agent.
Example project dependenciespackage.json
@puzzle-ui/ui@puzzle-ui/theme@puzzle-ui/pieces

Guidance ships with each installed package

Published package guidanceAI CONTEXT
@puzzle-ui/uiPublic exports / documented props
@puzzle-ui/themeSemantic tokens / typed overrides
@puzzle-ui/piecesComposable sections / supported variants
Choose your agent
  • GitHub Copilot
  • Claude Code
  • Cursor
  • AGENTS.md-compatible agents
  • Package-aware AI instructions

    The CLI reads published guidance for your installed Puzzle dependencies, so agents get package-specific API context without one-size-fits-all prompts.

  • Your favorite coding agent

    Choose GitHub Copilot, Claude Code, Cursor, or AGENTS.md-compatible agents. Keep using the tools you already prefer.

  • Always in sync

    Run create-puzzle ai update after package changes; create-puzzle ai check verifies instructions against installed packages.

  • Local and developer-controlled

    Generated files stay in your project. Init, update, and check read installed guidance locally without calling remote AI or Puzzle services.

ADD PACKAGE CONTEXT, NOT ANOTHER AGENT

Initialize instructions for the Puzzle packages in your project, then update or check them as those packages change.

TerminalInitialize / update / check
  1. npx @puzzle-ui/create ai init
  2. create-puzzle ai update
  3. create-puzzle ai check

These commands run locally once installed. npx may need network access to fetch the CLI.

Frequently asked questions

A few things worth knowing.

Some quick answers to help you decide whether Puzzle is right for your next project.

Build with Puzzle

Make something
remarkable.

Explore the components, create your design system and bring your ideas to life.