Skip to the content

Surface Inversion

SurfaceProvider declares that a subtree sits on a negative surface — a dark band on a light page, or the reverse. Styled code inside it that reads the Foundation or Semantic layers resolves to the opposite polarity, so the band's own styles need no if (dark) branch.
Theming

The rule

  • Wrap the region in <SurfaceProvider surface="negative"> from @apollion-dsi/core/themes/surface; positive is the default and a no-op.
  • Inside it, read theme.foundation.* in your styled code: bg.paper, text.primary, edge.border.
  • Invert regions — hero sections, dark footers, toolbars over images — not single elements.

How it works

A negative surface carries the opposite polarity's surface ladder: in light mode the subtree gets the dark ladder (dark paper, light ink), in dark mode the light one. The engine derives it from the same seeds and rebuilds theme.semantic and theme.foundation for the subtree. The structural palette (theme.colors) and spacing stay unchanged, and so does everything that resolves through them: token props such as bgColor and color, and the built-in component styles.

import styled from 'styled-components';
import { SurfaceProvider } from '@apollion-dsi/core/themes/surface';

const Band = styled.section`
  background: ${({ theme }) => theme.foundation.bg.paper};
  color: ${({ theme }) => theme.foundation.text.primary};
  border-top: 1px solid ${({ theme }) => theme.foundation.edge.border};
`;

<SurfaceProvider surface="negative">
  <Band>Dark band on a light page</Band>
</SurfaceProvider>;

ApollionProvider takes the same surface prop for the whole application. Outside React, invertForSurface(theme, 'negative') returns the inverted theme.

Pitfalls

  • <Flex surface="negative"> → layout containers take no surface; wrap the region in SurfaceProvider.
  • Expecting <Paper bgColor="surface.paper"> to flip inside the provider → token props resolve through the unchanged structural palette. For a dark band made of components, nest <ApollionProvider mode="dark" syncDocument={false}> and set color-scheme: dark on the band, as the Dark Mode demo does.
  • A literal color in the band's styles → read Foundation so the ink pairs with the ground.

See also