vtex-io-admin-react

管理用 React インターフェース

このスキルを使用する場面

VTEX Admin エクスペリエンス向けの管理用 React インターフェースを構築する場合に、このスキルを使用します。

• 設定ページ
• モデレーションツール
• 社内ダッシュボード
• 業務用フォームとテーブル

次の場合は、このスキルを使用しないでください。

• ストアフロントのコンポーネント
• render-runtime ブロック
• ルート認可の設計
• バックエンドサービスの構造

判断ルール

• 管理用インターフェースには、VTEX の公式デザインシステムを使用します。
• 顧客向けに公開する VTEX IO 管理アプリでは、デフォルトの選択肢として vtex.styleguide を優先します。
• 特に社内のバックオフィス環境では、公式 VTEX デザインシステムとして @vtex/shoreline も使用できます。
• ページ構成には、Layout、PageHeader、PageBlock などの Styleguide の基本的なレイアウトパターンを優先します。
• 管理における一般的なニーズには、Styleguide の構成要素である Table、Input、Dropdown、Toggle、Tabs、Modal、Spinner、Alert を優先します。
• 管理画面は、ストアフロントのスタイル上の懸念ではなく、業務の明瞭さを重視して構成します。
• データ量の多い管理ページでは、読み込み中、空、エラーの状態を明示することを優先します。
• 非同期アクションでは、ボタンの読み込み状態とトーストベースのフィードバックを使用し、変更がいつ開始、成功、失敗したかをユーザーが把握できるようにします。
• ラベルやフィードバックをストアやロケール間で統一できるよう、ハードコードされた管理画面の文言より国際化されたメッセージを優先します。
• VTEX Admin の慣例に沿ったテーブル、フォーム、フィルター、フィードバックのパターンを使用します。
• フォーカス動作、キーボードナビゲーション、アクセシビリティ属性がデフォルトで適切に機能するよう、カスタムのクリック可能な div や span パターンより公式デザインシステムのコンポーネントを優先します。
• 大規模なリストやテーブルでは、すべてのデータをブラウザーに読み込んでメモリー上で絞り込むのではなく、ページネーションとサーバーサイドフィルタリングを優先します。
• 検索やフィルタリングでは、独自のコントロール動作を作るのではなく、公式デザインシステムが提供する検索とフィルターのパターンを優先します。
• アプリ内のラベル、メッセージ、アクション文言は単一の言語に統一し、同じ画面でトーンや言語が混在しないようにします。
• フォームのアクションは一貫性を保ちます。主要な保存アクションを使用し、適切な場合は任意の二次的なキャンセルアクションを設け、送信後には明示的にフィードバックします。

厳格な制約

制約：管理 UI では VTEX のデザインシステムを使用する必要があります

管理パネルのコンポーネントには、VTEX の公式デザインシステムを使用しなければなりません。

重要な理由

VTEX Admin には一貫したデザイン言語があります。VTEX の公式デザインシステムはその一貫性を保ちますが、汎用のサードパーティ製 UI ライブラリーは、ビジュアルの不統一、スタイルの競合、レビュー上の問題を引き起こします。

検出方法

管理アプリで Material UI、Chakra、Ant Design、またはその他の汎用サードパーティ製 UI システムが使われている場合は、作業を停止し、VTEX デザインシステムのパターンに置き換えてください。@vtex/shoreline をサードパーティ製として指摘しないでください。

正しい例

import { Layout, PageHeader, PageBlock, Table } from 'vtex.styleguide'

import { Button, Table, EmptyState } from '@vtex/shoreline'

誤った例

import { DataGrid } from '@material-ui/data-grid'

制約：管理画面では読み込み中、空、エラーの状態を示す必要があります

業務用インターフェースでは、データの状態をユーザーに明示しなければなりません。

重要な理由

管理ユーザーには、信頼できる業務上のフィードバックが必要です。何も表示されない画面は、状態が明示された画面よりサポートや診断が困難です。

