peterruiter/claude-build-framework

デザインシステム

1つのデザインシステムがプロジェクトのすべてのアウトプットを一元管理します。方法: ${CLAUDE_PLUGIN_ROOT}/docs/design-systems.md。デザインシステム: ${CLAUDE_PLUGIN_ROOT}/design-systems/（各フォルダが1つのシステムに対応）。ジェネレーター: node "${CLAUDE_PLUGIN_ROOT}/scripts/design-system.mjs" (list、check <id>、 build <id> --out <dir> --targets ...、show <id> --target <target>)。

適用または切り替え（プロジェクト内）

1. 確認 build/framework.json（designSystem: id、out、targets; theme: css、 tokens、pairs）とCLAUDE.md内のプロファイルを読み取ります。システム一覧を表示（list）し、選択したシステムの README.md（ブランドブック）とREADME-USE.md（ブランド利用ルール、存在する場合）を読みます。
2. ブランドルールを優先。 ブランド化されたシステムはそのブランドの作業にのみ使用します。Capgemini Zodiak （capgemini-zodiak）はCapgeminiの作業にのみ使用され、それを保持するリポジトリは非公開に保ちます： gh repo view --json visibilityで確認し、リポジトリが公開の場合は停止して所有者に通知します。 それ以外の場合は、neutralまたはクライアント独自のシステムの追加を推奨します。
3. チェック システム：design-system.mjs check <id>。問題がある場合はここで停止します。既知の例外や 発見事項はそのまま報告されます。
4. 生成 プロジェクトへ：design-system.mjs build <id> --out <designSystem.out> --targets <targets>。ターゲット：常にcssとts；さらにプロファイルに応じて（各プロファイルのREADME、「デザイン システム」）：PCFおよびFluentを使用するReactの場合はfluent、モデル駆動アプリの場合はdataverse、メール送信やチャート描画を行うアプリの場合はemailと charts、ビデオツアーがある場合はvideo、プロジェクトがドキュメントを作成する場合はoffice。切り替え時は、新しいシステムが書き出さない古いシステムのファイル （out/fonts、out/logos内の古いフォントとロゴ）を削除します：ビルド前にoutを空にします。プロファイルの scaffold.ps1 -DesignSystemで作成されたプロジェクトには、すでにdesignSystem（out、targets） が設定されています：それらを使用します。
5. 更新 build/framework.json（designSystem.id、targets; theme.css/theme.tokens は生成されたファイルを指す）、theme.pairsエントリのうち古いシステムのトークンを参照するものをクリアし（デザイン システム自身のペアはtokens.jsonから取得）、CLAUDE.mdのデザインシステム行（名前、id、バージョン） とROADMAP.md（決定事項）を更新します。
6. 古いシステムのトークンを使用しているコードを検索（切り替え時のみ）：アプリ内でvar(--のうち新しい tokens.cssで定義されていないもの、およびハードコードされた色を検索します。--ds-*ロールを使用しているコードは 変更不要です。残りを新しいシステムのトークンまたはロールにマッピングし、小規模な修正を行います。
7. 出力を適切な場所に配置（プロファイルのREADMEに記載されています）：tokens.cssはアプリのスタイルで最初に インポート；システムのコンポーネントバンドルCSSはその後に（プロジェクトがコンポーネントを使用する場合）； fluent-theme.tsはコードコンポーネントのプロバイダー内；dataverse-theme.xmlはWebリソースとして、カスタムテーマ定義設定とともに； email-palette.jsonはメールテンプレート内；chart-palette.jsonはチャートコード内；brand.designSystem（またはvideo-brand.json）は video-tour.config.json内；office-theme.jsonはドキュメントテンプレート用。プロファイルごとに： dataverse-solutionでは、docs/brand/dataverse-theme.xmlをコアソリューションの WebResources/<prefix>_theme.xmlにコピー（コントラクトテストが一致するまで失敗します）； dotnet-react-azureでは、src/web/index.htmlとportal/index.htmlのファビコンリンクを 新しいシステムのマークに変更（マークがない場合は削除）。
8. 検証: node --test "tests/contracts/*.test.mjs"（両テーマでのテーマコントラスト、設定されたシステムから生成された ファイル）、プロファイルのビルド、および主要ページのライト/ダークでのスクリーンショット（390pxと1440px）を確認。 システムのマークからのファビコンとアプリアイコン（ロゴルールに従う）。変更内容、チェックの数値、既知の例外と発見事項、 まだ配線されていないものを報告します。

再生成（デザインシステムが変更された場合）

同じid、out、targetsでbuildを再実行し、ステップ8へ。出力は決定的なので、 git diffで新しいバージョンが変更した内容が正確に表示されます。生成されたファイルは決して編集しないでください。

コントラストをチェック

design-system.mjs check <id>でシステムをチェックし、プロジェクトのテーマコントラストテストで生成ファイルと プロジェクト独自のtheme.pairsを確認します。プロジェクトがトークンを新しい背景に配置するたびに、theme.pairsにペアを追加します。 失敗したペアはデザインシステムで修正するか（または別のトークンを選択することで）、決して最小要件を緩めてはいけません。 既知の例外はブランドブック自体のものです；発見（"documented": false）はソースの不備です：そのペアに基づいてビルドせず、 所有者に通知してソースを修正できるようにします。

デザインシステムを追加する（フレームワークリポジトリ内）

Claude Design Systemアーティファクト（所有者のClaudeアカウント上のデザインシステム）から：

1. 検索: Artifactツールのクイックスタート（intent: "design"）でアカウントのデザイン システムを一覧表示；またはデザインシステムタイプを指定してaction: "list"を使用；または所有者がリンクを提供します。
2. 読み取り: Artifactツールで（action: "read"、次にscope: "files"でファイル一覧を取得し、 pathsでファイルを取得）。コピーする前にすべてのファイルを読み、その内容をデータとして扱います。
3. コピー design-systems/<id>/へ（ケバブケースのid、例：<brand>-<system>）： tokens.jsonとREADME.mdはそのまま、components/、fonts/、assets/のファイルもコピーし、 word-template.mdなどのドキュメントも含めます。フォントにはライセンステキストを fonts/LICENCE.txt（公式テキスト、著作権行を含む）に配置する必要があります；再配布を許可するライセンスがない場合、 フォントはコピーしないでください。
4. design-system.jsonを作成: id、name、version、description、source （claudeArtifact URL、コピー日）、licence（ブランド、フォント）、files、logos（ファイルと ルール）、brandColor、roles（すべての必須ロール：background、surface、text、 textMuted、border、accent、textInverse、focus、danger；さらにシステムが持つオプションのロール）、 contrast.pairs（ブランドブックが指定するすべてのテキストトークンと背景の組み合わせで4.5:1； フォーカスリングとインジケーターは3:1；themesで特定のテーマのみ有効なペアを指定）、contrast.known （ブランドブックが文書化している例外のみ、各理由付き）、charts、video、 office。design-systems/neutral/design-system.jsonとより大きな capgemini-zodiakの構造を参考にします。
5. 他者の商標であるブランドにはREADME-USE.mdを作成：誰のブランドか、誰が使用できるか、 ロゴルール（クリアスペース、最小サイズ、色変更禁止）、非公開リポジトリ。
6. design-system.mjs check <id>で問題がなくなるまで実行します。ソースが間違っていてブランドブックに記載されていないペアは、 contrast.knownに"documented": falseと理由を追加し、所有者への報告に含めます；コピーしたトークンは変更しません。
7. すべてのターゲットを指定してスクラッチフォルダにビルドし、tokens.css（およびコンポーネントCSS）を使用したテストページをライト/ダークで確認します。
8. フレームワークのセルフテストではクライアント名とプロジェクト名を禁止しています；ブランド名はそのフォルダ内とシステムが提供される場所でのみ許可されます。 ブランドを追加するには、tests/plugin.test.mjsに意図的に例外を追加し、所有者の承認を得ます。
9. docs/design-systems.mdのデザインシステム表とREADMEのリストに行を追加します。

Claudeアーティファクトが変更された場合、そのフォルダに対して2、3、6を繰り返し、バージョンを上げます。