pencil-generate-library : jetons, thèmes et composants dans l'ordre
Construisez un système de design dans un fichier .pen qui correspond au code. Chargez d'abord pencil-use : il contient les règles d'execute. Cette skill contient l'ordre du travail et les décisions de conception.
1. La règle la plus importante
Ce n'est jamais un seul appel. Un petit système nécessite 15 à 40 appels execute, un plus grand beaucoup plus. Travaillez par plus petite unité utile, vérifiez-la, montrez-la, puis continuez. Un système construit en un long extrait arrive cassé et est difficile à réparer.
2. En quoi Pencil diffère des autres outils
Planifiez avec le modèle réel de Pencil, pas un emprunté ailleurs :
| Besoin | Dans Pencil |
|---|---|
| Jetons | Variables variables de type color, number, string, boolean, référencées comme $name |
| Modes (clair, sombre) | Axes de thème. La valeur d'une variable est une liste de {value, theme: {mode: "dark"}} ; un cadre choisit une valeur avec sa propriété theme |
| Alias (sémantique vers primitif) | Une variable dont la valeur est une autre variable : value: "$gray-900" |
| Styles de texte | Aucun. Utilisez des variables de police (famille, taille, hauteur de ligne, poids comme chaînes ou nombres) et, si utile, de petits composants de texte |
| Styles d'ombre | Aucun. Les effets d'ombre acceptent des variables pour la couleur, le flou et le décalage |
| Composant | Tout nœud avec reusable: true |
| Variantes | Pas d'ensembles de variantes. Un composant par variante, nommé avec des barres obliques : Button/Primary, Button/Outline |
| Option booléenne (afficher l'icône) | Remplacement d'instance enabled: false sur cette partie |
| Icône échangeable | Remplacement d'instance sur le nœud d'icône : {icon: "plus"} |
| Contenu échangeable | Un cadre slot à l'intérieur du composant, avec des identifiants de composants recommandés |
| Bibliothèque partagée | Un fichier converti en .lib.pen dans l'application (unidirectionnel, ne peut pas être annulé), importé par les fichiers d'écran |
3. Workflow
Phase 0 DÉCOUVERTE lire le code et le fichier, pas d'écriture -> point de contrôle : plan approuvé
Phase 1 FONDATIONS variables et thèmes -> point de contrôle : résumé des jetons approuvé
Phase 2 MISE EN PAGE zones sur le canevas, tableau des fondations -> point de contrôle : capture d'écran du tableau approuvée
Phase 3 COMPOSANTS un à la fois, atomes avant molécules -> point de contrôle après chaque composant
Phase 4 QA ET BIBLIOTHÈQUE audits, corrections, .lib.pen optionnel -> point de contrôle : validation
Nommez la phase suivante à chaque point de contrôle. Un « ça a l'air bien » à propos des jetons n'est pas une autorisation pour commencer les composants.
Phase 0. Découverte (lecture seule)
0a. Trouvez les jetons dans le code, dans cet ordre :
- Propriétés personnalisées CSS (
:root { --background: ... },.dark { ... }ou[data-theme="dark"]). - Configuration Tailwind ou blocs
@themeTailwind v4. - Fichiers de jetons (DTCG
.tokens.json, Style Dictionary). - Objets de thème dans CSS-in-JS, ou fichiers de thème natifs (catalogues d'actifs iOS,
colors.xmlAndroid).
Notez le mécanisme du mode sombre, les échelles d'espacement et de rayon, les polices et l'échelle typographique, et les ombres.
0b. Trouvez les composants dans le code : la liste des primitives UI (Button, Input, Checkbox, Badge, Avatar, Card...), leurs props, lesquelles sont des variantes (variant, size, state), lesquelles sont des booléennes, lesquelles prennent des enfants.
0c. Lisez le fichier :
Print(GetVariables())
Get(n => n.reusable && Print(n.id, "|", n.name))
Get(document, (n, c) => { if (c.depth === 1) { Print(n.id, "|", n.type, "|", n.name); c.skipChildren() } })
Vérifiez aussi get_app_state pour les bibliothèques importées. Faites correspondre toute nomenclature déjà présente dans le fichier.
0d. Verrouillez le périmètre avec l'utilisateur : la liste exacte des jetons et la liste exacte des composants pour cette session. Un premier cycle de six à dix composants est une bonne taille.
0e. Faites correspondre le code à Pencil et résolvez les conflits. Présentez un tableau :
Jeton code Variable Pencil Light Dark Statut
--background --background #FFFFFF #0A0A0A nouveau
--primary --primary #1D4ED8 #3B82F6 existe, valeur différente (demander)
Composant Composants Pencil Statut
Button variant x size Button/Primary, Button/Secondary, Button/Outline, Button/Ghost (taille via axe de thème) nouveau
Quand le code et le fichier sont en désaccord, demandez qui gagne. Ne décidez pas seul.
Point de contrôle : montrez le plan, attendez l'approbation.
Phase 1. Fondations
Nommage. Gardez les noms du code pour que le design et le code puissent faire un aller-retour : une variable CSS --muted-foreground devient la variable Pencil --muted-foreground, référencée comme $--muted-foreground. Ne commencez jamais un nom par $. Évitez : dans les noms. Si le code n'a pas de noms, utilisez des noms courts en kebab-case par rôle : surface, text, text-muted, border, accent, space-4, radius-md.
Couches.
- Primitives : valeurs brutes, sans thème (
gray-50...gray-950,blue-500,space-1...space-16). - Sémantiques : noms de rôle, thématisées, pointant vers des primitives (
--background: light$white, dark$gray-950). - Les composants utilisent uniquement les sémantiques. Un composant qui référence
$gray-900directement ne changera pas avec le thème.
Taille du système.
- En dessous d'environ 50 jetons : un ensemble plat, un axe
modeaveclightetdark. - Plus grand : primitives plus sémantiques comme ci-dessus, et des axes de thème supplémentaires uniquement si le code en a vraiment (
density: comfortable, compact;brand: a, b).
Écrivez par petits lots, une famille par appel (couleurs primitives, puis couleurs sémantiques, puis espacement et rayon, puis typographie), et relisez :
SetVariables({
"gray-50": {type: "color", value: "#FAFAFA"},
"gray-900": {type: "color", value: "#171717"},
"gray-950": {type: "color", value: "#0A0A0A"},
"white": {type: "color", value: "#FFFFFF"}
})
SetVariables({
"--background": {type: "color", value: [{value: "$white", theme: {mode: "light"}}, {value: "$gray-950", theme: {mode: "dark"}}]},
"--foreground": {type: "color", value: [{value: "$gray-900", theme: {mode: "light"}}, {value: "$gray-50", theme: {mode: "dark"}}]}
})
const v = GetVariables()
Print(Object.keys(v.variables).length, "variables", "|", JSON.stringify(v.themes))
- Vérifiez que la première valeur de l'axe
modeest celle par défaut que le produit utilise (généralementlight). - Donnez à chaque variable thématisée une valeur pour chaque valeur de thème que vous utilisez. Une valeur manquante affiche silencieusement la mauvaise couleur.
- Gardez les valeurs identiques entre les thèmes lorsqu'elles ne doivent pas changer (espacement, rayon).
- Typographie :
--font-sans(chaîne), tailles (text-sm14,text-base16...), hauteurs de ligne sous forme de ratios (leading-normal1.5), poids sous forme de chaînes ("400","600"). - Ombres : une variable de couleur thématisée pour l'ombre et des variables numériques pour le flou et le décalage si le code a une échelle d'ombre.
- Ne jamais
SetVariables(..., true)sur un fichier existant sans consentement explicite : cela efface toutes les variables.
Critères de sortie : chaque jeton du plan existe avec le bon type, chaque jeton thématisé a toutes les valeurs de thème, les alias pointent vers des variables existantes.
Point de contrôle : montrez le nombre par famille, les axes de thème, et toute valeur que vous avez dû deviner.
Phase 2. Mise en page du fichier et tableau des fondations
Gardez le canevas lisible :
- Un cadre Foundations en haut à gauche : échantillons de couleurs, spécimens typographiques, barres d'espacement, échantillons de rayon.
- Une zone Components à sa droite ou en dessous, un cadre par famille de composants (
Buttons,Inputs,Cards), contenant les composants avec un titre et une courte note d'utilisation. - Screens plus bas et à droite, jamais mélangés avec les composants.
- Utilisez
FindEmptySpacepour chaque cadre racine.
Les échantillons et spécimens doivent être liés aux variables, afin que le tableau se mette à jour lorsqu'un jeton change. Construisez les échantillons avec une boucle :
boardId = Insert(document, {type: "frame", name: "Foundations / Color", layout: "vertical", gap: 16, padding: 32, fill: "$--background", x: 0, y: 0})
rowId = Insert(boardId, {type: "frame", name: "Semantic colors", gap: 16})
for (const name of ["--background", "--foreground", "--primary", "--muted", "--border"]) {
const s = Insert(rowId, {type: "frame", name: "Swatch " + name, layout: "vertical", gap: 8})
Insert(s, {type: "rectangle", name: "Chip", width: 96, height: 64, cornerRadius: 8, fill: "$" + name, stroke: "$--border", strokeWidth: 1})
Insert(s, {type: "text", name: "Label", content: name, fontSize: 12, fill: "$--foreground"})
}
TakeScreenshot([boardId])
Copiez ensuite le tableau avec theme: {mode: "dark"} à côté : si quoi que ce soit reste clair, il manque une valeur sombre à un jeton.
Point de contrôle : capture d'écran des tableaux dans les deux thèmes.
Phase 3. Composants, un à la fois
Ordre par dépendance : atomes d'abord (wrappers d'icône, Badge, Avatar, Button, Input, Checkbox, Toggle), puis molécules (groupe d'Input avec étiquette et indication, élément de Menu, Tab), puis organismes (Card, Dialog, Sidebar, ligne de Table). Un composant qui en contient un autre doit être construit après lui, et doit contenir une instance de celui-ci, pas une copie redessinée.
Pour chaque composant :
3a. Concevez l'API avant de dessiner. D'après les props du code :
- Les axes de variantes qui changent la couleur ou la structure deviennent des composants séparés :
Button/Primary,Button/Secondary,Button/Outline,Button/Ghost,Button/Destructive. - Les axes qui ne font que changer les valeurs des jetons (taille, densité) peuvent être un axe de thème au lieu de plus de composants : des variables numériques thématisées comme
button-padding-yetbutton-padding-xavecsize: md, sm, lg(la première valeur est la valeur par défaut). Un seul composant sert alors chaque taille viatheme: {size: "sm"}sur l'instance. Testé et fonctionnel. Utilisez-le quand le code fonctionne de la même manière ; sinon, créez aussi des composants de taille. - Un commutateur global (afficher ou masquer tous les badges dans les maquettes) peut être une variable booléenne liée à
enabled: "$show-badge". Cela change chaque instance à la fois, alors réservez-le pour les toggles de démonstration, pas pour les options par instance. - Gardez le nombre raisonnable. Si le nombre de variantes fois tailles fois états dépasse environ 30 composants, divisez la famille ou déplacez un axe vers un thème.
- États : un composant
DisabledouFocusseulement lorsque l'utilisateur souhaite les afficher ; le survol et l'enfoncement sont souvent seulement documentés. - Les booléennes (avec icône, avec indication) ne sont pas des variantes : construisez le composant complet et masquez les parties par instance avec
enabled: false. - Les icônes ne sont pas des variantes : un nœud d'icône, échangé avec un remplacement
icon. - Les zones de contenu libre sont des slots : un cadre avec
slot: [recommendedComponentIds],width: "fill_container"et une hauteur fixe (par exempleheight: 40). Un slot vide dimensionné parfit_contentse réduit à zéro et disparaît.
3b. Construisez le composant de base en un seul appel : un cadre avec reusable: true, mise en page, remplissage, espacement, rayon et remplissages tous issus de variables, des enfants nommés (Label, Icon, Content). Capturez son identifiant et les identifiants de ses enfants dans des variables globales.
const pos = FindEmptySpace({width: 600, height: 200, direction: "right", padding: 80})
buttonsId = Insert(document, {type: "frame", name: "Buttons", layout: "vertical", gap: 24, padding: 32, x: pos.x, y: pos.y})
btnPrimaryId = Insert(buttonsId, {type: "frame", name: "Button/Primary", reusable: true, gap: 8, padding: ["$button-padding-y", "$button-padding-x"], cornerRadius: "$radius-md", fill: "$--primary", alignItems: "center", justifyContent: "center"})
btnIconId = Insert(btnPrimaryId, {type: "icon", name: "Icon", library: "lucide", icon: "plus", width: 16, height: 16, fill: "$--primary-foreground"})
btnLabelId = Insert(btnPrimaryId, {type: "text", name: "Label", content: "Button", fontFamily: "$--font-sans", fontSize: "$text-sm", fontWeight: "500", fill: "$--primary-foreground"})
TakeScreenshot([btnPrimaryId])
3c. Construisez les autres variantes. Copy d'un composant crée une instance, pas un nouveau composant. Pour obtenir des composants de variantes indépendants, reconstruisez chacun avec une petite fonction d'aide à l'intérieur d'un seul appel, en bouclant sur un tableau de variantes :
const make = (name, fill, fg, stroke) => {
const id = Insert(buttonsId, {type: "frame", name, reusable: true, gap: 8, padding: ["$button-padding-y", "$button-padding-x"], cornerRadius: "$radius-md", fill, alignItems: "center", justifyContent: "center", ...(stroke ? {stroke, strokeWidth: 1} : {})})
Insert(id, {type: "icon", name: "Icon", library: "lucide", icon: "plus", width: 16, height: 16, fill: fg})
Insert(id, {type: "text", name: "Label", content: "Button", fontFamily: "$--font-sans", fontSize: "$text-sm", fontWeight: "500", fill: fg})
return id
}
btnSecondaryId = make("Button/Secondary", "$--secondary", "$--secondary-foreground")
btnOutlineId = make("Button/Outline", "$--background", "$--foreground", "$--border")
btnGhostId = make("Button/Ghost", "#00000000", "$--foreground")
Gardez les noms des enfants identiques entre les variantes (Label, Icon) afin que les instances puissent être remplacées par nom et qu'un changement de variante continue de fonctionner.
3d. Disposez la famille dans une grille lisible à l'intérieur de son cadre de famille : une ligne par variante, une colonne par taille ou état, avec de petits en-têtes de texte. Utilisez des cadres de ligne avec gap, jamais de positions absolues.
3e. Documentez-la : un titre et une note d'utilisation de deux ou trois lignes dans le cadre de la famille (quand utiliser quelle variante, la règle de l'action principale unique).
3f. Vérifiez-la :
- Vérification codée en dur sur le cadre de la famille : pas de remplissages hexadécimaux à l'exception des transparents délibérés (
#00000000fonctionne comme un remplissage transparent pour les variantes ghost). - Le bloc
issues detectedde l'appel (cadres réduits, slots vides). La vérificationctx.problemspour le clipping donne de fausses alertes dans les versions actuelles : confirmez avec une capture d'écran. - Test d'instance : insérez une instance de chaque variante dans un cadre temporaire, remplacez l'étiquette par un texte long et masquez l'icône, puis prenez une capture d'écran en clair et en sombre (
themesur le cadre temporaire). Supprimez le cadre temporaire après.
Point de contrôle par composant : capture d'écran, liste des variantes et identifiants. Ne commencez pas le composant suivant avant l'approbation.
Phase 4. QA et bibliothèque
- Audit des jetons : chaque variable utilisée par un composant existe ; chaque variable thématisée a toutes les valeurs de thème.
- Audit des liaisons : pas de couleurs hexadécimales ni d'espacements bruts à l'intérieur des composants, sauf les valeurs listées comme délibérées.
- Contraste : texte par rapport à son arrière-plan dans les deux thèmes (4.5:1 pour le texte du corps, 3:1 pour le grand texte
... [tronqué pour la traduction]