検出方法

ページがリモートデータを読み込む際、読み込み中、データが空、エラーの場合に意味のある内容が何も表示されないなら、作業を停止して UI の状態を明示してください。

正しい例

if (loading) {
  return (
    <PageBlock>
      <Spinner />
    </PageBlock>
  )
}

if (error) {
  return (
    <PageBlock>
      <Alert type="error">Failed to load data. Please try again.</Alert>
    </PageBlock>
  )
}

誤った例

return <Table items={data?.items ?? []} />

制約：管理アクションではユーザーに明示的なフィードバックを提供する必要があります

管理画面での変更処理では、成功、失敗、または処理中の状態を明確に伝えなければなりません。

重要な理由

業務上のアクションは、実際のストア設定やデータに影響します。操作の繰り返しや曖昧さを避けるため、ユーザーには即時のフィードバックが必要です。

検出方法

ボタンが書き込み処理を実行するにもかかわらず、結果に対するフィードバックがない場合は、作業を停止して明示的なフィードバックを追加してください。

正しい例

<Button isLoading={saving}>Save</Button>
showToast({ message: 'Settings saved successfully' })

誤った例

<Button onClick={save}>Save</Button>

制約：データ量の多い管理画面は、表示範囲を限定し、操作しやすくする必要があります

一覧、テーブル、検索中心の管理画面では、ページネーションなどの表示範囲を限定するパターンを必ず使用し、API が対応している場合はサーバーサイドでのフィルタリングを優先してください。

重要な理由

管理ページでは、時間の経過とともに増加する運用データセットを扱うことがよくあります。一度に多くの行を描画したり、メモリ上だけでフィルタリングしたりすると、パフォーマンスが低下し、UX も不安定になります。

検出方法

ページネーションなしで非常に大きなコレクションを描画している場合や、ローカルでフィルタリングするためだけにデータセット全体をブラウザーに読み込んでいる場合は、作業を止め、表示範囲を限定したナビゲーションまたはサーバーサイドフィルタリングを追加してください。

正しい例

<Table items={items} />
<Pagination currentItemFrom={1} currentItemTo={10} totalItems={120} />

誤った例

const filtered = allItems.filter(matchesSearch)
return <Table items={filtered} />

制約：インタラクティブなコントロールには、アクセシブルなセマンティクスを使用する必要があります

管理画面の操作では、アクセシブルなコントロールを必ず使用し、セマンティクスのないクリック可能なカスタム要素ではなく、公式デザインシステムのコンポーネントを優先してください。

重要な理由

キーボードナビゲーション、フォーカス処理、スクリーンリーダーの動作は、管理画面の基本的な使いやすさに欠かせません。セマンティクスのないクリック可能な要素は、アクセシビリティのリグレッションを起こしやすくします。

検出方法

ボタン、リンク、またはデザインシステムのコンポーネントを使うべき箇所で、クリック可能な div または span 要素を主要なコントロールとして使用している場合は、作業を止めて置き換えてください。

正しい例

<Button variation="primary">Save</Button>

誤った例

<div onClick={save}>Save</div>

Admin ビルダーの構成

VTEX IO の管理ページは Admin ビルダーで公開されます。

• admin/ フォルダーを使用して、ナビゲーションとルートを宣言します。
• admin/navigation.json を使用して、セクション、サブセクション、Admin ナビゲーションパスを定義します。
• admin/routes.json を使用して、各 Admin パスを react/ 配下に実装された React コンポーネントに対応付けます。
• react/ フォルダーを使用して、Admin ルートで使用するページコンポーネントを実装します。

実践的なルール：

• admin/routes.json の各エントリーは、react/ 内の実在するコンポーネントを参照する必要があります。
• ルートの path は、admin/navigation.json で宣言したナビゲーション構造と一致させてください。
• ページコンポーネントでは、Layout、PageHeader、PageBlock などの VTEX Admin レイアウトパターン、または内部コンテキストにおける公式の Shoreline 相当パターンを使用してください。

