authoring-design-system

authoring-design-system — SKILL.md

バリアント： standard · 使用するタイミング： プロダクトの方向性をもとに、デザイナーやエンジニアが一貫性のあるアクセシブルな UI を構築できる品質基準を満たすデザインシステム文書を作成（または改訂）するとき。

概要

このスキルは、実用的で一貫性があり、アクセシブルなデザインシステム文書の書き方を示します。デザインシステムとは、プロダクトの UI がよりどころとする、再利用可能なビジュアル言語とインタラクション言語です（原則、デザイントークン、コンポーネントカタログ、パターン、レイアウトと国際化の規約、アクセシビリティ基準、ボイス、ライフサイクルとガバナンス）。ここで提供するのは作成者の判断力であり、セクションの一覧ではありません。このスキルでは、2 つの協力者を想定しています。セクションの構成を提供するデザインシステムテンプレートツールと、トークンやコンポーネントを確立されたプラクティスに基づかせるための詳細調査機能です。作成者はプロダクトの方向性（およびユーザーフロー）を受け取り、それを具体化する必要があります。一般的な定型文を出力してはいけません。満たすべき基準は、デザイナーが一貫性のある UI を構築でき、エンジニアが文書に基づいて実装できること、プロダクトの画面に必要なすべてのコンポーネントがカタログに網羅されていること、そしてシステムがアクセシブルであることです。この文書は、後続のワイヤーフレームや高精細デザインがよりどころとする語彙であり、それらに先立って作成されます。

成果物はテキスト形式の Markdownです。値としてのトークンと DTCG 形式のテーブル（hex／HSL／Oklch）、タイポグラフィのスケール、コンポーネント仕様のテーブルで構成されます。レンダリングされた Figma ファイルでも、コンパイル済みのトークンパッケージでもありません。手法は媒体に依存しませんが、現時点での成果物はテキストです。

有効化するタイミング

• プロダクトの方向性や PRD をもとに、新しいデザインシステム文書を作成するとき。
• 限定的なトークンセットやコンポーネントリストを、完全なデザインシステム（基盤、カタログ、パターン、アクセシビリティ、ボイス、ガバナンス）に拡張するとき。
• 変更に応じて既存のデザインシステムを改訂するとき（新規または変更されたトークンやコンポーネント）。範囲を限定したバージョン管理付きの差分として扱います（ステップ 7 を参照）。
• 調査に基づく、意思決定が完了した内容でデザインシステムテンプレートを埋めるとき。

有効化してはいけない場合：

• 完成したデザインシステムをレビューまたは評価するとき → reviewing-design-system を使用してください。このスキルが定めるものと同じ基準を評価します。
• 画面ごとのレイアウトやコンポーネントの配置を定義するとき → それは authoring-wireframes の役割です。authoring-wireframes は、このスキルが作成するデザインシステムを参照します。
• 高精細なコードプロトタイプを作成するとき → それは後続の利用者である authoring-hi-fi の役割です。
• コード化されたコンポーネントライブラリ（CSS／React）をリリースするとき → これは実装ではなく、トークン、仕様、ルールを含む文書です。
• 別の種類の文書を作成するとき → その種類に対応するスキルを使用してください。

入力

計画で渡されたすべての文書（上流の文書のうち、この文書に情報を提供するとディスカバリーで判断された depends_on のセット）を読み、この文書の内容がそれらにどう結び付くかをたどってください。プロダクション品質のデザインシステムを作成するために推奨される入力セットは、プロダクトの方向性／PRD（ペルソナ、目的、対象範囲）と、利用可能であればユーザーフロー（どの画面が存在し、それによってどのコンポーネントが必要になるかを示します）です。改訂の場合は、既存のデザインシステム文書と対象範囲を限定した変更も渡されます。この推奨セットはガイダンスであり、必須条件ではありません。自己完結型であることを意識し、実際に受け取った情報から作成してください。情報提供元として想定されていた文書がない場合は、手元にある情報で進め、不足を明示的な前提として示してください。決して捏造してはいけません。テンプレートを埋めるだけでなく、文書を包括的なものにするため、利用可能な場合は調査機能（詳細調査）を活用してください。

