design-system-patterns

design-system-patterns スキルの概要

design-system-patterns スキルは、スケーラブルな UI システムの土台となる設計を AI エージェントが組み立てるのに役立ちます。対象は、トークン構造、テーマ設計、コンポーネント API パターンです。新規のデザインシステムを作るチーム、既存システムをリファクタリングするチーム、コンポーネントライブラリを整備したいチーム、light/dark や multi-brand のテーマ対応を進めたいチーム、複数プロダクトにまたがるデザイン判断を標準化したいチームに特に向いています。

design-system-patterns スキルが最も力を発揮する場面

このスキルが強いのは、単発のコード断片ではなく、アーキテクチャの判断が必要なときです。AI エージェントが次のような論点を、構造立てて検討できるようになります。

• primitive / semantic / component token といったトークンレイヤーの分け方
• テーマ実装における CSS custom properties 戦略
• variants、polymorphism、compound components などのコンポーネント設計パターン
• 多数のコンポーネントへ広げても破綻しない design system の意思決定

実際の導入目的に即した使いどころ

多くのユーザーが必要としているのは、抽象的な意味での「デザインシステム」ではありません。実際には、次のような問いに答えるための実務的な方針です。

• トークンはどう命名し、どう整理すべきか
• すべてのコンポーネントを書き直さずに dark mode をどう支えるか
• ライブラリが大きくなっても保守しやすいコンポーネント API パターンは何か
• ハードコードされたスタイル指定がコードベース全体に広がるのをどう防ぐか

design-system-patterns スキルが有用なのは、こうした判断を単発のスタイリング作業ではなく、システム設計として扱えるようにしてくれる点です。

このスキルの導入に向いている人

相性がよいケース:

• 共通 UI 基盤を作る frontend engineers
• token と theming のルールを定める design system チーム
• 再利用可能なコンポーネントライブラリを作る React チーム
• デザインツールと実装パターンを揃えたいチーム

あまり向かないケース:

• 単発ページのスタイリング
• 再利用前提のない簡易ビジュアルモック
• 欲しい実装パターンがすでに明確な、強く framework に依存した実装作業

汎用プロンプトとの違い

汎用プロンプトでも「design tokens を使う」「dark mode を追加する」といった提案はできます。ただし design-system-patterns skill は、確立された design-system のレイヤーや設計パターンに沿ってエージェントに考えさせたいときに、より実用的です。付属リファレンスでは、token taxonomy、CSS variables を使った theming、component composition patterns まで踏み込んでいるため、出力が一貫しやすく、再利用もしやすくなります。

導入判断の前に確認したいファイル

適合性を見るなら、まず次を確認してください。

• SKILL.md
• references/design-tokens.md
• references/theming-architecture.md
• references/component-architecture.md

ここで扱っているテーマが今の課題と一致しているなら、このスキルは導入する価値が高いはずです。

design-system-patterns スキルの使い方

design-system-patterns のインストール前提

このスキル単体のカスタム package install は用意されておらず、wshobson/agents リポジトリ内に含まれています。skills 対応環境では、リポジトリからインストールしたうえで design-system-patterns スキルを指定します。

npx skills add https://github.com/wshobson/agents --skill design-system-patterns

エージェント実行環境で別の skill 読み込みフローを使っている場合は、次の repo URL と skill slug を参照してください。

plugins/ui-design/skills/design-system-patterns

このスキルに渡すべき入力情報

design-system-patterns の活用品質は、システム上の制約をどれだけ具体的に伝えられるかに大きく左右されます。少なくとも次は渡すのがおすすめです。

• 対象プラットフォーム: web only、React、mobile、multi-platform
• テーマ要件: light/dark、multi-brand、high contrast、reduced motion
• トークン範囲: colors のみ、foundation 全体、component tokens まで含むか
• コンポーネント対象: greenfield のライブラリ、新規移行、既存リファクタ
• 制約条件: CSS Modules、Tailwind、CSS-in-JS、SSR、legacy styles、design tooling
• 欲しい成果物: token schema、theme contract、component API examples、migration plan

この文脈がないと、エージェントは汎用的な design-system 論に寄りがちです。

ざっくりした要望を強いプロンプトに変える

弱いプロンプト:

Help me build a design system.

よりよいプロンプト:

Use the design-system-patterns skill to propose a token hierarchy and theming architecture for a React component library. We need light/dark themes, semantic color tokens, and scalable button/card/input APIs. We currently use CSS custom properties and want to avoid hard-coded colors in components. Show naming conventions, file organization, and example component variant patterns.

