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:
| Bedarf | In Pencil |
|---|---|
| Tokens | Dokument 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" |
| Textstile | Keine. Verwende Schriftvariablen (Familie, Größe, Zeilenhöhe, Gewicht als Strings oder Zahlen) und, falls sinnvoll, kleine Textkomponenten |
| Schattenstile | Keine. Schatteneffekte akzeptieren Variablen für Farbe, Unschärfe und Versatz |
| Komponente | Jeder Knoten mit reusable: true |
| Varianten | Keine 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 Symbol | Instanz-Override am Symbolknoten: {icon: "plus"} |
| Austauschbarer Inhalt | Ein slot-Frame innerhalb der Komponente, mit empfohlenen Komponenten-IDs |
| Gemeinsam genutzte Bibliothek | Eine 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:
- CSS-Custom-Properties (
:root { --background: ... },.dark { ... }oder[data-theme="dark"]). - Tailwind-Konfiguration oder Tailwind v4
@theme-Blöcke. - Token-Dateien (DTCG
.tokens.json, Style Dictionary). - 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-900referenziert, wechselt nicht mit dem Theme.
Größe des Systems.
- Unter etwa 50 Tokens: ein flaches Set, eine
mode-Achse mitlightunddark. - 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 (normalerweiselight). - 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-sm14,text-base16...), Zeilenhöhen als Verhältnisse (leading-normal1.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
FindEmptySpacefü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-yundbutton-padding-xmitsize: md, sm, lg(erster Wert ist der Standard). Eine Komponente bedient dann jede Größe durchtheme: {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- oderFocus-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: falseaus. - 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 durchfit_contentdimensioniert 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 (
#00000000funktioniert als transparente Füllung für Ghost-Varianten). - Der Block
issues detecteddes Aufrufs (eingeklappte Frames, leere Slots). Diectx.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 (
themeauf 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
- Token-Audit: Jede von einer Komponente verwendete Variable existiert; jede thematisierte Variable hat jeden Theme-Wert.
- Bindungs-Audit: Keine Hex-Farben oder rohen Abstände innerhalb von Komponenten, außer Werten, die als bewusst aufgelistet sind.
- Kontrast: Text gegen seinen Hintergrund in beiden Themes (4.5:1 für Fließtext, 3:1 für großen Text...