# Surface

A card container for grouping related content.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Surface.tsx)

Figma: [Content/Card](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5510)

## Overview

A surface renders a `div` with a thin border by default. Its `size` sets the corner radius and the padding to the same value.

## Examples

### Basic

```tsx
import { style, Surface } from '@tempoxyz/ds'
import { SwapHorizontal } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Surface>
        <Surface.Header>
          <Surface.Title>
            <SwapHorizontal />
            Routes
          </Surface.Title>
        </Surface.Header>
        <Surface.Description>
          Move stablecoins between Tempo and other networks.
        </Surface.Description>
        <Surface.Links>
          <a href="#basic">Make a transfer</a>
          <a href="#basic">Accept deposits</a>
          <a href="#basic">Supported routes</a>
        </Surface.Links>
      </Surface>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    backgroundColor: 'background.primary',
    display: 'grid',
    gap: '12',
    padding: '16',
    gridTemplateColumns: 'repeat(auto-fill, minmax(14rem, 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Basic.tsx)

### Header

Place a `Surface.Title` and an optional action inside `Surface.Header`.

```tsx
import { Button, style, Surface, TokenLogo } from '@tempoxyz/ds'

const balances = [
  ['Bridged USDC (Stargate)', '0x20c000000000000000000000b9537d11c60e8b50', '$2.02'],
  ['pathUSD', '0x20c0000000000000000000000000000000000000', '$0.12'],
  ['USDT0', '0x20c00000000000000000000014f22ca97301eb73', '$0.10'],
] as const

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Surface>
        <Surface.Header>
          <Surface.Title>Balances</Surface.Title>
          <Button size="small" variant="tertiary">
            View all
          </Button>
        </Surface.Header>
        {balances.map(([name, address, amount]) => (
          <div key={address} {...styles.balance()}>
            <TokenLogo address={address} />
            <span {...styles.name()}>{name}</span>
            {amount}
          </div>
        ))}
      </Surface>
    </div>
  )
}

namespace styles {
  export const balance = style({
    alignItems: 'center',
    columnGap: '12',
    display: 'flex',
    paddingBlock: '8',
    typography: 'body.b1Strong',
  })

  export const grid = style({
    backgroundColor: 'background.primary',
    display: 'grid',
    padding: '16',
  })

  export const name = style({ flex: '1 !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Header.tsx)

### List

A [ListGroup](/docs/components/list-group) inside a surface bleeds into its padding, so a row's hover fill reaches the edges of the surface. Each row is 44px, and a [Select](/docs/components/select) in a row hugs its value at the end of the row.

```tsx
/** Renders a small surface whose list holds a network picker and a row of token logos, for the Surface docs. @module */
import { ListGroup, NetworkLogo, Select, style, Surface, TokenLogo } from '@tempoxyz/ds'

const networks = [
  { available: true, id: 'tempo', name: 'Tempo' },
  { available: false, id: 'ethereum', name: 'Ethereum' },
  { available: false, id: 'base', name: 'Base' },
] as const

const stablecoins = [
  ['pathUSD', '0x20c0000000000000000000000000000000000000'],
  ['Bridged USDC (Stargate)', '0x20c000000000000000000000b9537d11c60e8b50'],
  ['USDT0', '0x20c00000000000000000000014f22ca97301eb73'],
] as const

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Surface size="small">
        <ListGroup>
          <ListGroup.Row>
            <ListGroup.Label id="surface-list-network">Network</ListGroup.Label>
            <Select.Root value="tempo">
              <Select.Trigger aria-labelledby="surface-list-network">
                <Select.Value>
                  {() => (
                    <span {...styles.value()}>
                      <NetworkLogo network="tempo" size="medium" />
                      Tempo
                    </span>
                  )}
                </Select.Value>
                <Select.Icon />
              </Select.Trigger>
              <Select.Popup align="end">
                {networks.map((network) => (
                  <Select.Item disabled={!network.available} key={network.id} value={network.id}>
                    <Select.ItemPrefix>
                      <NetworkLogo network={network.id} size="medium" />
                    </Select.ItemPrefix>
                    <Select.ItemText>{network.name}</Select.ItemText>
                    {network.available ? null : <Select.ItemSuffix>Coming soon</Select.ItemSuffix>}
                  </Select.Item>
                ))}
              </Select.Popup>
            </Select.Root>
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Supported stablecoins</ListGroup.Label>
            <span {...styles.coins()}>
              {stablecoins.map(([symbol, address]) => (
                <TokenLogo address={address} alt={symbol} key={address} />
              ))}
            </span>
          </ListGroup.Row>
        </ListGroup>
      </Surface>
    </div>
  )
}

namespace styles {
  export const coins = style({ display: 'flex', gap: '4', marginInlineStart: 'auto !custom' })

  export const grid = style({ display: 'grid', maxWidth: '25rem !custom', width: '100% !custom' })

  export const value = style({ alignItems: 'center', display: 'flex', gap: '8' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/List.tsx)

### Size

Set `size` to `small`, `medium`, or `large` (default).

```tsx
import { style, Surface } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.grid()}>
      {(['large', 'medium', 'small'] as const).map((size) => (
        <Surface key={size} size={size}>
          Size {size}
        </Surface>
      ))}
    </div>
  )
}

