foundation

Themes

Sets of styling that can be used to easily modify the style of Waffles` components and additionally custom components when used in conjunction with theme tokens.
GitHub
Figma

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.

Available themes

Waffles' currently offers two base themeslight and dark. For most use cases these themes should be enough, however all themes can also be sparingly overridden if necessary.

Any future themes will be added in a similar method.

Theme tokens

We have two types of tokens in Waffles—design tokens and theme tokens. For any colors, in both new and old apps, we recommend using our theme tokens. The main advantage of these are that the usage of colors is standardized across apps, allowing for easier updates to branding/theming going forward. Other utility-based design tokens can still be used alongside these, as they are outside the scope of theming.

Theme tokens come in the following different categorizations:

  • Common - the most frequently used tokens for the majority of cases, e.g. background and text
  • Status - colors used for signifying an important state, such as success and error
  • Accent - purely decorative colors, with no further use case implied, e.g. pink

Theme tokens can be accessed via theme.[type].[identifier], where type and identifier can be found as the title and content respectively in the tables below.

There are also some available helpers to support the usage of theme tokens.


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.

Text

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
inverse--wf-text--inverse#FFFFFF#05192D
inverseSubtle--wf-text--inverse-subtle#9BA3AB#5D6A77
link--wf-text--link#0065D1#5EB1FF
main--wf-text--main#05192D#EFEFF5
secondary--wf-text--secondary#213147#E1E1E8
subtle--wf-text--subtle#5D6A77#9BA3AB

Background

Used for the backgrounds of both the base content and individual components of apps. The layering hierarchy of colors should be followed when applied to different components.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
active--wf-bg--activergba(48, 57, 105, 0.1)rgba(255, 255, 255, 0.1)
contrast--wf-bg--contrast#FFFFFF#213147
contrastInverse--wf-bg--contrast-inverse#05192D#FFFFFF
focus--wf-bg--focusrgba(48, 57, 105, 0.06)rgba(255, 255, 255, 0.06)
hover--wf-bg--hoverrgba(48, 57, 105, 0.06)rgba(255, 255, 255, 0.06)
hoverStrong--wf-bg--hover-strongrgba(48, 57, 105, 0.1)rgba(255, 255, 255, 0.2)
hoverStrongInverse--wf-bg--hover-strong-inversergba(255, 255, 255, 0.2)rgba(48, 57, 105, 0.1)
main--wf-bg--main#F7F7FC#05192D
secondary--wf-bg--secondary#EFEFF5#13253A
tertiary--wf-bg--tertiary#E8E8EE#000820
transparent--wf-bg--transparentrgba(48, 57, 105, 0.1)rgba(255, 255, 255, 0.2)
transparentInverse--wf-bg--transparent-inversergba(255, 255, 255, 0.2)rgba(48, 57, 105, 0.1)

Border

Note: interactive should only be used for components that are typically clickable as the primary purpose—such as buttons, checkboxes and radio.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
focusOutline--wf-border-color--focus-outline#257DFE#257DFE
interactive--wf-border-color--interactivergba(48, 57, 105, 0.6)rgba(255, 255, 255, 0.6)
main--wf-border-color--mainrgba(48, 57, 105, 0.15)rgba(255, 255, 255, 0.15)
strong--wf-border-color--strongrgba(48, 57, 105, 0.3)rgba(255, 255, 255, 0.3)

Box Shadow

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
medium--wf-box-shadow--medium
0px 1px 4px -1px
rgba(48, 57, 105, 0.3)
0px 3px 10px -1px
rgba(0, 8, 32, 0.8)
thick--wf-box-shadow--thick
0px 3px 5px -1px
rgba(48, 57, 105, 0.3)
0px 5px 15px -1px
rgba(0, 8, 32, 0.8)
thin--wf-box-shadow--thin
0px 0px 2px 0px
rgba(48, 57, 105, 0.3)
0px 0px 3px 0px
rgba(0, 8, 32, 0.8)
xthick--wf-box-shadow--xthick
0px 8px 12px -4px
rgba(48, 57, 105, 0.3)
0px 8px 20px -4px
rgba(0, 8, 32, 0.8)

Brand

Used for representing the primary brand colors of DataCamp—useful for both decorative and purposeful content.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-brand--darker#00C74E#00C74E
lighter--wf-brand--lighter#65FF8F#65FF8F
main--wf-brand--main#03EF62#03EF62
text--wf-brand--text#05192D#FFFFFF
textOnColor--wf-brand--text-on-color#05192D#05192D
textSubtle--wf-brand--text-subtlergba(48, 57, 105, 0.6)rgba(255, 255, 255, 0.6)

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

Success

Used to show success or completion of an action or component.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-success--darker#00C74E#00C74E
lighter--wf-success--lighter#65FF8F#65FF8F
main--wf-success--main#03EF62#03EF62
text--wf-success--text#008031#03EF62
textOnColor--wf-success--text-on-color#05192D#05192D
transparent--wf-success--transparentrgba(3, 239, 98, 0.1)rgba(3, 239, 98, 0.2)

Info

Suitable for communication informative content to the user. Can also be used to indicate something is restricted.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-info--darker#257DFE#257DFE
lighter--wf-info--lighter#72E5FE#72E5FE
main--wf-info--main#5EB1FF#5EB1FF
text--wf-info--text#0065D1#5EB1FF
textOnColor--wf-info--text-on-color#05192D#05192D
transparent--wf-info--transparentrgba(94, 177, 225, 0.2)rgba(94, 177, 225, 0.2)

Warning

Used for actions or components that should warn the user.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-warning--darker#D87300#D87300
lighter--wf-warning--lighter#FFBC4B#FFBC4B
main--wf-warning--main#FF931E#FF931E
text--wf-warning--text#B75900#FF931E
textOnColor--wf-warning--text-on-color#05192D#05192D
transparent--wf-warning--transparentrgba(255, 188, 75, 0.2)rgba(255, 188, 75, 0.2)

Error

Suitable for both error and destructive related actions or components.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-error--darker#DD3400#DD3400
lighter--wf-error--lighter#FF782D#FF782D
main--wf-error--main#FF5400#FF5400
text--wf-error--text#C01100#FF5400
textOnColor--wf-error--text-on-color#05192D#05192D
transparent--wf-error--transparentrgba(255, 84, 0, 0.1)rgba(255, 84, 0, 0.2)

Upgrade / AI

Suitable for both upgrade and AI related actions or components.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-upgrade--darker#5646A5#5646A5
lighter--wf-upgrade--lighter#A781FF#A781FF
main--wf-upgrade--main#7933FF#7933FF
text--wf-upgrade--text#5646A5#A781FF
textOnColor--wf-upgrade--text-on-color#FFFFFF#FFFFFF
transparent--wf-upgrade--transparentrgba(121, 51, 255, 0.1)rgba(121, 51, 255, 0.2)

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

Green

Note:

  • These tokens should not be used to indicate success—use the success tokens under status instead.
  • These tokens should not be used for brand-related content—use the brand tokens under common instead.
Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-green--darker#00C74E#00C74E
lighter--wf-green--lighter#65FF8F#65FF8F
main--wf-green--main#03EF62#03EF62
text--wf-green--text#008031#03EF62
textOnColor--wf-green--text-on-color#05192D#05192D

Red

Note: These tokens should not be used to indicate an error or destructive action—use the error tokens under status instead.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-red--darker#DD3400#DD3400
lighter--wf-red--lighter#FF782D#FF782D
main--wf-red--main#FF5400#FF5400
text--wf-red--text#C01100#FF5400
textOnColor--wf-red--text-on-color#05192D#05192D

Orange

Note: These tokens should not be used to indicate a warning—use the warning tokens under status instead.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-orange--darker#D87300#D87300
lighter--wf-orange--lighter#FFBC4B#FFBC4B
main--wf-orange--main#FF931E#FF931E
text--wf-orange--text#B75900#FF931E
textOnColor--wf-orange--text-on-color#05192D#05192D

Yellow

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-yellow--darker#CFA600#CFA600
lighter--wf-yellow--lighter#FFEC3C#FFEC3C
main--wf-yellow--main#FCCE0D#FCCE0D
text--wf-yellow--text#907000#FCCE0D
textOnColor--wf-yellow--text-on-color#05192D#05192D

Blue

Note: These tokens should not be used to indicate informative or restrictive content —use the info tokens under status instead.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-blue--darker#257DFE#257DFE
lighter--wf-blue--lighter#72E5FE#72E5FE
main--wf-blue--main#5EB1FF#5EB1FF
text--wf-blue--text#0065D1#5EB1FF
textOnColor--wf-blue--text-on-color#05192D#05192D

Purple

Note: These tokens should not be used for upgrade or AI-related content/actions—use the success tokens under status instead.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-purple--darker#5646A5#5646A5
lighter--wf-purple--lighter#A781FF#A781FF
main--wf-purple--main#7933FF#7933FF
text--wf-purple--text#5646A5#A781FF
textOnColor--wf-purple--text-on-color#FFFFFF#FFFFFF

Pink

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-pink--darker#DC4D8B#DC4D8B
lighter--wf-pink--lighter#FF95CF#FF95CF
main--wf-pink--main#FF6EA9#FF6EA9
text--wf-pink--text#BF3072#FF6EA9
textOnColor--wf-pink--text-on-color#05192D#05192D

Navy

Note:

  • These tokens should not as backgrounds in non-decorative use cases—use the background tokens under common instead.
  • These tokens should not be used for text in most cases—use the text tokens under common instead.
Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-navy--darker#000820#000820
lighter--wf-navy--lighter#13253A#13253A
main--wf-navy--main#05192D#05192D
subtler--wf-navy--subtler#213147#213147
text--wf-navy--text#05192D#213147
textOnColor--wf-navy--text-on-color#FFFFFF#FFFFFF

Grey

Note: These tokens should not as backgrounds in non-decorative use cases—use the background tokens under common instead.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-grey--darker#E1E1E8#E1E1E8
lighter--wf-grey--lighter#EFEFF5#EFEFF5
main--wf-grey--main#E8E8EE#E8E8EE
subtler--wf-grey--subtler#F7F7FC#F7F7FC
text--wf-grey--text#848492#F7F7FC
textOnColor--wf-grey--text-on-color#05192D#05192D

Transparent Grey

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
darker--wf-transparent-grey--darkerrgba(48, 57, 105, 0.3)rgba(255, 255, 255, 0.3)
lighter--wf-transparent-grey--lighterrgba(48, 57, 105, 0.15)rgba(255, 255, 255, 0.15)
main--wf-transparent-grey--mainrgba(48, 57, 105, 0.2)rgba(255, 255, 255, 0.2)
subtler--wf-transparent-grey--subtlerrgba(48, 57, 105, 0.1)rgba(255, 255, 255, 0.1)
text--wf-transparent-grey--text#595D78#E1E1E8
textOnColor--wf-transparent-grey--text-on-color#05192D#FFFFFF

White

Note: These tokens should not be used for text in most cases—use the text tokens under common instead.

Name / CSS VariableLight Theme / Fallback ValueDark Theme ValueExample
main--wf-white--main#FFFFFF#FFFFFF
text--wf-white--text#FFFFFF#FFFFFF
textOnColor--wf-white--text-on-color#05192D#05192D

Examples

Applying theme styles

Dark-themed content

Intermediate Python

Level up your data science skills by creating visualizations using Matplotlib and manipulating DataFrames with pandas.

Applying theme tokens

Styling the colors of native html elements with theming

Try toggling the theme at the top of the page!

Overriding theme tokens

Custom-themed content

Heading

All of this content styled is using Waffles' theming, but with custom color overrides!

Local theming

Dark-themed content

This content is dark themed.

Light-themed Card

This content is light themed, even though it's parent has the dark theme.

Switching themes

Themed content

This content is themed based on the toggle within this example.


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';