ワークフロー

Step 1: テンプレートツールから構成を取得します — アウトラインを独自に作成しないでください

デザインシステムのテンプレートツール（包括的なバリアント）からセクション構成を取得してください。ここでセクション一覧を再掲したり、導き出したりしないでください。このスキルが提供するのは、それらのセクションを適切に埋める方法です。テンプレートが利用できない場合は、包括的な構成を用意してから（依頼するか、自分で作成するか、標準的なセットである「原則 → トークン → コンポーネントカタログ → パターン → レイアウトと i18n の規約 → アクセシビリティ → ボイス → ライフサイクル／ガバナンス」に従ってください）、次に進んでください。

Step 2: プロダクトの方向性と対象範囲を把握し、アーキタイプを特定します

プロダクトの方向性／PRD と、ユーザーフローを読みます。プロダクトのアーキタイプ（シンプルな CLI／ユーティリティ、コンテンツアプリ、または本格的なインタラクティブ UI プロダクト）を特定してください。これによって、i18n、マルチブランド、ガバナンスなど、適用される任意の観点を含むシステム全体の規模が決まります。ブランド／ビジュアルの方向性が不明瞭な場合は、選択した内容を明示的に（明記した前提または未解決の質問として）示し、汎用的な内容を黙って当てはめないでください。対象ユーザーはオーナーが決定します。対象ユーザーとドメイン知識のレベルを決定事項として記録してください。想定した対象ユーザーは未解決の質問として提示し、黙って前提に組み込まないでください。

Step 3: トークン、コンポーネント、アクセシビリティ、規約を裏付けるために調査します

徹底的な調査を行い、確立された実践に基づいて、トークン、コンポーネントセット、パターン、アクセシビリティの目標、トークンの形式、i18n／ガバナンスの規約を定めてください。独自に作り出さないでください。調査機能が利用できない場合は、捏造せず、標準的な既定値と照らし合わせ、選択した規約を明示的に前提として記載してください。

Step 4: セクションごとの手法を適用する

テンプレートの各セクションを、次の手法に沿って記入します（各項目の詳細は references/ にあります）。

• 原則 — レビュー担当者が意見の相違を解決する際に判断材料にできる、明確な立場を示した、実行可能な信念を3〜6個挙げ、それぞれにトレードオフを明記します。ありきたりな標語は避けます。
• デザイントークン — すべてのデザイン上の決定を、3つの階層でトークンとして定義します。プリミティブ／参照（生の値）→ セマンティック／システム（意図に基づく名前で、プリミティブを参照）→ コンポーネント（セマンティックを参照）。名前は見た目ではなく意図に基づけます（color.blue.500 ではなく color.action.primary）。セマンティック層は、コンポーネントが参照し、システムの一貫性とテーマ適用を可能にする層です。W3C DTCG 形式（型付きの $value、エイリアス）でトークンを記述します。これは大規模なシステムだけでなく、どの規模でも必須です（references/tokens-dtcg.md）。
  • 色 — プリミティブな色の段階と、セマンティックな役割のトークン（テキスト／アクション／フィードバック／サーフェス／境界線／フォーカス）を定義し、テキストと UI のすべての組み合わせについてコントラスト比を記録します（アクセシビリティと連動します）。製品に適している場合は、モダンな色空間（Oklch／Display-P3 と sRGB フォールバック）を使います。デフォルトとして sRGB を使うのも問題ありません。
  • タイポグラフィ — 役割 × サイズの書体スケール（ディスプレイ／見出し／タイトル／本文／ラベル）を、基準とする比率に基づいたサイズ／行の高さ／ウェイトの表として定義します。本文の行の高さは約1.4〜1.6とします。
  • スペーシングと密度 — 4／8px グリッドに基づく基本単位を1つと、乗算式のスケールを定めます。データ密度の高いサーフェスに対する密度の方針を明記します。
  • エレベーション — 小規模な名前付きレベルセット（通常 → 持ち上げ → オーバーレイ）を定めます。それぞれをシャドウ／サーフェスとして定義し、役割に対応づけます。
  • モーション — 時間とイージングのトークンを定義し、それらを組み合わせて名前付きトランジションを作成します。動きを抑える設定への方針も含めます。
  • アイコノグラフィ — アイコングリッド／キーライン、線の太さ、サイズセット、スタイルを1つずつ明記します。アセットが外部にある場合も、ルールを文書化します。
  • テーマ設定 — ライト／ダーク、および製品で必要な場合はマルチブランドに対応するため、固定されたセマンティック／コンポーネント階層の上で、テーマ／ブランドごとのプリミティブにセマンティックエイリアスの参照先を切り替えて実装します。コンポーネントを分岐させてはいけません。
