Communitygithub.com

pencil-generate-library

Workflow zum Aufbau oder zur Aktualisierung eines echten Designsystems in Pencil (pen.dev), meist aus einem Codebestand: Variablen (Farben, Abstände, Radius, Schrift), helle und dunkle Designs, wiederverwendbare Komponenten mit Varianten und Zuständen, Slots, eine Grundlagenfläche und eine optionale .lib.pen-Bibliothek.

Was ist pencil-generate-library?

Dieses Skill beschreibt einen vollständigen, mehrstufigen Workflow zur Erstellung eines Designsystems in Pencil (pen.dev) aus vorhandenem Code. Es ist speziell für die Verwendung mit dem Skill `pencil-use` konzipiert, der die Ausführungslogik für die Werkzeugaufrufe enthält. Das Skill definiert die genaue Reihenfolge der Arbeit: von der Erkundung des Codes (Phase 0: Discovery) über die Extraktion und Definition von Variablen und Designs (Phase 1: Foundations), das Layout der Zeichenfläche mit Grundlagentafeln (Phase 2: File Layout), den schrittweisen Aufbau einzelner Komponenten (Phase 3: Components) bis hin zur Qualitätssicherung und optionalen Erstellung einer gemeinsam nutzbaren `.lib.pen`-Bibliothek (Phase 4: QA and Library). Es geht detailliert auf die spezifischen Konzepte und Einschränkungen von Pencil ein, wie z. B. die Handhabung von Variablen mit Themenachsen für Light/Dark-Modi, die Erstellung von Komponentenvarianten als separate Komponenten, die Verwendung von Slots für austauschbare Inhalte und die korrekte Implementierung von Übersteuerungen (Instance Overrides) für Symbole und boolesche Optionen. Das Skill betont die Notwendigkeit kleiner, überprüfbarer Schritte mit Benutzerkontrollpunkten zwischen den Phasen, um Fehler zu vermeiden und eine enge Abstimmung mit dem Code zu gewährleisten.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

pencil-generate-library: Tokens, Themes und Komponenten in der richtigen Reihenfolge

Erstelle ein Designsystem in einer .pen-Datei, das dem Code entspricht. Lade zuerst pencil-use: Es enthält die execute-Regeln. Dieses Skill enthält die Arbeitsreihenfolge und die Designsystem-Entscheidungen.

1. Die wichtigste Regel

Dies ist niemals ein einziger Aufruf. Ein kleines System benötigt 15 bis 40 execute-Aufrufe, ein größeres deutlich mehr. Arbeite in der kleinsten sinnvollen Einheit, überprüfe sie, zeige sie und fahre dann fort. Ein in einem langen Schnipsel erstelltes System ist fehlerhaft und schwer zu reparieren.

2. Wie sich Pencil von anderen Werkzeugen unterscheidet

Plane mit Pencils tatsächlichem Modell, nicht mit einem aus anderen Tools entliehenen:

BedarfIn Pencil
TokensDokument variables vom Typ color, number, string, boolean, referenziert als $name
Modi (hell, dunkel)Themenachsen. Ein Variablenwert ist eine Liste von {value, theme: {mode: "dark"}}; ein Frame wählt einen Wert über seine theme-Eigenschaft aus
Alias (semantisch zu primitiv)Eine Variable, deren Wert eine andere Variable ist: value: "$gray-900"
TextstileKeine. Verwende Schriftvariablen (Familie, Größe, Zeilenhöhe, Gewicht als Strings oder Zahlen) und, falls sinnvoll, kleine Textkomponenten
SchattenstileKeine. Schatteneffekte akzeptieren Variablen für Farbe, Unschärfe und Versatz
KomponenteJeder Knoten mit reusable: true
VariantenKeine Variantensets. Eine Komponente pro Variante, benannt mit Schrägstrichen: Button/Primary, Button/Outline
Boolesche Option (Symbol anzeigen)Instanz-Override enabled: false an diesem Teil
Austauschbares SymbolInstanz-Override am Symbolknoten: {icon: "plus"}
Austauschbarer InhaltEin slot-Frame innerhalb der Komponente, mit empfohlenen Komponenten-IDs
Gemeinsam genutzte BibliothekEine Datei, die in der App in .lib.pen konvertiert wurde (einseitig, nicht rückgängig machbar), importiert von Bildschirmdateien

