Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(List): add XDSList and XDSListItem components (#261)

Cindy Zhang4f3173b5c605
diff --git a/apps/storybook/stories/List.stories.tsx b/apps/storybook/stories/List.stories.tsx
new file mode 100644
index 0000000000..0133aa25bd
--- /dev/null
+++ b/apps/storybook/stories/List.stories.tsx
@@ -0,0 +1,219 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSList, XDSListItem} from '@xds/core/List';
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSIcon} from '@xds/core/Icon';
+import {
+ Cog6ToothIcon,
+ BellIcon,
+ ShieldCheckIcon,
+ ChevronRightIcon,
+ InboxIcon,
+ PaperAirplaneIcon,
+ DocumentIcon,
+} from '@heroicons/react/24/outline';
+
+const meta: Meta<typeof XDSList> = {
+ title: 'Core/XDSList',
+ component: XDSList,
+ tags: ['autodocs'],
+ argTypes: {
+ density: {
+ control: 'select',
+ options: ['compact', 'balanced', 'spacious'],
+ description: 'Spacing density for list items',
+ },
+ hasDividers: {
+ control: 'boolean',
+ description: 'Whether to show dividers between items',
+ },
+ listStyle: {
+ control: 'select',
+ options: ['none', 'disc', 'decimal', 'circle'],
+ description: 'List marker style',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSList>;
+
+export const Basic: Story = {
+ render: args => (
+ <XDSList {...args}>
+ <XDSListItem label="Notifications" description="Manage your alerts" />
+ <XDSListItem label="Privacy" description="Control your data" />
+ <XDSListItem label="Security" description="Password and 2FA" />
+ </XDSList>
+ ),
+};
+
+export const WithDividers: Story = {
+ render: args => (
+ <XDSList hasDividers header={<strong>Settings</strong>} {...args}>
+ <XDSListItem
+ label="Notifications"
+ description="Manage your alerts"
+ startContent={<XDSIcon icon={BellIcon} />}
+ />
+ <XDSListItem
+ label="Privacy"
+ description="Control your data"
+ startContent={<XDSIcon icon={ShieldCheckIcon} />}
+ />
+ <XDSListItem
+ label="General"
+ description="App preferences"
+ startContent={<XDSIcon icon={Cog6ToothIcon} />}
+ />
+ </XDSList>
+ ),
+};
+
+export const Compact: Story = {
+ render: args => (
+ <XDSList density="compact" hasDividers {...args}>
+ <XDSListItem
+ label="Notifications"
+ onClick={() => {}}
+ endContent={<XDSBadge label="3" />}
+ />
+ <XDSListItem
+ label="Messages"
+ onClick={() => {}}
+ endContent={<XDSBadge label="12" />}
+ />
+ <XDSListItem label="Settings" onClick={() => {}} />
+ </XDSList>
+ ),
+};
+
+export const Spacious: Story = {
+ render: args => (
+ <XDSList density="spacious" {...args}>
+ <XDSListItem
+ label="Getting Started"
+ description="Learn the basics of our platform"
+ />
+ <XDSListItem
+ label="Advanced Topics"
+ description="Deep dive into advanced features"
+ />
+ <XDSListItem
+ label="API Reference"
+ description="Complete API documentation"
+ />
+ </XDSList>
+ ),
+};
+
+export const Interactive: Story = {
+ render: args => (
+ <XDSList {...args}>
+ <XDSListItem
+ label="Inbox"
+ isSelected
+ onClick={() => {}}
+ startContent={<XDSIcon icon={InboxIcon} />}
+ endContent={<XDSIcon icon={ChevronRightIcon} />}
+ />
+ <XDSListItem
+ label="Sent"
+ onClick={() => {}}
+ startContent={<XDSIcon icon={PaperAirplaneIcon} />}
+ endContent={<XDSIcon icon={ChevronRightIcon} />}
+ />
+ <XDSListItem
+ label="Drafts"
+ onClick={() => {}}
+ startContent={<XDSIcon icon={DocumentIcon} />}
+ endContent={<XDSIcon icon={ChevronRightIcon} />}
+ />
+ </XDSList>
+ ),
+};
+
+export const Links: Story = {
+ render: args => (
+ <XDSList {...args}>
+ <XDSListItem label="Documentation" href="/docs" />
+ <XDSListItem
+ label="GitHub"
+ href="https://github.com"
+ target="_blank"
+ description="View source code"
+ />
+ <XDSListItem
+ label="Storybook"
+ href="/storybook"
+ description="Component playground"
+ />
+ </XDSList>
+ ),
+};
+
+export const OrderedList: Story = {
+ render: args => (
+ <XDSList listStyle="decimal" {...args}>
+ <XDSListItem
+ label="Install the package"
+ description="npm install @xds/core"
+ />
+ <XDSListItem
+ label="Import components"
+ description="import { XDSList } from '@xds/core'"
+ />
+ <XDSListItem
+ label="Start building"
+ description="Use components in your app"
+ />
+ </XDSList>
+ ),
+};
+
+export const BulletedList: Story = {
+ render: args => (
+ <XDSList listStyle="disc" {...args}>
+ <XDSListItem label="Accessible by default" />
+ <XDSListItem label="Themeable with StyleX" />
+ <XDSListItem label="Composable and extensible" />
+ </XDSList>
+ ),
+};
+
+export const DisabledItems: Story = {
+ render: args => (
+ <XDSList {...args}>
+ <XDSListItem label="Available" onClick={() => {}} />
+ <XDSListItem label="Unavailable" onClick={() => {}} isDisabled />
+ <XDSListItem label="Also Available" onClick={() => {}} />
+ </XDSList>
+ ),
+};
+
+export const WithMedia: Story = {
+ render: args => (
+ <XDSList hasDividers {...args}>
+ <XDSListItem
+ label="Alex Johnson"
+ description="Hey, are we still on for lunch tomorrow?"
+ startContent={<XDSAvatar name="Alex Johnson" size="md" />}
+ onClick={() => {}}
+ endContent={<XDSBadge label="2" />}
+ />
+ <XDSListItem
+ label="Sam Rivera"
+ description="I pushed the latest changes to the repo"
+ startContent={<XDSAvatar name="Sam Rivera" size="md" />}
+ onClick={() => {}}
+ />
+ <XDSListItem
+ label="Jordan Lee"
+ description="Can you review the design spec when you get a chance?"
+ startContent={<XDSAvatar name="Jordan Lee" size="md" />}
+ onClick={() => {}}
+ endContent={<XDSBadge label="5" />}
+ />
+ </XDSList>
+ ),
+};
diff --git a/packages/core/src/List/README.md b/packages/core/src/List/README.md
new file mode 100644
index 0000000000..1f98173c46
--- /dev/null
+++ b/packages/core/src/List/README.md
@@ -0,0 +1,110 @@
+# XDSList
+
+Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model: `XDSList` wraps `XDSListItem` sub-components.
+
+## Files
+
+<!-- SYNC: Update when files are added/removed -->
+
+| File | Purpose |
+| -------------------- | ------------------------------------ |
+| `XDSList.tsx` | List container component |
+| `XDSListItem.tsx` | List item component |
+| `XDSListContext.tsx` | Internal context for density sharing |
+| `XDSList.test.tsx` | Unit tests |
+| `index.ts` | Public exports |
+| `README.md` | This documentation |
+
+## Usage
+
+```tsx
+import {XDSList, XDSListItem} from '@xds/core';
+
+// Basic list
+<XDSList>
+ <XDSListItem label="Notifications" description="Manage your alerts" />
+ <XDSListItem label="Privacy" description="Control your data" />
+</XDSList>
+
+// With dividers and header
+<XDSList hasDividers header={<strong>Team Members</strong>}>
+ <XDSListItem
+ label="Alice Johnson"
+ description="Engineering"
+ startContent={<XDSIcon icon={UserIcon} />}
+ />
+ <XDSListItem
+ label="Bob Smith"
+ description="Design"
+ startContent={<XDSIcon icon={UserIcon} />}
+ />
+</XDSList>
+
+// Interactive items
+<XDSList>
+ <XDSListItem label="Settings" onClick={() => navigate('/settings')} />
+ <XDSListItem label="Docs" href="/docs" target="_blank" />
+</XDSList>
+
+// Ordered list
+<XDSList listStyle="decimal">
+ <XDSListItem label="First step" />
+ <XDSListItem label="Second step" />
+</XDSList>
+```
+
+## XDSList Props
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------------------------------- | ------------ | ------------------------------------------------ |
+| `children` | `ReactNode` | — | List items (XDSListItem components) |
+| `density` | `'compact' \| 'balanced' \| 'spacious'` | `'balanced'` | Spacing density for items |
+| `hasDividers` | `boolean` | `false` | Show dividers between items |
+| `header` | `ReactNode` | — | Header content, associated via `aria-labelledby` |
+| `listStyle` | `'none' \| 'disc' \| 'decimal' \| 'circle'` | `'none'` | List marker style. `'decimal'` renders `<ol>` |
+| `xstyle` | `StyleXStyles` | — | Style overrides |
+| `data-testid` | `string` | — | Test ID |
+
+## XDSListItem Props
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ------- | ------------------------------------------------ |
+| `label` | `string` | — | Primary text (required) |
+| `description` | `string` | — | Secondary text below label |
+| `startContent` | `ReactNode` | — | Content before label area (icon, avatar) |
+| `endContent` | `ReactNode` | — | Content after label area (badge, chevron) |
+| `onClick` | `(e: MouseEvent) => void` | — | Click handler (enables invisible button pattern) |
+| `href` | `string` | — | Link URL (enables invisible anchor pattern) |
+| `target` | `string` | — | Link target (only with `href`) |
+| `isDisabled` | `boolean` | `false` | Disabled state |
+| `isSelected` | `boolean` | `false` | Selected state (`aria-selected`) |
+| `xstyle` | `StyleXStyles` | — | Style overrides |
+| `data-testid` | `string` | — | Test ID |
+
+## Interactive Pattern
+
+When `onClick` is provided, XDSListItem uses the **invisible button pattern**:
+
+```
+┌─ li (container, :focus-within outline, click area) ──────────┐
+│ [startContent] [button.invisible(label + desc)] [endContent] │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+- The `<li>` is the visual container with hover/press styles
+- An invisible `<button>` wraps the label + description for accessibility
+- `startContent` and `endContent` are siblings to the button (not inside it)
+- Container click fires `onClick` unless the click originated from an interactive child
+- `:focus-within` on the container shows the focus outline
+
+When `href` is provided, the same pattern uses an invisible `<a>` instead.
+
+## Accessibility
+
+- Semantic `<ul>` / `<ol>` with `<li>` elements
+- `role="list"` added when `listStyle='none'` (Safari fix)
+- `aria-labelledby` links header to list
+- `aria-selected` on selected items
+- `aria-disabled` on disabled items
+- Dividers are `aria-hidden="true"`
+- Interactive items are keyboard-focusable via Tab
diff --git a/packages/core/src/List/XDSList.test.tsx b/packages/core/src/List/XDSList.test.tsx
new file mode 100644
index 0000000000..d46ab152b0
--- /dev/null
+++ b/packages/core/src/List/XDSList.test.tsx
@@ -0,0 +1,566 @@
+/**
+ * @file XDSList.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSList, XDSListItem
+ * @output Unit tests for XDSList and XDSListItem components
+ * @position Testing; validates XDSList.tsx and XDSListItem.tsx implementation
+ *
+ * SYNC: When modified, update this header
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSList} from './XDSList';
+import {XDSListItem} from './XDSListItem';
+
+describe('XDSList', () => {
+ // ===========================================================================
+ // Basic rendering
+ // ===========================================================================
+
+ it('renders a list with items', () => {
+ render(
+ <XDSList>
+ <XDSListItem label="Item 1" />
+ <XDSListItem label="Item 2" />
+ </XDSList>,
+ );
+ expect(screen.getByText('Item 1')).toBeInTheDocument();
+ expect(screen.getByText('Item 2')).toBeInTheDocument();
+ });
+
+ it('renders label and description', () => {
+ render(
+ <XDSList>
+ <XDSListItem label="Settings" description="Manage your preferences" />
+ </XDSList>,
+ );
+ expect(screen.getByText('Settings')).toBeInTheDocument();
+ expect(screen.getByText('Manage your preferences')).toBeInTheDocument();
+ });
+
+ it('supports data-testid on list', () => {
+ render(
+ <XDSList data-testid="my-list">
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ expect(screen.getByTestId('my-list')).toBeInTheDocument();
+ });
+
+ it('supports data-testid on list item', () => {
+ render(
+ <XDSList>
+ <XDSListItem label="Item" data-testid="my-item" />
+ </XDSList>,
+ );
+ expect(screen.getByTestId('my-item')).toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Semantic HTML
+ // ===========================================================================
+
+ it('renders as <ul> by default', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ expect(container.querySelector('ul')).toBeInTheDocument();
+ expect(container.querySelector('ol')).not.toBeInTheDocument();
+ });
+
+ it('renders as <ol> when listStyle is decimal', () => {
+ const {container} = render(
+ <XDSList listStyle="decimal">
+ <XDSListItem label="First" />
+ <XDSListItem label="Second" />
+ </XDSList>,
+ );
+ expect(container.querySelector('ol')).toBeInTheDocument();
+ expect(container.querySelector('ul')).not.toBeInTheDocument();
+ });
+
+ it('renders as <ul> when listStyle is disc', () => {
+ const {container} = render(
+ <XDSList listStyle="disc">
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ expect(container.querySelector('ul')).toBeInTheDocument();
+ });
+
+ it('renders as <ul> when listStyle is circle', () => {
+ const {container} = render(
+ <XDSList listStyle="circle">
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ expect(container.querySelector('ul')).toBeInTheDocument();
+ });
+
+ it('adds role="list" when listStyle is none (Safari fix)', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ const ul = container.querySelector('ul');
+ expect(ul).toHaveAttribute('role', 'list');
+ });
+
+ it('does not add role="list" when listStyle is disc', () => {
+ const {container} = render(
+ <XDSList listStyle="disc">
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ const ul = container.querySelector('ul');
+ expect(ul).not.toHaveAttribute('role');
+ });
+
+ it('does not add role="list" when listStyle is decimal', () => {
+ const {container} = render(
+ <XDSList listStyle="decimal">
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ const ol = container.querySelector('ol');
+ expect(ol).not.toHaveAttribute('role');
+ });
+
+ it('renders items as <li> elements', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Item 1" />
+ <XDSListItem label="Item 2" />
+ </XDSList>,
+ );
+ const items = container.querySelectorAll('li');
+ expect(items).toHaveLength(2);
+ });
+
+ // ===========================================================================
+ // Header with aria-labelledby
+ // ===========================================================================
+
+ it('renders header and associates via aria-labelledby', () => {
+ const {container} = render(
+ <XDSList header={<span>Team Members</span>}>
+ <XDSListItem label="Alice" />
+ </XDSList>,
+ );
+ expect(screen.getByText('Team Members')).toBeInTheDocument();
+ const ul = container.querySelector('ul');
+ const headerId = ul?.getAttribute('aria-labelledby');
+ expect(headerId).toBeTruthy();
+ const headerEl = document.getElementById(headerId!);
+ expect(headerEl).toBeInTheDocument();
+ expect(headerEl?.textContent).toBe('Team Members');
+ });
+
+ it('does not render aria-labelledby when no header', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ const ul = container.querySelector('ul');
+ expect(ul).not.toHaveAttribute('aria-labelledby');
+ });
+
+ // ===========================================================================
+ // Density variants
+ // ===========================================================================
+
+ it('renders with compact density', () => {
+ const {container} = render(
+ <XDSList density="compact">
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ expect(container.querySelector('li')).toBeInTheDocument();
+ });
+
+ it('renders with balanced density (default)', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ expect(container.querySelector('li')).toBeInTheDocument();
+ });
+
+ it('renders with spacious density', () => {
+ const {container} = render(
+ <XDSList density="spacious">
+ <XDSListItem label="Item" />
+ </XDSList>,
+ );
+ expect(container.querySelector('li')).toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Dividers
+ // ===========================================================================
+
+ it('renders dividers between items when hasDividers is true', () => {
+ const {container} = render(
+ <XDSList hasDividers>
+ <XDSListItem label="Item 1" />
+ <XDSListItem label="Item 2" />
+ <XDSListItem label="Item 3" />
+ </XDSList>,
+ );
+ const dividers = container.querySelectorAll('hr');
+ expect(dividers).toHaveLength(2);
+ });
+
+ it('dividers have aria-hidden="true"', () => {
+ const {container} = render(
+ <XDSList hasDividers>
+ <XDSListItem label="Item 1" />
+ <XDSListItem label="Item 2" />
+ </XDSList>,
+ );
+ const divider = container.querySelector('hr');
+ expect(divider).toHaveAttribute('aria-hidden', 'true');
+ });
+
+ it('does not render dividers when hasDividers is false', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Item 1" />
+ <XDSListItem label="Item 2" />
+ </XDSList>,
+ );
+ const dividers = container.querySelectorAll('hr');
+ expect(dividers).toHaveLength(0);
+ });
+
+ // ===========================================================================
+ // Interactive items — onClick (invisible button pattern)
+ // ===========================================================================
+
+ it('renders an invisible button when onClick is provided', () => {
+ const onClick = vi.fn();
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Clickable" onClick={onClick} />
+ </XDSList>,
+ );
+ const button = container.querySelector('button');
+ expect(button).toBeInTheDocument();
+ expect(button?.textContent).toContain('Clickable');
+ });
+
+ it('fires onClick when invisible button is clicked', async () => {
+ const user = userEvent.setup();
+ const onClick = vi.fn();
+ render(
+ <XDSList>
+ <XDSListItem label="Clickable" onClick={onClick} />
+ </XDSList>,
+ );
+ await user.click(screen.getByRole('button'));
+ expect(onClick).toHaveBeenCalledTimes(1);
+ });
+
+ it('fires onClick when container area is clicked', async () => {
+ const user = userEvent.setup();
+ const onClick = vi.fn();
+ render(
+ <XDSList>
+ <XDSListItem
+ label="Clickable"
+ onClick={onClick}
+ data-testid="item"
+ startContent={<span data-testid="start">★</span>}
+ />
+ </XDSList>,
+ );
+ // Click on startContent (non-interactive, should propagate)
+ await user.click(screen.getByTestId('start'));
+ expect(onClick).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not fire item onClick when endContent interactive element is clicked', async () => {
+ const user = userEvent.setup();
+ const itemClick = vi.fn();
+ const buttonClick = vi.fn();
+ render(
+ <XDSList>
+ <XDSListItem
+ label="Item"
+ onClick={itemClick}
+ endContent={
+ <button type="button" onClick={buttonClick}>
+ Action
+ </button>
+ }
+ />
+ </XDSList>,
+ );
+ await user.click(screen.getByText('Action'));
+ expect(buttonClick).toHaveBeenCalledTimes(1);
+ expect(itemClick).not.toHaveBeenCalled();
+ });
+
+ it('invisible button is focusable via keyboard', async () => {
+ const user = userEvent.setup();
+ const onClick = vi.fn();
+ render(
+ <XDSList>
+ <XDSListItem label="Focusable" onClick={onClick} />
+ </XDSList>,
+ );
+ await user.tab();
+ expect(screen.getByRole('button')).toHaveFocus();
+ });
+
+ it('invisible button can be activated via keyboard', async () => {
+ const user = userEvent.setup();
+ const onClick = vi.fn();
+ render(
+ <XDSList>
+ <XDSListItem label="Pressable" onClick={onClick} />
+ </XDSList>,
+ );
+ await user.tab();
+ await user.keyboard('{Enter}');
+ expect(onClick).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not render nested buttons — only one invisible button', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Item" onClick={() => {}} />
+ </XDSList>,
+ );
+ const buttons = container.querySelectorAll('li button');
+ // Should be exactly 1 invisible button (no nesting)
+ expect(buttons).toHaveLength(1);
+ });
+
+ // ===========================================================================
+ // Interactive items — href (invisible anchor pattern)
+ // ===========================================================================
+
+ it('renders an invisible anchor when href is provided', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Link" href="/docs" />
+ </XDSList>,
+ );
+ const anchor = container.querySelector('a');
+ expect(anchor).toBeInTheDocument();
+ expect(anchor).toHaveAttribute('href', '/docs');
+ expect(anchor?.textContent).toContain('Link');
+ });
+
+ it('sets target on anchor when provided', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem
+ label="External"
+ href="https://example.com"
+ target="_blank"
+ />
+ </XDSList>,
+ );
+ const anchor = container.querySelector('a');
+ expect(anchor).toHaveAttribute('target', '_blank');
+ });
+
+ it('does not render button or anchor for static items', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Static" />
+ </XDSList>,
+ );
+ expect(container.querySelector('button')).not.toBeInTheDocument();
+ expect(container.querySelector('a')).not.toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Disabled state
+ // ===========================================================================
+
+ it('applies aria-disabled when isDisabled', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Disabled" isDisabled />
+ </XDSList>,
+ );
+ const li = container.querySelector('li');
+ expect(li).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('disables the invisible button when isDisabled', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Disabled" onClick={() => {}} isDisabled />
+ </XDSList>,
+ );
+ const button = container.querySelector('button');
+ expect(button).toBeDisabled();
+ });
+
+ it('does not fire onClick when disabled item is clicked', async () => {
+ const onClick = vi.fn();
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Disabled" onClick={onClick} isDisabled />
+ </XDSList>,
+ );
+ // pointerEvents: none prevents click, but let's verify the handler guards
+ const li = container.querySelector('li');
+ // Manually dispatch click (bypassing pointer-events)
+ li?.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+ expect(onClick).not.toHaveBeenCalled();
+ });
+
+ // ===========================================================================
+ // Selected state
+ // ===========================================================================
+
+ it('applies aria-selected when isSelected', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Selected" isSelected onClick={() => {}} />
+ </XDSList>,
+ );
+ const li = container.querySelector('li');
+ expect(li).toHaveAttribute('aria-selected', 'true');
+ });
+
+ it('does not apply aria-selected when not selected', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem label="Not Selected" />
+ </XDSList>,
+ );
+ const li = container.querySelector('li');
+ expect(li).not.toHaveAttribute('aria-selected');
+ });
+
+ // ===========================================================================
+ // startContent and endContent
+ // ===========================================================================
+
+ it('renders startContent before label', () => {
+ render(
+ <XDSList>
+ <XDSListItem
+ label="With Icon"
+ startContent={<span data-testid="icon">★</span>}
+ />
+ </XDSList>,
+ );
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ });
+
+ it('renders endContent after label', () => {
+ render(
+ <XDSList>
+ <XDSListItem
+ label="With Badge"
+ endContent={<span data-testid="badge">3</span>}
+ />
+ </XDSList>,
+ );
+ expect(screen.getByTestId('badge')).toBeInTheDocument();
+ });
+
+ it('startContent and endContent are siblings to invisible button', () => {
+ const {container} = render(
+ <XDSList>
+ <XDSListItem
+ label="Item"
+ onClick={() => {}}
+ startContent={<span data-testid="start">★</span>}
+ endContent={<span data-testid="end">→</span>}
+ />
+ </XDSList>,
+ );
+ const button = container.querySelector('button');
+ const li = container.querySelector('li');
+ // startContent and endContent should be children of li, not inside button
+ expect(li?.querySelector('[data-testid="start"]')).toBeInTheDocument();
+ expect(li?.querySelector('[data-testid="end"]')).toBeInTheDocument();
+ expect(
+ button?.querySelector('[data-testid="start"]'),
+ ).not.toBeInTheDocument();
+ expect(
+ button?.querySelector('[data-testid="end"]'),
+ ).not.toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Border radius
+ // ===========================================================================
+
+ it('applies content radius by default', () => {
+ render(
+ <XDSList>
+ <XDSListItem label="Item" data-testid="item" isSelected />
+ </XDSList>,
+ );
+ const item = screen.getByTestId('item');
+ expect(item).toBeInTheDocument();
+ });
+
+ it('removes radius when hasDividers is true', () => {
+ render(
+ <XDSList hasDividers>
+ <XDSListItem label="Item" data-testid="item" isSelected />
+ </XDSList>,
+ );
+ const item = screen.getByTestId('item');
+ expect(item).toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // List markers
+ // ===========================================================================
+
+ it('renders list markers for disc style', () => {
+ render(
+ <XDSList listStyle="disc">
+ <XDSListItem label="Bullet item" data-testid="item" />
+ </XDSList>,
+ );
+ const item = screen.getByTestId('item');
+ // When markers are shown, inner content is wrapped in a div
+ const innerWrapper = item.querySelector('div');
+ expect(innerWrapper).toBeInTheDocument();
+ });
+
+ it('does not wrap content when listStyle is none', () => {
+ render(
+ <XDSList listStyle="none">
+ <XDSListItem label="Plain item" data-testid="item" />
+ </XDSList>,
+ );
+ const item = screen.getByTestId('item');
+ // No inner div wrapper when no markers
+ const innerDiv = item.querySelector(':scope > div');
+ expect(innerDiv).not.toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Description rendering
+ // ===========================================================================
+
+ it('does not render description when not provided', () => {
+ render(
+ <XDSList>
+ <XDSListItem label="Label Only" />
+ </XDSList>,
+ );
+ // Should have the label span only (plus possibly wrapper spans)
+ expect(screen.getByText('Label Only')).toBeInTheDocument();
+ expect(screen.queryByText('undefined')).not.toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsx
new file mode 100644
index 0000000000..4b969817cf
--- /dev/null
+++ b/packages/core/src/List/XDSList.tsx
@@ -0,0 +1,206 @@
+/**
+ * @file XDSList.tsx
+ * @input Uses React forwardRef, ReactNode, StyleXStyles, theme tokens, XDSListContext
+ * @output Exports XDSList component, XDSListProps, XDSListDensity, XDSListStyle types
+ * @position Core implementation; consumed by index.ts, tested by XDSList.test.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/List/README.md
+ * - /packages/core/src/List/XDSList.test.tsx
+ * - /packages/core/src/List/index.ts
+ * - /apps/storybook/stories/List.stories.tsx
+ */
+
+import {forwardRef, useId, useMemo, Children, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {colorVars, spacingVars} from '../theme/tokens.stylex';
+import {XDSListContext, type XDSListDensity} from './XDSListContext';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** List marker style. */
+export type XDSListStyle = 'none' | 'disc' | 'decimal' | 'circle';
+
+export {type XDSListDensity} from './XDSListContext';
+
+export interface XDSListProps {
+ /**
+ * List items. Should be XDSListItem components.
+ */
+ children: ReactNode;
+
+ /**
+ * Spacing density for list items.
+ * - 'compact': Tighter spacing for dense UIs
+ * - 'balanced': Standard spacing
+ * - 'spacious': Extra spacing for readability
+ * @default 'balanced'
+ */
+ density?: XDSListDensity;
+
+ /**
+ * Whether to show dividers between list items.
+ * @default false
+ */
+ hasDividers?: boolean;
+
+ /**
+ * Header content rendered above the list.
+ * Semantically associated via aria-labelledby.
+ */
+ header?: ReactNode;
+
+ /**
+ * List marker style.
+ * When 'decimal', renders an `<ol>`. Otherwise renders a `<ul>`.
+ * @default 'none'
+ */
+ listStyle?: XDSListStyle;
+
+ /**
+ * StyleX styles to apply to the list container.
+ */
+ xstyle?: StyleXStyles;
+
+ /**
+ * Test ID for testing frameworks.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ list: {
+ margin: 0,
+ paddingInlineStart: 0,
+ },
+ listWithMarkers: {
+ paddingInlineStart: spacingVars['--spacing-6'],
+ },
+ header: {
+ marginBottom: spacingVars['--spacing-2'],
+ },
+ divider: {
+ height: '1px',
+ border: 'none',
+ margin: 0,
+ backgroundColor: colorVars['--color-divider'],
+ },
+});
+
+const listStyleTypes = stylex.create({
+ none: {
+ listStyleType: 'none',
+ },
+ disc: {
+ listStyleType: 'disc',
+ },
+ decimal: {
+ listStyleType: 'decimal',
+ },
+ circle: {
+ listStyleType: 'circle',
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A vertical list component for rendering collections of items.
+ *
+ * Renders semantic `<ul>` or `<ol>` elements with configurable density,
+ * dividers, marker styles, and an optional header.
+ *
+ * @example
+ * ```tsx
+ * <XDSList>
+ * <XDSListItem label="Notifications" description="Manage your alerts" />
+ * <XDSListItem label="Privacy" description="Control your data" />
+ * </XDSList>
+ *
+ * <XDSList listStyle="decimal" density="compact">
+ * <XDSListItem label="First step" />
+ * <XDSListItem label="Second step" />
+ * </XDSList>
+ * ```
+ */
+export const XDSList = forwardRef<
+ HTMLUListElement | HTMLOListElement,
+ XDSListProps
+>(
+ (
+ {
+ children,
+ density = 'balanced',
+ hasDividers = false,
+ header,
+ listStyle = 'none',
+ xstyle,
+ 'data-testid': testId,
+ },
+ ref,
+ ) => {
+ const headerId = useId();
+ const isOrdered = listStyle === 'decimal';
+ const hasMarkers = listStyle !== 'none';
+ const Tag = isOrdered ? 'ol' : 'ul';
+
+ const contextValue = useMemo(
+ () => ({density, hasDividers, hasMarkers}),
+ [density, hasDividers, hasMarkers],
+ );
+
+ // Interleave dividers between children when hasDividers is true
+ let renderedChildren = children;
+ if (hasDividers) {
+ const childArray = Children.toArray(children);
+ const withDividers: ReactNode[] = [];
+ childArray.forEach((child, i) => {
+ withDividers.push(child);
+ if (i < childArray.length - 1) {
+ withDividers.push(
+ <hr
+ key={`divider-${i}`}
+ aria-hidden="true"
+ {...stylex.props(styles.divider)}
+ />,
+ );
+ }
+ });
+ renderedChildren = withDividers;
+ }
+
+ return (
+ <XDSListContext.Provider value={contextValue}>
+ {header != null && (
+ <div id={headerId} {...stylex.props(styles.header)}>
+ {header}
+ </div>
+ )}
+ <Tag
+ ref={ref as React.Ref<HTMLUListElement & HTMLOListElement>}
+ data-testid={testId}
+ aria-labelledby={header != null ? headerId : undefined}
+ {...(listStyle === 'none' && !isOrdered ? {role: 'list'} : {})}
+ {...stylex.props(
+ styles.list,
+ listStyleTypes[listStyle],
+ hasMarkers && styles.listWithMarkers,
+ xstyle,
+ )}>
+ {renderedChildren}
+ </Tag>
+ </XDSListContext.Provider>
+ );
+ },
+);
+
+XDSList.displayName = 'XDSList';
diff --git a/packages/core/src/List/XDSListContext.tsx b/packages/core/src/List/XDSListContext.tsx
new file mode 100644
index 0000000000..2f7eba1dee
--- /dev/null
+++ b/packages/core/src/List/XDSListContext.tsx
@@ -0,0 +1,18 @@
+/**
+ * @file XDSListContext.tsx
+ * @input Uses React createContext
+ * @output Exports XDSListContext for sharing density between XDSList and XDSListItem
+ * @position Internal context; consumed by XDSList.tsx and XDSListItem.tsx
+ */
+
+import {createContext} from 'react';
+
+export type XDSListDensity = 'compact' | 'balanced' | 'spacious';
+
+export interface XDSListContextValue {
+ density: XDSListDensity;
+ hasDividers: boolean;
+ hasMarkers: boolean;
+}
+
+export const XDSListContext = createContext<XDSListContextValue | null>(null);
diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsx
new file mode 100644
index 0000000000..2582055818
--- /dev/null
+++ b/packages/core/src/List/XDSListItem.tsx
@@ -0,0 +1,370 @@
+/**
+ * @file XDSListItem.tsx
+ * @input Uses React forwardRef, ReactNode, StyleXStyles, theme tokens
+ * @output Exports XDSListItem component, XDSListItemProps type
+ * @position Core implementation; consumed by XDSList, index.ts, tested by XDSList.test.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/List/README.md
+ * - /packages/core/src/List/XDSList.test.tsx
+ * - /packages/core/src/List/index.ts
+ * - /apps/storybook/stories/List.stories.tsx
+ */
+
+import {forwardRef, useContext, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ radiusVars,
+ spacingVars,
+ textSizeVars,
+ lineHeightVars,
+ transitionVars,
+} from '../theme/tokens.stylex';
+import {XDSListContext} from './XDSListContext';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSListItemProps {
+ /**
+ * Primary text label for the item.
+ */
+ label: string;
+
+ /**
+ * Secondary description text below the label.
+ */
+ description?: string;
+
+ /**
+ * Content rendered before the item (icon, avatar, checkbox).
+ * Uses start/end naming for RTL support.
+ */
+ startContent?: ReactNode;
+
+ /**
+ * Content rendered after the item (badge, action button, chevron).
+ */
+ endContent?: ReactNode;
+
+ /**
+ * Click handler for interactive items.
+ * Automatically enables hover/press styles when provided.
+ */
+ onClick?: (e: React.MouseEvent) => void;
+
+ /**
+ * URL for link items. Renders an invisible anchor element.
+ * Automatically enables hover/press styles when provided.
+ */
+ href?: string;
+
+ /**
+ * Link target (e.g., '_blank'). Only used with href.
+ */
+ target?: string;
+
+ /**
+ * Whether the item is disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+
+ /**
+ * Whether the item is currently selected.
+ * @default false
+ */
+ isSelected?: boolean;
+
+ /**
+ * StyleX styles to apply to the list item.
+ */
+ xstyle?: StyleXStyles;
+
+ /**
+ * Test ID for testing frameworks.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ // Default layout: <li> is the flex container
+ item: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-3'],
+ position: 'relative',
+ boxSizing: 'border-box',
+ textAlign: 'start',
+ },
+ // When list has markers (disc/decimal/circle), <li> must be list-item
+ // so the browser renders the ::marker. Flex layout moves to inner wrapper.
+ itemWithMarker: {
+ display: 'list-item',
+ position: 'relative',
+ boxSizing: 'border-box',
+ textAlign: 'start',
+ },
+ // Inner flex wrapper used when markers are shown
+ innerWrapper: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-3'],
+ },
+ withRadius: {
+ borderRadius: radiusVars['--radius-content'],
+ },
+ noRadius: {
+ borderRadius: 0,
+ },
+ interactive: {
+ cursor: 'pointer',
+ transitionProperty: 'background-image',
+ transitionDuration: transitionVars['--transition-fast'],
+ backgroundImage: {
+ default: null,
+ ':hover': `linear-gradient(${colorVars['--color-hover-overlay']}, ${colorVars['--color-hover-overlay']})`,
+ ':active': `linear-gradient(${colorVars['--color-pressed-overlay']}, ${colorVars['--color-pressed-overlay']})`,
+ },
+ },
+ focusWithinOutline: {
+ outline: {
+ default: 'none',
+ ':focus-within': `2px solid ${colorVars['--color-focus-outline']}`,
+ },
+ outlineOffset: {
+ default: '0',
+ ':focus-within': '2px',
+ },
+ },
+ disabled: {
+ cursor: 'not-allowed',
+ opacity: 0.5,
+ pointerEvents: 'none' as const,
+ },
+ selected: {
+ backgroundColor: colorVars['--color-accent-deemphasized'],
+ },
+ invisibleButton: {
+ all: 'unset',
+ cursor: 'inherit',
+ font: 'inherit',
+ color: 'inherit',
+ display: 'flex',
+ flexDirection: 'column',
+ flex: 1,
+ minWidth: 0,
+ textAlign: 'start',
+ },
+ invisibleAnchor: {
+ all: 'unset',
+ cursor: 'inherit',
+ font: 'inherit',
+ color: 'inherit',
+ display: 'flex',
+ flexDirection: 'column',
+ flex: 1,
+ minWidth: 0,
+ textAlign: 'start',
+ textDecoration: 'none',
+ },
+ content: {
+ display: 'flex',
+ flexDirection: 'column',
+ flex: 1,
+ minWidth: 0,
+ textAlign: 'start',
+ },
+ label: {
+ color: colorVars['--color-text-primary'],
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ description: {
+ color: colorVars['--color-text-secondary'],
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ startContent: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ },
+ endContent: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ marginInlineStart: 'auto',
+ },
+});
+
+const densityStyles = stylex.create({
+ compact: {
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-2'],
+ fontSize: textSizeVars['--text-xsm'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ },
+ balanced: {
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ fontSize: textSizeVars['--text-sm'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ },
+ spacious: {
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-4'],
+ fontSize: textSizeVars['--text-base'],
+ lineHeight: lineHeightVars['--leading-normal'],
+ },
+});
+
+const descriptionSizeStyles = stylex.create({
+ compact: {
+ fontSize: textSizeVars['--text-2xs'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ },
+ balanced: {
+ fontSize: textSizeVars['--text-xsm'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ },
+ spacious: {
+ fontSize: textSizeVars['--text-sm'],
+ lineHeight: lineHeightVars['--leading-normal'],
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A list item component for use within XDSList.
+ *
+ * Renders structured content with label, description, start/end content areas.
+ * When `onClick` is provided, uses the invisible button pattern for accessibility.
+ * When `href` is provided, uses an invisible anchor pattern.
+ *
+ * @example
+ * ```tsx
+ * <XDSListItem label="Settings" description="Manage your preferences" />
+ * <XDSListItem label="Profile" onClick={() => navigate('/profile')} />
+ * <XDSListItem label="Docs" href="/docs" target="_blank" />
+ * ```
+ */
+export const XDSListItem = forwardRef<HTMLLIElement, XDSListItemProps>(
+ (
+ {
+ label,
+ description,
+ startContent,
+ endContent,
+ onClick,
+ href,
+ target,
+ isDisabled = false,
+ isSelected = false,
+ xstyle,
+ 'data-testid': testId,
+ },
+ ref,
+ ) => {
+ const ctx = useContext(XDSListContext);
+ const density = ctx?.density ?? 'balanced';
+ const hasDividers = ctx?.hasDividers ?? false;
+ const hasMarkers = ctx?.hasMarkers ?? false;
+ const isInteractive = onClick != null || href != null;
+
+ const labelAndDescription = (
+ <>
+ <span {...stylex.props(styles.label)}>{label}</span>
+ {description != null && (
+ <span
+ {...stylex.props(
+ styles.description,
+ descriptionSizeStyles[density],
+ )}>
+ {description}
+ </span>
+ )}
+ </>
+ );
+
+ const handleContainerClick = (e: React.MouseEvent) => {
+ if (isDisabled) return;
+ const target = e.target as HTMLElement;
+ // Don't fire onClick if click originated from an interactive child
+ if (target.closest('button, a, input, select, textarea')) return;
+ onClick?.(e);
+ };
+
+ const innerContent = (
+ <>
+ {startContent != null && (
+ <span {...stylex.props(styles.startContent)}>{startContent}</span>
+ )}
+
+ {href != null ? (
+ <a
+ href={href}
+ target={target}
+ aria-disabled={isDisabled || undefined}
+ tabIndex={isDisabled ? -1 : undefined}
+ {...stylex.props(styles.invisibleAnchor)}>
+ {labelAndDescription}
+ </a>
+ ) : onClick != null ? (
+ <button
+ type="button"
+ onClick={onClick}
+ disabled={isDisabled}
+ {...stylex.props(styles.invisibleButton)}>
+ {labelAndDescription}
+ </button>
+ ) : (
+ <span {...stylex.props(styles.content)}>{labelAndDescription}</span>
+ )}
+
+ {endContent != null && (
+ <span {...stylex.props(styles.endContent)}>{endContent}</span>
+ )}
+ </>
+ );
+
+ return (
+ <li
+ ref={ref}
+ data-testid={testId}
+ aria-selected={isSelected || undefined}
+ aria-disabled={isDisabled || undefined}
+ {...stylex.props(
+ hasMarkers ? styles.itemWithMarker : styles.item,
+ densityStyles[density],
+ hasDividers ? styles.noRadius : styles.withRadius,
+ isInteractive && styles.interactive,
+ isInteractive && styles.focusWithinOutline,
+ isDisabled && styles.disabled,
+ isSelected && styles.selected,
+ xstyle,
+ )}
+ onClick={isInteractive ? handleContainerClick : undefined}>
+ {hasMarkers ? (
+ <div {...stylex.props(styles.innerWrapper)}>{innerContent}</div>
+ ) : (
+ innerContent
+ )}
+ </li>
+ );
+ },
+);
+
+XDSListItem.displayName = 'XDSListItem';
diff --git a/packages/core/src/List/index.ts b/packages/core/src/List/index.ts
new file mode 100644
index 0000000000..1ebd48cd4d
--- /dev/null
+++ b/packages/core/src/List/index.ts
@@ -0,0 +1,13 @@
+/**
+ * @file index.ts
+ * @input Imports from XDSList.tsx and XDSListItem.tsx
+ * @output Exports XDSList, XDSListItem components and their props/types
+ * @position Package entry point for List
+ *
+ * SYNC: When modified, update /packages/core/src/List/README.md
+ */
+
+export {XDSList} from './XDSList';
+export type {XDSListProps, XDSListStyle, XDSListDensity} from './XDSList';
+export {XDSListItem} from './XDSListItem';
+export type {XDSListItemProps} from './XDSListItem';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index f6bd4bce2c..39d7ee5257 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -24,6 +24,7 @@ export * from './RadioList';
export * from './Divider';
export * from './EmptyState';
export * from './Link';
+export * from './List';
export * from './Slider';
export * from './Stack';
export * from './Switch';