Surface

Using Surface Tokens

Surfaces automatically adapt to modes (like light and dark) based on the global settings, making your components responsive to theme changes without extra configuration. Surface tokens can be applied across a range of use cases to fit your design needs. The implementation of surfaces can be broken down into two main areas: Toggling Surfaces and Using Surface Tokens.

---

Toggling Surfaces

Surfaces can be toggled using the <Surface> component or the data-dls-surface attribute, depending on your application setup.

1. Using the Surface Component

Recommended

The <Surface> component provides a streamlined, type-safe way to apply surfaces in React. By setting the variant prop, you can easily specify the desired surface style and apply a background color and text color for children of the <Surface> component. This component automatically applies the correct background color, ensuring that your component is consistent with the design system.

1<Surface className="width-full pad-2 flex" variant="fg-brand">
2  <Component>
3    <NestedComponent />
4  </Component>
5</Surface>

The variant prop supports the following values:

• base: Standard background for large content areas.
• foreground: For elements requiring higher contrast.
• fg-subtle: For subtle contrast elements.
• fg-brand: Brand color emphasis for critical actions.
• fg-brand-alt: An alternative brand color option.

2. Using the Surface Data Attribute

The data-dls-surface data attribute can be added to any element on the page, and will allow any nested DLS components to automatically reflect the token decisions from that surface context.

Unlike the <Surface /> component this will not automatically add the background color and text styling to the wrapper. If this is also desired, you can use the foundation classes color-surface-bg and color-text-regular to reflect the surface background and text colors respectively.

Adding both the data-dls-surface data attribute and foundation classnames will result in the same behaviour as the <Surface /> component.

1<div data-dls-surface="fg-brand" className="color-surface-bg color-text-regular">
2  <Component >
3    <NestedComponent />
4  </Component>
5</div>

Using Surface-Aware Colors

Surface tokens are CSS variables provided by the DLS stylesheet, enabling consistent styling across themes and contexts. While the <Surface> component and data-dls-surface attribute abstract much of this functionality, tokens can still be referenced directly for advanced use cases.

For a complete list of available design tokens, their default values, and usage recommendations, refer to the Design Tokens Implementation page.

---

Global Surface Settings with Helmet

The default surface of applications set by the DLS stylesheet is foreground. In some cases, it might be beneficial to change the default surface at the top-level of your application. To do this, you can set the surface on the html element of your application. In One App modules this is typically done using the Helmet component from react-helmet.

1<Helmet htmlAttributes={{ 'data-dls-surface': 'base' }} />