こちらのほうがうまく機能するのは、対象範囲、実装の方向性、成功条件が明確だからです。

design-system-patterns 活用のおすすめワークフロー

実務では、次の順番が進めやすいです。

1. いきなりコード生成を求めず、まずアーキテクチャを出してもらう
2. token layers と theme model を検証する
3. それらを消費する component API patterns を出してもらう
4. その後で、代表的な 1〜3 個のコンポーネント実装例を依頼する
5. 最後に migration steps と guardrails を整理する

この順番には意味があります。最初にコンポーネントコードから入ると、token system が固まる前に場当たり的な判断が固定化されやすくなります。

リポジトリ内で先に読むべきファイル順

最短で理解したいなら、読む順番は次がおすすめです。

1. スコープ把握のための SKILL.md
2. トークン構造を確認する references/design-tokens.md
3. CSS variables と theme 設計を見る references/theming-architecture.md
4. 再利用可能な component patterns を確認する references/component-architecture.md

この順番は、多くのチームが実装でたどるべき順序とも一致しています。つまり、tokens → themes → components です。

design-tokens リファレンスが特に役立つ場面

references/design-tokens.md は、エージェントに次の区別をさせたいときに有効です。

• 生の palette values にあたる primitive tokens
• text / background / surface など役割ベースの semantic tokens
• 個別コンポーネント内の判断に使う component tokens

これは design-system-patterns guide の中でも、特に導入成否に直結しやすい部分です。多くのチームは、palette values からいきなり component code に飛んでしまうことで失敗します。

theming リファレンスで整理できる判断

references/theming-architecture.md は、次の論点を含むプロンプト設計に向いています。

• CSS custom property の contract
• [data-theme] による theme switching
• system preference の検出
• theme choice の永続化
• reduced motion や high contrast などアクセシビリティ関連モード

本当の目的が component API ではなく theme architecture なら、その点を明示してこの資料に寄せると効果的です。

component architecture リファレンスが得意な範囲

references/component-architecture.md は、次のような依頼に向いています。

• compound components
• variant と size の API
• polymorphic as パターン
• context ベースの component composition

再利用可能なライブラリを作るうえで、単一のコンポーネント群に閉じない API 設計をしたいなら、ここが重要です。

質の高いプロンプトテンプレート

design-system-patterns for Design Systems の用途では、次の構成で依頼すると精度が上がります。

• プロダクトとプラットフォーム
• 現在のスタイリング手法
• theming 要件
• 必要な token categories
• 最初に標準化したい components
• アクセシビリティ制約
• 欲しい deliverable の形式

例:

Use the design-system-patterns skill. We are building a React web design system for two brands with light/dark themes. Current stack: CSS custom properties plus TypeScript. We need primitive and semantic tokens first, then component tokens for button, input, and card. Recommend naming conventions, theme variable structure, component variant patterns, and a migration plan from hard-coded styles.

出力品質を上げる実践的なコツ

エージェントには、広い説明文ではなく、具体的な成果物を出させるのがおすすめです。たとえば次のようなものです。

• token naming matrix
• theme variable contract
• component API table
• folder structure
• migration checklist
• risks and tradeoffs

こうした形式のほうが、抽象的な助言よりレビューしやすくなります。

先に共有しておきたい導入上のボトルネック

このスキルに頼る前に、次の点は事前に伝えておくとよいです。

• design 側に token source of truth がすでにあるか
• 出力を複数プラットフォームで利用する必要があるか
• components が SSR をサポートする必要があるか
• アクセシビリティモードを初期段階から必須とするか
• 後方互換を保った migration が必要か

これらの制約は、このスキルが提案すべきアーキテクチャを大きく左右します。

design-system-patterns スキル FAQ

design-system-patterns スキルは初心者にも向いていますか？

はい。ただし、基本的な UI スタイリングや component 開発をある程度理解していることが前提です。リファレンスは中級レベルのチームがよりよいシステム判断をするのに十分な構成になっています。一方、完全な初心者であれば、CSS、React、アクセシビリティの基礎は別途補う必要があります。

通常のプロンプトではなく design-system-patterns を使うべきなのはいつですか？

課題がシステム全体の整合性に関わるときです。たとえば token hierarchy、theming、再利用可能な component architecture などです。単一コンポーネントの見た目調整や、一回限りの UI バグ修正なら、通常のプロンプトのほうが速いことが多いです。

