Communitygithub.com

pencil-generate-library: トークン、テーマ、コンポーネントを順序立てて構築

コードベースから実在するデザインシステムをPencil(pen.dev)に構築または更新するためのワークフローです。変数(色、スペーシング、角丸、タイポグラフィ)、ライト/ダークテーマ、再利用可能なコンポーネント(バリアント、状態、スロット)、ファンデーションボード、オプションの.lib.penデザインライブラリを生成します。

pencil-generate-library: トークン、テーマ、コンポーネントを順序立てて構築 とは?

このスキルは、Pencil(pen.dev)上でコードベースと完全に一致するプロダクションレベルのデザインシステムを構築するための詳細なワークフローを提供します。開発者は、CSSカスタムプロパティ、Tailwind設定、Style Dictionaryトークン、またはCSS-in-JSテーマからトークンを自動発見し、それらをPencilの変数(色、数値、文字列、真偽値)にマッピングできます。このスキルは、Pencilが他のツールと異なる点(バリアントセットがない、スロット、インスタンスオーバーライドなど)を明確に説明し、発見、ファンデーション(変数とテーマ)、ファイルレイアウト、コンポーネント(1つずつアトム→分子→有機体)、QAとライブラリ変換という5つのフェーズに分かれたワークフローを定義します。各フェーズの終わりにはユーザーチェックポイントがあり、すべての呼び出しが最小限の単位で行われ、確認と承認が行われます。このスキルは、pencil-useスキルの実行ルールと組み合わせて使用することを前提としており、コードの実際の動作に合わせてデザインシステムを構築したい開発者やデザイナーにとって不可欠です。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

pencil-generate-library: トークン、テーマ、コンポーネントを順序立てて構築 は何をしますか?

コードに一致するデザインシステムを.penファイル内に構築します。最初にpencil-useをロードしてください:このスキルにはexecuteルールが含まれています。このスキルは作業の順序とデザインシステムの決定事項を保持します。

1. 最も重要なルール

これは決して1回の呼び出しでは完了しません。 小規模なシステムでも15~40回のexecute呼び出しが必要であり、大規模なものではさらに多くなります。最小限の有効な単位で作業し、確認し、表示してから次に進んでください。1つの長いスニペットで構築されたシステムは壊れてしまい、修復が困難です。

2. Pencilが他のツールと異なる点

他のツールから借りたモデルではなく、Pencilの実際のモデルで計画を立ててください:

ニーズPencilでの実現方法
トークンcolor、number、string、boolean 型のドキュメントvariables。$nameとして参照
モード(ライト、ダーク)テーマ軸。変数の値は {value, theme: {mode: "dark"}} のリスト。フレームはthemeプロパティで値を選択
エイリアス(セマンティック→プリミティブ)値が別の変数である変数:value: "$gray-900"
テキストスタイルなし。フォント変数(ファミリー、サイズ、行高、ウェイトを文字列または数値で)を使用し、必要に応じて小さなテキストコンポーネントを使用
シャドウスタイルなし。シャドウエフェクトは色、ぼかし、オフセットに変数を受け入れる
コンポーネントreusable: true の任意のノード
バリアントバリアントセットなし。バリアントごとに1つのコンポーネントを作成し、スラッシュで命名:Button/Primary、Button/Outline
真偽値オプション(アイコン表示)そのパーツに対してインスタンスオーバーライド enabled: false
交換可能なアイコンアイコンノードに対するインスタンスオーバーライド:{icon: "plus"}
交換可能なコンテンツコンポーネント内部のslotフレーム。推奨コンポーネントIDを指定
共有ライブラリアプリ内で.lib.penに変換されたファイル(一方通行、元に戻せない)。画面ファイルでインポート

3. ワークフロー

フェーズ0  発見         コードとファイルを読み取り、書き込みはしない          -> チェックポイント:計画が承認される
フェーズ1  基礎         変数とテーマ                                   -> チェックポイント:トークンサマリーが承認される
フェーズ2  ファイルレイアウト  キャンバス上のエリア、ファンデーションボード   -> チェックポイント:ボードのスクリーンショットが承認される
フェーズ3  コンポーネント   1つずつ、アトムの前に分子                      -> 各コンポーネント後にチェックポイント
フェーズ4  QAとライブラリ  監査、修正、オプションの.lib.pen               -> チェックポイント:承認完了

各チェックポイントで次のフェーズに名前を付けます。トークンについて「よさそうだ」と言っても、コンポーネントを開始する承認にはなりません。

フェーズ0. 発見(読み取りのみ)

0a. コード内のトークンを見つける、以下の順序で:

  1. CSSカスタムプロパティ(:root { --background: ... }、.dark { ... } または [data-theme="dark"])。
  2. Tailwind設定またはTailwind v4の@themeブロック。
  3. トークンファイル(DTCG .tokens.json、Style Dictionary)。
  4. CSS-in-JSのテーマオブジェクト、またはネイティブテーマファイル(iOSアセットカタログ、Android colors.xml)。