3. Workflow

Phase 0  DISCOVERY        Code und Datei lesen, keine Schreibvorgänge -> Kontrollpunkt: Plan genehmigt
Phase 1  FOUNDATIONS      Variablen und Themes                       -> Kontrollpunkt: Token-Zusammenfassung genehmigt
Phase 2  FILE LAYOUT      Bereiche auf der Zeichenfläche, Grundlagentafel -> Kontrollpunkt: Screenshot der Tafel genehmigt
Phase 3  COMPONENTS       Eine nach der anderen, Atome vor Molekülen -> Kontrollpunkt nach jeder Komponente
Phase 4  QA UND LIBRARY   Audits, Korrekturen, optional .lib.pen     -> Kontrollpunkt: Freigabe

Benenne die nächste Phase an jedem Kontrollpunkt. Ein "sieht gut aus" bezüglich der Tokens ist keine Genehmigung, mit Komponenten zu beginnen.

Phase 0. Erkundung (nur lesen)

0a. Finde die Tokens im Code in dieser Reihenfolge:

  1. CSS-Custom-Properties (:root { --background: ... }, .dark { ... } oder [data-theme="dark"]).
  2. Tailwind-Konfiguration oder Tailwind v4 @theme-Blöcke.
  3. Token-Dateien (DTCG .tokens.json, Style Dictionary).
  4. Theme-Objekte in CSS-in-JS oder native Theme-Dateien (iOS Asset Catalogs, Android colors.xml).

Notiere den Dark-Mode-Mechanismus, die Abstands- und Radius-Skalen, Schriftarten und die Schriftgrößenskala sowie Schatten.

0b. Finde die Komponenten im Code: die Liste der UI-Primitiven (Button, Input, Checkbox, Badge, Avatar, Card...), ihre Props, welche Props Varianten sind (variant, size, state), welche boolesch sind, welche Children akzeptieren.

0c. Lese die Datei:

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

Überprüfe auch get_app_state nach importierten Bibliotheken. Gleiche bereits vorhandene Benennungen in der Datei ab.

0d. Lege den Umfang fest mit dem Benutzer: die genaue Token-Liste und die genaue Komponenten-Liste für diese Runde. Eine erste Runde mit sechs bis zehn Komponenten ist eine gute Größe.

0e. Ordne Code Pencil zu und löse Konflikte. Präsentiere eine Tabelle:

Code-Token            Pencil-Variable       Hell       Dunkel     Status
--background          --background          #FFFFFF    #0A0A0A    neu
--primary             --primary             #1D4ED8    #3B82F6    existiert, Wert weicht ab (fragen)
Komponente            Pencil-Komponenten                           Status
Button x Grße          Button/Primary, Button/Secondary, Button/Outline, Button/Ghost (Größe über Themenachse)   neu

Wenn Code und Datei unterschiedlicher Meinung sind, frage, welche gewinnt. Entscheide nicht allein.

Kontrollpunkt: Zeige den Plan, warte auf Genehmigung.

Phase 1. Grundlagen

Benennung. Behalte die Namen des Codes bei, damit Design und Code hin- und hergehen: Eine CSS-Variable --muted-foreground wird zur Pencil-Variable --muted-foreground, referenziert als $--muted-foreground. Beginne einen Namen niemals mit $. Vermeide : in Namen. Wenn der Code keine Namen hat, verwende kurze Kebab-Namen nach Rolle: surface, text, text-muted, border, accent, space-4, radius-md.

Ebenen.

  • Primitive: Rohe Werte, kein Theme (gray-50 ... gray-950, blue-500, space-1 ... space-16).
  • Semantik: Rollennamen, thematisiert, zeigen auf Primitive (--background: hell $white, dunkel $gray-950).
  • Komponenten verwenden nur Semantik. Eine Komponente, die direkt $gray-900 referenziert, wechselt nicht mit dem Theme.

