pencil-design

Pencil デザインスキル

Pencil で本番品質の UI をデザインし、そこからクリーンで保守しやすいコードを生成します。このスキルでは、デザインシステムの再利用、変数の使用、レイアウトの正確性、ビジュアル検証、デザインからコードへのワークフローに関するベストプラクティスを徹底します。

このスキルを使用する場面

• .pen ファイルで画面、ページ、コンポーネントをデザインするとき
• Pencil のデザインからコード（React、Next.js、Vue、Svelte、HTML/CSS）を生成するとき
• Pencil でデザインシステムを構築または拡張するとき
• Pencil とコードの間でデザイントークンを同期するとき（Tailwind v4 @theme、shadcn/ui トークン）
• 既存のコードを Pencil のデザインにインポートするとき
• Pencil の MCP ツール（pencil_batch_design、pencil_batch_get など）を使用するとき

重要なルール

これらのルールは、エージェントによくある誤りを防ぎます。違反すると、デザインに一貫性がなく、保守しにくくなり、生成されるコードの品質も低下します。

ルール 1：デザインシステムのコンポーネントを必ず再利用する

デザインファイルに既存のコンポーネントがある場合、コンポーネントを一から作り直してはいけません。

要素を挿入する前に、必ず次の手順を実行してください。

1. pencil_batch_get を patterns: [{ reusable: true }] で呼び出し、利用可能なすべての再利用可能なコンポーネントを一覧表示します
2. 結果から、必要なものに一致するコンポーネント（ボタン、カード、入力欄、ナビゲーションなど）を探します
3. 一致するものがあれば、I(parent, { type: "ref", ref: "<componentId>" }) を使って ref インスタンスとして挿入します
4. U(instanceId + "/childId", { ... }) を使って子孫要素を更新し、インスタンスをカスタマイズします
5. 適切な再利用可能なコンポーネントがない場合に限り、新しいコンポーネントを一から作成します

詳しいワークフローについては、references/design-system-components.md を参照してください。

ルール 2：ハードコード値ではなく、必ず変数を使用する

変数がある場合、色、角丸、余白、タイポグラフィの値をハードコードしてはいけません。

スタイル値を適用する前に、必ず次の手順を実行してください。

