brandmd

brandmdは、稼働中のウェブサイトをマシン読み取り可能なデザイン仕様書に変換するコマンドラインツールです。ページをレンダリングして実際のスタイリングを観察し、その結果をオープンな@google/design.md仕様で定義された形式のDESIGN.mdとして書き出します。この形式は、色、タイポグラフィ、角丸、スペーシング、コンポーネントなどの型定義されたトークンを保持するYAMLフロントマターと、それに続くOverview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'tsなどの散文セクションで構成されています。生成されたファイルは、公式の@google/design.md lintコマンドで正常に検証されることを目的としています。 開発の動機は、AIコーディングエージェントがプロジェクトの色、フォント、スペーシング、コンポーネントの慣習を欠いている場合、汎用的なインターフェースを生成してしまうことです。プロジェクトのルートにDESIGN.mdを配置することで、Claude Code、Cursor、Gemini CLI、Codex、Google Stitchなどのエージェントに、あらかじめそのコンテキストを提供できます。例えば、npx brandmdをURLに対して実行してDESIGN.mdを書き出すという一度の呼び出しだけで十分であり、仕様書を手動で作成する必要はありません。 抽出はローカルで実行されます。このツールはPlaywright経由でヘッドレスブラウザを起動し、遅延読み込みコンテンツをトリガーするためにスクロールし、クッキーバナーやオーバーレイを排除し、:rootからCSSカスタムプロパティ（メディアクエリを含む）を読み取り、可視要素から計算済みスタイルを収集します。その後、類似した色をクラスタリングし、スペーシングスケールとベースグリッドユニットを導出し、境界線の半径とシャドウスタイルを特定し、ボタン、カード、入力フォームなどのコンポーネントパターンを認識します。タイポグラフィの検出はロールを認識し、等幅フォント、フォールバックフォント、アイコンフォントをスキップしながら、本文よりも見出し、見出しよりもディスプレイフォントを優先します。デフォルトのパスでは、LLMの呼び出しやAPIキーは使用されません。 デフォルトのDESIGN.mdに加えて、いくつかの出力形式が提供されています。スクリプトやツールチェーン用のraw JSONトークン、CSSカスタムプロパティ、Tailwind v4の@themeブロック、およびスウォッチ、タイプ標本、スペーシングの可視化、シャドウ例を含む自己完結型のHTMLブランドガイドです。複数のURLを渡してページ間でトークンをマージすることができ、ページごとに頻度が正規化されるため、ボタンが多いドキュメントページがホームページの決定権を上回ることはありません。オプションのdarkフラグを使用すると、prefers-color-schemeを用いてダークテーマのトークンを抽出します。オプションのvisionフラグを使用すると、Gemini APIキーを用いてスクリーンショットからイラストのスタイル、写真のムード、コピーライティングのトーンを読み取り、追加します。 さらにagentフラグを使用すると、Cursorルールとスキルファイルをユニバーサルな.agents/skillsパスとClaude Codeスキルディレクトリの両方に書き出すため、手動の設定なしにブランドコンテキストが読み込まれます。brandmd自体もインストール可能なAgent Skillとして配布されており、コンパニオンリポジトリではTailwind CSS、shadcn/ui、Vercel、Mintlify、Anthropic向けの既製のブランドスキルが提供されています。 このツールは意図的に「フェイルクローズ（失敗時に閉じる）」設計になっています。ブロックページ、アクセス拒否レスポンス、ログインウォール、または証拠が少なすぎるページの場合、すべての形式で終了コード2で拒否され、アーティファクトは書き出されません。これにより、不完全なキャプチャが良好なDESIGN.mdを上書きすることを防ぎます。overrideフラグを使用すると出力を強制できますが、各形式のアーティファクトにその旨がマークされます。書き込みはトランザクション的に行われ、一時ファイルを使用してリネームし、ロールバックを伴います。終了コードによって、成功、運用上のエラーまたは検証エラー、拒否、およびcheckサブコマンドによって検出されたドリフトを区別します。 checkサブコマンドは、デプロイされたページをコミット済みのDESIGN.mdと比較してデザインドリフトを確認します。色は順序のない16進数のセットとしてではなく、セマンティックロールによって比較され、ロールの喪失や再塗装、プライマリまたはセカンダリフォントの変更があった場合にビルドを失敗させます。ドキュメントでは限界についても率直に述べています。コンポーネントのドリフトは報告されますがビルドは失敗せず、セカンダリフォントの変更は見逃される可能性があり、動的に変化するページは偽の重大な変更を生成する場合があるため、結果を信頼する前に再現させる必要があります。別のdiffサブコマンドでは、2つのDESIGN.mdファイルを比較し、共有および固有の色、タイポグラフィ、スペーシング、半径、およびコンポーネントごとの差異と、コピーすべき内容の合成レポートをMarkdownで生成します。リポジトリには、Stripe、Linear、GitHub、Vercel、Notion、Cursor、Anthropic、Figma、Supabase、Raycastなどの出力例ギャラリーが含まれています。本プロジェクトはMITライセンスです。