このスキルは本番投入できるコードを生成してくれますか？

どちらかといえば、すぐ貼り付ける実装ジェネレーターというより、アーキテクチャとパターン設計のためのスキルとして捉えるのが適切です。サンプルコード生成には役立ちますが、本質的な価値は、大規模実装に入る前に token、theme、component の判断を一貫したものにできる点にあります。

design-system-patterns スキルは React 専用ですか？

いいえ。ただし、compound components や polymorphic component の例など、一部の参照パターンは React 寄りです。とはいえ、token や theming の考え方自体は、実装レイヤーが異なっても広く応用できます。

multi-brand theming にも役立ちますか？

はい。これは design-system-patterns skill が特にはまりやすいケースのひとつです。semantic tokens と CSS custom property contracts を組み合わせると、特に効果が出やすくなります。

このスキルを選ばないほうがよいのはどんなときですか？

次のような場合は見送るのが妥当です。

• 実装アーキテクチャではなく、ビジュアルデザインの探索が目的
• framework 固有の低レベルなスタイル修正が必要
• 共通 component system を持たない小規模アプリ
• 再利用性が低い marketing-site 中心のスタイリング

最大の制約は何ですか？

このスキルが提供するのはパターンであり、リポジトリ固有の強制力ではありません。この skill folder には scripts、rules、generators が含まれていないため、品質は、制約条件をどれだけ明確に伝えられるか、そして提案パターンを自分たちの stack にどれだけ適切に落とし込めるかに左右されます。

design-system-patterns スキルをより良く活用するには

コンポーネント要求より先に、まずアーキテクチャを固める

design-system-patterns で弱い結果を招く最短ルートは、token layers や theme semantics を決める前に Button のコードを求めることです。先に system model を出させ、その後で実装例に進めてください。

token 戦略の brief を渡す

強い入力になるのは、たとえば次のような判断材料や未解決論点です。

• primitive と semantic token の分離方針
• naming conventions
• aliasing rules
• theme ごとに変えてよい値
• brand をまたいでも固定すべき値

これにより、エージェントが raw values と semantic roles を混同しにくくなります。

theming model を明示する

必要なのが何かを、はっきり伝えてください。

• light/dark のみ
• brand themes と color modes の両方
• OS preference detection
• user preference の永続化
• accessibility modes

ここが曖昧だと、theming architecture が過剰にも不足にもなりやすいです。

代表的なコンポーネントで反復する

ごく単純な 1 コンポーネントだけでスキルを評価しないでください。たとえば次のような小さなセットでモデル化させると有効です。

• Button で variants と states を確認する
• Input で form semantics を確認する
• Card で surfaces と elevation を確認する

この組み合わせを見ることで、提案された token system と component API が本当にスケールするか判断しやすくなります。

推奨案だけでなく、トレードオフも出させる

有効な追加入力の例:

Using the design-system-patterns skill, compare two token naming approaches and explain migration, readability, and long-term maintenance tradeoffs.

単一の「最善策」を求めるより、こちらのほうが意思決定の質は上がります。

よくある失敗パターンは早めに修正する

初回出力では、次のような問題をチェックしてください。

• semantic tokens が raw palette names に寄りすぎている
• component APIs がスタイリング内部を露出しすぎている
• dark mode が token contract ではなく override として追加されている
• component examples が tokens を消費せず値をハードコードしている
• accessibility modes が考慮されていない

問題を見つけたら、全部を再生成させるのではなく、そのレイヤーだけを指定して修正させるほうが効果的です。

design と engineering が一緒にレビューできる成果物を求める

design-system-patterns guide の出力を改善したいなら、チームレビューにそのまま持ち込める成果物を依頼してください。

• token JSON examples
• CSS variable contract examples
• component prop API tables
• migration phase plan
• naming rules with examples and anti-examples

こうした形式は、抽象的な推奨事項よりも議論しやすく、導入にもつながりやすいです。

実際のリポジトリ制約をもとに反復する

2 回目以降のプロンプトでは、コードベースの現実的な制約を入れるのが最も効果的です。たとえば次のような情報です。

• 既存の token files
• 現在の CSS variable names
• component props の不整合
• theming bugs
• brand requirements

design-system-patterns スキルは、理想論を説明させるより、散らかった現実のシステムをどう改善するかという文脈で使うほうが、はるかに価値を発揮します。