Vue d’ensemble · Documentation

Système de conceptionFondations

Concevoir des produits cohérents avec PyColorsLien vers la section

PyColors UI n'est pas une collection de composants isolés. C'est un Système de décisions visuelles conçus pour assurer la cohérence des interfaces produits au fur et à mesure de leur croissance.

Le système de conception définit les règles derrière:

composants réutilisables
tableaux de bord de produits
pages de documentation
paramètres et surfaces de facturation
sections marketing
futurs modèles et starters SaaS

L’objectif est simple : les composants doivent rester petits car la fondation porte la complexité.

Pourquoi cela compte

La plupart des incohérences de produits ne proviennent pas d'un mauvais composant. Cela vient de nombreuses petites décisions locales qui s’éloignent lentement les unes des autres. PyColors empêche cela en déplaçant les décisions visuelles dans des rôles, des tokens et des règles partagés.

Ce que vous comprendrezLien vers la section

Couches système

Comprenez comment les tokens, les couleurs, la typographie et les composants fonctionnent ensemble au lieu de rivaliser localement.

Rôles sémantiques

Use meaning-driven utilities such as bg-card, text-muted-foreground, and border-border.

Cohérence du produit

Gardez PyColors lisible, premium et fiable sur les documents, les tableaux de bord et les pages commerciales.

ÉtapesLien vers la section

Commencez par les rôles, pas par les valeurs brutesLien vers la section

Les composants doivent consommer des rôles sémantiques au lieu de valeurs visuelles codées en dur.

components/product-card.tsx

export function ProductCard() {
  return (
    <article className="rounded-2xl border border-border bg-card p-6 text-card-foreground">
      <p className="text-sm text-muted-foreground">
        Production-shaped SaaS foundation
      </p>
      <h2 className="mt-2 text-xl font-semibold tracking-tight">Starter Pro</h2>
    </article>
  );
}

Cela maintient le composant stable lorsque le thème évolue. Le composant n'a pas besoin de connaître la couleur exacte, le rayon ou la valeur de contraste. Il a juste besoin de savoir quel rôle il doit jouer.

Utilisation	Éviter
`bg-card`	valeurs hexadécimales codées en dur
`text-muted-foreground`	valeurs d'opacité uniques
`border-border`	Couleurs de frontière locales
tokens de rayon partagé	Valeurs de coin arbitraires

Garder une source de véritéLien vers la section

Les décisions visuelles globales doivent être prises une fois, puis réutilisées partout.

Cela comprend :

rayon
ombres
Rôles de couleur
Hiérarchie typographique
focus states
densité de surface du produit

styles/globals.css

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-primary: var(--primary);
  --color-border: var(--border);
}

Note d ' exécution

Un système de conception devient utile lorsque vous changez un token pour mettre à jour plusieurs surfaces de manière cohérente. C’est la différence entre un thème et une collection de styles locaux.

Construire de petites primitives sur des fondations solidesLien vers la section

Les primitives PyColors restent intentionnellement petites car le système en dessous définit déjà le comportement visuel.

Tokens

Définissez la géométrie, l'élévation, la direction d'espacement et les futures échelles visuelles.

Rôles

Définir le sens des surfaces, du texte, des frontières, des états et des actions.

Composants

Composer des rôles dans des primitives d'interface utilisateur réutilisables et des modèles de produits.

Couches systèmeLien vers la section

PyColors est organisé comme un système à plusieurs couches. Chaque couche a une responsabilité claire et ne doit pas remplacer la couche en dessous.

Couche	Responsabilité	Exemple
Tokens	Décisions visuelles atomiques	rayon, ombres, échelles futures
Couleurs	Rôles de couleurs sémantiques	`background`, `card`, `primary`, `muted`
Typographie	Hiérarchie lisible	en-têtes, corps de texte, étiquettes, métadonnées
Composants de l'interface utilisateur	primitives réutilisables	boutons, cartes, entrées, dialogues
Schémas de produits	Flux composés	tableaux de bord, paramètres, facturation, onboarding

Pourquoi cela compte

Lorsque chaque couche a une responsabilité claire, les composants deviennent plus faciles à raisonner. Vous savez où changer le système au lieu de corriger le symptôme localement.

Guide de décisionLien vers la section

Utilisez le système de conception lorsque :

une décision visuelle apparaît à plus d'un endroit
un composant doit prendre en charge le mode clair et sombre
Une page doit être cohérente avec le reste du produit.
un motif sera réutilisé dans des documents, des entrées ou des pages commerciales
la décision affecte la confiance, la lisibilité ou le polissage du produit

Évitez les remplacements locaux lorsque :

la valeur est purement décorative
La même exception existe déjà ailleurs
Le changement affaiblit la signification sémantique
le contournement rend la thématisation plus difficile
le code devient plus difficile à maintenir que la règle du système

Préférez

Les rôles sémantiques sur les valeurs brutes
tokens pour des décisions visuelles répétées
petites primitives avec un comportement prévisible
Règles de couleur et de typographie centralisées
documentation qui explique l'intention du système

Éviter

couleurs codées en dur à l'intérieur des composants réutilisables
Rayon unique et valeurs d'ombre
échelles typographiques locales par page
utiliser les couleurs des graphiques comme états d'interface
dupliquer les décisions visuelles dans les zones de produits

Chemin de lectureLien vers la section

Suivez cet ordre pour comprendre le système de la fondation à la mise en œuvre.

TokensCommencez par les décisions atomiques qui alimentent le système visuel.ArrondiDécouvrez comment la géométrie d'angle maintient les surfaces et les contrôles cohérents.OmbresComprendre les règles d'élévation pour une profondeur calme et prévisible.CouleursUtilisez des rôles sémantiques pour les surfaces, le texte, les états et le thème.TypographieDéfinissez la hiérarchie, le rythme, les étiquettes et la structure du produit lisible.

Là où cela convientLien vers la section

PyColors est structuré en couches de produits :

Couche de produit	Objet
Système de conception	Règles, tokens, rôles et fondations visuelles
composants UI	primitives réutilisables construites au-dessus du système
Motifs	Guide de composition pour les surfaces réelles du produit
Starter Free	UX adaptée au produit pour validation
Starter Pro	fondations SaaS adaptées à la production avec auth, facturation, backend et livraison

Le système de conception est la couche la plus profonde de cet empilement. Il protège la cohérence avant que la complexité du produit n'augmente.

Prêt à transformer le système en fondation de lancement ?

Passez des fondations visuelles à la mise en œuvre du produit avec Starter Pro. /docs/starter-pro

Questions courantesLien vers la section

Prochaines étapesLien vers la section

TokensCommencez par les décisions visuelles atomiques derrière PyColors UI.CouleursDécouvrez comment les couleurs sémantiques maintiennent les surfaces, le texte et les états cohérents.TypographieRevoir la hiérarchie, les étiquettes, la densité et la copie lisible du produit.composants UIPassez des fondations aux primitives réutilisables construites avec PyColors UI.