@vinyasa/layout

13 structural layout primitives: Box, Flex, Stack, Inline, Grid, Container, Surface, Divider, ScrollArea, Portal, AspectRatio, Center, Spacer.

Installation

pnpm add @vinyasa/layout @vinyasa/tokens react react-dom

@vinyasa/tokens is a peer dependency: most of these primitives reference the shared design-token contract, and rendering them requires a VinyasaProvider (from @vinyasa/tokens) somewhere above them in the tree. See @vinyasa/tokens's README.

This package has no root export — every component is subpath-only (import Box from '@vinyasa/layout/box', never from '@vinyasa/layout'). A root barrel re-exporting all 13 components would let a bundler tree-shake the unused JS down to just the ones you import, but the CSS side-effect imports the others carry are not eligible for the same tree-shaking (confirmed empirically with both esbuild and Rollup on this monorepo's other packages). Removing the root entry entirely makes that the only possible outcome, not something that depends on your bundler being clever enough to shake it out.

Spacing

Every component in this package except Portal (which renders no wrapper element of its own) and Spacer (which has no properties left to space) accepts the same set of margin/padding shorthand props, resolved against @vinyasa/tokens's space1–space6 scale — the same scale Flex/Grid's gap already use:

| Prop | CSS applied | Prop | CSS applied | | ---- | --------------- | ---- | ---------------- | | m | margin | p | padding | | mx | margin-inline | px | padding-inline | | my | margin-block | py | padding-block | | mt | margin-top | pt | padding-top | | mr | margin-right | pr | padding-right | | mb | margin-bottom | pb | padding-bottom | | ml | margin-left | pl | padding-left |

Each accepts 1–6, mapping directly to a token:

| Scale | Token | Value | | ----- | -------- | ----------------- | | 1 | space1 | 0.25rem (4px) | | 2 | space2 | 0.5rem (8px) | | 3 | space3 | 0.625rem (10px) | | 4 | space4 | 1rem (16px) | | 5 | space5 | 1.25rem (20px) | | 6 | space6 | 1.5rem (24px) |

Values are scale-only — there's no raw-string escape hatch for margin/padding, so spacing always traces back to a token. General → axis → specific-side precedence applies, same as CSS shorthand: mx/my override m; mt/mr/mb/ml override both. A consumer-supplied style prop always wins over any spacing prop.

import Surface from '@vinyasa/layout/surface';
import Box from '@vinyasa/layout/box';

<Surface p={4} m={2}>...</Surface>
<Box px={4} py={2}>...</Box>

Usage

Box

A minimal polymorphic wrapper — an as prop, native props, and the spacing props above. Every other primitive below builds its own small set of curated, token-aware props on top of this same as pattern.

import Box from '@vinyasa/layout/box';

<Box as="section" p={4} mb={6}>
	content
</Box>;

Flex, Stack, Inline, Center

Flex is the one real recipe (direction, align, justify, wrap, gap); Stack, Inline, and Center are thin, fixed-prop wrappers over it — not duplicated CSS.

import Flex from '@vinyasa/layout/flex';
import Stack from '@vinyasa/layout/stack';
import Inline from '@vinyasa/layout/inline';
import Center from '@vinyasa/layout/center';

<Flex direction="row" align="center" justify="between" gap={4} px={4} py={2}>...</Flex>
<Stack gap={3} p={4}>...</Stack>    {/* Flex direction="column" */}
<Inline gap={2} mx={4}>...</Inline> {/* Flex direction="row" */}
<Center p={6}>...</Center>          {/* Flex align/justify="center" */}

Grid

columns/rows each take a number (repeat(N, 1fr)) or a raw grid-template-* string for advanced layouts; flow maps to grid-auto-flow; align/justify use the same value sets as Flex.

import Grid from '@vinyasa/layout/grid';

<Grid columns={3} rows={2} gap={4} align="center" justify="between" flow="row-dense" p={4}>
	...
</Grid>
<Grid columns="1fr 2fr" gap={4}>...</Grid>

Container

Centers content and snaps its max-width at each breakpoint (640/768/1024/1280px) as the viewport grows — the same mechanism Tailwind's own .container utility uses. maxWidth is an escape hatch for a narrower container regardless of viewport (e.g. a login form).

import Container from '@vinyasa/layout/container';

<Container my={6}>...</Container>
<Container maxWidth="20rem">...</Container>

Surface

import Surface from '@vinyasa/layout/surface';

<Surface p={4} radius="md" elevation="raised" m={2}>
	...
</Surface>;

radius is the same sm/md/full scale @vinyasa/button's radius prop uses; elevation is raised/overlay/modal.

Divider

import Divider from '@vinyasa/layout/divider';

<Divider />                                  {/* <hr>, horizontal */}
<Divider orientation="vertical" />           {/* role="separator" div */}
<Divider orientation="vertical" decorative /> {/* aria-hidden, purely visual */}
<Divider my={4} />                           {/* spacing props apply here too */}

ScrollArea

A fully custom, cross-browser-consistent scrollbar (thumb/track/drag), built by styling @radix-ui/react-scroll-area with our own tokens rather than hand-rolling pointer-drag math and accessibility. maxHeight/maxWidth are applied as real height/width (not max-height/max-width) since Radix's internal viewport needs an explicit bound to resolve its own 100% sizing against.

import ScrollArea from '@vinyasa/layout/scroll-area';

<ScrollArea maxHeight="20rem">{longContent}</ScrollArea>
<ScrollArea maxHeight="20rem" maxWidth="24rem">{content}</ScrollArea>

Portal

An SSR-safe wrapper around createPortal (mounts only on the client, no hydration mismatch). No spacing props — it renders no wrapper element of its own.

import Portal from '@vinyasa/layout/portal';

<Portal>{children}</Portal>                    {/* defaults to document.body */}
<Portal container={someElement}>{children}</Portal>

AspectRatio

import AspectRatio from '@vinyasa/layout/aspect-ratio';

<AspectRatio ratio={16 / 9} m={4}>
	{video}
</AspectRatio>;

ratio is an arbitrary runtime number, not a themed/discrete design value — this is why it's a plain inline aspect-ratio style rather than a recipe() variant, unlike everything else in this package.

Spacer

A flexible filler (flex: 1 0 0%) for pushing content apart inside Flex/Stack/Inline. No props beyond native ones — a spacer being "spaceable" itself doesn't add anything.

import Inline from '@vinyasa/layout/inline';
import Spacer from '@vinyasa/layout/spacer';

<Inline>
	<span>Left</span>
	<Spacer />
	<span>Right</span>
</Inline>;

Subpath imports

Every component is imported by its own subpath (e.g. @vinyasa/layout/surface) — there is no root @vinyasa/layout entry, so import { X } from '@vinyasa/layout' fails to resolve. See "This package has no root export" above for why.

Development

From the repository root:

pnpm --filter @vinyasa/layout build
pnpm --filter @vinyasa/layout test
pnpm --filter @vinyasa/layout lint
pnpm storybook   # Layout/*