react-spectrum-s2

React Spectrum S2（Spectrum 2）

要件から使用する React Spectrum コンポーネントが明確にわからない場合は、コンポーネントを選ぶ前にコンポーネント選択ツリーを参照してください。

Figma のデザイン、フレーム、URL に関するリクエストの場合、または Figma MCP（get_design_context,search_design_system など）が利用できる場合は、コードを生成する前にReact Spectrum S2 での Figma デザインの実装を参照してください。

S2 コンポーネントを使用するテストを作成する場合は、React Spectrum S2 のテストを参照し、独自にロールやセレクターを使ってクエリを作成するよりも、@react-spectrum/test-utils の ARIA パターンテスターを優先してください。

React Spectrum S2 と React Aria Components

React Spectrum S2 は React Aria Components を基盤としています。S2 コンポーネントは、スタイルのない React Aria プリミティブに Spectrum 2 のスタイル、動作、スロット構造を追加します。React Spectrum の作業では、あらかじめスタイルが適用され、デザインシステムに準拠し、一般的な UI パターンの大半をカバーする S2 コンポーネントを常に優先してください。

React Aria Components を直接使用するのは、次の場合に限ります。

• 要件に合う S2 コンポーネントがないため、カスタムコンポーネントを作成する場合。カスタムコンポーネントの作成に従い、React Aria プリミティブと S2 の style マクロを組み合わせて Spectrum のスタイルを適用してください。
• FocusScope、VisuallyHidden、useFocusRing、mergeProps などのユーティリティが必要な場合。

React Aria Components のドキュメントは references/react-aria/ に含まれています。スタイルのない React Aria Components の多くは S2 コンポーネントと同じ名前なので、必要に応じて正しいドキュメントを検索し、参照していることを確認してください。

インポート

ドキュメントに合わせたサブパスインポートを使用してください。パッケージのバレル '@react-spectrum/s2' からはインポートしないでください。

import {Button} from '@react-spectrum/s2/Button';
import {Card, CardPreview, Image, Content, Text, Footer} from '@react-spectrum/s2/Card';
import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
import Folder from '@react-spectrum/s2/icons/Folder';
import CloudUpload from '@react-spectrum/s2/illustrations/gradient/generic2/CloudUpload';

