Spacing and sizing

The 4px spacing scale, the control heights that change with density, and the widths pages and panels keep to.

buttery's spacing is a scale of steps on a 4px grid, from 0.5 (2px) to 32 (128px). Use a step for every gap and padding, and the space around things stays in proportion from one screen to the next.

Spacing steps

Layout props take a step, not a length: gap={3} is 12px and pad={4} is 16px. Half steps are numbers too, such as gap={1.5} for 6px, and any step can also be written as a string, such as padX="0.5".

import type { ReactElement } from "react";
import { Inline, Stack, Surface, Text } from "@butteryui/core";
import { Button } from "@butteryui/react";

export function PayoutCard(): ReactElement {
  return (
    <Surface level="card" pad={5}>
      <Stack gap={3}>
        <Text variant="title-sm">Next payout</Text>
        <Text variant="body-sm" tone="secondary">
          $1,280.40 arrives on Friday.
        </Text>
        <Inline gap={2}>
          <Button size="sm">View payouts</Button>
        </Inline>
      </Stack>
    </Surface>
  );
}

Every step, with its variable and its length:

In CSS the steps are variables, --bt-space-<step>, with an underscore for a half step: var(--bt-space-0_5).

.toolbar {
  gap: var(--bt-space-2);
}

.toolbar {
  gap: 10px;
}

Control heights

Every control is one of a few heights, so buttons, fields and segmented controls line up in a row. Each height has a comfortable value and a compact one, and ButteryProvider's density picks between them for the whole app.

Components take their height from these tokens on their own. In your own CSS, read them as var(--bt-h-control) and the like.

Widths

Fixed widths for the parts that have one, such as the sidebar, a dialog or a page's content. Anything else takes its width from its container.

--bt-w-shell-max

1380px

--bt-w-inspector

340px

--bt-w-sidebar

240px

--bt-w-sidebar-rail

56px

--bt-w-app-page

1280px

--bt-w-app-page-md

960px

--bt-w-app-page-sm

820px

--bt-w-aside

320px

--bt-w-search

360px

--bt-w-search-open

600px

--bt-w-side-panel

360px

--bt-w-side-panel-wide

560px

--bt-w-dialog

400px

--bt-w-auth

360px

--bt-w-dialog-md

560px

--bt-w-dialog-lg

880px

--bt-w-menu-min

200px

--bt-w-row-control

160px

--bt-w-page

1200px

--bt-w-prose

720px

--bt-bento-row

320px

--bt-nav-panel-min

200px

--bt-inset-titlebar

84px

--bt-focus-width

2px

--bt-focus-offset

2px

--bt-icon-sm

16px

--bt-icon-md

20px

--bt-blur-scrim

10px