Installation

Install the primitive layer firstLink to section

@pycolors/ui is the public primitive package for PyColors product interfaces. Install it when you want reusable React primitives for SaaS surfaces such as forms, settings, dashboards, billing panels, overlays, and data views.

PrerequisitesLink to section

Before installing, confirm the consuming app already has:

• React and React DOM installed;
• Tailwind CSS available in the app stylesheet/build;
• a global stylesheet where token CSS can be imported;
• a React or Next.js setup that supports ESM packages.

@pycolors/ui is Tailwind-friendly and token-driven. Components use semantic utilities such as bg-card, text-muted-foreground, border-border, and ring-ring. Those utilities need matching design tokens in the consuming app.

Install packagesLink to section

Install @pycolors/ui with your package manager.

pnpm add @pycolors/ui

npm i @pycolors/ui

yarn add @pycolors/ui

Peer dependenciesLink to section

@pycolors/ui declares these peer dependencies:

The package README documents this install command for peer dependencies:

pnpm add react react-dom lucide-react

Use the equivalent npm or yarn command when the app does not use pnpm.

Add design tokensLink to section

Use @pycolors/tokens when your app does not already provide the PyColors semantic variables and Tailwind v4 mappings.

pnpm add @pycolors/tokens

npm i @pycolors/tokens

yarn add @pycolors/tokens

Import the token CSS once from your global stylesheet.

@import "@pycolors/tokens/tokens.css";

In the PyColors marketing app, this is done from apps/marketing/app/global.css.

The token CSS provides:

• semantic CSS variables such as --background, --foreground, --card, --primary, --border, and --ring;
• light and dark values using a .dark class strategy;
• Tailwind v4 @theme inline mappings for semantic utilities.

Import from the public entry pointLink to section

Import supported primitives from @pycolors/ui.

import {
  Button,
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@pycolors/ui";

export function FirstPyColorsCard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>PyColors UI installed</CardTitle>
        <CardDescription>
          Your app can now compose token-driven product primitives.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <Button asChild>
          <a href="/docs/ui/usage-patterns">Explore usage patterns</a>
        </Button>
      </CardContent>
    </Card>
  );
}

Do not import from package internals.

Server and client component boundariesLink to section

Static primitive composition can stay server-rendered in a Next.js App Router app. Add "use client" only when the file owns browser state, effects, event handlers, or interactive overlay/toast state.

import { Button, Card, CardContent, CardHeader, CardTitle } from "@pycolors/ui";

export function BillingCard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Billing ready</CardTitle>
      </CardHeader>
      <CardContent>
        <Button asChild>
          <a href="/settings/billing">Manage billing</a>
        </Button>
      </CardContent>
    </Card>
  );
}

Use a client boundary for local interaction state.

"use client";

import { Button } from "@pycolors/ui";

export function SaveButton() {
  return (
    <Button type="button" onClick={() => window.alert("Saved")}>
      Save
    </Button>
  );
}

Verify the first screenLink to section

pnpm --filter pycolors-marketing types:check
pnpm build

Common mistakesLink to section

Next stepsLink to section