Themes

Usage guidance

Theming is built around the use of CSS variables and as a result switching between themes will traditionally not trigger a rerender of an app/components. This also allows them to be easily overridden in the rare cases that warrant so.

Additionally this means that parent or wrapper apps/components can naturally impact the styling of children, meaning that you may have to reset your local theme if this is undesirable.

Themes in Waffles consists of two main features—theme tokens and theme styles.

Theme styles can be applied either globally to an entire app or locally to a component/group of components. Waffles provides serialized style objects for both themes, accessible as lightThemeStyle and darkThemeStyle. These can be applied like ordinary Emotion CSS, via the style or css props. Waffles' components are styled with the light theme by default and do not require you to set the base theme if you do not wish to support additional themes in your app. See the examples below for more information.

Theme tokens can be used to apply themed colors to custom components. This will enable support for theme styling in these components, just like Waffles' components.

Best practices

Helpers

Most color-based Waffles' Helpers will also work for the theme tokens for advanced colors adjustments. There are however a few exceptions to note:

• hexToRgba - will only work properly in non-SSR apps. For those apps that are server-side rendered, the value returned will instead be the fallback value
• readableHexColor - in most cases, the need for this helper is replaced by our theme.[accent-color].textOnColor property

In addition, there are also some theme-specific helpers that can be of help when using the theme tokens:

• isCssVar - useful for checking if the value is a CSS variable
• isCssVarFunc - useful for checking if the value is a CSS variable function (e.g. our theme tokens)
• valueFromCssVar - obtains the current value of the CSS variable, if it's defined
• cssVarFromCssVarFunc - extracts the CSS variable from a CSS variable function
• cssVarFuncFallback - extracts the fallback value of a CSS variable function

Common tokens

Common tokens are the values most frequently used across both components and other apps. They each have a specific purpose and should be used accordingly.

Always favor them over the other less-specific tokens.

0px 1px 4px -1px
rgba(48, 57, 105, 0.3)

0px 3px 10px -1px
rgba(0, 8, 32, 0.8)

0px 3px 5px -1px
rgba(48, 57, 105, 0.3)

0px 5px 15px -1px
rgba(0, 8, 32, 0.8)

0px 0px 2px 0px
rgba(48, 57, 105, 0.3)

0px 0px 3px 0px
rgba(0, 8, 32, 0.8)

0px 8px 12px -4px
rgba(48, 57, 105, 0.3)

0px 8px 20px -4px
rgba(0, 8, 32, 0.8)

Status tokens

Status tokens should be used to communicate a specific state to the user. This can apply to both interactive elements and static content.

Tokens within this category are of the following format:

• text - to be used for colored text of the specific status
• textOnColor - to be used for text on top of the specific status
• lighter - a lighter background color of the specific status to help show a hierarchy
• main - the base background color of the specific status, to be used for most decorative cases
• darker - a darker background color of the specific status to help show a hierarchy
• transparent - typically used for overlay backgrounds such as hover states for the status colors

Accent tokens

The use of the following accent tokens should be considered carefully, ensuring there is no other more suitable alternative that is more specifc (e.g. using theme.info.main instead of theme.blue.main when providing important information to a user).

Tokens within this category are typically of the following format, with a few exceptions for navy, grey, transparentGrey and white:

• text - to be used for colored text of the specific accent
• textOnColor - to be used for text on top of the specific accent color
• lighter - a lighter background color of the specific accent to help show a hierarchy
• main - the base background color of the specific accent, to be used for most decorative cases
• darker - a darker background color of the specific accent to help show a hierarchy

Examples

Imports

You can import the following components, utilities or types from this module:

import {
  THEME_DATA_ATTRIBUTE,
  darkThemeStyle,
  lightThemeStyle,
  scopedThemeCss,
  theme,
} from '@datacamp/waffles/theme';
import type { WafflesThemeStyle } from '@datacamp/waffles/theme';