• コンポーネントカタログ — サイズ設定については Step 5 を参照してください。各コンポーネントを、次の6つの項目で統一して仕様化します。目的、構成（パーツと、それぞれが使うトークン）、状態（該当する場合はデフォルト／ホバー／アクティブ／フォーカス／無効／読み込み中／エラー）、バリエーション（種類 + サイズ）、使用時の注意点、アクセシビリティ（ロール、キーボード操作、フォーカス、コントラスト、状態の伝え方）。カタログ全体でAPI の用語を統一します（同じバリエーション軸には常に同じ名前を付けます。variant／size／state を使い、ある箇所では type、別の箇所では mode としないようにします。共通の値は各軸に沿って組み合わせられるようにします）。
• パターン — フローで必要となる、複数のコンポーネントを組み合わせた繰り返しのシナリオ（フォームの検証、空の状態、破壊的操作の確認など）に名前を付けます。それぞれで組み合わせるコンポーネント／トークンとルールを記載します。
• レイアウトと国際化の規約 — ブレークポイント、グリッド（列／ガター／マージン）、最小タッチターゲット、フォーカス順を定めます。製品がローカライズ済み、または今後ローカライズされる場合は、国際化と RTL についても定めます。テキストの拡張に備える余裕（柔軟なコンテナ）、論理 CSS プロパティ、RTL／双方向テキストのミラーリング、ロケール別フォントスタック、ロケールに応じた書式設定を含めます。単一ロケール向けのツールであれば、国際化を対象外にすることを明示できます。
• アクセシビリティ基準 — WCAG 2.2 AA に準拠し、数値で測定・確認できる基準を定めます（Step 6 を参照）。
• 文体とコンテンツ — 文体とトーンの幅（フォーマル ↔ 遊び心のある表現）を定めます。重要度の高い場面では、ブランドの文体より明確さを優先するルールを設けます（エラーや破壊的操作の場合）。用語は1つの概念につき1つに統一します。コンポーネント内の文言ルール（ボタンは動詞から始める、エラーは原因 + 解決策、空の状態では次の行動を案内する）を定めます。
• ライフサイクルとガバナンス — メンテナーが1人、利用者が1人、外部向けにバージョン管理されていないシステムであれば省略可能です。それを超える場合は必須となり、バージョン管理（semver）と変更履歴、非推奨化と移行の方針、貢献モデル、所有権、導入と利用開始の方法、記録された対象ユーザーを文書化します（references/governance.md）。

Step 5: コンポーネントカタログの規模を決める — 必須最低限と標準セット

カタログでは、両方を網羅する必要があります。（a）画面領域の必須最低限 — プロダクトのフロー／画面で実際に使用するすべてのコンポーネントを、各項目の仕様を完全に定めて含めます（必須）。そして、（b）アーキタイプに応じた標準セット — 小規模なツールなら少数、フル機能の UI プロダクトなら幅広いセットを揃えます。必要なコンポーネントを、入手できる指針だけでは完全に仕様化できない場合は、動作を作り上げず、未解決の質問として提示します。

Step 6: アクセシビリティを数値で定める（WCAG 2.2 AA）