namespace styles {
  // Surfaces keep their content height instead of stretching to the tallest one in a row.
  export const grid = style({
    alignItems: 'start',
    backgroundColor: 'background.primary',
    display: 'grid',
    gap: '12',
    padding: '16',
    gridTemplateColumns: 'repeat(auto-fill, minmax(14rem, 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Size.tsx)

### Render

Pass a `button` or link to `render` for a pressable surface with hover, press, and focus styles.

```tsx
import { style, Surface } from '@tempoxyz/ds'
import { SwapHorizontal } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Surface render={<a href="#render" />}>
        <Surface.Header>
          <Surface.Title>
            <SwapHorizontal />
            Routes
          </Surface.Title>
        </Surface.Header>
        <Surface.Description>
          Move stablecoins between Tempo and other networks.
        </Surface.Description>
      </Surface>
      <Surface render={<button type="button" />}>Interactive button</Surface>
      <Surface render={<a href="#render" />}>Interactive link</Surface>
    </div>
  )
}

namespace styles {
  // Surfaces keep their content height instead of stretching to the tallest one in a row.
  export const grid = style({
    alignItems: 'start',
    backgroundColor: 'background.primary',
    display: 'grid',
    gap: '12',
    padding: '16',
    gridTemplateColumns: 'repeat(auto-fill, minmax(14rem, 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Render.tsx)

### Disabled

Set `disabled` on a pressable surface to block interaction.

```tsx
import { style, Surface } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Surface disabled render={<button type="button" />}>
        Disabled button
      </Surface>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    backgroundColor: 'background.primary',
    display: 'grid',
    padding: '16',
    gridTemplateColumns: 'repeat(auto-fill, minmax(14rem, 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Surface/Disabled.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Surface } from '@tempoxyz/ds'

<Surface>
  <Surface.Header>
    <Surface.Title />
  </Surface.Header>
  <Surface.Description />
  <Surface.Links />
</Surface>
```

## Guidelines

### When to Use

* Group related content into a card, such as a wallet's Balance, an Activity list, or an API key's details.
* Make a whole card pressable when it leads to one place, such as a project card that opens its dashboard.

### When Not to Use

* Use [Alert](/docs/components/alert) for a message about a section, and [Banner](/docs/components/banner) for one about the page.
* Use [Dialog](/docs/components/dialog) or [Popover](/docs/components/popover) for content that opens over the page.
* Use [Stack](/docs/components/stack) or [Inset](/docs/components/inset) to space content without a visible container.
* Use [Frame](/docs/components/frame) inside a surface for a card with a footer of actions.

### Name Each Card

Start a card with a `Surface.Header` that holds a `Surface.Title`. Put a card-level action at the end of the header, such as a `small` `tertiary` [Button](/docs/components/button).

**Do:** Name the card with a `Surface.Title`, and put its action at the end of the header.

```tsx
/**
 * Do example for "Name Each Card" on the Surface page.
 * Name the card with a `Surface.Title`, and put its action at the end of the header.
 * @module
 */
import { Amount, Button, ListGroup, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface size="medium">
        <Surface.Header>
          <Surface.Title>Balances</Surface.Title>
          <Button size="small" variant="tertiary">
            View all
          </Button>
        </Surface.Header>
        <ListGroup dividers={false}>
          <ListGroup.Row>
            <ListGroup.Label>USDC</ListGroup.Label>
            <Amount value="1250.00" />
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>pathUSD</ListGroup.Label>
            <Amount value="80.25" />
          </ListGroup.Row>
        </ListGroup>
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })
}
```

**Don't:** Start a card with its content.

```tsx
/** Don't example for "Name Each Card" on the Surface page. Don't start a card with its content. @module */
import { Amount, ListGroup, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface size="medium">
        <ListGroup dividers={false}>
          <ListGroup.Row>
            <ListGroup.Label>USDC</ListGroup.Label>
            <Amount value="1250.00" />
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>pathUSD</ListGroup.Label>
            <Amount value="80.25" />
          </ListGroup.Row>
        </ListGroup>
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })
}
```

### Match Size to Density

* **Large (24px):** The default, for page cards such as Balances.
* **Medium (16px):** For dashboard tiles, such as TPS.
* **Small (12px):** For compact tiles, such as Block time.

Keep one size across cards that sit side by side.

### Keep Pressable Cards Free of Other Controls

A surface rendered as a link or button is one target, and screen readers announce the whole card as one control.

**Do:** Make the whole card one link with a short title.

```tsx
/**
 * Do example for "Keep Pressable Cards Free of Other Controls" on the Surface page.
 * Make the whole card one link with a short title.
 * @module
 */