Größe des Systems.

  • Unter etwa 50 Tokens: ein flaches Set, eine mode-Achse mit light und dark.
  • Größer: Primitive plus Semantik wie oben und zusätzliche Themenachsen nur, wenn der Code sie wirklich hat (density: comfortable, compact; brand: a, b).

Schreibe in kleinen Stapeln, eine Familie pro Aufruf (primitive Farben, dann semantische Farben, dann Abstände und Radien, dann Schrift) und lies zurück:

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))
  • Überprüfe, dass der erste Wert der mode-Achse der Standard ist, den das Produkt verwendet (normalerweise light).
  • Gib jeder thematisierten Variable einen Wert für jeden Theme-Wert, den du verwendest. Ein fehlender Wert zeigt stillschweigend die falsche Farbe an.
  • Halte Werte über Themes hinweg identisch, wenn sie sich nicht ändern sollen (Abstände, Radien).
  • Typografie: --font-sans (String), Größen (text-sm 14, text-base 16...), Zeilenhöhen als Verhältnisse (leading-normal 1.5), Gewichte als Strings ("400", "600").
  • Schatten: eine thematisierte Farbvariable für den Schatten und Zahlenvariablen für Unschärfe und Versatz, wenn der Code eine Schattenskala hat.
  • Nie SetVariables(..., true) auf einer vorhandenen Datei ohne ausdrückliche Zustimmung: Es löscht jede Variable.

Abbruchkriterien: Jedes Token im Plan existiert mit dem richtigen Typ, jedes thematisierte Token hat jeden Theme-Wert, Aliase zeigen auf vorhandene Variablen.

Kontrollpunkt: Zeige Anzahlen pro Familie, Themenachsen und alle Werte, die du schätzen musstest.

Phase 2. Datei-Layout und Grundlagentafel

Halte die Zeichenfläche lesbar:

  • Ein Grundlagen-Frame oben links: Farbmuster, Schriftexemplare, Abstandsbalken, Radius-Beispiele.
  • Ein Komponenten-Bereich rechts davon oder darunter, ein Frame pro Komponentenfamilie (Buttons, Inputs, Cards), der die Komponenten mit einem Titel und einer kurzen Nutzungsnotiz enthält.
  • Bildschirme weiter unten und rechts, niemals mit Komponenten vermischt.
  • Verwende FindEmptySpace für jeden Stammframe.

Muster und Exemplare müssen an Variablen gebunden sein, damit sich die Tafel aktualisiert, wenn sich ein Token ändert. Baue Muster mit einer Schleife:

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])

Kopiere dann die Tafel mit theme: {mode: "dark"} daneben: Wenn etwas hell bleibt, fehlt einem Token sein dunkler Wert.

Kontrollpunkt: Screenshot der Tafeln in beiden Themes.

Phase 3. Komponenten, eine nach der anderen

Reihenfolge nach Abhängigkeit: Atome zuerst (Icon-Wrapper, Badge, Avatar, Button, Input, Checkbox, Toggle), dann Moleküle (Input-Gruppe mit Label und Hinweis, Menüpunkt, Tab), dann Organismen (Card, Dialog, Sidebar, Tabellenzeile). Eine Komponente, die eine andere enthält, muss nach dieser erstellt werden und muss eine Instanz davon enthalten, keine neu gezeichnete Kopie.

Für jede Komponente:

