# Inset

Pads content with spacing tokens.

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

## Overview

Inset pads its content on every side or per axis, and adds no other styles.

## Examples

### Basic

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

export function Demo() {
  return (
    <Inset space="24" {...styles.card()}>
      <Stack gap="12">
        <span>Card content</span>
        <span>Second line</span>
      </Stack>
    </Inset>
  )
}

namespace styles {
  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
}
```

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

### Space

Set `space` to pad every side.

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

export function Demo() {
  return (
    <Inline align="start" gap="16" wrap>
      {(['8', '16', '24', '32'] as const).map((space) => (
        <Inset key={space} space={space} {...styles.card()}>
          space {space}
        </Inset>
      ))}
    </Inline>
  )
}

namespace styles {
  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
}
```

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

### Block

Set `block` or `inline` to override `space` on one axis.

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

export function Demo() {
  return (
    <Inset block="24" inline="32" {...styles.card()}>
      Block 6, inline 8
    </Inset>
  )
}

namespace styles {
  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
}
```

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

## Anatomy

Import the component and assemble its parts.

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

<Inset />
```

## Guidelines

### When to Use

* Pad a region with no padding of its own, such as a custom panel or a band of page content.
* Pad each axis differently, such as `block="16"` and `inline="24"` around a toolbar.

### When Not to Use

* Use [Surface](/docs/components/surface) for a card. Its `size` sets padding and corner radius.
* Use [Container](/docs/components/container) for page gutters that grow with the viewport.
* Use the `gap` of [Stack](/docs/components/stack), [Inline](/docs/components/inline), or [Grid](/docs/components/grid) for space between siblings.

### Don't Double the Padding

[Surface](/docs/components/surface), [Dialog](/docs/components/dialog), and `AppShell.Main` of [AppShell](/docs/components/app-shell) already pad their content.

**Do:** Place content directly in a Surface, so it lines up with the cards beside it.

```tsx
/**
 * Do example for "Don't Double the Padding" on the Inset page.
 * Place content directly in a Surface, so it lines up with the cards beside it.
 * @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 size="medium">
        <Surface.Title>Balance</Surface.Title>
        <Surface.Description>1,250.00 USDC</Surface.Description>
      </Surface>
      <Surface size="medium">
        <Surface.Title>Activity</Surface.Title>
        <Surface.Description>3 payments today</Surface.Description>
      </Surface>
    </div>
  )
}

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

**Don't:** Add an Inset inside a Surface, which moves its content off the shared edge.

```tsx
/**
 * Don't example for "Don't Double the Padding" on the Inset page.
 * Don't add an Inset inside a Surface, which moves its content off the shared edge.
 * @module
 */
import { Inset, 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.Title>Balance</Surface.Title>
        <Surface.Description>1,250.00 USDC</Surface.Description>
      </Surface>
      <Surface size="medium">
        <Inset space="16">
          <Surface.Title>Activity</Surface.Title>
          <Surface.Description>3 payments today</Surface.Description>
        </Inset>
      </Surface>
    </div>
  )
}

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

### Match Surface Padding

Use `16` or `24` for most regions, so they line up with a `medium` or `large` [Surface](/docs/components/surface).

* **Medium (16):** Matches a `medium` Surface, such as a dashboard tile.
* **Large (24):** Matches a `large` Surface, such as a page card.

## Accessibility

An inset adds padding only. It has no role, name, or keyboard behavior.

### Semantics

* **Default Element (div):** Has no role. Screen readers pass over it.
* **Semantic Element (render):** Render a section or aside when needed, such as `render= {<section aria-labelledby="…" />}`.

### Your Responsibilities

Keep large inline padding off narrow viewports, so content [reflows](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) at 320px without horizontal scrolling.

## Related

[Surface](/docs/components/surface)

Use for padded cards.

[Stack](/docs/components/stack)

Use for space between siblings.

[Layout](/docs/foundations/layout)

Covers the spacing scale.
