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. コード内のトークンを見つける、以下の順序で:
- CSSカスタムプロパティ(
:root { --background: ... }、.dark { ... }または[data-theme="dark"])。 - Tailwind設定またはTailwind v4の
@themeブロック。 - トークンファイル(DTCG
.tokens.json、Style Dictionary)。 - 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-sm14、text-base16...)、行高は比率(leading-normal1.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とライブラリ
- トークン監査:コンポーネントが使用するすべての変数が存在すること。すべてのテーマ付き変数がすべてのテーマ値を持つこと。
- バインディング監査:コンポーネント内に16進数の色や生のスペーシングがないこと(意図的にリストされた値を除く)。
- コントラスト:両方のテーマでテキストとその背景のコントラスト(本文テキストで4.5:1、大きなテキストで3:1...)
...(以降は翻訳のため省略)