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;positiveis 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 nosurface; wrap the region inSurfaceProvider.- 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 setcolor-scheme: darkon 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.