Spacing & density

import { Button, Column, Surface, Table, Text, TextField, Theme } from '@envsemble/envui';

// Padding is inside the surface; gap is between its children.
<Surface padding={5} render={<Column gap={4} />}>
  <Text render={<h2 />} variant="title">
    Workspace
  </Text>
  <Text>Shared plans and notes for the project.</Text>
</Surface>;

// A desktop productivity app: one compact scale for the whole window, and tighter rows.
<Theme theme="light" scale="compact">
  <TextField label="Title" defaultValue="Quarterly report" />
  <Button>Rename</Button>
  <Table.Root aria-label="Reports" density="sm">
    …
  </Table.Root>
</Theme>;

The words of the figures

• Tight, inside a group: gap 1–3: a heading and its description, a label and its value, short lines that read as one block.
• Roomier, between groups: gap 4–5: the fields of a form, a form and its actions, the groups of a section.
• The most, between sections: gap 6–9: the sections of a page or a settings pane.
• Components bring their own padding: don't pad a Button, field or Card from outside; arrange the space between them.
• Big enough for a finger: nothing to do; controls grow to the touch minimum under a coarse pointer, as Touch says.

Two axes of density

• Scale is the size of the whole system, comfortable or compact: it switches every size token at once. Compact is about 0.8 of comfortable in space and corners, with controls a step shorter and type a step smaller, for desktop productivity apps. Icons keep a 1 rem floor; borders and focus rings keep their widths. system, the default, is compact under pointer: fine and comfortable otherwise; the stylesheet decides, so the server render and the first paint already have it.
• Row density is how tightly Table, Tree and List pack their rows: xs to lg, padding only.

Within a scale, size picks one of three control heights for a deliberate local difference; every control of one size lines up. A control without a size takes its container's --env-control-height, md unless the container sets another, as a table cell does with sm.

Guidelines

• The parent owns gaps, through Row, Column and Grid; each component owns its padding. Text has no outer margins.
• Use relative units; let text wrap and controls grow with their content. In your own grids, minmax(0, 1fr) tracks, min-inline-size: 0 on flex children and max-inline-size: 100% on media.
• Choose Surface for a plain pane and Card for a content surface, and keep their corners.
• Use --env-radius-full where a pill is meant, never 50% or 9999px: one line tall it draws round ends, and an element that grows taller, such as a wrapping button, keeps the same corners. 50% is only for parts that are always square, such as avatars and round icon buttons.
• One scale per app or window, on the root Theme or ThemePreferenceProvider. Leave it at system for a tool used with a mouse and on touch; set comfortable for a website with room to breathe, or compact for a dense tool on touch too. A fixed scale, rendered on the server, goes to the provider and to createThemeBootstrapScript too, so the first paint has it.
• Another scale only at a Theme boundary around a whole region, such as a docked inspector: <Theme {...useTheme()} scale="compact">.
• Rows match: a button beside a field takes its size, and a table's toolbar follows its rows.
• Choose a row density for how people read: sm or xs for scanning, md or lg for reading row by row.
• Read the tokens in application CSS, such as block-size: var(--env-control-height-sm).

Inside a Theme these tokens follow the theme, its scale and the reader's text size. Their values in each scale are under Sizes in each scale, and every value is on the Design tokens page of the Docs.

Corners by what they are

The catalogue shows four kinds of corner; small marks are a fifth, for code. Their tokens:

Sizes in each scale

At the default 16 px root; every value is a token in rem.

Touch

• Under a coarse pointer, @media (pointer: coarse), controls and rows grow to at least 44 px in either scale, and entered text becomes 1 rem so phones don't zoom into a field. A touchscreen laptop used with a mouse keeps the desktop density.
• A control's own box is its hit area, so a press always reaches the control it lands on.
• Grow your own targets the same way, since --env-control-height keeps its value under touch:

.my-target {
  block-size: var(--env-control-height);
}
@media (pointer: coarse) {
  .my-target {
    block-size: max(var(--env-control-height), var(--env-control-height-touch));
  }
}

• A link in text, a breadcrumb and a Switch's track stay smaller, under WCAG 2.5.8's spacing exception; with a mouse every target is at least 24 px.

TypeScript declarations provide the complete public API.