gravity-ui

Gravity UI で UI を構築する

記憶に頼るのではなく、実際の Gravity UI コンポーネントを使って UI を構築してください。Gravity UI は複数のパッケージで構成される React デザインシステム（@gravity-ui/*）です。そのため、よくある問題は、誤ったパッケージを選ぶことと、誤ったバージョンの API を使うことです。このスキルでは、適切なパッケージへ案内し、インストール済みのバージョンに基づいて作業できるようにし、API をでっち上げないようにします。推測するのではなく、インストール済みのバージョンに合わせ、エコシステムカタログに従ってください。

ステップ 0 — まず適切なパッケージを選ぶ（エコシステムの案内）

何よりも先に、タスクで必要となる @gravity-ui/* ライブラリを特定してください。学習データから推測してはいけません。エコシステムには、見分けにくいパッケージの組み合わせ（charts と chartkit、uikit の Table と @gravity-ui/table、date-components と date-utils など）があり、誤ったパッケージを選ぶことは最もよくある失敗です。

references/package-routing.md を開き、冒頭を読んでください。そこには、オンラインとオフラインの情報源の優先順位、「間違いやすい組み合わせ」の見分け方、各パッケージの用途と代わりに使うものを一行で説明したエコシステムカタログがあります。このカタログを使ってパッケージを選んでから、ここに戻ってステップ 1 に進んでください。

パッケージを選んだ後にのみステップ 1 を実行し、そのパッケージのインストール済みバージョンと API を確認してください。

ステップ 1 — 選択したパッケージのインストール済みバージョンを確認する

1. package.json を読みます。 インストールされている各 @gravity-ui/* パッケージとそのバージョンを確認してください。情報源として信頼すべきなのはインストール済みのバージョンであり、記憶ではありません。バージョン範囲の解決には、ルートの package.json にある範囲文字列ではなく、node_modules の <pkg>/package.json にある version フィールドを使ってください。

2. 使用するパッケージのドキュメントを、次の順に取得してください。質問に答える情報が見つかった時点で、それ以上先には進みません。

   (a) ローカル — まず node_modules/@gravity-ui/<pkg>/dist/docs/INDEX.md または node_modules/@gravity-ui/<pkg>/build/docs/INDEX.md を確認します。 このパッケージに INDEX.md がない場合は、パッケージのルートにある node_modules/@gravity-ui/<pkg>/README.md を確認します。 これはインストール済みのバージョンと完全に一致するため、バージョンに依存する質問では常に優先してください。 注：バンドルされたドキュメントが追加されたのは最近です。uikit で build/docs が同梱されるようになったのは 7.45.0 以降です。 それより古いインストールにはローカルドキュメントがなく、それは想定どおりであり、エラーではありません。(b) に進んでください。 (b) オンライン — パッケージごとの llms.txt をメジャー系列で取得します。 https://gravity-ui.com/llms/<pkg>/<major>/llms.txt （例：^7.2.1 では /llms/uikit/7/llms.txt）。メジャー系列の URL は、そのメジャーの最新マイナーバージョンを提供します。メジャーバージョンには追従しますが、正確なパッチバージョンには追従しません。 ローカルにそのパッケージのドキュメントがない場合に使用してください。

3. フォールバックのルール — 情報源の取得に失敗した場合や内容が空の場合、黙って先へ進まないでください。

   • ローカルにそのパッケージの README／dist/docs／build/docs がない場合、または内容が空の場合 → オンラインのメジャー系列 llms.txt（b）を取得します。
   • オンラインのリクエストに失敗した場合（ネットワークのタイムアウト、DNS、接続拒否 （ネットワーク分離環境／企業プロキシ）、HTTP 404（そのメジャーバージョンはホストされていない）、または空の／Markdown ではない本文） → ローカルの README と dist/docs または build/docs（a）にフォールバックします。
   • フォールバックとして /llms/<pkg>/llms.txt の「latest」エイリアスを使ってはいけません。 最新のメジャーバージョンが提供されるため、インストール済みのものと異なり、API も異なる可能性があります。バージョン指定のフォールバックにはメジャー系列の URL を使い、それでも取得できない場合は「latest」ではなくローカルを使ってください。
   • そのパッケージの情報源がオンライン・ローカルの両方で利用できない場合は、そこで停止し、パッケージのドキュメントにアクセスできないことをユーザーに伝えてください。学習データから API を推測してはいけません。

ステップ 2 — 選んだパッケージを使って実装し、型チェックする

1. ステップ 0 で選び、ステップ 1 でインストール済みであることを確認した @gravity-ui/* パッケージだけを使って実装してください。 それらのパッケージから正確にインポートし、よく似た別のライブラリ（MUI、Ant、通常の <input>）で代用したり、ステップ 1 でインストール済みと確認されていない @gravity-ui/* パッケージを使ったりしないでください。記憶ではなく、今読んだドキュメントに記載された prop API に従ってください。使いたい prop がドキュメントに記載されていない場合、その prop は存在しません。ドキュメントに記載された prop を使うか、ユーザーに確認してください。

2. 実装中は、rules/hallucination-traps.md にある横断的なルールを適用してください。タイポグラフィのバリアント、flex の契約、テーマ設定／ラダー、Button view、Icon data が含まれます。コンポーネントごとの注意点は、各パッケージの dist/docs に記載されています。

3. 完了を報告する前に型チェックしてください。 プロジェクトの型チェックコマンドを実行します（通常は tsc --noEmit、モノレポの場合はワークスペースの typecheck スクリプト）。完了を報告する前にすべてのエラーを修正してください。型エラーはほぼ必ず、誤った prop、誤ったインポートパス、またはバージョンの不一致を意味します。これはまさにステップ 0〜1 で防ぐべき問題です。

   • 型チェックで、ステップ 1 で読んだドキュメントと矛盾する prop／パスが見つかった場合は、ドキュメントのスナップショットではなく、インストール済みのバージョン（型チェッカー）を優先してください。ドキュメントが別のマイナーバージョンのものである可能性があります。実際にインストールされている型を確認するため、node_modules 内のパッケージの dist/docs/INDEX.md を読み直してください。
   • 型チェックを実行できない場合（プロジェクトに TS がない場合）は、その旨を明示し、どのように検証するかユーザーに確認してください。検証を黙って省略してはいけません。
   • 例外。 ユーザーが検証を明示的に省略してよいとした場合（「簡単なスケッチでいい」「クイックプロトタイプ」「確認不要」など）は、型チェックを省略できます。ただし、返信で次のように明記してください。"ユーザーの依頼により型チェックを省略しました — コードは検証されていません"。黙って省略してはいけません。
   • 型チェックで確認できないことも把握してください。 tsc が成功すれば API が実在することは確認できますが、レイアウトやコントラストについては何も分かりません。完了を報告する前にその点を伝え、次の項目を確認するか、ユーザーが手動で確認できるよう列挙してください。light と dark の両テーマでの画面表示（特に色付きの塗りつぶし上のテキストとコントロール）、横方向にはみ出さないかを確認するための狭い（約 375px）幅と広い（約 1400px）幅のビューポート、空・読み込み中・エラーの各状態。

厳守事項

• すべての Gravity UI プロジェクトに @gravity-ui/uikit をインストールする必要があります。 これは、ほかのすべての @gravity-ui/* パッケージが基盤としている、基本コンポーネントとデザイントークンのライブラリです。これがないと、コンポーネントはスタイルなしで表示されます。package.json に含まれていない場合は、作業を中断し、まずユーザーにインストールと設定を行ってもらってください（セットアップ：https://gravity-ui.com/llms/uikit/llms.txt）。
• @gravity-ui/* パッケージをインポートする前に、package.json を読んでください。 パッケージがインストール済みだと決めつけたり、メジャーバージョンを決めつけたりしないでください。
• プロパティやコンポーネントを創作しないでください。 コンポーネント API に確信が持てない場合は、使用する前に rules/hallucination-traps.md（エコシステムのパターン）と、dist/docs にあるコンポーネントの README を確認してください。それでも不明な場合は、推測せずにユーザーに尋ねてください。
• アイコン名を決して推測しないでください — ほとんどの場合、幻覚による誤りです。スクリーンショット／写真／モックのアイコンを特定するには、scripts/icon-image-search.sh（画像の逆検索）を実行してください。説明しかない場合は、gravity-ui.com/icons で名前を調べるか、ユーザーに尋ねてください。名前を創作してはいけません。そのうえで文字列キーではなく、オブジェクトとして渡してください（<Icon data={CheckIcon} />）。references/icons.md を参照してください。
• テーマ設定にはセマンティックな --g-* トークンを使用します。 色（#fff、blue-500）をハードコードしたり、dark: のオーバーライドを手書きしたりしないでください。トークンの一覧は references/theming.md にあります。複数領域にまたがる注意事項（ブランド設定の一部のみのオーバーライド、ページ全体にテーマを適用する ThemeProvider、ブランド背景上のコントロール）は rules/hallucination-traps.md にあります。
• 必須のセットアップはパッケージごとに異なります（スタイルのインポート、ThemeProvider、ピア依存関係）。各パッケージのルート README にある「Required setup」に記載されています。パッケージごとに一度確認し、記憶に頼らないでください。

やってはいけないこと

以下は、エージェントが Gravity UI のコードを壊す最も一般的な 5 つの方法です。これらは上記のルールからも明らかですが、このセクションでは明示的な禁止事項として示します。いずれかを行おうとしている場合は、作業を中断して、前提を確認し直してください。

• Gravity UI 以外のライブラリで代用しないでください。 MUI、Ant Design、素の <input>／<button>、見た目が似たコンポーネントライブラリは使用しないでください。タスクに必要な @gravity-ui/* パッケージを使用してください。
• コンポーネント API やプロパティを創作しないでください。 Step 1 で読んだドキュメントにプロパティが記載されていない場合、そのプロパティは存在しません。variant=、color=、（Icon の）name=、header-3 バリアントなどを書かないでください。ドキュメントに記載されたプロパティを使うか、ユーザーに尋ねてください。rules/hallucination-traps.md を参照してください。
• フォールバックとして /llms/<pkg>/llms.txt の「latest」エイリアスを使用しないでください。 これは最新のメジャーバージョンを提供するため、インストール済みのバージョンと異なり、API も異なる場合があります。オンラインでフォールバックする場合は、バージョン指定の URL（/llms/<pkg>/<major>/llms.txt）を使用してください。それより先はローカルを確認してください。
• ブランド設定の一部だけを変更しないでください。 --g-color-base-brand だけを設定すると、選択状態、フォーカス、リンク、コントラストにはデフォルトのアクセントカラーが残り、UI に不整合が生じます。サポートする各テーマで、ブランドトークン一式をオーバーライドしてください。
• [class*='…'] や ID セレクターで内部マークアップをオーバーライドしないでください。 これは特定の DOM 構造に依存し、コンポーネントが変更されると気付かないまま壊れます。構造に手を加える前に、カスタマイズの段階を踏んでください（グローバルトークン → コンポーネント CSS API → 対象を絞った、注意書き付きのハック）。

詳細な資料 — 必要に応じて参照

これらのファイルはこの SKILL.md と同じ場所にあり、関連する場合にのみ読み込まれます。

• references/package-routing.md — エコシステムカタログ （gravity-ui.com/llms.txt）のオフラインスナップショット。各スキルリリース時に 更新されます。Step 0 でオフライン時の代替として使用されます。
• references/theming.md — uikit の docs/theming.md の原文そのままのコピー： --g-* トークンレイヤー、ThemeProvider、ブランディング、カスタムテーマ、スコープ付き テーマ、uikit-themer。同梱版は古くなっている場合があります。バージョンに対応するファイルは node_modules/@gravity-ui/uikit/build/docs/guides/theming.md を参照してください。
• references/layout.md — uikit の docs/layout.md の原文そのままのコピー： スペーシングスケール（--g-spacing-*）、Flex／Box、Row／Col／Container グリッド、ブレークポイント、useLayoutContext。
• references/icons.md — 画像からアイコンを探す方法 （scripts/icon-image-search.sh）、または gravity-ui.com/icons で探す方法、 オブジェクトと文字列のレンダリング規則。
• rules/hallucination-traps.md — よく捏造される API の誤り／正しい例： タイポグラフィのバリアント（header-3..6 は存在せず、Heading もありません）、フレックスの仕様 （min-width:0、縮小する要素）、テーマ設定の落とし穴（ブランドの一部のみの上書き、ページ全体に テーマを適用する ThemeProvider、カスタマイズの段階）、Button は variant ではなく view、 Icon は name ではなく data。コンポーネントごとの落とし穴は、各パッケージの dist/docs にあります。