共通の型とリストデータ用フックは @react-spectrum/s2 から再エクスポートされています。react-aria-components、react-stately、@react-types/* からではなく、そちらからインポートしてください。

import type {Key, Selection, SortDescriptor, PressEvent, RangeValue, DateValue, DateRange, TimeValue, RouterConfig} from '@react-spectrum/s2';
import {useListData, useTreeData, useAsyncList} from '@react-spectrum/s2';

コレクションごとに型付きの Item を使用する

各 S2 コレクションコンポーネントには、それぞれ専用の item エクスポートがあります。汎用の Item コンポーネントはありません。Menu → MenuItem／MenuSection、Picker → PickerItem／PickerSection、ComboBox → ComboBoxItem／ComboBoxSection、ListView → ListViewItem、TreeView → TreeViewItem（TreeViewItemContent を使用）、TableView → Row／Column／Cell／TableHeader／TableBody、SegmentedControl → SegmentedControlItem、TagGroup → Tag、Breadcrumbs → Breadcrumb、Accordion → AccordionItem（AccordionItemHeader／AccordionItemTitle／AccordionItemPanel を使用）。

スタイリング

デフォルトのスタイリング方法として、S2 コンポーネントと S2 の style マクロを使用してください。

• まず S2 コンポーネントを優先し、styles prop はレイアウトスタイルのプロパティにのみ使用してください。
• 汎用的なレイアウト（flex、grid など）には、style マクロとネイティブ HTML 要素を使用してください。
• S2 の実装では、Tailwind、radix-ui、shadcn/ui、その他のサードパーティ製デザインシステムの使用を避けてください。
• 重要：UNSAFE_style と UNSAFE_className の使用は避けてください。

S2 コンポーネントの styles prop（複数形）で指定できるのは、次のレイアウトプロパティに限られます。

• margin、marginStart、marginEnd、marginTop、marginBottom、marginX、marginY
• width、minWidth、maxWidth
• flexGrow、flexShrink、flexBasis
• justifySelf、alignSelf、order
• gridArea、gridRow、gridRowStart、gridRowEnd、gridColumn、gridColumnStart、gridColumnEnd
• position、zIndex、top、bottom、inset、insetX、insetY、insetStart、insetEnd
• visibility
• height、minHeight、maxHeight（固有の高さがない特定のコンポーネントのみ）

<Button styles={style({marginStart: 8})}>Edit</Button>

ネイティブ HTML 要素と React Aria Components では className={style(...)} を使用します。この場合、マクロに制限はありません。

import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
import {Checkbox} from 'react-aria-components';

<div className={style({display: 'grid', gap: 12, padding: 16, backgroundColor: 'gray-75'})}>
  <h2 className={style({font: 'heading-sm'})}>Preferences</h2>
  <Checkbox
    className={style({
      display: 'flex',
      alignItems: 'center',
      gap: 8,
      color: {
        default: 'neutral',
        isSelected: 'blue-900'
      }
    })}
  />
</div>

間隔の値は 4px グリッド（0、2、4、8、12、16、…）に従います。

要素ごとに style({...}) の呼び出しを1つにする

複数のスタイル文字列を生成して要素上で結合するのではなく、条件システムを使って、1つの style({...}) 呼び出しの中で実行時のバリエーションを表現します。

• 条件キーには、ネストされたオブジェクト（variant: {primary: ..., secondary: ...}）または is／allows で始まるブール条件（isSelected、allowsRemoving、isHovered）を使用できます。マクロは関数を返します。実行時の値を渡して呼び出します（styles({variant, isSelected})）。
• マクロの戻り値をテンプレートリテラル、clsx、classnames、または文字列のスペースで連結しないでください。クラス名にはスタイルの優先順位が組み込まれており、連結するとそれが崩れます。実行時に2つの別々のスタイル文字列を本当に結合する必要がある場合は、mergeStyles を使用してください。
• 同じ要素で className={style({...})}（または styles）とインラインの style={{...}} を組み合わせないでください。インラインプロパティはトークンを迂回し、レイヤーの順序を崩します。インラインの style プロパティは、ビルド時には本当に値を決められない場合（例：ドラッグハンドラーの位置）にのみ使用してください。

// ❌ Two near-identical style calls combined at the call site.
const base = style({padding: 8, backgroundColor: 'gray-100'});
const active = style({backgroundColor: 'accent'});
<div className={`${base} ${isActive ? active : ''}`} />

// ✅ One call with a runtime condition.
const card = style({
  padding: 8,
  backgroundColor: {
    default: 'gray-100',
    isActive: 'accent'
  }
});
<div className={card({isActive})} />

マクロでは値を表現できないように思える場合は、インラインスタイルに頼る前にスタイルマクロのリファレンスを確認してください。ほとんどの CSS プロパティ（グリッド配置、オーバーフロー、位置、サイズ、表示）はサポートされています。

スタイルマクロの値は生の CSS ではなくトークンです

マクロは型付きのトークンシステムです。生の CSS 文字列は型チェックに失敗し、エージェントがインラインスタイルで回避しようとする原因になります。よくある混同は次のとおりです。

• width／height／maxWidth／maxHeight／minWidth／minHeight：'100%' ではなく 'full'、'screen'、または数値を使います。
• alignItems／justifyContent／alignSelf／justifySelf：'flex-start'／'flex-end' ではなく、'start'／'center'／'end'／'space-between' を使います。
• 余白（margin、padding、gap、top など）：'1rem' のような文字列ではなく、4px グリッド上のピクセル数値を使います。
• borderRadius：'none'、'sm'、'default'、'lg'、'xl'、'full'、'pill' を使います。'md' はありません。
• 色：16進数、rgb()、var(--…) ではなく、'gray-100'、'accent'、'neutral'、'neutral-subdued' などのトークン名を使います。
• フォント：CSS のフォント省略記法ではなく、font: 'heading-xl'、font: 'body-sm' などを使います。
• 物理的な paddingLeft／paddingRight／marginLeft／marginRight／borderTopLeftRadius ではなく、論理的な辺を使います。paddingStart／paddingEnd／marginStart／marginEnd／insetStart／insetEnd／borderStartStartRadius を使用してください。論理バリアントは RTL で正しく反転します。

色が意味を持つ場合は、セマンティックな色トークンを優先します。エラー／成功／情報／警告／ブランドには、'red-…'／'green-…'／'blue-…'／'orange-…' ではなく、'accent'、'neutral'、'negative'、'positive'、'informative'、'notice' を使います。生の色相トークンを使うのは、装飾やグラフの色に限ってください。

デフォルトのプロパティ値を再指定しない

Button の variant="primary"、ほとんどのコンポーネントの size="M"、コレクションの density="regular" のように、プロパティにデフォルト値を設定するのは余計な記述です。省略してください。

レスポンシブデザイン

レイアウトはビューポートのサイズに応じて調整される必要があります。style マクロにはレイアウトプロパティ用のブレークポイント条件が組み込まれています。固定幅のデザインを作るのではなく、これらを使用してください。

ブレークポイント（モバイルファーストの最小幅）：xs 480、sm 640、md 768、lg 1024、xl 1280、2xl 1536。最小のビューポートには default の値が適用され、各ブレークポイントのしきい値を超えると、その値が適用されます。

const grid = style({
  display: 'grid',
  gridTemplateColumns: {
    default: '1fr',
    sm: 'repeat(2, 1fr)',
    lg: 'repeat(3, 1fr)',
    xl: 'repeat(4, 1fr)'
  },
  gap: {default: 12, md: 16, lg: 24},
  padding: {default: 16, md: 24, lg: 32}
});

コンポーネントの構成

S2 コンポーネントは、独自の内部 DOM とスロット構造を定義します。コンポーネントが特定の子要素 API を想定している場合は、ラッパー要素を挿入しないでください。

• コレクション項目の子要素を <div>、<span>、<section> などで囲まないでください。コンポーネントのドキュメントに記載されたスロットコンポーネントを使用してください。
  • TreeView の行には、div ではなく TreeViewItemContent を使用します。
  • ListView、Menu、Picker、ComboBox、Tabs などでは、Text（該当する場合は slot="label"／slot="description" を指定）と、ドキュメントに記載されたアイコン／画像／アバターのスロットを使用します。
  • Card、AssetCard、UserCard、ProductCard では、指定されたスロットコンポーネント（CardPreview、Image、Content、Text、Footer など）を使用します。
• スロット内に追加するレイアウトは、スロットコンポーネントの外側ではなく、内側に配置します。
• コンポーネントを組み合わせる前に、そのドキュメントページの API セクションを確認してください。想定される子コンポーネント、スロット、制約が記載されています。ドキュメントの例を信頼できる情報源として参照してください。

テキストとアイコンを含むボタン

アイコンとテキストラベルの両方を含む Button／ActionButton／LinkButton では、ラベルを <Text> で囲む必要があります。アイコンの隣にプレーンな文字列を置くと、正しく表示されません。（アイコンのみの子要素は問題なく表示されますが、aria-label が必要です。）Text は各ボタンのサブパスから再エクスポートされています。

import {ActionButton, Text} from '@react-spectrum/s2/ActionButton';
import Download from '@react-spectrum/s2/icons/Download';

<ActionButton>
  <Download />
  <Text>Download</Text>
</ActionButton>

例外：任意のコンテンツを受け入れるコンポーネント

明示的に自由形式のコンポーネントがいくつかあります。TableView の Cell、Dialog／Popover の本文、Disclosure／Accordion のパネルです。これらは、ページの各セクションと同様に、ネイティブ要素と style マクロを使って構成できます。それ以外のコンポーネントでは、スロットコンポーネントに従ってください。

コンポーネントのドキュメントに記載された slot 値のみを使用する

親コンポーネントのドキュメントにそのスロットが記載されている場合にのみ、slot を指定してください。

• Dialog の ButtonGroup 内の Button に slot="close" を指定しないでください。ダイアログが独自に閉じる処理を行います。別の要素に slot="close" を指定すると、親のコンテキストによってその要素が非表示になります。
• Text に slot="label"／slot="description" を、これらのスロットを公開しているコンポーネントの外でむやみに指定しないでください。

Card／CardView を独自に作り直さない

オブジェクト／ファイル／製品／人物のグリッドには、CardView と指定されたバリアント（AssetCard、UserCard、ProductCard）、または Card と CardPreview／Content／Text／Footer の組み合わせを使用してください。独自に作成したカード用の div や <article> ラッパーは出力しないでください。適切なバリアントがない場合に限り、ドキュメントに記載されたスロットコンポーネントのみを使用してカスタムカードを作成します。

コレクションコンポーネントは独自にスクロールを処理する

TableView、ListView、TreeView、CardView、Menu、ListBox は、内部で仮想化とスクロールを行います。overflow／overflowY／overflowX コンテナーで囲まないでください。ネストされたスクロール領域ができ、キーボード操作が機能しなくなります。代わりに、styles プロパティを使ってコレクションに制限付きの height／maxHeight を指定してください。

// ❌ Nested scroller around CardView.
<div className={style({overflowY: 'auto', height: 480})}><CardView>…</CardView></div>

// ✅ Let the collection size itself and scroll internally.
<CardView styles={style({height: 480})}>…</CardView>

コレクション

コレクションコンポーネント（Menu、Picker、ComboBox、ListView、TreeView、TableView、CardView、SegmentedControl、TagGroup、Breadcrumbs など）には、共通の規則がいくつかあります。これらを誤ると、実行時の警告、選択の不具合、キーボード操作の不具合が発生します。

すべての項目に id が必要

項目の id は、選択、onAction(key)、並べ替え、展開、React の再調整に使用されます。静的な項目にはリテラルの id を指定し、動的な項目にはレンダー関数内で id={item.something} を指定します。.map を使用する場合は、id と React の key の両方を設定してください。

// ✅ With array.map — set BOTH `id` (for the collection) and `key` (for React).
<ListView aria-label="Files">
  {files.map(item => (
    <ListViewItem key={item.id} id={item.id}>{item.name}</ListViewItem>
  ))}
</ListView>

items プロパティでデータを渡し、レンダー関数を使用する場合に必要なのは id のみです。

項目の子要素がプレーンテキストでない場合は textValue を指定

項目の子要素にプレーンな文字列以外（アイコン、アバター、複数のスロットを使ったレイアウト、カスタムコンポーネントなど）が含まれる場合は、textValue="..." を指定してください。コレクションは、スクリーンリーダーでの通知、タイプアヘッド、ドラッグ＆ドロップのラベルにこの値を使用します。指定しないと、実行時の警告が発生します。

<ListViewItem id={item.id} textValue={item.name}>
  <FileIcon />
  <Text slot="label">{item.name}</Text>
  <Text slot="description">{item.size}</Text>
</ListViewItem>

コレクションコンテナーに aria-label を指定

すべてのコレクション（ListView、TableView、CardView、TreeView、Menu、ListBox、GridList、TagGroup、Breadcrumbs）には、アクセシブルな名前が必要です。aria-label="..." または aria-labelledby="..." を指定してください。

空の状態と読み込み中の状態は組み込み済みです

• 空の状態：IllustratedMessageを返すrenderEmptyStateを渡します。コレクション全体を条件付きでカスタムの空のdivに置き換えないでください。
• 非同期データ：useAsyncList（または任意のデータ取得ライブラリ）と、コレクションのloadingState／onLoadMoreプロパティを使用します。別途スピナーを描画しないでください。

ActionBarを使った一括操作

コレクションのrenderActionBarプロパティを使うと、項目が選択されたときにActionBarを表示できます。コレクションはコールバックに現在のselectedKeysを渡し、選択数と選択解除を自動的に設定します。selectedItemCountやonClearSelectionを手動でActionBarに渡さないでください。

タイポグラフィ

Text、Heading、Contentはスロットコンポーネントです。カード、ダイアログ、リスト、ピッカー、メニュー、タブなど、スロットコンテキストを提供するS2コンポーネント内でのみ、適切なタイポグラフィを適用します。これらのコンテキスト外では、styleマクロとネイティブHTML要素を使用してください。

// ✅ Standalone heading.
<h1 className={style({font: 'heading-xl'})}>Project overview</h1>

// ❌ Standalone <Heading> with no slot context.
<Heading className={style({font: 'heading-xl'})}>Project overview</Heading>

fontのショートハンドは、fontFamily、fontSize、fontWeight、lineHeight、およびデフォルトのcolorを設定します。デフォルトを上書きする意図がない限り、fontの値と一緒に冗長なcolorを指定しないでください。

フォントスケール — サイズではなく役割で選びます

• heading-* — ページ／セクションの見出し（h1～h6）。ドキュメントのアウトラインに対応します。
• title-* — ページのアウトラインに含まれない、コンポーネント内のタイトル（カードタイトル、ダイアログタイトル、タイルラベル）。
• body-* — 通常の文章や長文のコピー。
• detail-* — 補足メタデータ、キャプション、タイムスタンプ、脚注。
• ui-* — ボタン、メニュー項目、フォームラベル、テーブルセルなどの操作用UIテキスト。
• code-* — インラインコードまたはブロックコード（等幅フォントファミリー）。

サイズは-xs、-sm、デフォルト（サフィックスなし）、-lg、-xl、-2xl、-3xlです（ファミリーによっては、すべてのサイズが用意されているわけではありません。スタイルマクロのリファレンスを参照してください）。

プロバイダーのスコープ

アプリケーションのルート（body内で、最上位のレイアウトを囲む位置）に、単一のProviderをマウントします。

• <html>、<head>、<body>をProviderで囲まないでください。
• Dialog、Popover、Toast、その他のポータル表示されるオーバーレイをProviderで囲まないでください。これらはコンテキストを通じて継承します。
• Providerを入れ子にしないでください。サブツリーに別のlocale／router／colorSchemeを適用する場合に限り、ネストが適切です。このケースはまれです。
• colorSchemeの管理はProviderに任せてください。スクリーンショットに合わせるためにcolorScheme="light"やcolorScheme="dark"をハードコードしないでください。単発のライト／ダークの色の違いには、lightDark()を使用してください。

アプリでToastQueueを使用する場合は、ルートレイアウトの兄弟要素として、Provider内に<ToastContainer />を1つだけ配置します。

import {Provider} from '@react-spectrum/s2/Provider';
import {ToastContainer} from '@react-spectrum/s2/Toast';

function App() {
  return (
    <Provider>
      <ToastContainer />
      <YourApp />
    </Provider>
  );
}

フォームフィールド

S2のフォームフィールドは、ラベル、説明、エラーメッセージ、必須インジケーターをそれぞれ自身で描画します。これらはフィールドのプロパティとして渡してください。付与するためにフィールドを<label>／<p>／<div>で囲まないでください。

• label="..." — 表示されるラベル。
• description="..." — 補足テキスト。
• errorMessage="..."（または関数） — バリデーションエラー。isInvalid／validate／validationBehaviorと組み合わせます。
• isRequired — 必須項目としてマークし、インジケーターを表示します。
• necessityIndicator="icon" | "label" — 必須／任意の表示方法。
• contextualHelp={<ContextualHelp>…</ContextualHelp>} — ラベルの横に表示するヘルプポップオーバー。
• aria-label="..." — 表示ラベルが不要な場合。

<TextField type="email" label="Email" description="We'll never share it." isRequired />

関連するフィールドはFormでグループ化します。Formはラベルの配置（labelPosition、labelAlign）、デフォルトサイズ、必須インジケーター、送信／バリデーションのフローを処理します。Formは縦1列のレイアウトに限定されません。フィールドの一部をスタイル付きのネイティブ要素で囲むことで、複数列やグリッドのレイアウトを構成できます。

アイコン

S2 に組み込まれているアイコンとイラストを使用してください。

• アイコンは @react-spectrum/s2/icons/... から、イラストは @react-spectrum/s2/illustrations/... からインポートしてください。
• サードパーティ製のアイコンライブラリ（lucide-react、phosphor-icons、heroicons など）は導入しないでください。
• アイコンは Icons カタログ、または利用可能であれば S2 MCP の search_s2_icons ツールで検索してください。カタログを正としてください。
• node_modules や S2 のソースを grep しないでください。時間がかかり、目的の名前が見つからないことが多く、古い名前や内部用の名前が見つかる場合もあります。
• カタログ全体を検索してください。一部の名前の一致だけで決めないでください。Heart と HeartBroken は異なり、Edit と EditIn も異なります。

import AlertTriangle from '@react-spectrum/s2/icons/AlertTriangle';
import DropToUpload from '@react-spectrum/s2/illustrations/gradient/generic1/DropToUpload';
import Warning from '@react-spectrum/s2/illustrations/linear/Warning';

イラストには、Gradient（Generic 1／Generic 2 のバリエーション）と Linear のスタイルがあります。

よく使用されるアイコン：AlertTriangle、Close、ChevronDown、Checkmark、Preview、CheckmarkCircle、Add、ChevronUp、Data、FileText、InfoCircle、OpenIn、Chat、Code。

カタログ全体については、Icons と Illustrations を参照してください。

完了を報告する前の確認

タスクの完了を報告する前に、プロジェクト独自のツールチェーンを実行してください。style マクロは、エディターだけでは確認できないビルド時チェックを行います。

• 型チェック。 プロジェクトの型チェック（tsc --noEmit、tsc -b など）を実行してください。問題はすべて修正してください。誤った size の値、必須の props の不足、マクロ内の生の CSS などは、ここで検出されます。
• ビルドまたは開発サーバー。 少なくとも一度は実行してください。マクロの「cannot statically evaluate」エラーは、style({...}) 内の値がリテラルではない値に依存していることを示します。実行時の条件分岐または実行時のスタイル関数を使うように修正してください。
• 実行時の警告。 ページをレンダリングできる場合は、コンソールで aria-label／textValue の不足、非推奨の props などを確認してください。これらは失敗として扱ってください。

ドキュメントの構成

references/ ディレクトリには、以下のように構成された詳細なドキュメントがあります。

ガイド

• コンポーネント選択ツリー：要件でコンポーネントが明示されていない場合に、適切な S2 コンポーネントを選ぶ方法。
• React Spectrum S2 での Figma デザインの実装：Figma MCP を使用して、Figma デザインを S2 コンポーネントと style マクロに置き換える方法。
• カスタムコンポーネントの作成：React Aria Components と style マクロを使用して、カスタムの Spectrum 2 コンポーネントを構築する方法。
• React Spectrum S2 でのテスト：@react-spectrum/test-utils の ARIA パターンテスターを使用して、S2 コンポーネントのテストを作成する方法。
• コレクション
• ドラッグ＆ドロップ
• フォーム
• はじめに
• Spectrum 2 への移行
• 選択
• Style マクロ
• スタイリング
• テスト
• AI の活用

コンポーネント

コンポーネントのドキュメントは references/components/ にあります。コンポーネントごとに Markdown ファイルが用意されています（例：references/components/Button.md）。API、props、使用例、アクセシビリティに関する注意事項が必要な場合は、該当するコンポーネントのファイルを参照してください。

利用可能なコンポーネント：Accordion、ActionBar、ActionButton、ActionButtonGroup、ActionMenu、Avatar、AvatarGroup、Badge、Breadcrumbs、Button、ButtonGroup、Calendar、Card、CardView、Checkbox、CheckboxGroup、ColorArea、ColorField、ColorSlider、ColorSwatch、ColorSwatchPicker、ColorWheel、ComboBox、ContextualHelp、DateField、DatePicker、DateRangePicker、Dialog、Disclosure、Divider、DropZone、Form、Icons、IllustratedMessage、Illustrations、Image、InlineAlert、LabeledValue、Link、LinkButton、ListView、Menu、Meter、NumberField、Picker、Popover、ProgressBar、ProgressCircle、Provider、RadioGroup、RangeCalendar、RangeSlider、SearchField、SegmentedControl、SelectBoxGroup、SideNav、Skeleton、Slider、StatusLight、Switch、TableView、Tabs、TagGroup、TextArea、TextField、TimeField、Toast、ToggleButton、ToggleButtonGroup、Tooltip、TreeView。

追加のリファレンス

• React Aria Components：スタイルのないアクセシブルなプリミティブのドキュメントです。要件に合う React Spectrum S2 コンポーネントがない場合にのみ使用してください。