例：navigation.json の構成

admin/navigation.json：

[
  {
    "section": "storeSettings",
    "subSection": "storeFront",
    "subSectionItems": [
      {
        "labelId": "admin/my-settings.navigation.title",
        "path": "/admin/app/my-settings"
      }
    ]
  }
]

主なフィールド：

• section / subSection：Admin ナビゲーションツリー内でリンクを表示する位置を定義します。
• subSectionItems[].path：admin/routes.json で宣言した path と一致させてください。
• titleId / labelId：ナビゲーションラベルの国際化に使用するメッセージ ID です。
• adminVersion：任意の項目で、従来の Admin と新しい Admin のエクスペリエンス間の互換性を保つ場合にのみ必要です。新しいアプリのデフォルト例では使用しないでください。

例：Admin ビルダーと React ページの連携

admin/routes.json：

{
  "admin.app.my-settings": {
    "component": "MySettingsPage",
    "path": "/admin/app/my-settings"
  }
}

react/MySettingsPage.tsx：

import React from 'react'
import { Layout, PageHeader, PageBlock } from 'vtex.styleguide'

const MySettingsPage: React.FC = () => (
  <Layout pageHeader={<PageHeader title="My settings" />}>
    <PageBlock>
      {/* Page content goes here */}
    </PageBlock>
  </Layout>
)

export default MySettingsPage

推奨パターン

運用状態を明確に示し、装飾的な UI よりもわかりやすさを重視するために、VTEX デザインシステムを使用してください。 適切な場合は Styleguide の PageHeader と PageBlock を使用し、内部コンテキストでは公式の Shoreline 相当パターンを使用してください。データの状態には Spinner／Alert／EmptyState を使用し、非同期処理のフィードバックには showToast とボタンのローディング状態を使用してください。 大規模なデータセットにはページネーション付きテーブルを使用し、可能な場合はサーバーサイドフィルタリングを優先してください。また、フォームの操作は、保存を主操作、キャンセルを任意操作とする一貫した動作にしてください。

よくある失敗

• 管理アプリでサードパーティ製 UI ライブラリを使用する。
• ローディング状態、空の状態、エラー状態を省略する。
• 目に見えるフィードバックなしでデータを変更する。
• 大規模なテーブルをページネーションなしで描画する、またはすべてのフィルタリングをメモリ上だけで行う。
• アクセシブルなボタンやリンクではなく、セマンティクスのない要素でクリック可能なコントロールを構築する。
• 同じ管理画面内で言語を混在させたり、文体を統一しなかったりする。

レビュー用チェックリスト

• 画面では、汎用的な UI ライブラリではなく、VTEX 公式のデザインシステム（Styleguide または Shoreline）を使用していますか？
• 適切な箇所で PageHeader と PageBlock のレイアウトパターン（または Shoreline の同等機能）を使用していますか？
• 読み込み中、空、エラーの各状態が明示されていますか？
• 大規模なテーブルやリストを、拡張性のある方法でページ分割し、フィルタリングしていますか？
• 書き込み操作は安全で、ユーザーに明確に示されていますか？
• インタラクティブなコントロールでは、意味的でない要素をクリック可能にするのではなく、アクセシブルなセマンティクスを使用していますか？
• ラベルやフィードバックメッセージはハードコードせず、国際化されていますか？
• アプリ全体で、ラベルやアクションの言語とトーンが統一されていますか？
• UI は VTEX Admin ツールのような見た目と動作になっていますか？

参考資料

• Admin アプリ - Admin builder の概要
• Shoreline リポジトリ - VTEX 公式 Shoreline デザインシステムのリポジトリ
• Shoreline ドキュメント - Shoreline のコンポーネントとデザインシステムのドキュメント