Layout primitives

Quick start

After the application setup, copy this component into your application. It imports only public packages; the complete live demo later on this page also uses documentation layout helpers.

import { Container, Grid, Stack, Inline, AspectRatio } from '@fayegram-ai/faye-ui/layout/layout';
import { Card, CardBody } from '@fayegram-ai/faye-ui/core/surface';

export function ResponsiveCards() {
  return <Container width="content">
    <Stack gap="6">
      <Inline wrap rowGap="3" columnGap="4"><span>Places</span><span>Collections</span></Inline>
      <Grid columns={{ base: 1, md: 2, lg: 3 }} gap="4">
        {['Coast', 'Gardens', 'City'].map(name => <Card key={name}>
          <AspectRatio ratio={16 / 9}><div style={{ height: '100%', background: 'var(--faye-ui-color-accent-soft)' }} /></AspectRatio>
          <CardBody>{name}</CardBody>
        </Card>)}
      </Grid>
    </Stack>
  </Container>;
}

API reference: Surface.

Usage contract

The responsive class vocabulary is finite and validated. GridItem adds span, start and order. Use logical direction rather than left/right layout assumptions. CSS column masonry has column-major reading order; do not use it when row-major order is essential.

Customization

Use semantic tokens for visual changes, public component parts for structural customization, and explicit props for instance behavior. The surrounding site lets you compare light and dark, different brands and density.

Source and verification

The examples below import actual public package entries. Full source is downloadable. Source coverage does not establish keyboard, hydration or browser compatibility; those require the application test suite.

Live examples

Try the controls below, then read or copy the complete example to adapt it for your application.

Responsive twelve-column grid

8 / 12, full width on narrow screens

4 / 12

Full row

Stacks, inline groups and constrained width

Leading

Trailing

Research

Design

Engineering

Operations

Centered without a custom margin rule

Responsive split and query boundary

Context

The containing element is the responsive boundary.

3:1 content region

Controlled half-gutter bleed

Column masonry

Item 1

Variable content height.

Item 2

Variable content height.

Item 3

Variable content height.

Item 4

Variable content height.

Item 5

Variable content height.

Item 6

Variable content height.

CSS columns preserve column-major reading order. This is not a row-packed JavaScript masonry engine.

Read the complete example

import { Stack, Inline, Cluster, Grid, Container, Center, Spacer, Split, AspectRatio, Bleed, QueryContainer } from '@fayegram-ai/faye-ui/layout/layout';
import { GridItem } from '@fayegram-ai/faye-ui/layout/grid-item';
import { Masonry } from '@fayegram-ai/faye-ui/layout/masonry';
import { Text } from '@fayegram-ai/faye-ui/core/text';
import { Section } from '../example';
const Cell = ({ children }: {
    children: React.ReactNode;
}) => <div className="docs-layout-cell">{children}</div>;
export default function Layout() {
    return <><Section title="Responsive twelve-column grid"><Grid columns={{ base: 1, md: 12 }} gap={{ base: '2', md: '4' }}><GridItem span={{ base: 'full', md: 8 }}><Cell>8 / 12, full width on narrow screens</Cell></GridItem><GridItem span={{ base: 'full', md: 4 }}><Cell>4 / 12</Cell></GridItem><GridItem span="full"><Cell>Full row</Cell></GridItem></Grid></Section><Section title="Stacks, inline groups and constrained width"><Container width="reading"><Stack gap="4"><Inline align="center" wrap><Cell>Leading</Cell><Spacer /><Cell>Trailing</Cell></Inline><Cluster gap="2" rowGap="3" columnGap={{ base: '1', md: '2' }}>{['Research', 'Design', 'Engineering', 'Operations'].map(x => <Cell key={x}>{x}</Cell>)}</Cluster><Center p="4"><Text>Centered without a custom margin rule</Text></Center></Stack></Container></Section><Section title="Responsive split and query boundary"><Split ratio="sidebar-start" collapseAt="md"><Cell>Context</Cell><QueryContainer name="example"><Cell>The containing element is the responsive boundary.</Cell></QueryContainer></Split><AspectRatio ratio={3}><Center className="docs-layout-cell" style={{ height: '100%' }}>3:1 content region</Center></AspectRatio><div style={{ paddingInline: '1rem' }}><Bleed amount="2"><Cell>Controlled half-gutter bleed</Cell></Bleed></div></Section><Section title="Column masonry" note="CSS columns preserve column-major reading order. This is not a row-packed JavaScript masonry engine."><Masonry columns={{ base: 1, sm: 2, lg: 3 }} gap="4">{[2, 4, 3, 5, 2, 4].map((n, i) => <Cell key={i}><p>Item {i + 1}</p>{Array.from({ length: n }, (_, j) => <p key={j}>Variable content height.</p>)}</Cell>)}</Masonry></Section></>;
}