ダークモードのメカニズム、スペーシングと角丸のスケール、フォントとタイプスケール、シャドウに注意してください。

0b. コード内のコンポーネントを見つける:UIプリミティブのリスト(Button、Input、Checkbox、Badge、Avatar、Card...)、そのprops、どのpropsがバリアント(variant、size、state)か、どれが真偽値か、どれが子要素を取るか。

0c. ファイルを読み取る:

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

また、get_app_state でインポートされたライブラリを確認します。ファイル内にすでにある命名と一致させます。

0d. スコープをユーザーと確定する:今回のラウンドで使用する正確なトークンリストとコンポーネントリスト。最初のラウンドで6~10コンポーネントが適切なサイズです。

0e. コードをPencilにマッピングし、競合を解決する。 以下のようなテーブルを提示します:

コードトークン          Pencil変数           ライト        ダーク        ステータス
--background            --background          #FFFFFF      #0A0A0A      新規
--primary               --primary             #1D4ED8      #3B82F6      既存、値が異なる(確認)
コンポーネント          Pencilコンポーネント                            ステータス
Button variant x size   Button/Primary, Button/Secondary, Button/Outline, Button/Ghost(サイズはテーマ軸経由)   新規

コードとファイルが矛盾する場合、どちらを優先するか尋ねてください。自分で決定しないでください。

チェックポイント:計画を表示し、承認を待ちます。

フェーズ1. 基礎

命名。 コードとデザインが双方向に変換できるよう、コードの名前を保持します:CSS変数 --muted-foreground はPencil変数 --muted-foreground となり、$--muted-foreground として参照されます。名前を $ で始めないでください。名前に : を使用しないでください。コードに名前がない場合は、役割に応じて短いケバブケースの名前を使用します:surface、text、text-muted、border、accent、space-4、radius-md。

レイヤー。

  • プリミティブ:生の値、テーマなし(gray-50 ... gray-950、blue-500、space-1 ... space-16)。
  • セマンティック:役割名、テーマ付き、プリミティブを指す(--background:ライト $white、ダーク $gray-950)。
  • コンポーネントはセマンティックのみを使用します。$gray-900 を直接参照するコンポーネントはテーマで切り替わりません。

システムの規模。

  • 約50トークン未満:1つのフラットセット、light と dark の mode 軸1つ。
  • 大規模:上記のようにプリミティブとセマンティックを使用し、コードに実際に存在する場合にのみ追加のテーマ軸を追加します(density: comfortable, compact、brand: a, b)。

小さなバッチで書き込み、1回の呼び出しで1ファミリーずつ(プリミティブカラー、次にセマンティックカラー、次にスペーシングと角丸、次にタイポグラフィ)、読み戻します:

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))
  • mode 軸の最初の値が製品が通常使用するデフォルト値であることを確認します(通常は light)。
  • テーマ付き変数にはすべてのテーマ値に対して値を指定します。値が欠けていると、正しくない色が静かに表示されます。
  • 変更すべきでない値(スペーシング、角丸)はテーマ間で同じに保ちます。
  • タイポグラフィ:--font-sans(文字列)、サイズ(text-sm 14、text-base 16...)、行高は比率(leading-normal 1.5)、ウェイトは文字列("400"、"600")。
  • シャドウ:コードにシャドウスケールがある場合、シャドウ用のテーマ付きカラー変数と、ぼかし/オフセット用の数値変数。
  • 明示的な同意なしに、既存のファイルに対して SetVariables(..., true) を決して使用しないでください:すべての変数が消去されます。

終了条件:計画内のすべてのトークンが正しい型で存在し、すべてのテーマ付きトークンがすべてのテーマ値を持ち、エイリアスが既存の変数を指していること。

チェックポイント:ファミリーごとのカウント、テーマ軸、および推測せざるを得なかった値を表示します。

フェーズ2. ファイルレイアウトとファンデーションボード

キャンバスを読みやすく保つ:

  • 左上にFoundationsフレーム:カラースウォッチ、タイプ見本、スペーシングバー、角丸サンプル。
  • その右または下にComponentsエリア:コンポーネントファミリーごとに1つのフレーム(Buttons、Inputs、Cards)、タイトルと短い使用上の注意とともにコンポーネントを保持。
  • Screensはさらに右下に配置し、コンポーネントと混在させない。
  • すべてのルートフレームに FindEmptySpace を使用します。

スウォッチと見本は変数にバインドする必要があります。これにより、トークンが変更されたときにボードが更新されます。スウォッチはループで構築します:

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

次に、ボードを theme: {mode: "dark"} でその隣にコピーします。何かがライトのままの場合、そのトークンにダーク値が欠けています。

チェックポイント:両方のテーマでのボードのスクリーンショット。

フェーズ3. コンポーネント、1つずつ

