# Layout primitives

Responsive grids, spacing, constraints, container boundaries and native columns.

## Quick start

After the [application setup](/docs/installation/#component-consumption), copy this component into your application. It imports only public packages; the complete live demo later on this page also uses documentation layout helpers.

```tsx
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](/docs/api-core-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.

## Executable example source

```tsx
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></>;
}
```