Vue d’ensemble
Des tokens de conception atomique qui définissent les fondations visuelles de PyColors UI.
La base de chaque interfaceLien vers la section
Les tokens de conception sont les Une seule source de vérité pour le langage visuel de PyColors UI.
Ils encodent les petites décisions que chaque composant peut consommer :
- rayon
- dénivelé
- Rôles de couleur
- rôles typographiques
- futures règles de mouvement, d'espacement et de superposition
Les tokens ne sont pas des composants. Ce ne sont pas des valeurs CSS aléatoires. Ils sont décisions de conception exprimées en variables réutilisables.
Pourquoi cela compte
Sans tokens, chaque composant commence lentement à prendre ses propres décisions visuelles. Cela crée une dérive, rend les refactors risqués et affaiblit le sentiment de prime du produit au fil du temps.
Ce que les tokens contrôlentLien vers la section
Géométrie
Élévation
Intention du système
Jumeler les surfaces avec leurs tokens de premier planLien vers la section
Utilisation primary avec primary-foregroundet destructive avec destructive-foreground. Leurs premiers plans utilisent du texte sombre en mode sombre parce que ces surfaces sémantiques deviennent plus claires; le texte blanc codé en dur ne conserve pas de contraste lisible. Le mode lumière muted-foreground supporte également le texte sur la surface en sourdine. Les palettes personnalisées, l'opacité et les arrière-plans superposés nécessitent toujours des contrôles de contraste dans leur contexte réel.
ÉtapesLien vers la section
Commencez par les décisions de conceptionLien vers la section
Un token existe lorsqu'une décision visuelle doit être partagée par le système.
Au lieu de demander à chaque composant de décider de son propre rayon, ombre ou traitement de surface, PyColors définit ces décisions une fois.
Design decisions
↓
Tokens
↓
Tailwind utilities
↓
UI components
↓
Product surfacesCe flux maintient les composants petits pendant que le système reste expressif.
Définir les tokens de manière centraliséeLien vers la section
Les tokens sont définis comme des variables CSS et mappés dans des utilitaires.
:root {
--radius: 0.625rem;
}
@theme inline {
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
}La valeur brute reste dans la couche de token. Les composants consomment l'utilité.
export function ProductCard() {
return (
<article className="rounded-lg border bg-card p-6 shadow-sm">
<h2 className="text-lg font-semibold tracking-tight">Product surface</h2>
<p className="mt-2 text-sm leading-6 text-muted-foreground">
This surface consumes tokens indirectly through utilities.
</p>
</article>
);
}Étendre uniquement lorsque le système en a besoinLien vers la section
Toutes les valeurs visuelles n’ont pas besoin de devenir un token le premier jour.
Un nouveau token devrait exister lorsqu'il :
- apparaît à plusieurs endroits
- exprime une décision de produit réutilisable
- améliore le thème ou la cohérence
- réduit le style local dupliqué
- Rendre les changements futurs plus sûrs
Règle du système
Identifiez les décisions de conception répétées, pas les préférences visuelles uniques.
Catégories de tokensLien vers la section
PyColors commence intentionnellement avec une petite surface de token. Cela permet de garder le système compréhensible et évite l'étalement des tokens trop tôt.
| Catégorie | Objet | Situation actuelle |
|---|---|---|
| Arrondi | Géométrie d'angle pour les commandes, les cartes et les superpositions | Actif |
| Ombres | Élévation pour surfaces et couches flottantes | Actif |
| Couleurs | Rôles sémantiques de surface, de texte, d'état et de graphique | Actif |
| Typographie | Rôles de police, hiérarchie, étiquettes et densité | Actif |
| Espacement | Rythme et densité de mise en page du produit | Futurs |
| Motion | Transitions, assouplissement et interaction | Futurs |
| Z-index | Règles de superposition pour les superpositions et la navigation | Futurs |
Pourquoi la surface est intentionnellement petite
Un système de tokens plus petit est plus facile à comprendre, à documenter et à maintenir. PyColors ajoute des tokens quand ils clarifient le système, pas quand ils créent du vocabulaire supplémentaire.
Guide de décisionLien vers la section
Utilisez un token lorsque :
- la valeur apparaît sur plusieurs composants
- Le changer à l'échelle mondiale serait utile
- la valeur porte la signification du produit
- il améliore la cohérence à travers le mode clair et sombre
- il empêche les équipes d’inventer des alternatives locales
Évitez de créer un token lorsque :
- la valeur est purement décorative
- Il n'apparaît qu'une seule fois
- Le nom serait vague
- le token duplique un rôle existant
- Cela rend le système plus difficile à comprendre
Préférez
- tokens pour des décisions visuelles répétées
- les noms sémantiques qui décrivent l'intention
- Valeurs centralisées exposées par les utilitaires
- petites échelles faciles à retenir
- documentation qui explique quand utiliser chaque token
Éviter
- tokeniser chaque valeur unique
- Les noms qui ne décrivent que l'apparence
- Dupliquer les rôles sémantiques existants
- valeurs de token de hardcoding à l'intérieur des composants
- ajouter des balances avant que le produit n'en ait besoin
Flux de tokensLien vers la section
1
Décision
Le système a besoin d'une sensation de coin cohérente.
2
Token
--radius-lg définit la géométrie partagée.
3
Utilité
rounded-lg expose le token aux composants.
4
Surface
Les cartes, les dialogues et les panneaux sont liés.