Backgrounds and groups

Backgrounds separate a section's content layout from its visual surface. Use a standard background for a contained panel and a full background for a page-wide transition.

<script>
  import { Section, SectionSurfaceGroup } from '@page-sections/svelte';
</script>

<SectionSurfaceGroup>
  <Section
    section={{
      id: 'first',
      title: 'First',
      headline: 'A shared surface',
      background: { color: 'standard' }
    }}
  >
    <p>These adjacent sections share their outer corner treatment.</p>
  </Section>
  <Section section={{ id: 'second', title: 'Second', background: { color: 'muted' } }}>
    <p>A different opaque color still belongs to the same surface group.</p>
  </Section>
</SectionSurfaceGroup>

Colors: transparent, standard, muted, transparentToStandard, transparentToMuted, standardToTransparent, standardToMuted, mutedToTransparent, mutedToStandard.

Gradients run top to bottom and require full size. With standard size, normalization uses the gradient's end color and returns a diagnostic. Section uses that normalized color but does not log the diagnostic itself. Full surfaces expand to 100vw without changing the content width and have square corners. This assumes centered content; an off-center embedded section should use standard size.

import { normalizeSectionBackground } from '@page-sections/core';
const full = normalizeSectionBackground({ color: 'standardToMuted', size: 'full' });
const contained = normalizeSectionBackground({ color: 'standardToMuted' });
console.log(full.gradient); // true
console.log(contained.color, contained.diagnostic?.code); // muted, gradient-requires-full-background

Props are optional children: Snippet and pageKind: PageKind (content/detail, inherited by default). A detail context forces standard backgrounds, so gradients fall back to their end color. ContentPage already supplies a group; use an explicit group for standalone or nested compositions. The wrapper uses display: contents, so it adds no box or landmark.

Adjacent standard-size, nontransparent surfaces share corners even if their colors differ. Transparent or full-size surfaces separate groups. Outer corners appear from viewport XL (1600px), using --ps-radius; detail groups return to square corners at 3XL (2300px); ungrouped Section surfaces default to square corners. Group membership concerns registered sections, not arbitrary divs inserted between them.

Rules are emitted after registration during SSR, and nested groups have isolated scopes. Client updates and keyed DOM moves are reconciled by the registry/MutationObserver. The core SectionSurfaceRegistry exposes equivalent ordering and corner data for another renderer; see Core API.

Related: Section and ContentGrid, Themes and Styling.

Standard-width sections with standard or muted backgrounds receive a subtle shadow, whether or not the page has sidebars. Joined surfaces clip internal shadow edges. Transparent and full-width backgrounds do not receive this shadow. Full backgrounds still paint across the viewport when a sidebar makes the content column asymmetric.