@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/tile/content.md

@@ -0,0 +1,703 @@
+# Tile (https://design.candescent.com/docs/components/tile)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=8843-7101), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-tile--default)
+
+A compound component with sub-components for leading content, title, description, selection indicator, trailing content, and grouping. Selection state lives in `Tile.Group`; individual tiles are pressable.
+
+```tsx
+import { Tile } from '@cdx-ui/components';
+```
+
+## Shapes
+
+`shape` sets how tiles look and how they sit together. Set it on `Tile.Group` so every child inherits it, or override per `Tile`.
+
+```tsx
+import { useState } from 'react';
+import { Tile, View } from '@cdx-ui/components';
+
+export default function TileShapesDemo() {
+  const [card, setCard] = useState('checking');
+  const [flat, setFlat] = useState('checking');
+
+  return (
+    <View className="w-full max-w-md gap-6">
+      <Tile.Group
+        type="single"
+        shape="card"
+        value={card}
+        onValueChange={setCard}
+        aria-label="Card shape"
+      >
+        <Tile value="checking">
+          <Tile.Content>
+            <Tile.Title>Card</Tile.Title>
+            <Tile.Description>Bordered and rounded, with gaps between tiles.</Tile.Description>
+          </Tile.Content>
+          <Tile.Indicator />
+        </Tile>
+        <Tile value="savings">
+          <Tile.Content>
+            <Tile.Title>Card</Tile.Title>
+            <Tile.Description>Each tile stands alone.</Tile.Description>
+          </Tile.Content>
+          <Tile.Indicator />
+        </Tile>
+      </Tile.Group>
+      <Tile.Group
+        type="single"
+        shape="flat"
+        spacing="none"
+        value={flat}
+        onValueChange={setFlat}
+        aria-label="Flat shape"
+      >
+        <Tile value="checking" showSeparator>
+          <Tile.Content>
+            <Tile.Title>Flat</Tile.Title>
+            <Tile.Description>Borderless rows that touch, split by separators.</Tile.Description>
+          </Tile.Content>
+          <Tile.Indicator />
+        </Tile>
+        <Tile value="savings">
+          <Tile.Content>
+            <Tile.Title>Flat</Tile.Title>
+            <Tile.Description>Suited to lists and cards.</Tile.Description>
+          </Tile.Content>
+          <Tile.Indicator />
+        </Tile>
+      </Tile.Group>
+    </View>
+  );
+}
+```
+
+### Card
+
+The default. Each tile is a bordered, rounded surface with gaps between tiles. Use `type="single"` for radio semantics — one value at a time.
+
+```tsx
+import { useState } from 'react';
+import { Avatar, Tile } from '@cdx-ui/components';
+import { Person } from '@cdx-ui/icons';
+
+export default function TileCardDemo() {
+  const [selected, setSelected] = useState('checking');
+
+  return (
+    <Tile.Group
+      type="single"
+      shape="card"
+      value={selected}
+      onValueChange={setSelected}
+      aria-label="Choose an account"
+      className="w-full max-w-md"
+    >
+      <Tile value="checking">
+        <Tile.LeadingSlot>
+          <Avatar size="md">
+            <Avatar.Icon as={Person} />
+          </Avatar>
+        </Tile.LeadingSlot>
+        <Tile.Content>
+          <Tile.Title>Joint Checking · 6643</Tile.Title>
+          <Tile.Description>$11,308.34 available</Tile.Description>
+        </Tile.Content>
+        <Tile.Indicator />
+      </Tile>
+      <Tile value="savings">
+        <Tile.LeadingSlot>
+          <Avatar size="md">
+            <Avatar.Icon as={Person} />
+          </Avatar>
+        </Tile.LeadingSlot>
+        <Tile.Content>
+          <Tile.Title>High Yield Savings · 7891</Tile.Title>
+          <Tile.Description>$25,430.00 available</Tile.Description>
+        </Tile.Content>
+        <Tile.Indicator />
+      </Tile>
+    </Tile.Group>
+  );
+}
+```
+
+### Flat
+
+Borderless rows with no radius. Pair with `spacing="none"` and `showSeparator` for tight lists, and see [In card](#in-card) and [List](#list) for common placements.
+
+```tsx
+import { useState } from 'react';
+import { Tile } from '@cdx-ui/components';
+
+export default function TileFlatDemo() {
+  const [selected, setSelected] = useState('checking');
+
+  return (
+    <Tile.Group
+      type="single"
+      shape="flat"
+      spacing="none"
+      value={selected}
+      onValueChange={setSelected}
+      aria-label="Choose an account"
+      className="w-full max-w-md"
+    >
+      <Tile value="checking" showSeparator>
+        <Tile.Content>
+          <Tile.Title>Joint Checking · 6643</Tile.Title>
+          <Tile.Description>$11,308.34 available</Tile.Description>
+        </Tile.Content>
+        <Tile.Indicator />
+      </Tile>
+      <Tile value="savings">
+        <Tile.Content>
+          <Tile.Title>High Yield Savings · 7891</Tile.Title>
+          <Tile.Description>$25,430.00 available</Tile.Description>
+        </Tile.Content>
+        <Tile.Indicator />
+      </Tile>
+    </Tile.Group>
+  );
+}
+```
+
+## Without indicator
+
+Omit `Tile.Indicator` when the selected tile styling provides enough visual affordance for the interaction.
+
+```tsx
+import { useState } from 'react';
+import { Tile } from '@cdx-ui/components';
+
+export default function TileWithoutIndicatorDemo() {
+  const [selected, setSelected] = useState('standard');
+
+  return (
+    <Tile.Group
+      type="single"
+      shape="card"
+      value={selected}
+      onValueChange={setSelected}
+      aria-label="Choose a delivery speed"
+      className="w-full max-w-md"
+    >
+      <Tile value="standard">
+        <Tile.Content>
+          <Tile.Title>Standard delivery</Tile.Title>
+          <Tile.Description>Arrives in 3–5 business days</Tile.Description>
+        </Tile.Content>
+      </Tile>
+      <Tile value="express">
+        <Tile.Content>
+          <Tile.Title>Express delivery</Tile.Title>
+          <Tile.Description>Arrives the next business day</Tile.Description>
+        </Tile.Content>
+      </Tile>
+    </Tile.Group>
+  );
+}
+```
+
+## Multiple
+
+Use `type="multiple"` for checkbox semantics. Optional `max` caps how many tiles can be selected; unselected tiles disable when the cap is reached.
+
+```tsx
+import { useState } from 'react';
+import { Tile } from '@cdx-ui/components';
+
+const CATEGORY_OPTIONS = [
+  ['dining', 'Dining out'],
+  ['groceries', 'Groceries'],
+  ['transport', 'Transportation'],
+  ['travel', 'Travel'],
+] as const;
+
+export default function TileMultipleDemo() {
+  const [categories, setCategories] = useState<string[]>(['dining']);
+
+  return (
+    <Tile.Group
+      type="multiple"
+      shape="card"
+      max={3}
+      value={categories}
+      onValueChange={setCategories}
+      aria-label="Spending categories"
+      className="w-full max-w-md"
+    >
+      {CATEGORY_OPTIONS.map(([id, label]) => (
+        <Tile key={id} value={id}>
+          <Tile.Content>
+            <Tile.Title>{label}</Tile.Title>
+          </Tile.Content>
+          <Tile.Indicator />
+        </Tile>
+      ))}
+    </Tile.Group>
+  );
+}
+```
+
+## Horizontal
+
+Set `direction="row"` for side-by-side segment-style choosers. Give each tile `className="flex-1"` so widths split evenly.
+
+```tsx
+import { useState } from 'react';
+import { Tile } from '@cdx-ui/components';
+
+export default function TileHorizontalDemo() {
+  const [selected, setSelected] = useState('expense');
+
+  return (
+    <Tile.Group
+      type="single"
+      direction="row"
+      shape="card"
+      value={selected}
+      onValueChange={setSelected}
+      aria-label="Transaction type"
+      className="w-full max-w-md"
+    >
+      <Tile value="expense" className="flex-1">
+        <Tile.Content>
+          <Tile.Title>Expense</Tile.Title>
+        </Tile.Content>
+        <Tile.Indicator />
+      </Tile>
+      <Tile value="income" className="flex-1">
+        <Tile.Content>
+          <Tile.Title>Income</Tile.Title>
+        </Tile.Content>
+        <Tile.Indicator />
+      </Tile>
+    </Tile.Group>
+  );
+}
+```
+
+## In card
+
+Use the [flat shape](#flat) for tight rows inside a `Card`. Use `Card.Content fullBleed` so tiles stretch edge-to-edge.
+
+```tsx
+import { useState } from 'react';
+import { Card, Tile } from '@cdx-ui/components';
+
+export default function TileInCardDemo() {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Card className="w-full max-w-md">
+      <Card.Content fullBleed>
+        <Tile.Group
+          type="multiple"
+          spacing="none"
+          shape="flat"
+          value={selected}
+          onValueChange={setSelected}
+          aria-label="Statement preferences"
+        >
+          <Tile value="transactions" showSeparator>
+            <Tile.Content>
+              <Tile.Title>Transactions</Tile.Title>
+            </Tile.Content>
+            <Tile.Indicator />
+          </Tile>
+          <Tile value="running" showSeparator>
+            <Tile.Content>
+              <Tile.Title>Running balance</Tile.Title>
+            </Tile.Content>
+            <Tile.Indicator />
+          </Tile>
+          <Tile value="daily">
+            <Tile.Content>
+              <Tile.Title>Daily balances</Tile.Title>
+            </Tile.Content>
+            <Tile.Indicator />
+          </Tile>
+        </Tile.Group>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## List
+
+Use the same [flat](#flat) rows without a `Card` for a plain list. Omit `showSeparator` on the last row.
+
+```tsx
+import { useState } from 'react';
+import { Text, Tile } from '@cdx-ui/components';
+
+const PAYMENT_OPTIONS = [
+  { value: 'regular', title: 'Regular payment', description: 'Make your scheduled loan payment.' },
+  {
+    value: 'principal',
+    title: 'Principal only',
+    description: 'Apply your payment directly to the loan principal.',
+  },
+  { value: 'interest', title: 'Interest only', description: 'Pay only the accrued interest.' },
+  {
+    value: 'escrow',
+    title: 'Escrow only',
+    description: 'Pay only the escrow portion of your loan.',
+  },
+  {
+    value: 'fees',
+    title: 'Fees only',
+    description: 'Pay outstanding fees only.',
+    amount: '$109.30',
+  },
+  {
+    value: 'payoff',
+    title: 'Pay off balance',
+    description: 'Pay the loan in full and keep the account open.',
+  },
+];
+
+export default function TileListDemo() {
+  const [selected, setSelected] = useState<string[]>(['fees']);
+
+  return (
+    <Tile.Group
+      type="multiple"
+      spacing="none"
+      shape="flat"
+      value={selected}
+      onValueChange={setSelected}
+      aria-label="Payment type"
+      className="w-full max-w-md"
+    >
+      {PAYMENT_OPTIONS.map((option, index) => (
+        <Tile
+          key={option.value}
+          value={option.value}
+          showSeparator={index < PAYMENT_OPTIONS.length - 1}
+        >
+          <Tile.Content>
+            <Tile.Title>{option.title}</Tile.Title>
+            <Tile.Description>{option.description}</Tile.Description>
+          </Tile.Content>
+          {option.amount ? (
+            <Tile.TrailingSlot>
+              <Text>{option.amount}</Text>
+            </Tile.TrailingSlot>
+          ) : null}
+          <Tile.Indicator />
+        </Tile>
+      ))}
+    </Tile.Group>
+  );
+}
+```
+
+## Standalone
+
+A `Tile` without a parent `Tile.Group` manages its own selection via `isSelected` / `defaultSelected` / `onSelectedChange`. Standalone tiles use checkbox semantics.
+
+```tsx
+import { useState } from 'react';
+import { Tile } from '@cdx-ui/components';
+
+export default function TileStandaloneDemo() {
+  const [agreed, setAgreed] = useState(false);
+
+  return (
+    <Tile
+      value="terms"
+      shape="card"
+      isSelected={agreed}
+      onSelectedChange={setAgreed}
+      className="w-full max-w-md"
+    >
+      <Tile.Content>
+        <Tile.Title>I agree to the terms and conditions</Tile.Title>
+        <Tile.Description>By selecting this, you accept our privacy policy.</Tile.Description>
+      </Tile.Content>
+      <Tile.Indicator indicatorType="checkbox" />
+    </Tile>
+  );
+}
+```
+
+## With trailing
+
+`Tile.TrailingSlot` carries amounts, chips, or status text — separate from `Tile.Indicator`, which is reserved for the selection affordance.
+
+```tsx
+import { useState } from 'react';
+import { Avatar, Text, Tile } from '@cdx-ui/components';
+import { Person } from '@cdx-ui/icons';
+
+export default function TileWithTrailingDemo() {
+  const [selected, setSelected] = useState<string[]>(['checking']);
+
+  return (
+    <Tile.Group
+      type="multiple"
+      shape="card"
+      value={selected}
+      onValueChange={setSelected}
+      aria-label="Accounts"
+      className="w-full max-w-md"
+    >
+      <Tile value="checking">
+        <Tile.LeadingSlot>
+          <Avatar size="md">
+            <Avatar.Icon as={Person} />
+          </Avatar>
+        </Tile.LeadingSlot>
+        <Tile.Content>
+          <Tile.Title>Joint Checking · 6643</Tile.Title>
+          <Tile.Description>Available balance</Tile.Description>
+        </Tile.Content>
+        <Tile.TrailingSlot>
+          <Text>$11,308.34</Text>
+        </Tile.TrailingSlot>
+        <Tile.Indicator />
+      </Tile>
+      <Tile value="savings">
+        <Tile.LeadingSlot>
+          <Avatar size="md">
+            <Avatar.Icon as={Person} />
+          </Avatar>
+        </Tile.LeadingSlot>
+        <Tile.Content>
+          <Tile.Title>High Yield Savings · 7891</Tile.Title>
+          <Tile.Description>Available balance</Tile.Description>
+        </Tile.Content>
+        <Tile.TrailingSlot>
+          <Text>$25,430.00</Text>
+        </Tile.TrailingSlot>
+        <Tile.Indicator />
+      </Tile>
+    </Tile.Group>
+  );
+}
+```
+
+## Disabled
+
+Set `disabled` on a single tile, or `isDisabled` on `Tile.Group` to cascade across the whole group.
+
+```tsx
+import { Avatar, Tile } from '@cdx-ui/components';
+import { Person } from '@cdx-ui/icons';
+
+export default function TileDisabledDemo() {
+  return (
+    <Tile.Group
+      type="multiple"
+      shape="card"
+      defaultValue={['open']}
+      aria-label="Accounts"
+      className="w-full max-w-md"
+    >
+      <Tile value="open">
+        <Tile.LeadingSlot>
+          <Avatar size="md">
+            <Avatar.Icon as={Person} />
+          </Avatar>
+        </Tile.LeadingSlot>
+        <Tile.Content>
+          <Tile.Title>Joint Checking · 6643</Tile.Title>
+          <Tile.Description>$11,308.34 available</Tile.Description>
+        </Tile.Content>
+        <Tile.Indicator />
+      </Tile>
+      <Tile value="closed" disabled>
+        <Tile.LeadingSlot>
+          <Avatar size="md">
+            <Avatar.Icon as={Person} />
+          </Avatar>
+        </Tile.LeadingSlot>
+        <Tile.Content>
+          <Tile.Title>Closed account</Tile.Title>
+          <Tile.Description>Press is no-op; opacity reduced</Tile.Description>
+        </Tile.Content>
+        <Tile.Indicator />
+      </Tile>
+    </Tile.Group>
+  );
+}
+```
+
+## API
+
+### Tile
+
+Pressable root that toggles selection on press. Requires a unique `value`. Inside a `Tile.Group`, selection is owned by the group; standalone usage supports `isSelected` / `defaultSelected` / `onSelectedChange`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode \| ((state: PressableStateCallbackType) => React.ReactNode)` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `shape?` | `'card' \| 'flat'` | `'card'` | Visual shape. Overrides the shape inherited from `Tile.Group`. `card` is a bordered surface; `flat` is a borderless row. |
+| `showSeparator?` | `boolean` | `false` | Renders a bottom border. Omit it on the last row of a tight list. |
+| `asChild?` | `boolean` | — | Merge tile props onto a single child instead of rendering the default Pressable. |
+| `value` | `string` | — | Identifies this tile within `Tile.Group`. Must be unique within the group. Standalone tiles still require a value (useful for form submission, analytics, etc.). |
+| `isSelected?` | `boolean` | — | Controlled selected state for **standalone** usage (no parent `Tile.Group`). Ignored when the tile is rendered inside a `Tile.Group` — selection is owned by the group. |
+| `defaultSelected?` | `boolean` | — | Initial selected state for **standalone**, uncontrolled usage. |
+| `onSelectedChange?` | `((isSelected: boolean) => void)` | — | Called when standalone selection state changes. Group context overrides this — when inside a `Tile.Group`, use the group's `onValueChange` instead. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) (including `onPress`).
+
+| Attribute       | Values                     | Description     |
+| --------------- | -------------------------- | --------------- |
+| `data-slot`     | `tile`                     | Root pressable  |
+| `data-state`    | `selected` \| `unselected` | Selection state |
+| `data-disabled` | `true` \| `false`          | Disabled state  |
+
+## Sub-components
+
+### Tile.Group
+
+Selection state container and layout. `type="single"` uses radio semantics and does not clear the current value when that tile is pressed again; `type="multiple"` (optional `max`) uses checkbox semantics. `direction` and `spacing` constrain layout to the three supported patterns. `shape` cascades to child tiles.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `direction?` | `'column' \| 'row' \| null` | — | — |
+| `spacing?` | `'default' \| 'none' \| null` | — | — |
+| `shape?` | `'flat' \| 'card' \| null` | — | — |
+| `type?` | `'single' \| 'multiple'` | — | — |
+| `value?` | `string \| string[]` | — | — |
+| `defaultValue?` | `string \| string[]` | — | — |
+| `onValueChange?` | `((value: string) => void) \| ((value: string[]) => void)` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `isDisabled?` | `boolean` | — | — |
+| `max?` | `number` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props). `Tile.Group` is a discriminated union on `type`; `max` applies only when `type="multiple"`.
+
+| `direction`        | `spacing`           | Use case                          |
+| ------------------ | ------------------- | --------------------------------- |
+| `column` (default) | `default` (default) | Vertical stack with gaps          |
+| `column`           | `none`              | Tight vertical stack (rows touch) |
+| `row`              | `default`           | Side-by-side horizontal layout    |
+
+### Tile.LeadingSlot
+
+Optional leading adornment (Avatar, Icon). Decorative and `aria-hidden` by default — override for meaningful leading content.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Tile.Content
+
+Flex column for the text stack (`Tile.Title` and `Tile.Description`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Tile.Title
+
+Primary label. Truncates to one line by default (`numberOfLines={1}`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Tile.Description
+
+Secondary text below the title. Wraps freely by default.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Tile.Indicator
+
+Decorative selection affordance — radio for `type="single"`, checkbox for `type="multiple"`. Always `aria-hidden`; the tile root owns the press target and ARIA role. Use `indicatorType` to override (required for radio styling when standalone).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Replaces the default radio or checkbox visual when provided. |
+| `asChild?` | `boolean` | — | — |
+| `indicatorType?` | `'radio' \| 'checkbox'` | — | Explicit indicator visual. When inside a `Tile.Group`, auto-infers from `type` (`single` → radio, `multiple` → checkbox). For standalone tiles, defaults to `'checkbox'` to match the standalone `checkbox` ARIA role; override with `indicatorType="radio"` if a radio-style visual is needed. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Tile.TrailingSlot
+
+Optional trailing content (amount, chip, status text) — distinct from `Tile.Indicator`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`        | Element              |
+| ------------------ | -------------------- |
+| `tile`             | Root pressable       |
+| `tile-group`       | Selection group      |
+| `tile-leading`     | Leading adornment    |
+| `tile-content`     | Text stack           |
+| `tile-title`       | Primary label        |
+| `tile-description` | Secondary text       |
+| `tile-indicator`   | Selection affordance |
+| `tile-trailing`    | Trailing content     |
+
+## Hook
+
+### useTileContext
+
+Reads this tile's selection state from a child, for example to swap a leading icon when the tile is selected. Call it inside a `Tile`; it throws otherwise.
+
+```tsx
+const { isSelected } = useTileContext();
+```
+
+| Return          | Type                     | Description                                                                            |
+| --------------- | ------------------------ | -------------------------------------------------------------------------------------- |
+| `value`         | `string`                 | This tile's `value`.                                                                   |
+| `isSelected`    | `boolean`                | Whether the tile is selected.                                                          |
+| `isDisabled`    | `boolean`                | Effective disabled state from the tile's `disabled` prop or group rules such as `max`. |
+| `selectionType` | `'single' \| 'multiple'` | The group's `type`, or `'multiple'` when the tile is standalone.                       |
+
+## Accessibility
+
+| Attribute              | Behavior                                                                                                                                              |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Role**               | `Tile.Group` is `radiogroup` for `single`, `group` for `multiple`. Each `Tile` is `radio` or `checkbox` accordingly. Standalone tiles are `checkbox`. |
+| **`aria-checked`**     | Reflects per-tile selection state.                                                                                                                    |
+| **`aria-disabled`**    | Set on disabled tiles and on unselected tiles when `max` is reached.                                                                                  |
+| **Keyboard**           | Focusable via Tab; activated with Enter or Space. Focus-visible ring on web.                                                                          |
+| **`Tile.LeadingSlot`** | `aria-hidden` by default — override for meaningful leading content.                                                                                   |
+| **`Tile.Indicator`**   | Always `aria-hidden`. The tile root is the accessible interactive element.                                                                            |
+
+## When to use
+
+| Use `Tile` when…                                               | Use `ListItem` when…                                           |
+| -------------------------------------------------------------- | -------------------------------------------------------------- |
+| The user is choosing one or many items                         | The row displays information, navigates, or triggers an action |
+| The row should be a `radio` or `checkbox` with selection state | The row should not carry built-in selection state              |