Spacing

Spacing on a theme is a named step scale compiled to --space-* custom properties. Layout components — Stack, Grid, Surface, and similar hosts — read those names through token props (rowGap, hPadding, columnGap, and the rest) so you compose rhythm in JSX instead of re-implementing flex gap and padding in CSS. When the brand needs a denser or roomier UI, you retune the scale on the theme sheet; every prop and every var(--space-…) reference picks up the new lengths without chasing individual screens.

Compose with layout props

Gap and padding props accept the same step names the theme defines (small, medium, large, and so on — check the active theme or @viraui/foundation specs for the live set). Paste a layout prompt into your agent when you are building or reshaping a section.

Build this settings block with Stack and Grid. Use token gap and padding props only — no custom spacing CSS. Outer Stack: rowGap medium, hPadding and vPadding large. Inner grid: two columns, columnGap medium, rowGap large. Each card is a Surface with color 1, radius medium, hPadding and vPadding medium.

import { Grid, Stack, Surface, Text, Title } from '@viraui/react';

<Stack rowGap="medium" hPadding="large" vPadding="large">
  <Title size="3" render={<h2 />}>
    Section
  </Title>
  <Grid columns={2} columnGap="medium" rowGap="large">
    <Surface color={1} radius="medium" hPadding="medium" vPadding="medium">
      <Text>Card A</Text>
    </Surface>
    <Surface color={1} radius="medium" hPadding="medium" vPadding="medium">
      <Text>Card B</Text>
    </Surface>
  </Grid>
</Stack>

Reach for raw spacing CSS only when layout props cannot express the distance — scroll offsets under sticky chrome, absolute insets, third-party wrappers, and similar one-offs. Even then, reference var(--space-…) so a theme edit still flows through.

.section-heading {
  scroll-margin-block-start: var(--space-2x-large);
}

Retune the scale

Edit --space-* on a custom theme or switch a built-in preset. Step names and layout props stay stable — only the resolved lengths change. App Studio gives you a live canvas and an export-ready theme file when you want to explore rhythm visually.

Tighten the space scale for a denser brand. Keep step names and relative proportions; snap every length to whole (even) pixels — no half-pixels.

Open up medium through wide for a roomier product UI. Preserve the scale's progression rules and proportions; avoid half-pixel values.