[RFC] Sass theming, theme zoning, and whitelabelling

[mattrosno]

This RFC looks at our current Sass architecture to identify how we can better support theming. As-is, we support a page-level theme and Sass variable overrides for theme colors and some component styling properties. The current Sass architecture breaks down quickly if a product is looking to use two or more themes at once, or if they want to modify component styling in a future-friendly way (as opposed to CSS overrides), a.k.a. whitelabel.

Definitions

The word "theme" is currently overloaded, causing confusion. At the end of the day, everything is a Sass variable (or map) so let's start there.

Variables - _vars.scss has been renamed to _variables.scss to better describe the file.

_theme-tokens.scss got moved into _variables.scss as it included theming variables as well as v9 to v10 feature gate variables. Bumping up versions does not constitute a theme.

Variants - button primary, secondary, etc. are variants not themes. Mixin names have been updated accordingly.

Theme - for now let's consider a theme being just colors. These colors are defined as Sass variables.

Inline Theme - when a theme is nested inside another theme.

Tokens - subset of theme variables. These are defined in the carbon website and come from @carbon/carbon-elements as theme tokens.

Whitelabel - if you want to override more than default color variables.

NOTE - inline theming only affects colors. If for some reason you want whitelabel just part your webpage (e.g. this secondary part of the page gets rounded buttons), use CSS overrides, or include two full Carbon builds to target that secondary part of the page.

Theme Overrides

Now that Carbon supports four themes out-of-box (as defined in tokens), you can global override the default theme variable using theme-white, theme-g10, theme-g90, theme-g100, or theme-custom. E.g. in your Sass build:

$token-theme: 'theme-g90';

@import '../node_modules/carbon-components/scss/global/styles.scss';

To support inline themes, token sets need to be in a Sass map. To use custom tokens, simply do this in your Sass build:

$token-theme: 'theme-custom';

$custom-theme-tokens: (
  interactive-03: pink,
);

@import '../node_modules/carbon-components/scss/global/styles.scss';

Any token not recognized is ignored, and unspecified custom tokens default to the white theme.

Inline Themes

Also called theme zones, or styling islands, this is possible by giving your theme a namespace class and deciding which component styling to include. Include just the components that you'll need in the inline themes to keep CSS bloat down. In your Sass build:

@import '../node_modules/carbon-components/scss/global/styles.scss';

@if feature-flag-enabled('components-x') {
  .my-dark-theme {
    @include theme-g90() {
      @include button-theme--x;
    }
  }
}

For the purpose of this RFC, only button Sass has been updated to support inline themes. The CSS output looks like:

.my-dark-theme .bx--btn--primary {
  background-color: #0062ff;
  border-color: transparent;
  color: #ffffff;
}

.my-dark-theme .bx--btn--primary:focus::before {
  border-color: #ffffff;
}

.my-dark-theme .bx--btn--primary:focus::after {
  border-color: #0062ff;
}

...

The inline theme overrides just contain colors to minimize CSS bloat.

If you want, you could even use your custom theme in inline themes:

$custom-theme-tokens: (
  interactive-03: pink,
);

@import '../node_modules/carbon-components/scss/global/styles.scss';

@if feature-flag-enabled('components-x') {
  .my-custom-theme {
    @include theme-custom() {
      @include button-theme--x;
    }
  }
}

Things to review

Carbon-elements

Question: Can we get carbon-elements to include Sass maps of colors? Since we can't interpolate Sass variable names, it's easiest to have the carbon-elements mixins set one $carbon--theme-tokens map. Using maps greatly simplifies handling custom tokens as global Sass override.

Notice how that does not use the !default keyword so our inline theme definitions can override the one $carbon--theme-tokens, print out inline theme declaration blocks, and move on by using @content.

Button

I used the new token map $carbon--theme-tokens instead of token variables, through a new theme-token function. E.g. theme-token(ui-04) instead of $ui-04.

I also shifted around button mixins so the main experimental mixin includes colors via button-theme--x mixin, but that mixin can also be used when defining inline themes. If you look at button-theme--x, it only includes colors.

Question: What would be the best way to test that this mixin refactor doesn't negatively impact selector specificity (order).

Whitelabel

In addition to using a non-default theme, a custom theme, or inline theme, we need a better way to allow styling customizations beyond color. This is where a two-layer Sass variable strategy comes in place.

Some variables are global (token map, color variables, font family, spacing, etc.) and for certain properties, components should use their own variables that reference the global variables. E.g. let's say you want more space between ghost button text and icon.

.#{$prefix}--btn--ghost {
  @include button-variant--x;

  .#{$prefix}--btn__icon {
    margin-left: $spacing-xs;
  }
}

You likely don't want to globally override $spacing-xs. You also don't want to override the declaration block as that becomes a migration nightmare. Instead, use a component variable:

$button-icon-margin-x: $spacing-xs !default;

.#{$prefix}--btn--ghost {
  @include button-variant--x;

  .#{$prefix}--btn__icon {
    margin-left: $button-icon-margin-x;
  }
}

And then in your custom Sass build:

$button-icon-margin-x: 12px;

@import '../node_modules/carbon-components/scss/global/styles.scss';

Things to review

Variables

Question: How many variables are too many variables? Evaluating Boostrap's Sass, it looks like colors, text, and box model can take you a very long way.

Question: What do we think of Bootstrap's variable naming convention? Is a Carbon prefix needed on these variables?

Variables should follow the $component-state-property-size formula for consistent naming. Ex: $nav-link-disabled-color and $modal-content-box-shadow-xs.

Question: What migration risks / actions does this entail? E.g. can we change a file name?

To Do

• Commit with button variables example

[netlify]

Deploy preview for the-carbon-components ready!

Built with commit b47ffcf

https://deploy-preview-1822--the-carbon-components.netlify.com

[asudoh]

Thanks @mattrosno for the proposal! I see your proposal includes valuable APIs (such as theme tokens defined as maps), or possibility of ones. Let's discuss further on these. When we discussed this topic with design team, IIRC @joshblack quickly demonstrated some of his ideas that I thought makes sense to some extent. Wondering if such idea has been incorporated.

While I understand looking at the codebase is sometimes frustrating with miscellaneous lack of expressiveness, I suggest avoiding changes to just improve them for now (or at least making them separate), for the sake of backward-compatibility. Also I suggest making the effort introduction of new (probably clean) APIs (with compatibility layer as necessary), instead of refactoring existing ones. In this way we can make the effort free from our release schedule (e.g. of v10).

Another of my thoughts on naming scheme is that theme is not just for colors IMO. Given the notion of theme involves designers in large extent, let's discuss this with our designers.

[asudoh]

Were lines here removed by accident...?

[mattrosno]

Intentional. Moved down to the button-theme--x mixin because it sets color. So when doing an inline theme and calling the button-theme--x mixin, that fill would be updated accordingly.

[asudoh]

Got it - Thanks @mattrosno for explaining!

[asudoh]

Mix-in name is considered an API; thus let's not change the stable ones.

[mattrosno]

If going forward with separate color-only component mixins to be called during inline theme creation, it'd be great to use the component-theme naming convention across all components. E.g. to include two components in a dark inline theme.

@if feature-flag-enabled('components-x') {
  .my-dark-theme {
    @include theme-g90;
    @include button-theme--x;
    @include modal-theme--x;
  }
}

Lack of inline theme support is blocking some adoption, so changing this mixin name could be worth justifying the breaking change.

[asudoh]

Not sure why you seem to think the name here blocks inline theme support - Wondering if you have more background. Probably the topic may connect to your attempt to narrow-scroping "theme" word definition?

[asudoh]

My apologies for not understanding you intent of not using !global here in the meeting. I see that calling this mix-in should override $carbon-theme-tokens variable, instead of letting application code directly define $carbon-theme-tokens for overriding - Please correct me if I'm still misunderstanding here.

One idea here is defining the map for each theme as variables (e.g. $carbon-theme-tokens-white/$carbon-theme-tokens-g10). In this way, we can do a couple of things:

• Something like @include theme-custom($custom-theme-variables, $carbon-theme-tokens-g10), where the 2nd parameter should default to $carbon-theme-tokens-white
• Defining $ui-01, etc. (compatibility) variables from the map

[mattrosno]

!global is on $carbon--theme-tokens. !default is not. Having !default prevents reassignment during inline theming.

Thanks for your suggestion on unique token map naming per theme. I'll explore that. And defining compatibility variables from the map.

[asudoh]

Rename here is considered a breaking change, e.g. application code, or more for inheriting component library, calling @import 'carbon-components/scss/globals/scss/vars.

Same comment for other file renames - Generally we need to be very careful about changing @import structures. Searching for my Slack message in our internal Slack channel about #1709 provides more details - I had to sent out the message because my acceptance test revealed that it breaks an app.

[mattrosno]

Is there a better place than developers getting started where we can document our Sass API? Also variable/mixin/function naming conventions. General acceptance criteria to improve commit quality for new (and active) contributors?

Having a location for that in this repo's markdown will also help PR review as we can see documented suggested changes.

Regarding the name change, _vars.scss goes against common convention when looking for where to reference global Sass variables. This file name is least important aspect of this PR. If it needs to stay _vars.scss to minimize breaking changes, 👍.

Regarding redundant @imports, I found and removed and extra theme import in _link.scss.

[asudoh]

Is there a better place than developers getting started where we can document our Sass API?