3a. Entwerfe die API vor dem Zeichnen. Aus den Code-Props:

  • Variantenachsen, die Farbe oder Struktur ändern, werden zu separaten Komponenten: Button/Primary, Button/Secondary, Button/Outline, Button/Ghost, Button/Destructive.
  • Achsen, die nur Token-Werte ändern (Größe, Dichte), können eine Themenachse sein anstatt weiterer Komponenten: thematisierte Zahlenvariablen wie button-padding-y und button-padding-x mit size: md, sm, lg (erster Wert ist der Standard). Eine Komponente bedient dann jede Größe durch theme: {size: "sm"} auf der Instanz. Getestet und funktioniert. Verwende es, wenn der Code auf die gleiche Weise funktioniert; ansonsten erstelle auch Größenkomponenten.
  • Ein globaler Schalter (jedes Badge in Mockups anzeigen oder ausblenden) kann eine boolesche Variable sein, die an enabled: "$show-badge" gebunden ist. Es ändert jede Instanz auf einmal, also behalte es für Demo-Umschalter, nicht für Pro-Instanz-Optionen.
  • Halte die Anzahl vernünftig. Wenn Varianten mal Größen mal Zustände über etwa 30 Komponenten hinausgehen, teile die Familie auf oder verschiebe eine Achse in ein Theme.
  • Zustände: Eine Disabled- oder Focus-Komponente nur, wenn der Benutzer sie zeigen möchte; Hover und Pressed werden oft nur dokumentiert.
  • Boolesche Werte (mit Icon, mit Hinweis) sind keine Varianten: Baue die vollständige Komponente und blende Teile pro Instanz mit enabled: false aus.
  • Symbole sind keine Varianten: Ein Symbolknoten, ausgetauscht mit einem icon-Override.
  • Freie Inhaltsbereiche sind Slots: Ein Frame mit slot: [recommendedComponentIds], width: "fill_container" und einer festen Höhe (z. B. height: 40). Ein leerer Slot, der durch fit_content dimensioniert wird, kollabiert auf Null und verschwindet.

3b. Baue die Basiskomponente in einem Aufruf: Ein Frame mit reusable: true, Layout, Padding, Abstand, Radius und Füllungen alle aus Variablen, benannte Children (Label, Icon, Content). Erfasse ihre ID und die IDs ihrer Children in globalen Variablen.

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. Baue die anderen Varianten. Copy einer Komponente erzeugt eine Instanz, keine neue Komponente. Um unabhängige Variantenkomponenten zu erhalten, erstelle jede mit einer kleinen Hilfsfunktion innerhalb eines Aufrufs neu, indem du über eine Variantentabelle iterierst:

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")

Halte Child-Namen über Varianten hinweg identisch (Label, Icon), damit Instanzen nach Namen überschrieben werden können und ein Variantenwechsel weiterhin funktioniert.

3d. Ordne die Familie in einem lesbaren Raster innerhalb ihres Familien-Frames an: Eine Zeile pro Variante, eine Spalte pro Größe oder Zustand, mit kleinen Text-Überschriften. Verwende Zeilen-Frames mit gap, niemals absolute Positionen.

3e. Dokumentiere sie: Ein Titel und eine zwei- oder dreizeilige Nutzungsnotiz im Familien-Frame (wann welche Variante zu verwenden ist, die Eine-primäre-Aktion-Regel).

3f. Überprüfe sie:

  • Hartcodierte Prüfung auf dem Familien-Frame: keine Hex-Füllungen außer bewussten transparenten (#00000000 funktioniert als transparente Füllung für Ghost-Varianten).
  • Der Block issues detected des Aufrufs (eingeklappte Frames, leere Slots). Die ctx.problems-Clipping-Prüfung gibt in aktuellen Versionen Fehlalarme: Bestätige mit einem Screenshot.
  • Instanz-Test: Füge eine Instanz jeder Variante in einen Scratch-Frame ein, überschreibe das Label mit einem langen Text und blende das Icon aus, mache dann einen Screenshot davon in Hell und Dunkel (theme auf dem Scratch-Frame). Lösche den Scratch-Frame danach.

Kontrollpunkt pro Komponente: Screenshot, Variantenliste und die IDs. Beginne nicht mit der nächsten Komponente vor der Genehmigung.

Phase 4. Qualitätssicherung und Bibliothek

  1. Token-Audit: Jede von einer Komponente verwendete Variable existiert; jede thematisierte Variable hat jeden Theme-Wert.
  2. Bindungs-Audit: Keine Hex-Farben oder rohen Abstände innerhalb von Komponenten, außer Werten, die als bewusst aufgelistet sind.
  3. Kontrast: Text gegen seinen Hintergrund in beiden Themes (4.5:1 für Fließtext, 3:1 für großen Text...

Individual skills in this repo

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

Verwandte Skills