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, 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 propsCopy Anchor Link

Gap and padding props accept the same step names the theme defines (s, m, l, 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 a settings section: heading at the top, two-column grid of cards below with comfortable outer padding and tighter gaps between cards. Match the app's spacing rhythm — don't hand-roll gap CSS.

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

<Stack rowGap="m" hPadding="l" vPadding="l">
  <Title size="3" render={<h2 />}>
    Section
  </Title>
  <Grid columns={2} columnGap="m" rowGap="l">
    <Surface color={1} radius="m" hPadding="m" vPadding="m">
      <Text>Card A</Text>
    </Surface>
    <Surface color={1} radius="m" hPadding="m" vPadding="m">
      <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-2xl);
}

Beyond the largest stepCopy Anchor Link

When the top of the scale still feels tight (hero band, tall marketing gap), extend the brand sheet with one more --space-* step instead of a raw pixel length:

:root {
  --space-6xl: 8rem;
}

Then reference it only in your CSS:

.hero {
  padding-block: var(--space-6xl);
}

ViraUI layout props (rowGap, hPadding, and the rest) stay on the built-in scale names. A brand-only step is not wired into those props — agents and components will not pick it up. Keep custom steps for custom CSS; retune existing --space-* values (see Tune below) when the whole product needs roomier rhythm.

For a one-off multiple of an existing step, calc() works the same way and still tracks the theme:

.hero {
  padding-block: calc(var(--space-5xl) * 2);
}

TuneCopy Anchor Link

App Studio in ViraUI Pro is the easiest path when you want to reshape rhythm: tweak --space-* on a live ViraUI canvas, share the theme with the team, and export CSS that already matches the contract. Drop the export into the app as a custom theme. Step names and layout props stay stable; only the resolved lengths change.

Without Studio, paste a prompt into your agent or edit --space-* on a custom theme sheet (or switch a built-in preset). Every rowGap, hPadding, and var(--space-…) reference picks up the new scale without chasing individual screens.

Tighten the theme spacing scale for a denser, more compact feel. Keep the relative rhythm between small, medium, and large gaps.