aragrp/docs/design-system/sections.md

Sections

Every major page band is a section with shared shell, rhythm, and background language.

Required pattern

import { Container } from "@/components/container";
import { layout } from "@/lib/layout";
import { type, typeSpacing } from "@/lib/typography";
import { cn } from "@/lib/utils";

<section
  id="services"
  className={cn("section-shell bg-section-canvas", layout.sectionY, layout.scrollMargin)}
>
  <div className="section-decor" aria-hidden>
    {/* optional ambient glow */}
  </div>
  <Container className="section-content">
    <div className={cn("mx-auto max-w-2xl text-center", typeSpacing.sectionStack)}>
      <p className={type.eyebrow}>…</p>
      <h2 className={type.h2}>…</h2>
      <p className={type["section-intro"]}>…</p>
    </div>
    {/* section body */}
  </Container>
</section>

One job per section

• One purpose, one headline, usually one supporting sentence.
• Do not combine unrelated marketing goals in a single band.
• Secondary actions belong in the CTA group, not as parallel headline systems.

Background variants

Utility	Intent
bg-section-canvas	Default continuous wash (subtle primary tint)
bg-section-muted	Soft muted band (replaces hard gray patches)
bg-gradient-hero	Hero atmosphere
bg-gradient-featured	Featured / highlight band
bg-gradient-cta	Strong brand CTA panel
bg-background	Flat canvas when wash is unnecessary

Alternate canvas ↔ muted between adjacent sections to create rhythm without hard blocks.

Vertical rhythm

• Use layout.sectionY (py-16 md:py-20) so every block-to-block gap is the same (8rem / md:10rem).
• First section under header: layout.sectionTopWithHeader (homepage hero uses this too).
• Anchors: always add layout.scrollMargin.

Intro block

Prefer centered or start-aligned intro using typeSpacing.sectionStack:

• Eyebrow → Heading → Section intro
• Constrain measure with max-w-2xl / max-w-3xl on the intro only

Decorative layers

<div className="section-decor" aria-hidden>
  <div className="absolute start-1/2 top-0 size-[min(32rem,80vw)] -translate-x-1/2 rounded-full bg-glow-primary" />
</div>

Rules:

• Must sit in .section-decor.
• pointer-events-none, no layout participation.
• Never position: fixed for section atmosphere.
• Opacity kept low (see gradients.md).

Motion

Wrap section bodies with MotionReveal / MotionRevealItem for scroll entrance. Keep stagger ≤ ~8 children.

Forbidden

• Random py-12 / py-24 section padding.
• Hard bg-gray-100 patches disconnected from bg-section-*.
• Multiple competing H2s in one section.

Related

• layout.md
• gradients.md
• footer.md