React Spectrum S2

# React Spectrum S2 (Spectrum 2)

If the requirements do not clearly specify which React Spectrum component to use, consult the [Component Decision Tree](references/guides/component-decision-tree.md) before choosing a component.

If the request involves a Figma design, frame, or URL — or if the Figma MCP (`get_design_context`,`search_design_system`, etc.) is available — consult [Implementing Figma designs with React Spectrum S2](references/guides/figma-to-s2.md) before generating code.

When writing tests that exercise S2 components, consult [Testing with React Spectrum S2](references/guides/test-utils-guidance.md) and prefer the ARIA pattern testers from `@react-spectrum/test-utils` over hand-rolled role/selector queries.

## React Spectrum S2 vs React Aria Components

React Spectrum S2 is built on top of React Aria Components. The S2 components add Spectrum 2 styling, behavior, and slot structure on top of the unstyled React Aria primitives. Always prefer S2 components for React Spectrum work because they are pre-styled, design-system compliant, and cover most common UI patterns.

Only reach for React Aria Components directly when:
- Building a custom component because no S2 component matches the requirements. Follow [Creating Custom Components](references/guides/creating-custom-components.md) and pair the React Aria primitive with the S2 `style` macro for Spectrum styling.
- You need a utility such as `FocusScope`, `VisuallyHidden`, `useFocusRing`, `mergeProps`, etc.

The React Aria Components documentation is bundled under `references/react-aria/`. Many unstyled React Aria Components share the same name as S2 components, so ensure that you're searching and accessing the correct docs where needed.

## Imports

Use subpath imports matching the documentation — don't import from the package barrel `'@react-spectrum/s2'`:

```tsx
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';
```

Common types and list-data hooks are re-exported from `@react-spectrum/s2` — prefer importing from there instead of `react-aria-components`, `react-stately`, or `@react-types/*`:

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

### Use the typed Item for each collection

Each S2 collection component has its own item export — there is no generic `Item` component. `Menu` → `MenuItem`/`MenuSection`; `Picker` → `PickerItem`/`PickerSection`; `ComboBox` → `ComboBoxItem`/`ComboBoxSection`; `ListView` → `ListViewItem`; `TreeView` → `TreeViewItem` (with `TreeViewItemContent`); `TableView` → `Row`/`Column`/`Cell`/`TableHeader`/`TableBody`; `SegmentedControl` → `SegmentedControlItem`; `TagGroup` → `Tag`; `Breadcrumbs` → `Breadcrumb`; `Accordion` → `AccordionItem` (with `AccordionItemHeader`/`AccordionItemTitle`/`AccordionItemPanel`).

## Styling

Use S2 components and the S2 `style` macro as the default styling approach.

- Prefer S2 components first; use their `styles` prop only for layout-style properties.
- For generic layouts (flex, grid, etc.), use native HTML elements with the