目標として WCAG 2.2 AA を明示し、すべてのしきい値を数値で示します（references/accessibility-wcag22.md）。テキストのコントラスト比は 4.5:1 以上（大きな文字／UI は 3:1 以上）。フォーカス時に視認できるフォーカスインジケーター（SC 2.4.7、AA）を設け、フォーカス時に隠れないようにします（SC 2.4.11、AA）。さらに、より厳格な AAA Focus Appearance（SC 2.4.13）を独自ルールとして採用し、2px 以上、非フォーカス時とのコントラスト比 3:1 以上、隣接要素とのコントラスト比 3:1 以上とします。ターゲットサイズは 24×24（間隔による例外あり）、すべての操作をキーボードで実行できること、動きを抑える設定への対応、色だけに意味を持たせないこと、各コンポーネントのロール／名前／状態を伝えることを求めます。アクセシビリティを後工程に回さず、トークン仕様（コントラスト、フォーカス）と各コンポーネントのアクセシビリティ項目に組み込みます。

Step 7: 改訂モード — 既存システムをバージョン管理された差分として編集する

既存のデザインシステムと対象範囲を定めた変更が渡された場合は、再生成せず、改訂します（references/amend.md）。変更範囲は、対象となるトークン／コンポーネントとその波及範囲（変更したトークンを参照するすべてのコンポーネント、名前を変更したコンポーネントを利用するすべての箇所、影響を受けるすべてのテーマエイリアス）に限定します。既存の箇所を最小限だけ編集し、変更のないトークン／コンポーネントはバイト単位でそのまま維持します。差分をバージョン管理します。システムの semver を更新し（破壊的変更は MAJOR — 名前の変更／削除／型の変更、追加は MINOR、修正は PATCH）、Keep-a-Changelog のエントリー（Added／Changed／Deprecated／Removed／Fixed）を追加します。破壊的変更では、非推奨化してから移行します（MINOR で非推奨化 → 移行に関する注記 → MAJOR で削除）。告知なしに削除してはいけません。エイリアスレイヤーを活用します。すべてのコンポーネントを編集する代わりにセマンティックエイリアスの参照先を変更すれば、影響範囲を縮小できます。

Step 8: 引き渡し前に基準に照らしてセルフチェックする

すべての項目が満たされていることを確認します（reviewing-design-system が求める同じ基準です）。原則が明記されていること。トークンが定義され、DTCG に準拠し、意図を表す名前が付いていること。コンポーネントがセマンティックトークンを参照しており、生の値を直接使っていないこと。アーキタイプに必要な基盤として、グリッド／密度／アイコノグラフィ／モダンカラーが網羅されていること。すべてのコンポーネントが完全に仕様化されていること（6 つの項目）と、API の用語が統一されていること。カタログが必須最低限とアーキタイプの標準セットを網羅していること。パターンが揃っていること。レイアウトと i18n に対応しているか、i18n を対象外として明示していること。アクセシビリティが WCAG 2.2 AA に基づいて数値化されていること。ボイスとコピーのルールが含まれていること。ライフサイクル／ガバナンスが含まれていること（または、しきい値を下回る場合に正当に省略されていること）。定型文ではなく、根拠に基づいていること。既存システムの改訂では、差分の範囲が限定され、バージョン管理され、非推奨化の手順が安全に定められていること。**指針が不十分な場合のゲート：**画面領域をおおよそでも推定できない場合は、カタログを作り上げず、ブロッカーとして提示します。

ルール

必ず守るルール（例外なし）：