Two places I can think of; SassDoc and README.md files in src. And thank you for understanding my concern on breaking changes! We sometime tend to be inclined to be frustrated to see our Sass code like functions, variables, mix-ins, etc. being used by consumers and finding hard to change them (and I with Sass had more notion of scoping, etc.) even for something like wrong names, but we care about our users - One way we'd tackle this kind of problem is making the module of the old name import the one of the new name, with @warn for deprecation.

[mattrosno]

Thank you for the review @asudoh. I'll make another pass to address your feedback.

[mattrosno]

Is there a better place than developers getting started where we can document our Sass API? Also variable/mixin/function naming conventions. General acceptance criteria to improve commit quality for new (and active) contributors?

Having a location for that in this repo's markdown will also help PR review as we can see documented suggested changes.

Regarding the name change, _vars.scss goes against common convention when looking for where to reference global Sass variables. This file name is least important aspect of this PR. If it needs to stay _vars.scss to minimize breaking changes, 👍.

Regarding redundant @imports, I found and removed and extra theme import in _link.scss.

[mattrosno]

Intentional. Moved down to the button-theme--x mixin because it sets color. So when doing an inline theme and calling the button-theme--x mixin, that fill would be updated accordingly.

[mattrosno]

If going forward with separate color-only component mixins to be called during inline theme creation, it'd be great to use the component-theme naming convention across all components. E.g. to include two components in a dark inline theme.

@if feature-flag-enabled('components-x') {
  .my-dark-theme {
    @include theme-g90;
    @include button-theme--x;
    @include modal-theme--x;
  }
}

Lack of inline theme support is blocking some adoption, so changing this mixin name could be worth justifying the breaking change.

[mattrosno]

!global is on $carbon--theme-tokens. !default is not. Having !default prevents reassignment during inline theming.

Thanks for your suggestion on unique token map naming per theme. I'll explore that. And defining compatibility variables from the map.

[mattrosno]

Another of my thoughts on naming scheme is that theme is not just for colors IMO. Given the notion of theme involves designers in large extent, let's discuss this with our designers.

@asudoh It comes down to support and drawing a circle around how we intend inline theme functionality to work. Trying to keep this contained, regarding tokens and inline theming, it makes a lot of sense to keep this to just colors. And, if we intentionally use more component Sass variables going forward, that sets us up for improved whitelabelling. Whitelabelling is always going to be "do at your own risk / we don't support your whitelabel customizations / but we've made whitelabelling easy and future-friendly for you".

@IBM/carbon-design-system Please chime in if you see future theme variations that we officially support being more than colors. I'm hoping that component modifiers (cozy data table, condensed data table, etc.) will handle variations not related to color, and theming handles color.

[jeanservaas]

wow @mattrosno thank you for all this work!!!!! I wonder if the designers could have a smaller meeting with you to walk through this and figure out a roadmap for some next steps.

Most importantly how do we make this sass map?

Also I know there's an aversion from the language team to calling the background colors "themes" they refer to themes only at the light and dark level... but that's more of a conceptual vs. a practical issue at the moment.

[mattrosno]

@jeanservaas I'd be happy to show this to the design team after we have a better idea of development containment (effort and minimizing breaking changes.)

The Sass maps are just a way to put each set of tokens in a single "variable".

As for design input, it'd be nice to know if any future "theming" concepts or ideas extend beyond colors, as that influences how this is architected.

[asudoh]

@mattrosno Thank you for giving it your thoughts on my comments! Added some follow-up comments.

It comes down to support and drawing a circle around how we intend inline theme functionality to work. Trying to keep this contained, regarding tokens and inline theming, it makes a lot of sense to keep this to just colors.

Seems that it's more of technical scoping rather than re-defining "theme" word. Would like to more details here - My knee-jerk reaction to above comment is that probably usage of "colors" in variables/functions, etc. would make sense here.

[asudoh]

Got it - Thanks @mattrosno for explaining!

[asudoh]

Not sure why you seem to think the name here blocks inline theme support - Wondering if you have more background. Probably the topic may connect to your attempt to narrow-scroping "theme" word definition?

[asudoh]

Is there a better place than developers getting started where we can document our Sass API?

Two places I can think of; SassDoc and README.md files in src. And thank you for understanding my concern on breaking changes! We sometime tend to be inclined to be frustrated to see our Sass code like functions, variables, mix-ins, etc. being used by consumers and finding hard to change them (and I with Sass had more notion of scoping, etc.) even for something like wrong names, but we care about our users - One way we'd tackle this kind of problem is making the module of the old name import the one of the new name, with @warn for deprecation.

[joshblack]

Really like the direction this stuff is heading 💯 I think the only concern would be around theming more than just color, and how extracting color could impact how a contributor authors styles.

[asudoh]

@mattrosno Can we mark this as superseded by #1872 - Thanks again for the uddate!