datocms-plugin-design-system

DatoCMS プラグインのデザインシステム

プラグインの UI をネイティブに見せます。視覚的な統一感、構造、密度、スタイリングに使用します。フックの接続やスキャフォールディングには使用しません。

対象：

• 設定画面をネイティブな見た目にする
• サイドバーパネルをダッシュボードに合わせてスタイル変更する
• ネイティブなページの見た目にするため、生の CSS を使用する
• モーダルの余白と階層を整える
• CMS の UI に合う datocms-react-ui コンポーネントを選ぶ

ステップ 1：コンテキストを確認する

1. 対象を特定します：既存のプラグイン、新規スキャフォールド、単一の画面。
2. 画面を特定します：設定画面、ページ、サイドバーパネル、サイドバー全体、モーダル、アウトレット、インスペクター、アセットソース。
3. プロジェクトで datocms-react-ui を使用しているか確認します。
4. 変更の種類を特定します：視覚、レイアウト、コントロールの選択、テーマ、密度。
5. 必要最小限の範囲を読みます：画面のエントリーポイント、スタイル変更対象のコンポーネント、ローカル CSS、必要に応じて package.json。

リポジトリの内容が不明な場合に限り、質問してください。

ステップ 2：実装方法を選ぶ

ネイティブな見た目を保てる、最も限定的な方法を使用します。

A. まず公開コンポーネントを使用する

datocms-react-ui に必要なコントロールがある場合に使用します。

以下で優先します：

• Canvas
• フォームのラッパー、グループ化された設定
• 標準フィールド、ボタン、ボタングループ
• セクション、ツールバー、ヘッダーの構造
• サイドバーパネル、ドロップダウン、スピナー
• 利用できる場合は VerticalSplit

B. 生の React + CSS による代替

公開パッケージに必要なレイアウトがない場合、または CMS の構成を正確に再現することが重要な場合に使用します。

以下に使用します：

• CMS の余白設定が必要なページシェル
• リスト／テーブルのラッパー、サマリー行
• 空の状態、情報ブロック
• UI パッケージにプリミティブがない場合の分割レイアウト
• テーマ変数が必要な画面固有のラッパー

非公開の CMS スタイルやクラス名はインポートしないでください。Canvas 変数を使用し、プラグイン内の CSS で再現してください。

ステップ 3：必要最小限のリファレンスを読み込む

必ず最初に以下を読み込みます：

• references/foundations.md
• references/datocms-react-ui-bridge.md

公開ドキュメントとプラグインコードだけでは不十分な場合に限り、references/source-map.md を読み込みます。

次に、変更する対象に応じてリファレンスを読み込みます：

• レイアウト／ページ → references/layouts.md
• フォーム／設定／コントロール → references/forms-and-controls.md
• タブ／ドロップダウン／テーブル／通知 → references/navigation-feedback-and-data-display.md
• フック固有の画面構成 → references/plugin-surfaces.md
• 生の CSS → references/raw-css-fallbacks.md

小規模なスタイル変更では、リファレンス一式をすべて読み込まないでください。

ステップ 4：ネイティブな見た目の UI を構築する

留意点：

• レイアウトを独自に考案する前に、DatoCMS の密度に合わせます。
• ハードコードしたブランドカラーではなく、<Canvas> のテーマ変数を使用します。
• CMS が使用している場合は、1px の境界線、3〜5px の角丸、控えめな影を優先します。
• ページ幅、ツールバーの高さ、セクション間の余白、フォームの間隔を CMS に近づけます。
• セクション／画面ごとに主要なアクションを 1 つにします。
• 破壊的なアクションは分離します。
• ラベルはコントロールの上、補足説明は下に配置し、エラーは簡潔にします。
• 装飾的なカードより、セクション／ツールバー／サイドバー／テーブルを優先します。
• ヒーローブロック、KPI グリッド、装飾的な文言、大きすぎる角丸、強いグラデーション、ダッシュボードの埋め草は避けます。
• カスタム CSS はローカルに置き、変数を使用します。
• 公開コンポーネントだけでは不十分でも近いものがある場合は、その周囲を組み合わせて補います。

「ネイティブ」な UI では、次の順で最適化します：

1. 構造
2. 余白
3. タイポグラフィ
4. 色／テーマ
5. コントロールの選択
6. マイクロインタラクション

ステップ 5：検証する

有用な最小限の検証を実行します：

• 既存のビルドスクリプト（npm run build、pnpm build）

手動で確認する UI 項目を 1 つ挙げます：

• 設定画面 → 余白、セクションのグループ化、主要なアクションの配置
• ページ → ツールバー／ヘッダーの間隔、スクロール動作
• サイドバーパネル → 密度、折りたたみ／展開時の動作
• モーダル → フォーカス、幅、アクションの階層
• アウトレット → 周囲の CMS UI とのインライン表示の適合性
• アセットソース → 検索／結果の間隔、サイズ
• インスペクター／サイドバー全体 → noAutoResizer、2 ペインの動作

スキル間の振り分け

• 新しいプラグイン／プロジェクト／フォルダー → datocms-plugin-scaffold
• 既存のプラグインの機能／フック／パラメーター／画面の動作 → datocms-plugin-builder
• 複数の作業を含むタスクは通常、次のように分担します：
  • このスキルはネイティブな DatoCMS UI を担当
  • スキャフォールド／ビルダーはフック／セットアップを担当
• プラグイン UI 外での単独の CMA → datocms-cma
• フロントエンドサイトとの統合 → datocms-frontend-integrations