依存関係の順序:アトムが先(Iconラッパー、Badge、Avatar、Button、Input、Checkbox、Toggle)、次に分子(ラベルとヒント付きのInputグループ、Menu項目、Tab)、次に有機体(Card、Dialog、Sidebar、Table行)。別のコンポーネントを含むコンポーネントは、その後に構築し、再描画されたコピーではなく、そのインスタンスを含める必要があります。

各コンポーネントについて:

3a. 描画前にAPIを設計する。 コードのpropsから:

  • 色や構造を変更するバリアント軸は別々のコンポーネントになります:Button/Primary、Button/Secondary、Button/Outline、Button/Ghost、Button/Destructive。
  • トークン値のみを変更する軸(サイズ、密度)は、より多くのコンポーネントの代わりにテーマ軸にできます:button-padding-y や button-padding-x などのテーマ付き数値変数に size: md, sm, lg(最初の値がデフォルト)。1つのコンポーネントが theme: {size: "sm"} をインスタンスに設定することで、すべてのサイズに対応します。テスト済みで動作します。コードが同じように動作する場合に使用します。それ以外の場合は、サイズコンポーネントも作成します。
  • グローバルスイッチ(モックアップ内のすべてのバッジを表示/非表示)は、enabled: "$show-badge" にバインドされた真偽値変数にできます。すべてのインスタンスを一度に変更するため、デモの切り替えに使用し、インスタンスごとのオプションには使用しないでください。
  • 数を適切に保ちます。バリアント×サイズ×状態が約30コンポーネントを超える場合は、ファミリーを分割するか、1つの軸をテーマに移動します。
  • 状態:ユーザーが表示したい場合のみ Disabled または Focus コンポーネントを作成します。ホバーや押下は多くの場合ドキュメント化のみされます。
  • 真偽値(アイコン付き、ヒント付き)はバリアントではありません:完全なコンポーネントを構築し、インスタンスごとに enabled: false でパーツを非表示にします。
  • アイコンはバリアントではありません:1つのアイコンノードを、icon オーバーライドで交換します。
  • 自由コンテンツ領域はスロットです:slot: [recommendedComponentIds]、width: "fill_container"、および固定の高さ(例:height: 40)を持つフレーム。fit_content でサイズ設定された空のスロットはゼロに収縮して消えます。

3b. ベースコンポーネントを1回の呼び出しで構築する:reusable: true、レイアウト、パディング、ギャップ、角丸、塗りつぶしをすべて変数から設定したフレーム、名前付きの子要素(Label、Icon、Content)。そのidと子idをグローバルにキャプチャします。

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. 他のバリアントを構築する。 コンポーネントの Copy はインスタンスを作成し、新しいコンポーネントは作成しません。独立したバリアントコンポーネントを取得するには、1回の呼び出し内で小さなヘルパー関数を使用して各コンポーネントを再構築し、バリアントテーブルをループします:

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

バリアント間で子要素の名前を同一に保ちます(Label、Icon)。これにより、名前でインスタンスをオーバーライドでき、バリアントスワップが機能し続けます。

3d. ファミリーをそのファミリーフレーム内の読みやすいグリッドにレイアウトする:バリアントごとに1行、サイズまたは状態ごとに1列、小さなテキストヘッダーを付けます。gap を持つ行フレームを使用し、絶対位置は使用しないでください。

3e. ドキュメント化する:ファミリーフレーム内にタイトルと2~3行の使用上の注意(どのバリアントをいつ使用するか、1つのプライマリアクションルールなど)。

3f. 確認する:

  • ファミリーフレームのハードコードされたチェック:意図的な透明なもの(ゴーストバリアント用の #00000000)を除き、16進数の塗りつぶしがないこと。
  • 呼び出しの issues detected ブロック(折りたたまれたフレーム、空のスロット)。ctx.problems クリッピングチェックは現在のバージョンでは誤検知を引き起こします:スクリーンショットで確認してください。
  • インスタンステスト:各バリアントのインスタンスを1つスクラッチフレームに挿入し、ラベルを長いテキストでオーバーライドし、アイコンを非表示にして、ライトとダーク(スクラッチフレームの theme)でスクリーンショットを撮ります。その後、スクラッチフレームを削除します。

チェックポイント(コンポーネントごと):スクリーンショット、バリアントリスト、およびid。次のコンポーネントを承認前に開始しないでください。

フェーズ4. QAとライブラリ

  1. トークン監査:コンポーネントが使用するすべての変数が存在すること。すべてのテーマ付き変数がすべてのテーマ値を持つこと。
  2. バインディング監査:コンポーネント内に16進数の色や生のスペーシングがないこと(意図的にリストされた値を除く)。
  3. コントラスト:両方のテーマでテキストとその背景のコントラスト(本文テキストで4.5:1、大きなテキストで3:1...)

...(以降は翻訳のため省略)

Individual skills in this repo

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

関連スキル