Question about theming

What package(s) are you using?

carbon-components carbon-components-angular

• carbon-components
• carbon-components-react

Summary

Hi there! I found about Carbon Design System just some months ago, and I’m thrilled to use it in my next project. You are doing an awesome job by allowing non-IBMers to use and contribute to, your awesome work.

I’m having a hard time using themes into my project. I find the documentation about applying themes a bit lacking in examples of real usage, and I’d like to ask for further explanation to use them into my project.

In particular, I’d like to achieve a dark-mode switch that the user could toggle to switch to the dark side of the website. The themes involved are

$carbon--theme--white $carbon--theme--g90

I’m using Angular for my project, and I successfully imported the carbon theme in my main .scss file:

@import "~carbon-components/scss/globals/scss/vendor/@carbon/themes/scss/themes";

First question:

Is it correct to import themes in this way? Should I rely on @carbon/[name_of_package] for importing carbon packages instead?

After importing the main theme file, I’m doing this to apply the dark theme on my website

$carbon--theme: $carbon--theme--g90;

Second question:

What should I do in order to allow the user to switch themes? I was thinking about a top-level class (eg. .dark-theme, .light-theme) which uses one carbon-theme or another, but I’m having a hard time figuring out how to use carbon mixins to achieve that.

Have you any example project / piece of documentation that could help me to achieve that?

Thanks!

Relevant information

// carbon-overrides.scss
@import "~carbon-components/scss/globals/scss/vendor/@carbon/themes/scss/themes";

$carbon--theme: $carbon--theme--g90;

EDIT:

I tried to add my theme as recommended in the guidelines https://github.com/carbon-design-system/carbon/tree/master/packages/themes but I can’t get it working at all:

// carbon-overrides.scss

// Importing the themes from the @carbon/themes this time
@import '@carbon/themes/scss/themes';
@include carbon--theme($carbon--theme--g90);

[joshblack]

Hi there @brendanahart, @victor-grajski, and @will-hu-0!

This is a great question and is one of the biggest drivers for our v11 release that’s coming in Q1 2022. In v10, there is not a simple way to change the theme in response to a user action. There are a couple of ways to accomplish it, but unfortunately, they often require building separate stylesheets or using an experimental feature we have for CSS Custom Properties.

In v11, we will use CSS Custom Properties for all tokens so that theme switching (and inline theming) will be available out of the box. We will also make sure documentation on how to accomplish this, plus examples, is available for this use-case!

If you have any questions about this, I would definitely use our discussions tab and I would love to continue this chat.

[joshblack]

Hi there @Lc0rE! 👋

Thanks so much for reaching out and taking the time to put together such a great question 🙏

Is it correct to import themes in this way?

I think your best bet will be:

@import '~carbon-components/scss/globals/scss/theme';

Definitely agreed that this stuff needs to be better documented! Part of our current roadmap is to better address this in docs and also add more obvious entry points that can be used for common use-cases 😄

What should I do in order to allow the user to switch themes?

This is a great question and one that we’re actively looking at right now to see how we can introduce it without a breaking change and in a way that still supports folks on IE11.

Unfortunately, we haven’t been able to integrate some of these ideas yet into the stable codebase. There are some experiments behind feature flags that use CSS Custom Properties for this use-case, but unfortunately, the usage on IE11 has been a problem.

As it stands, creating a light mode / dark mode from the stable codebase will unfortunately result in duplicate CSS in your bundle 😞 (since it will emit the styles for each theme and not only the colors)

For folks that have wanted to try out the experimental feature, there is a feature flag for enabling custom properties that will let you set CSS Custom Properties on the page but this is likely to break as we make changes to it in the near future (for example, making rgba colors work with it)

I tried to add my theme as recommended in the guidelines

I think your best bet for custom themes will be:

@import '~carbon-components/scss/globals/scss/theme';

// Pass in the theme to override
$carbon--theme: map-merge($carbon--theme--white, (
  // Specify your overrides
  'interactive-01': '...',
));

@include carbon--theme();

Hope this helps!