aragrp/docs/design-system/layout.md

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

<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

// ❌ 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
• grid.md
• sections.md
• responsive.md