Surface Contrast Scoping

Layout primitives accept a surface prop that creates a local contrast scope — semantic tokens remap independently of the page theme. Switch between the four modes below to see how each behaves on light vs dark pages.

Prop	Light page	Dark page	Use case
`dark`	dark tokens	inverts → light	Contrast band against page
`light`	light tokens	inverts → dark	Contrast band against page
`dark-always`	dark tokens	dark tokens	Dark media bg — text stays light
`light-always`	light tokens	light tokens	Light media bg — text stays dark

light pagesurface="dark-always"

Section title

Content inside the surface scope.

dark pagesurface="dark-always"

Section title

Content inside the surface scope.

surface prop — live preview

<Flex direction="column" gap="3" surface="dark-always"
  bgImage="https://images.unsplash.com/photo-1719841602002-1dcc795bed24"
  bgOverlays="dark-50"
  className="rounded-[var(--radius-panel)] p-6">
  <Heading size="sm">Section title</Heading>
  <Text size="xs" color="subtle">Content inside the surface scope.</Text>
  <Flex direction="row" gap="2">
    <Button size="sm" variant="solid" tone="accent">Action</Button>
    <Button size="sm" variant="outline">Cancel</Button>
  </Flex>
</Flex>

The surface prop is on the layout primitives; see Theme System for themes and scoped providers.