# Layout

Page structure rules for Amin Rayan. Every marketing page, blog surface, and product block must share the same content column, gutters, and vertical rhythm.

## Principles

1. One content width for the whole site.
2. Full-bleed backgrounds are allowed; content is never full-bleed unless intentionally edge-to-edge media.
3. Section vertical rhythm comes from `layout.sectionY`—not one-off `py-*` values.
4. Decorative layers never participate in document flow or cause horizontal overflow.
5. The fixed header defines safe top offsets and scroll margins.

## Canonical tokens

Defined in `lib/layout.ts`:

| Token | Class / value | Use |
| --- | --- | --- |
| `layout.gutter` | `px-6` (24px) | Horizontal padding |
| `layout.maxWidth` | `max-w-[76.8rem]` (1228.8px) | Content cap |
| `layout.container` | `mx-auto w-full max-w-[76.8rem] px-6` | Standard shell |
| `layout.sectionY` | `py-16 md:py-20` | Section vertical padding (adjacent gap = 8rem / md:10rem) |
| `layout.sectionTopWithHeader` | `pt-28 pb-16 md:pt-32 md:pb-20` | First section under fixed header |
| `layout.scrollMargin` | `scroll-mt-24` | In-page anchors |

Component wrapper: `<Container>` from `@/components/container`.

## Section anatomy

```tsx
<section className={cn("section-shell bg-section-canvas", layout.sectionY)}>
  <div className="section-decor" aria-hidden>
    {/* optional absolute glow / wash — never in flow */}
  </div>
  <Container className="section-content">
    {/* real content */}
  </Container>
</section>
```

Utility classes (from `app/globals.css`):

| Class | Role |
| --- | --- |
| `.section-shell` | `relative isolation-isolate overflow-x-clip` |
| `.section-decor` | Absolute decorative layer, `pointer-events-none`, `z-0` |
| `.section-content` | Content above decor, `z-1` |

## Alignment rules

- Left and right edges of text/CTA columns must align with header content and footer content (same `Container`).
- Do not nest another `max-w-*` shell around an entire section. Inner measures (`max-w-xl`, `max-w-2xl`, `max-w-3xl`) are allowed only on **text blocks** for readability.
- Grids live **inside** `Container`. Never place a grid that escapes the container unless it is intentionally full-bleed media.

## Safe areas

- Header uses `pt-[env(safe-area-inset-top,0px)]` for notched devices.
- First content under the fixed header: use `layout.sectionTopWithHeader` or explicit `pt-24 md:pt-36` (hero) so titles are not obscured.
- Anchor targets (`id="…"`) must include `layout.scrollMargin` (`scroll-mt-24`).

## Overflow rules

- `html` and `body` use `overflow-x: clip`.
- Sections use `section-shell` / `overflow-x: clip` so glows cannot create horizontal scroll.
- Never use `position: fixed` decorative blobs for section atmosphere—keep them inside `.section-decor`.
- Prefer `transform` / absolute positioning for decorations; do not widen the document with large negative margins without clipping.

## Forbidden patterns

```tsx
// ❌ Second container width
<div className="mx-auto max-w-5xl px-4">…

// ❌ Section without shared rhythm
<section className="py-12 px-8">…

// ❌ Full-bleed text without Container
<section className="w-full px-4">
  <h2>…</h2>
</section>

// ✅ Correct
<section className={cn("section-shell bg-section-muted", layout.sectionY)}>
  <Container>
    <h2 className={type.h2}>…</h2>
  </Container>
</section>
```

## Related docs

- [container.md](./container.md)
- [grid.md](./grid.md)
- [sections.md](./sections.md)
- [responsive.md](./responsive.md)