Layout System

The Layout Philosophy

Our layout primitives provide consistent margins, padding, and alignment properties out of the box. To maintain visual parity and clean theme scaling, avoid using ad-hoc negative margins or custom padding sizes.

Rule of alignment: Never use margin utility classes for component-to-component spacing. Always structure components inside a layout wrapper and configure spacing via the parent container's gap properties.

Core Primitives

BoxGeneric Container

The fundamental utility node. Supports custom padding, borders, background styles, and positioning offsets. Useful for grouping block contents.

FlexFlexible Columns/Rows

Flexible layouts supporting wrapping, direction toggles, and item spacing gaps. Ideal for items alignment and dynamic layouts.

Grid2D Grid System

A standard, fixed column layout system. Map layouts across grid spaces with structured token gaps ranging from 0px to 48px.

ContainerMax-Width Wrapper

Sets responsive maximum widths for main page elements, preventing visual stretching on ultra-wide screens.

Example Usage

Responsive Grid & Card Layout

Interactive Card

Content descriptions and metadata display here cleanly within the card layout.

Settings Block

Configure your workspace preferences and notifications.

import { Card, Button } from "@shavin/ui";

export default function LayoutDemo() {
  return (
    <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
      <Card padding="md" className="flex flex-col gap-3">
        <span className="font-semibold text-fg text-sm">Interactive Card</span>
        <p className="text-xs text-fg-muted">Content descriptions and metadata display here cleanly within the card layout.</p>
        <div className="flex gap-2">
          <Button size="sm" variant="solid">Explore</Button>
          <Button size="sm" variant="outline">Learn More</Button>
        </div>
      </Card>
      <Card padding="md" className="flex flex-col gap-3">
        <span className="font-semibold text-fg text-sm">Settings Block</span>
        <p className="text-xs text-fg-muted">Configure your workspace preferences and notifications.</p>
        <div className="flex gap-2">
          <Button size="sm" variant="soft">Manage</Button>
        </div>
      </Card>
    </div>
  );
}