import { style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface render={<a href="#" />} size="medium">
        <span {...styles.title()}>Production key</span>
        <span {...styles.meta()}>Created 3 days ago</span>
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    padding: '16',
    width: '16rem !custom',
  })

  export const meta = style({ color: 'content.secondary', display: 'block', typography: 'body.b3' })

  export const title = style({ display: 'block', typography: 'body.b1Strong' })
}
```

**Don't:** Place a button inside a pressable card.

```tsx
/**
 * Don't example for "Keep Pressable Cards Free of Other Controls" on the Surface page.
 * Don't place a button inside a pressable card.
 * @module
 */
import { Button, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface render={<a href="#" />} size="medium">
        <span {...styles.title()}>Production key</span>
        <span {...styles.meta()}>Created 3 days ago</span>
        <Button size="small" {...styles.action()}>
          Revoke key
        </Button>
      </Surface>
    </div>
  )
}

namespace styles {
  export const action = style({ marginBlockStart: '12' })

  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    padding: '16',
    width: '16rem !custom',
  })

  export const meta = style({ color: 'content.secondary', display: 'block', typography: 'body.b3' })

  export const title = style({ display: 'block', typography: 'body.b1Strong' })
}
```

### Don't Nest Surfaces

Divide the content of one surface with [ListGroup](/docs/components/list-group), a [Table](/docs/components/table), or a [Separator](/docs/components/separator). A table placed directly inside a surface bleeds 12px into its padding, so its rows end 12px inside the edges of a large surface and its text stays on the content edge. The surface draws no border around it.

**Do:** Divide one surface with ListGroup.

```tsx
/** Do example for "Don't Nest Surfaces" on the Surface page: divide one surface with ListGroup. @module */
import { Amount, Hex, ListGroup, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface size="medium">
        <ListGroup>
          <ListGroup.Row>
            <ListGroup.Label>Amount</ListGroup.Label>
            <Amount symbol="USDC" value="48.50" />
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Recipient</ListGroup.Label>
            <Hex value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
          </ListGroup.Row>
        </ListGroup>
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })
}
```

**Don't:** Place surfaces inside a surface.

```tsx
/** Don't example for "Don't Nest Surfaces" on the Surface page. Don't place surfaces inside a surface. @module */
import { Amount, Hex, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface size="medium" {...styles.outer()}>
        <Surface size="small" {...styles.row()}>
          <span>Amount</span>
          <Amount symbol="USDC" value="48.50" />
        </Surface>
        <Surface size="small" {...styles.row()}>
          <span>Recipient</span>
          <Hex value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
        </Surface>
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })

  export const outer = style({ display: 'flex', flexDirection: 'column', gap: '8' })

  export const row = style({
    alignItems: 'center',
    backgroundColor: 'container.regular',
    display: 'flex',
    justifyContent: 'space-between',
  })
}
```

## Content

* Write titles as short nouns, such as Balances, Activity, or Routes.
* Keep `Surface.Description` to one or two sentences.
* Use `Surface.Links` for two or three follow-up tasks, written as verbs, such as Make a transfer.

## Accessibility

A surface takes its semantics from the element you render, such as a `section`, a `button`, or a link.

### Semantics

* **Default Element (div):** Carries no role.
* **Surface.Title (h2):** Lets screen reader users find the card by heading.
* **Surface.Description (p):** A plain paragraph under the title.
* **Pressable Cards (button or link):** The whole card becomes one control, named by its text.
* **Disabled (aria-disabled):** Dims the card and drops pointer events. Only a button also stops keyboard activation.

### Keyboard

For a pressable surface rendered as a button or link:

* **Move Focus to the Card (Tab):** Moves focus to the card.
* **Activate a Link or Button (Enter):** Activates a link or button card.
* **Activate a Button (Space):** Activates a button card.

### Your Responsibilities

* **Name Regions (aria-labelledby):** If the card is a distinct region, render a section labelled by its title.
* **Fit the Outline (h2):** Place cards where their title's heading level fits the page outline.
* **Keep Pressable Text Short:** The card's full content becomes its accessible name, so keep its text short.
* **Disabling Link Cards (href):** A link can't be disabled. Remove its `href` when it must not work.

## Related

[Frame](/docs/components/frame)

Use for a header, body, and footer inside a card.

[ListGroup](/docs/components/list-group)

Use for divided content in a card.

[Grid](/docs/components/grid)

Use for laying out several cards.

[Dashboards](/docs/patterns/dashboards)

Covers metric tiles.