• 重複ではなく、組み合わせる。 セクション構成はテンプレートツールから引き継ぎ、このスキルではその内容を埋める方法を定めます。
• 意図に基づいてトークンに名前を付け、DTCG 形式で表現する。 意味に基づく名前のセマンティックトークン（color.feedback.danger など）を使い、コンポーネントは生の値ではなく、必ずセマンティックトークンを参照します。トークンは、どのような規模でも、型付きかつエイリアスを含む W3C DTCG 形式にします。値の表による例外は認めません。
• テーマの切り替えはエイリアスの差し替えで行う。 ライト／ダークテーマや複数ブランドへの対応には、単一の固定ティア上でセマンティックエイリアスの参照先を変更します。コンポーネントを分岐させてはいけません。
• すべてのコンポーネントを完全に仕様化し、API の用語を統一する。 構造、状態、バリアント、使用方法、アクセシビリティを網羅し、カタログ全体で同じバリエーション軸には同じ名前を使います。
• 対象範囲の最低ラインを満たす。 実際の画面で使われるすべてのコンポーネントをカタログに含め、完全に仕様化します。
• アクセシビリティは WCAG 2.2 AA に基づき、数値で定める。 コントラスト、フォーカス（可視であり、隠されないことを AA で満たす。さらに、AAA のフォーカス表示に関する基準である 2px／3:1 を独自ルールとして採用）、ターゲットサイズ 24px、キーボード操作、動きの低減、色だけに依存しないことを扱います。数値を伴わない「アクセシブル」は基準になりません。
• i18n：対応するか、明示的に対象外とする。 ローカライズ対象の製品では、テキストの拡張、論理プロパティ、RTL を網羅します。単一ロケールのツールでは、対象外とする範囲を明記し、省略したままにしません。
• ガバナンス：基準を下回る場合は省略し、上回る場合は必須とする。 メンテナーが 1 人、利用者が 1 者、外部向けのバージョン管理がない場合は、ライフサイクル／ガバナンスのセクションを省略できます。それ以外の場合は必須です。
• 変更時は描き直さずに編集し、バージョン付きの差分を作る。 変更時は、対象範囲を絞った最小限の編集を行い、バージョンを付けます（semver と変更履歴）。互換性を損なう変更は、廃止を告知してから移行します。変更のない箇所を再生成したり、刷新したりしてはいけません。
• 捏造しない。 根拠があるように見せるために、パレット、コントラスト値、慣習を作り出してはいけません。不明な点は、仮定であることを明示します。
• テキスト形式で作成する。 レンダリング済みのデザインファイルではなく、値と仕様表（Markdown）を使います。
• 構築可能でなければ、完成とはみなさない。 デザイナーやエンジニアが、一貫性とアクセシビリティを備えた UI を構築できないシステムを引き渡してはいけません。

推奨事項（必要に応じて変更可能）：

• 「包括的」は目指す水準を示すものであり、製品の規模に応じた内容にします。行数ではなく、決定事項が網羅されていることを重視します。規模の小さい製品では、セクションをまとめ、標準セットを絞り、i18n／複数ブランドへの対応を対象外とし、ガバナンスを省略できます。ただし、必須の最低ライン、DTCG、アクセシビリティの数値基準は維持します。
• 原則は簡潔な箇条書き 3〜6 項目にまとめ、一般的なトークン階層／タイプスケールの役割を優先します。
• 互換性を維持できる場合は、トークンを破壊的に変更するのではなく、セマンティックエイリアスの参照先を変更します。

注意点

• 値に基づく名前、または DTCG 形式ではないトークン。 ボタンが参照する color.blue.500 や、DTCG 構造のない単純な HEX 値の一覧は、テーマ設定と相互運用性を損ないます。小規模なシステムでも、意味に基づいて命名し、DTCG 形式で表現します。
• 仕様が不完全なコンポーネント。 状態（またはアクセシビリティ）のないバリアントは、完成しているように見えても、一貫して構築できません。すべてのコンポーネントで、6 つの要素すべてを網羅します。
• API の用語の揺れ。 コンポーネントごとに type、variant、mode を使い分けると、システムの一貫性が損なわれます。用語を統一します。
• 標準セットだけで作るカタログ。 実際の画面で使われるコンポーネントを省くと、カバー範囲に抜けが生じます。まずフローを確認します。
• 目標だけを掲げたアクセシビリティ。 WCAG 2.2 の目標や数値がなければ、基準にはなりません。
• 後回しにされる i18n。 固定幅のテキストや物理プロパティに基づく CSS は、翻訳時に問題を引き起こします。基盤の段階から、柔軟なコンテナーと論理プロパティを組み込みます。
• 変更のたびに再生成する。 1 つのトークンを変更するためにシステム全体を書き直すのは、対象範囲を絞ったバージョン付きの差分ではなく、変更時に再生成するというアンチパターンです。描き直さずに編集します。
• 汎用的な内容で埋める。 どの製品にも当てはまるトークンやコンポーネントばかりなら、具体化したのは 製品 ではなく テンプレート です。

