Skip to main content
Digitaltableteur

Design system components

Section

Semantic section wrapper with spacing and background tokens.

Status: stable. Group: layout. Markdown version: /design-system/components/section.md

When to use

Section is the page-level band: it owns vertical rhythm (spacing, responsive paddings) and surface (background), while Container inside it owns the horizontal clamp. hero and follow are a pair; the hero band keeps a generous top and tight bottom, and the section right after uses follow to avoid a double gap. inverse flips to the dark surface with matching text tokens. Give sections an id when they are anchor or skip targets.

When not to use

  • Do not nest Sections; bands are siblings; nesting compounds paddings and backgrounds.
  • Do not use Section inside a component or card; it is page architecture, not component padding.
  • Do not use Section inside components or cards; it is page architecture, not component padding.

Look-alikes

  • Card: Do not wrap page sections or whole forms in cards, and never nest cards in cards; that is Section/Stack territory.
  • Center: Do not use Center as a page layout root; that is Container + Section.

Props

Section props
PropTypeDefaultDescriptionRequired
childrenReactNodenoneSection content.Yes
spacing"sm" | "md" | "lg" | "xl" | "none" | "hero" | "follow"mdBlock padding scale.No
background"default" | "muted" | "accent" | "inverse"defaultSurface background token.No
classNamestringnoneSection class names.No
idstringnoneSection id (anchor target).No
spotlightTargetstringnoneOptional stable selector target for host-app guided navigation.No

Variants

  • Available spacings: none, sm, md, lg, xl, hero, follow (default md).
  • Available backgrounds: default, muted, accent, inverse (default default).

Invalid combinations

The contract records no invalid combinations.

Keyboard

The contract records no keyboard interaction.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

Section rules
LevelRuleHow it is checked
MUSTRequired stories produce no axe violations at the configured severity.Automated by npm run test:stories:matrix:ci. WCAG 2.5.8.
MUSTThe accessibility tree (role, name, state) matches the committed snapshot for every required story.Automated by npm run test:stories:matrix:ci. WCAG 1.3.1, 4.1.2.
MUSTThe component remains legible and operable under a real browser forced-colors: active pass.Automated by npm run test:stories:hc.
MUSTA human completed an end-to-end accessibility review of this component.Manual review, last on 2026-11-04.
SHOULDPair spacing="hero" on the page hero with spacing="follow" on the next section; that is what kills the double gap.Not stated in the contract.
SHOULDAlternate background="muted" sparingly to group related content; every-other-band zebra striping reads as noise.Not stated in the contract.
SHOULDPut a Container directly inside; Section handles vertical, Container horizontal.Not stated in the contract.
SHOULDGive anchor/deep-link targets an id, and use spotlightTarget only when the host app needs stable guided-navigation selectors.Not stated in the contract.
SHOULD NOTDo not nest Sections; bands are siblings; nesting compounds paddings and backgrounds.Not stated in the contract.

Install and import

  • Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
  • Import: import { Section } from "@digitaltableteur/react";
  • Entry point: @digitaltableteur/react/layout exports it too.
  • Styles: import @digitaltableteur/react/style.css once at the app boundary.
  • Also available as the custom element <dt-section>; see the custom elements manifest.

Links