# Spacing, Radius & Shadows

Three token categories describe how much room things take and how they sit on the page, plus one that themes fenced code blocks. All four are plain name-to-value maps, and all four are optional.

## `spacing`

Named layout tokens. Unlike the other categories, a spacing value is a **string of Tailwind classes** rather than a single CSS value — which lets one token carry a whole layout decision, responsive variants included.

```yaml
theme:
  spacing:
    container: 'max-w-7xl mx-auto px-4'
    section: 'py-16 sm:py-20'
    card: 'p-6'
    gap: 'gap-8'
```

Token names are lowercase kebab-case. Reference a token wherever you would write the classes by hand, and a later change to the page rhythm becomes a one-line config edit instead of a find-and-replace across every page.

## `borderRadius`

Named radius tokens as CSS values. Each becomes a `rounded-{name}` utility.

```yaml
theme:
  borderRadius:
    card: '0.75rem'
    button: '0.5rem'
    pill: '9999px'
```

## `shadows`

Named box-shadow tokens as CSS `box-shadow` values. Each becomes a `shadow-{name}` utility.

```yaml
theme:
  shadows:
    card: '0 4px 6px rgba(0, 0, 0, 0.1)'
    elevated: '0 10px 30px rgba(0, 0, 0, 0.2)'
```

:::callout
**Name tokens for their role, not their look.** `shadow-card` and `rounded-card` survive a redesign that changes what a card looks like; `shadow-subtle` and `rounded-8` do not, and leave every usage site to be re-audited by hand.
:::

## `codeBlock`

Selects the syntax-highlighting theme applied to markdown fenced code blocks — on [markdown pages](/en/docs/pages-collections#markdown), in content directories, and in any `text` component rendering markdown.

| Property | Description                                                         |
| -------- | ------------------------------------------------------------------- |
| `theme`  | Name of the highlighting theme, e.g. `github-dark`, `github-light`. |

```yaml
theme:
  codeBlock:
    theme: github-dark
```

This is a single global choice rather than a per-block one, so a documentation site's code samples stay visually consistent regardless of which page they appear on.

## Putting Them Together

Tokens compose the same way handwritten classes do — the point is that the decisions are named and central:

```yaml
theme:
  spacing:
    section: 'py-20'
  borderRadius:
    card: '1rem'
  shadows:
    card: '0 1px 3px rgba(0, 0, 0, 0.08)'
```

```yaml
- type: container
  props: { className: 'py-20' }
  children:
    - { type: card, props: { className: 'rounded-card shadow-card' } }
```

## Related Pages

- [Theme Overview & Colors](/en/docs/theme) — the theme block and color tokens.
- [Typography](/en/docs/theme-typography) — the `fonts` block.
- [Baseline & Dark Mode](/en/docs/theme-dark-mode) — the second palette.
- [Responsive Design](/en/docs/responsive-design) — `breakpoints` and per-breakpoint overrides.
- [Layout Components](/en/docs/layout-components) — the surfaces these tokens style.