アンチパターン

• 「アウトラインは自分で書きます。」 テンプレートツールと重複します。構成はそのまま使い、方法と基準を補います。
• 「DTCG が必要なのは大規模なシステムだけです。」 規模にかかわらず必要です。小規模なシステムでも、型付き／エイリアス付きのトークンを使用します。
• 「アクセシビリティは後で対応します。」 コントラスト、フォーカス、キーボード操作はトークンとコンポーネントの仕様に含めます。最初から WCAG 2.2 に準拠させます。
• 「標準セットがカタログのすべてです。」 それは半分です。残りの半分は、製品の画面で使うすべてのコンポーネントです。
• 「小さな変更なので、システム全体を再生成します。」 範囲を限定したバージョン付きの差分として変更を加え、手を加えていない部分は決して刷新しません。
• 「方向性が曖昧なので、カタログ全体を自分で作ります。」 不足している範囲は、ブロッカー／未解決の質問として明示します。

出力

Step 8 の基準を満たすデザインシステム文書（原則、一貫して適用される意図を表す名前付きの DTCG トークン、アイコン・グリッド・密度・モダンカラーを含むすべての基盤、完全な仕様と統一された API 用語を備えたすべてのコンポーネント、最低限必要な範囲と標準セットを網羅するカタログ、パターン、レイアウトと i18n、数値で示す WCAG 2.2 AA アクセシビリティ基準、トーンとコピーのルール、必要に応じたライフサイクル／ガバナンス、定型文ではなく根拠に基づいた内容、改訂時は範囲を限定したバージョン付きの差分）。抽象的な利用者は、後続工程のワイヤーフレーム作成とハイファイデザイン（この文書のコンポーネントを参照）、UI エンジニアリング（この文書をもとに構築）、およびレビュー担当者（同じ基準で評価）です。テキスト（Markdown）で記述し、ワイヤーフレーム／ハイファイデザインに一方向で先行します。

関連項目

• デザインシステムのテンプレートツール（コンテンツ／テンプレートのゲートウェイ）— このスキルが記入するセクション構成を提供します。
• ディープリサーチ機能 — トークン、コンポーネント、パターン、アクセシビリティ目標、DTCG 形式、i18n／ガバナンスの慣例の根拠を提供します。
• reviewing-design-system — 同じ基準で評価します。作成者とレビュー担当者が同じ基準を共有することで、認識のずれを防ぎます。
• authoring-wireframes + authoring-hi-fi — 後続工程の利用者です。画面ではこの文書のコンポーネントを配置し、トークンを参照します。
• 上流のプロダクト方針／PRD（および任意でユーザーフロー）— このスキルが具体化する入力です。白紙から始めることはありません。

段階的な開示

• references/tokens-dtcg.md — DTCG トークン形式（階層、型付きの $value、エイリアス設定、テーマ／マルチブランド、モダンな色空間）。
• references/accessibility-wcag22.md — WCAG 2.2 AA の数値基準と、コンポーネントごとのアクセシビリティ。
• references/i18n-rtl.md — 国際化／RTL の規約（テキストの拡張、論理プロパティ、ロケール別タイポグラフィ）。
• references/governance.md — ライフサイクルとガバナンスのポリシー（バージョン管理、非推奨化／移行、コントリビューション、オーナーシップ、採用、対象者）と、しきい値未満の場合は省略するルール。
• references/amend.md — 改訂モード（影響範囲の特定、描き直しではなく編集、バージョン付きの差分、非推奨化してから移行）。
• references/sources.md — 方法、トークン／コンポーネントの規約、アクセシビリティ基準に関する調査の出典情報。

本文の上限

• description は 1,024 文字以下（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークン以下。
• 大量のコンテンツは references/ に置き、必要に応じて読み込みます。