Surfaces
A surface sets the color scheme for everything inside it. Components read color roles (text.primary, icon.secondary, base.backgroundHover) and never check the scheme themselves. A scope changes what the roles resolve to, so the same variant works on light and on dark.
Dark surfaces
Set data-theme="dark" on the element that paints the dark material. Give it bg="dark.surface", and boxShadow="darkRaised" when it floats. Inside it, use the usual variants: tertiary for controls.
Dark means now. Use the dark material for the object in hand, such as a floating toolbar for a selection. Never use it for page structure.
Component pages show their dark look in a dark preview, for example Button and Icon button.
Light islands
Set data-theme="light" on content that must keep its light colors inside a dark surface, such as a customer's ad or email. It restores the light roles for its subtree.
Roles with dark values
These roles take a dark value inside a dark scope. Primitives such as white and gray.300 never change, so only reach for a role when a color must follow the scheme.
| Role | Dark value | Light | Dark |
|---|---|---|---|
text.primary | text.white | ||
text.secondary | dark.fg2 | ||
text.tertiary | dark.fg2 | ||
text.disabled | dark.fg2 | ||
icon.primary | icon.white | ||
icon.secondary | dark.fg | ||
icon.tertiary | dark.fg2 | ||
icon.disabled | dark.fg2 | ||
base.border | dark.divider | ||
base.divider | dark.divider | ||
base.backgroundHover | dark.hover | ||
base.backgroundPressed | dark.pressed |
Focus
Inside a dark scope, the focus rings drop the white gap. outline turns to a 1px dark.focus ring with an 8px glow, outlineInset to a 1px inset ring, and outlineRed and outlineYellow to a 1px ring in their color.
Coverage
A component looks right on dark when every role it reads has a dark value. Today that covers tertiary and secondary buttons, icon buttons, menu triggers and split buttons, dividers, and the focus ring. Other components inside a dark scope can mix light and dark colors, so check them in a dark preview first.
Menus, popovers and tooltips render in a portal outside the scope, so they stay light.
Form surfaces
The surface prop on Box, Row and Column is a separate system. It tells form fields whether they sit on white or on grey, so they pick a resting fill that stands out. It does not make a subtree dark. See Form elements.