Communitygithub.com

pencil-generate-library : jetons, thèmes et composants dans l'o…

Workflow pour construire ou mettre à jour un véritable système de design dans Pencil (pen.dev), généralement à partir d'une base de code : variables (couleurs, espacements, rayons, typographie), thèmes clair et sombre, composants réutilisables, leurs variantes et états, des emplacements, un tableau des fondations, et une bibliothèque de design .lib.pen optionnelle.

Qu'est-ce que pencil-generate-library : jetons, thèmes et composants dans l'o… ?

Cette skill définit l'ordre de travail et les décisions de conception pour construire un système de design dans un fichier `.pen` qui reflète fidèlement le code. Elle est destinée aux développeurs et aux utilisateurs d'agents IA qui souhaitent créer ou synchroniser un design system dans Pencil (pen.dev), en suivant une approche structurée en phases : découverte, fondations (variables et thèmes), mise en page du fichier, composants un par un, et enfin QA et transformation en bibliothèque partagée. La skill insiste sur le fait que la construction ne se fait jamais en un seul appel, mais en une série de 15 à 40 appels `execute` (ou plus) pour un système de taille moyenne, chaque étape étant vérifiée et approuvée avant de passer à la suivante. Elle détaille les concepts spécifiques à Pencil (variables, thèmes par axes, composants avec variantes via des composants séparés, slots, etc.) et fournit des exemples de code (en JavaScript) pour les appels d'API Pencil, comme `SetVariables`, `Insert` et `TakeScreenshot`. Les plateformes cibles sont les environnements utilisant Pencil pour le design, et les cas d'utilisation typiques incluent l'import de tokens CSS ou Tailwind, l'ajout du mode sombre, la création de composants et la génération d'une bibliothèque de design.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/alekpixel/pencil-skills/tree/main/skills/pencil-generate-library

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

BesoinDans Pencil
JetonsVariables 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 texteAucun. 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'ombreAucun. Les effets d'ombre acceptent des variables pour la couleur, le flou et le décalage
ComposantTout nœud avec reusable: true
VariantesPas 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 échangeableRemplacement d'instance sur le nœud d'icône : {icon: "plus"}
Contenu échangeableUn cadre slot à l'intérieur du composant, avec des identifiants de composants recommandés
Bibliothèque partagéeUn 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 :

  1. Propriétés personnalisées CSS (:root { --background: ... }, .dark { ... } ou [data-theme="dark"]).
  2. Configuration Tailwind ou blocs @theme Tailwind v4.
  3. Fichiers de jetons (DTCG .tokens.json, Style Dictionary).
  4. Objets de thème dans CSS-in-JS, ou fichiers de thème natifs (catalogues d'actifs iOS, colors.xml Android).

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-900 directement ne changera pas avec le thème.

Taille du système.

  • En dessous d'environ 50 jetons : un ensemble plat, un axe mode avec light et dark.
  • 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 mode est celle par défaut que le produit utilise (généralement light).
  • 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-sm 14, text-base 16...), hauteurs de ligne sous forme de ratios (leading-normal 1.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 FindEmptySpace pour 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-y et button-padding-x avec size: md, sm, lg (la première valeur est la valeur par défaut). Un seul composant sert alors chaque taille via theme: {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 Disabled ou Focus seulement 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 exemple height: 40). Un slot vide dimensionné par fit_content se 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 (#00000000 fonctionne comme un remplissage transparent pour les variantes ghost).
  • Le bloc issues detected de l'appel (cadres réduits, slots vides). La vérification ctx.problems pour 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 (theme sur 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

  1. Audit des jetons : chaque variable utilisée par un composant existe ; chaque variable thématisée a toutes les valeurs de thème.
  2. 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.
  3. 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]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills associés