1. pencil_get_variables を呼び出し、定義済みのデザイントークンをすべて読み取ります
2. 使用する値を既存の変数に対応付けます（例：#3b82f6 ではなく primary、6 ではなく radius-md を使用）
3. 生の値ではなく、変数参照を使って値を適用します
4. コードを生成するときは、Tailwind v4 のセマンティックなユーティリティクラス（例：bg-primary、text-foreground、rounded-md）を使用します。任意の値を指定する構文（bg-[#3b82f6]、text-[var(--primary)]、rounded-[6px]）は使用してはいけません

詳しいワークフローについては、references/variables-and-tokens.md を参照してください。

ルール 3：テキストとコンテンツのはみ出しを防ぐ

テキストや子要素が親要素またはアートボードからはみ出してはいけません。

すべてのテキスト要素とコンテナについて、次の手順を実行してください。

1. 適切なテキストの折り返しと切り詰めを設定します
2. 特にモバイル画面（通常、幅 375px）では、幅を親要素の範囲内に収めます
3. 自動レイアウトフレーム内のテキスト要素には、幅として "fill_container" を使用します
4. コンテンツを挿入した後、pencil_snapshot_layout を problemsOnly: true で呼び出し、クリッピングやはみ出しを検出します
5. 次に進む前に、報告された問題をすべて修正します

詳しいワークフローについては、references/layout-and-text-overflow.md を参照してください。

ルール 4：すべてのセクションを必ず視覚的に検証する

セクションや画面を作成した後に、視覚的な検証を省略してはいけません。

各論理セクション（ヘッダー、ヒーロー、サイドバー、フォーム、カードグリッドなど）を完成させたら、次の手順を実行してください。

1. セクションまたは画面全体のノードに対して pencil_get_screenshot を呼び出します
2. スクリーンショットを確認し、配置の問題、余白の不一致、テキストのはみ出し、表示上の不具合、コンテンツの欠落がないか調べます
3. pencil_snapshot_layout を problemsOnly: true で呼び出し、クリッピングや重なりを検出します
4. 次のセクションに進む前に、見つかった問題をすべて修正します
5. デザイン全体が完成したら、画面全体の最終スクリーンショットを撮影します

詳しいワークフローについては、references/visual-verification.md を参照してください。

ルール 5：既存のアセット（ロゴ、アイコン、画像）を再利用する

ドキュメント内に既存のロゴやアセットがある場合、新しいロゴを生成したり、アセットを複製したりしてはいけません。

画像やロゴを生成する前に：

1. pencil_batch_get を呼び出し、名前のパターンで既存の画像／ロゴノードを検索します（例：patterns: [{ name: "logo|brand|icon" }]）
2. ドキュメント内の別の場所（別のアートボード／画面）に一致するアセットがある場合は、C()（コピー）操作でコピーします
3. ドキュメント内のどこにも存在しない、本当に新しい画像に対してのみ G()（生成）操作を使用します
4. ロゴについては、必ず既存のインスタンスからコピーし、再生成してはいけません

詳しいワークフローについては、references/asset-reuse.mdを参照してください。

ルール 6：必ず frontend-design スキルを読み込む

frontend-design スキルを読み込まずに Pencil でデザインしたり、Pencil からコードを生成したりしてはいけません。

frontend-design スキルは、一般的で型にはまった UI を避けるための、美的な方向性とデザイン品質基準を示します。必ず次のことを行ってください。

1. Pencil でのデザインまたはコード生成タスクを開始する際に、frontend-design スキルを読み込みます
2. そのデザイン思考プロセスに従います。目的を理解し、際立った美的方向性を定め、差別化を検討します
3. Pencil でのデザイン時と、Pencil のデザインからコードを生成する時の両方で、タイポグラフィ、色、動き、空間構成、視覚的な細部に関するガイドラインを適用します
4. ありきたりな AI 風のデザイン（使い古されたフォント、陳腐な配色、予測可能なレイアウト）を決して作成しません

これは、次のどちらにも当てはまります。

• Pencil のデザインタスク：スキルの美的ガイドラインを参考にして、.pen ファイルのレイアウト、タイポグラフィ、色、構成を選びます
• Pencil からのコード生成：生成コードに、特徴的なタイポグラフィ、意図的な配色、動き／アニメーション、洗練された視覚的な細部が含まれるよう、スキルのガイドラインを適用します。デザインツリーを機械的に変換するだけにしてはいけません

デザインワークフロー

新しいデザインを始める

0. Load `frontend-design` skill   -> Get aesthetic direction and design quality standards
1. pencil_get_editor_state        -> Understand file state, get schema
2. pencil_batch_get (reusable)    -> Discover design system components
3. pencil_get_variables           -> Read design tokens
4. pencil_get_guidelines          -> Get relevant design rules
5. pencil_get_style_guide_tags    -> (optional) Get style inspiration
6. pencil_get_style_guide         -> (optional) Apply style direction
7. pencil_find_empty_space_on_canvas -> Find space for new screen
8. pencil_batch_design            -> Build the design (section by section)
9. pencil_get_screenshot          -> Verify each section visually
10. pencil_snapshot_layout        -> Check for layout problems

セクションごとに構築する

画面の各セクション（ヘッダー、コンテンツ領域、フッター、サイドバーなど）について：

1. 計画 - 再利用するデザインシステムのコンポーネントを特定します
2. 構築 - コンポーネントを ref インスタンスとして挿入し、スタイルに変数を適用します
3. 確認 - セクションのスクリーンショットを撮り、レイアウトに問題がないか確認します
4. 修正 - はみ出し、配置、余白に関する問題に対処します
5. 続行 - 確認に合格してから、次のセクションに進みます

デザインからコードへのワークフロー

完全なワークフローについては、references/design-to-code-workflow.mdを参照してください。 Pencil から Tailwind への完全な対応表については、references/tailwind-shadcn-mapping.mdを参照してください。 複数のアートボードを対象としたレスポンシブなコード生成については、references/responsive-breakpoints.mdを参照してください。

概要：

1. 美的な方向性を定めるために frontend-design スキルを読み込みます
2. トピック "code" と "tailwind" を指定して pencil_get_guidelines を呼び出します
3. pencil_get_variables を呼び出し、デザイントークンを Tailwind の @theme 宣言に対応付けます
4. pencil_batch_get でデザインツリーを読み取ります
5. 再利用可能な Pencil コンポーネントを shadcn/ui コンポーネント（Button、Card、Input など）に対応付けます
6. セマンティックな Tailwind クラス（bg-primary、rounded-md）を使用してコードを生成し、任意の値は使いません
7. frontend-design のガイドライン（特徴的なタイポグラフィ、意図的な配色、動き、空間構成）を適用します
8. カスタムコンポーネントのバリアントには CVA、クラスのマージには cn()、アイコンには Lucide を使用します

MCP ツール クイックリファレンス

ツール	使用するタイミング
pencil_get_editor_state	最初に呼び出し、ファイルの状態を把握して .pen スキーマを取得します
pencil_batch_get	ノードを読み取り、コンポーネント（reusable: true）を検索し、構造を確認します
pencil_batch_design	要素の挿入、コピー、更新、置換、移動、削除、画像の生成を行います
pencil_get_variables	デザイントークン（色、角丸、間隔、フォント）を読み取ります
pencil_set_variables	デザイントークンを作成または更新します
pencil_get_screenshot	任意のノードを視覚的に確認します
pencil_snapshot_layout	クリッピング、はみ出し、要素の重なりを検出します
pencil_get_guidelines	code、table、tailwind、landing-page、design-system のデザインルールを取得します
pencil_find_empty_space_on_canvas	新しい画面やフレームを配置するスペースを探します
pencil_get_style_guide_tags	利用可能なスタイルの方向性を確認します
pencil_get_style_guide	特定のスタイルのインスピレーションを取得します
pencil_search_all_unique_properties	ドキュメント全体のプロパティ値を監査します
pencil_replace_all_matching_properties	プロパティを一括更新します（例：色の置き換え）
pencil_open_document	.pen ファイルを開くか、新しいドキュメントを作成します

避けるべきよくある間違い

間違い	正しい方法
ボタンを一から作成する	既存のボタンコンポーネントを検索し、ref として挿入します
fill: "#3b82f6" を使う	変数を使い、primary または対応する変数を参照します
cornerRadius: 8 を使う	変数を使い、radius-md または対応する変数を参照します
コードで bg-[#3b82f6] を生成する	セマンティックな Tailwind クラス bg-primary を使います
コードで text-[var(--primary)] を生成する	セマンティックな Tailwind クラス text-primary を使います
コードで rounded-[6px] を生成する	セマンティックな Tailwind クラス rounded-md を使います
className で var(--primary) を使う	セマンティックな Tailwind クラス bg-primary または text-primary を使います
はみ出しを確認しない	各セクションの後に pencil_snapshot_layout(problemsOnly: true) を呼び出します
スクリーンショットを省略する	各セクションの後に pencil_get_screenshot を呼び出します
新しいロゴを生成する	C() を使って、別のアートボードにある既存のロゴをコピーします
画面全体を作成してから確認する	セクションごとに作成して確認します
pencil_get_guidelines を無視する	作業を始める前に、関連するトピックのガイドラインを必ず呼び出します
tailwind.config.ts を使う	CSS の @theme ブロックを使います（Tailwind v4）
コードで Material Icons を使う	Lucide アイコンに対応付けます（<Search />、<ArrowRight /> など）
frontend-design スキルを省略する	Pencil でのデザインやコード生成の前に、必ず読み込みます
一般的な AI 風のデザイン（Inter フォント、紫のグラデーション）	独自性があり、意図の明確なデザインにするため、frontend-design のガイドラインに従います

リソース

• Pencil ドキュメント
• Pencil プロンプトギャラリー
• コードとしてのデザイン
• 変数
• コンポーネント
• デザインからコードへ
• スタイルと UI キット