Carbon: Question about theming

[Lc0rE]

What package(s) are you using?

carbon-components
carbon-components-angular

• [x] 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 @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!

[Lc0rE]

Hey @joshblack thanks for the answer!

I managed somehow to land on the CSS Custom Properties option by enabling the $feature-flags relative option. It's working as I expected and the switch is smooth as it should. However, I'll follow your suggestion and I'll wait for introducing this feature in my project.

About the other question, can you confirm me that the @carbon/themes is not a mandatory package to be installed along with the carbon-components to apply custom theming?

[joshblack]

@Lc0rE yup! You're totally right, @carbon/themes is included by default for you to use 😄

[tw15egan]

Closing as resolved, feel free to reopen if there's anything else you need

[Lc0rE]

I'm dealing again with some problems with carbon themes. While the method proposed by @joshblack is working fine for all carbon-components, I still have the issue when I'm going to use $tokens.

To be honest, I'm also having trouble understanding what dependencies to include in my sass file to use tokens. Now my style file looks like this:

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

.home__header__title {
  color: $interactive-01;
}

But when the project is bundling (I'm using Angular for that particular project), sass compiler complains that it can't find the $interactive-01 token. As far as I understand, there should be no other imports in my sass file to use color tokens, however it's only working when I also add both typography.scss and type.scss as dependencies:

@import '~carbon-components/scss/globals/scss/typography';
@import '~carbon-components/scss/globals/scss/vendor/@carbon/type/scss/type.scss';
@import '~carbon-components/scss/globals/scss/colors';

.home__header__title {
  color: $interactive-01;
}

Now, surprise surprise, the $interactive-01 color is the default one and not the one I customized (which is working fine in components).

What am I missing?

[joshblack]

Hey there @Lc0rE! 👋 You can use the following import path:

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

Here's a codesandbox demonstrating this: https://codesandbox.io/s/throbbing-fast-oy69w?file=/src/styles.scss

Hope this helps!

[Lc0rE]

Hey there @joshblack! Thank you for your answer.
I'm kindly asking you to keep the issue open just a little longer cause I can't test it right now. I'll report you back as soon as I can to see if your suggestion is solving my issues :)

[Lc0rE]

After further digging, I found out that it's actually an peculiar behavior related to the Angular framework. But hopefully it's just something that I'm doing wrong and you can help me understanding this!

I reproduced the issue and attached to the codesandbox below:

https://codesandbox.io/s/carbon-custom-theme-angular-7im8r?file=/src/components/carbon-button.component.scss

Apparently, I'm able to apply a custom theme just for the elements in the file where the override occurs. In my case, the file is the styles.scss which should actually spreading the style globally through the other components.

What am I doing wrong?

[joshblack]

@Lc0rE ah, you may be running into a challenge with sass-loader under-the-hood. Sass files that are imported separately don't have the same context, meaning that if you define something in one file it won't be available in the other file.

For example:

// styles.scss
$some-value: 1;

// carbon-button.component.scss
@debug $some-value; // This value will not be defined

In this case, you are setting $carbon--theme in styles.scss and expecting it to apply to carbon-button.component.scss. If this is the case, you would need to instead @import the carbon-button.component.scss file from styles.scss versus in the component.

This may not be it, but would be my best guess based on what you shared!

[joshblack]

Hey there! Going to close this issue out due to inactivity. Feel free to comment and I can re-open!