Installation

Installer la couche primitive en premierLien vers la section

Ce guide vous emmène d'une application React existante à un composant PyColors de style. Vous installerez les paquets, connecterez le CSS et vérifierez un petit écran dans votre propre application.

PréalablesLien vers la section

Avant l'installation, confirmez que l'application consommatrice a déjà:

• React et React DOM installés ;
• Tailwind CSS v4 configuré dans l'application stylesheet/build;
• une feuille de style globale où le token CSS peut être importé ;
• une configuration React ou Next.js qui prend en charge les packages ESM.

@pycolors/ui est Tailwind-friendly et token-driven. Les composants utilisent des utilitaires sémantiques comme bg-card, text-muted-foreground, border-borderet ring-ring. Ces utilitaires ont besoin de tokens de conception correspondants dans l'application de consommation.

Installer les packagesLien vers la section

Installez les primitives publiques et leurs tokens sémantiques ensemble. C'est la commande canonique first-install pour un projet pnpm.

pnpm add @pycolors/ui @pycolors/tokens

Utilisez l'équivalent npm install ou yarn add commande lorsque l'application n'utilise pas pnpm. Conservez les deux noms de paquet dans la commande afin que les composants et leur contrat de token arrivent ensemble.

Dépendances entre pairsLien vers la section

@pycolors/ui déclare ces dépendances entre pairs :

Le paquet README documente cette commande d'installation pour les dépendances de pairs :

pnpm add react react-dom lucide-react

Utilisez la commande équivalente npm ou yarn lorsque l'application n'utilise pas pnpm.

Ajouter des tokens de conceptionLien vers la section

La commande canonique install ci-dessus inclut @pycolors/tokens. Utilisez son token CSS lorsque votre application ne fournit pas déjà les variables sémantiques PyColors et les mappages Tailwind v4.

Dans une application Next.js avec un app/ à la racine du projet, ajoutez ce qui suit à votre feuille de style globale et importez cette feuille de style app/layout.tsx. Conservez tous les styles d'application existants après ces directives.

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

@source "../node_modules/@pycolors/ui/dist";
@custom-variant dark (&:where(.dark, .dark *));

@layer base {
  * {
    @apply border-border;
  }

  body {
    @apply bg-background text-foreground;
  }
}

Tailwind ignore node_modules lors de la détection automatique de la source. Les @source directive inclut les classes de composants installées afin que leurs utilitaires soient générés. Il s'agit d'un chemin d'analyse CSS; les importations JavaScript utilisent toujours uniquement @pycolors/ui.

Le chemin est relatif à la feuille de style. Pour src/app/globals.css, utiliser ../../node_modules/@pycolors/ui/dist Au lieu de cela. Dans d'autres configurations React, ajustez le chemin d'accès pour atteindre le package installé de l'application consommatrice et chargez cette feuille de style à partir du point d'entrée de l'application. N'ajoutez pas une seconde importation Tailwind si elle existe déjà.

Les règles de base appliquent les couleurs sémantiques des bordures et des pages. Fusionnez-les avec vos styles de base existants si l’application définit déjà ces rôles.

Le token CSS fournit:

• les variables CSS sémantiques telles que --background, --foreground, --card, --primary, --borderet --ring;
• valeurs claires et sombres à l'aide d'un .dark stratégie de classe;
• Tailwind v4 @theme inline mappages pour les utilitaires sémantiques.

Vérifier les composants dans StorybookLien vers la section

Utilisez le guide du consommateur Storybook pour rendre PyColors dans votre propre Storybook React/Vite avec des tokens, des utilitaires Tailwind générés et une barre d'outils claire/sombre. Pour des exemples sans configuration locale, ouvrez PyColors UI Explorer.

Importation à partir du point d'entrée publicLien vers la section

Importer des primitives prises en charge à partir @pycolors/ui.

Dans la même application Next.js, utilisez cette page pour vérifier l'installation. D’autres applications React peuvent effectuer le rendu du composant exporté à partir de leur route ou point d’entrée existant.

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

export default 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="https://pycolors.io/docs/ui/usage-patterns">
            Explore usage patterns
          </a>
        </Button>
      </CardContent>
    </Card>
  );
}

Ne pas importer à partir des internes du paquet.

Limites des composants serveur et clientLien vers la section

La composition primitive statique peut rester server-rendered dans une application Next.js App Router. Ajouter "use client" uniquement lorsque le fichier possède l'état du navigateur, les effets, les gestionnaires d'événements ou l'état interactif de superposition / toast.

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>
  );
}

Utilisez une limite client pour l'état d'interaction locale.

"use client";

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

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

Vérifier le premier écranLien vers la section

pnpm types:check
pnpm build

Erreurs courantesLien vers la section

Prochaines étapesLien vers la section