[RFC v2] Sass theming, theme zoning, and whitelabelling

[mattrosno]

This RFC is the second iteration of #1822. This addresses the feedback on the original RFC to:

1. Minimize breaking changes (renaming files, renaming Sass variables/mixins/functions)
2. Simplify custom theming
3. Be able to change more than just colors in inline themes

As demonstrated in the first commit, the only Sass change is calling @include carbon--theme; instead of @include carbon--theme-white();. The rest of the changes are in carbon-elements themes, which as open to change as they were introduced in v10.

Global Variables

Like before, global variables come from many different places specified with !defaults. Sass files often import global variables from @carbon/colors, @carbon/elements themes, etc. You can take any of those and globally define them in your custom Sass build:

$prefix: 'foo'; // from _vars.scss
$interactive-03: pink; // from _theme-tokens.scss, ultimately @carbon/elements
$carbon--orange-40: yellow; // from _colors.scss, ultimately @carbon/colors

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

If you want to use a non-default theme like g10, g90, g100... now you can simply set the new carbon--theme global variable.

$carbon--theme: 'g90';

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

If you wanted to modify one of the alternate themes, you can do that too!

$interactive-03: pink;
$carbon--theme: 'g90';

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

Inline Themes

Regardless if you are using global variables for your default theme or not... you can define inline themes by setting global variables after styles.scss has been built. In this simple example, $interactive-03 is orange in the default theme and the inline theme with namespace class my-inline-theme sets $interactive-03 to pink then includes button declaration blocks.

$interactive-03: orange;

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

@if feature-flag-enabled('components-x') {
  .my-inline-theme {
    $interactive-03: pink;
    @include button--x;
    // other component mixins go here to include in inline theme
  }
}

Should you want to include an alternate theme as provided by @carbon-elements, use the new mixin carbon--theme-overrides that defines all tokens without !default so they can globally override the default declarations.

$interactive-03: orange;

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

@if feature-flag-enabled('components-x') {
  .my-dark-theme {
    @include carbon--theme-overrides('g90');
    @include button--x;
    // other component mixins go here to include in inline theme
  }
}

To Do

• Refactor button example so you can call a colors mixin to prevent inline theme CSS bloat

Whitelabelling

Any global variable with a default value is fair game in default and inline theming. Let's say you wanted bigger buttons in your default theme and giant buttons in an inline theme. Assuming each component has separate colors mixins, if modifying something beyond colors, you'd need to call the full component mixin again.

$button-height: 100px;

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

@if feature-flag-enabled('components-x') {
  .my-custom-theme {
    $button-height: 200px;
    @include button--x;
    // other component mixins go here to include in inline theme
  }
}

To Do

• Evaluate button component variables, following Bootstrap's example on variable naming conventions and what component variables they include (colors, text, box model)

[netlify]

Deploy preview for the-carbon-components ready!

Built with commit 76c6725

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

[asudoh]

LGTM 👍, the code is much cleaner - Good to go from my perspective. Thanks @mattrosno!

[mattrosno]

In the second commit, I demonstrate how we can move color properties to new color-only mixins. That allows us to prevent CSS bloat when using inline themes, since inline themes only include color changes. E.g.

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

@if feature-flag-enabled('components-x') {
  .my-dark-theme {
    @include carbon--theme-overrides('g90');
    @include accordion-colors--x;
    @include button-colors--x;
    @include text-input-colors--x;
  }
}

Naming convention is that component mixins that only contain colors are suffixed with -colors.

Accordion

Accordion is a straight forward example. It may seem a little awkward to split up CSS shorthand like border into border-width and border-style in the main mixin, and border-color in the colors mixin, but I don’t find that a big deal. As a convention, it’s feels right to keep all use of color variables in the colors mixins.

You’ll also notice that included mixins that use color variables like @include focus-outline('outline’); have been moved to the -colors mixin.

Button

button/_mixins.scss has button-theme--x mixin, and I moved color properties out of that into button-theme-colors--x mixin. That’d be a breaking change, as somebody currently using:

@include button-theme--x(…vars);

Would need to modify to:

@include button-theme--x;
@include button-theme-colors--x(…vars);

If we’re concerned about that breaking change, we could create the button colors mixin in a way that doesn’t change the original theme mixin - it’d just have duplicated non-color declarations in inline theme CSS.

Input

Nothing new was discovered when creating text-input-colors—x, that hadn’t already been done in the accordion example.

[mattrosno]

@asudoh part two of this RFC is ready for review: color-only mixins to use in inline theming. As demonstrated in the second commit and the above comment, I tried it out with three components.

@joshblack do you have any ideas on how we could test for styling regression as this moves around outputted css source order a bit?

[joshblack]

@mattrosno one potential way for checking this would be to "render" the styles in jsdom and then make sure the CSS Style Rules themselves are the same.

So something like:

test('some selector', async () => {
  // Render Sass to get the output
  const { result } = await renderSass(`
// Imports here
`);

  // Create the stylesheet and add the CSS as its content
  const stylesheet = document.createElement('style');
  stylesheet.textContent = result;

  // Iterate through cssRules to find selector in mind
  const selector = Array.from(stylesheet.cssRules).filter(/* ... */);

  // Make an assertion on the value of the selector
  expect(selector).toMatchSnapshot();
});

Might be able to use globals too like StyleSheet, CSSStyleSheet, CSSSTyleRule, etc.

[joshblack]

Copying note over from the other one, once concern I have is that we would need to parse out anything that is theme-able into it's own mixin. Is there any worry about how this could impact authorship? Seems like it could be easy to do the wrong thing when it comes to color and add it to the selector instead of pulling it out. In addition, would we have to do this for other theme-able properties in the future? For example, type, spacing, etc.

[asudoh]

Thank you for coming up with the second round of RFC @mattrosno! Not sure if it's the same as what @joshblack brought up above, but wanted to understand why themeable colors are extracted out in a mix-in. It appears that other abstractions we have like variables, lower-level mixins are good enough for many places (e.g. border color of accordion) and CSS bloat is a concern only for extreme cases of customization (e.g. using some other property instead of border).

[mattrosno]

Color-Optimized Inline Theming

@asudoh the purpose of color-only mixins is inline theming. Why optimize inline theming for color overrides? Because that's the need. @joshblack with this approach, you could make an inline theme that modifies more than just colors with:

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

@if feature-flag-enabled('components-x') {
  .my-crazy-theme {
    $button-height: 400px;
    $button-border-width: 10px;
    @include button--x;
  }
}

This uses the full button mixin. With that comes CSS bloat via unnecessary selector overrides. I don't see that happening often. I expect non-color global overrides to just be needed at the default theme level (also applied to inline themes).

A more realistic example is marketing page striping where sections of the page use alternate themes:

Page heros... call to action sections... all just modifications to color:

Authorship

@joshblack on authorship, it's just something that we document and enforce along with our BEM-style selectors, component variable naming convention, oh and when you use colors, do so in -colors mixins so those can be cleanly used in inline themes.

[asudoh]

Thank you for more explanation @mattrosno! Your 2nd screenshot above and the words around it give me an impression that you wanted component-specific, color-only theme zoning. Is it correct?

[asudoh]

^ If so - From a technical sense I see the current codebase doesn’t have a good way to do that. OTOH, mulling over this topic further, I imagine that applying the notion of theme zoning only to a combination of specific styling area (color) paves a way for applications to easily lose UX coherency. Good to see with designers where we'd go with theme zoning.

[mattrosno]

@asudoh I think our Sass should allow anything to be used in inline themes to allow ultimate flexibility. That being said, I expect (through personal experience, discussions with various teams here) color-only changes to be the primary use of inline theming. That's why this RFC allows anything to be used in inline theming, and optimizes for color-only inline theming to minimize CSS bloat.

@photodow @elizabethsjudd can you chime in with your needs regarding inline theming?

[elizabethsjudd]

Thank you for looking in to this! It's going to make our work in WH so much more manageable. Overall I think this is looking great and I only had a few questions with naming so I can better understand the expectations between the beta and GA releases of Carbon X. Right now there seems to be some inconsistencies and these mixins are going to be referenced out side of Carbon so I want to make sure there are clear expectations.

My other question comes for setting global variables to white label (change aspects that aren't colors). We don't pull the entire suite of Carbon components but pull in the styles on a per component basis (and we advise our users to only pull in the components that they use) to reduce bloat. If we change the value of a global variable for a "zone" wouldn't that create side-effects if that component were to be referenced by another?

[elizabethsjudd]

Just wanted to make sure I understand the future expectations. Once v10 is released, we shouldn't have to be setting the feature flags to get the Carbon X styles. Is the --x going to remain on the mixin names?

[asudoh]

When we release v10, the default values of feature flags will be flipped. It means that v10 styles will be effective by default.

[elizabethsjudd]

That's specifically why I asked this... Carbon users use these mixins directly so when the feature flag is turned off we'd have to go and update all reference to these mixins... seems very tedious from a user perspective.

[joshblack]

Might be worth submitting a request to: https://github.com/carbon-design-system/carbon-upgrade and we can try and include it 👍

For reference, here is how we used it to update color names. We also used it for updating namespaces here for layout.

In v10, we will also be more strict around our sassdoc annotations so that it is clear what is intended for public or private access. These component-level mixins aren't intended for public access, as far as I'm aware. @asudoh feel free to correct me if I'm wrong here 👍

[asudoh]

^ Right, these are just for conditional import.

[elizabethsjudd]

The color mixins are 100% meant to be public, that's what my request is for. I want the ability to call a mixin that would change only the colors of a component. If they are private then they provide no value to WH which is why having the --x and changing it with the feature flags does seem realistic for manageability.

@joshblack isn't my request on this repo the request for the update? I don't understand why you're asking to have a duplicate thread.

[elizabethsjudd]

@mattrosno can you chime in here... this is a very big concern for WH and would basically make a lot of this work moot for us. Were you also under the impression that these would be private mixins? Based on this comment this does not seem to be your impression

[elizabethsjudd]

I would expect the button-theme mixin to call the button-theme-color mixin like in accordion. https://github.com/IBM/carbon-components/blob/9504fa4d6a3470275cd9eb6f5f5f2d3e6a503f4c/src/components/accordion/_accordion.scss#L277

Another question about future expectations: would button-theme become button and button-theme-color become button-color to align with what is going on with accordion?

[elizabethsjudd]

I don't know where the comment went but I swear I saw an email with a response to this. To be clear, for buttons the button-theme mixin is actually a variant. The name button-theme is confusing given the new inline-theming/zone option that this PR introduces. I wonder if it would be smart to take advantage of the Carbon X release and rename this to be clearer to something like button-variant instead.

[elizabethsjudd]

@mattrosno This is beyond the scope of this PR but as I was reading these files, it would be nice if the mixins were defined in a separate file from the where the @include exports is declared so we can reference only mixins without fear of side effects in our CSS. (This would be a non-breaking change to existing Carbon users)

We use the carbon @include exports in WH and there are still areas where we are getting duplicate code in our generated CSS but I haven't had a chance to dig in to why it's happening on some components and not others. Separating these aspects (code that is stripped from CSS and code that is the CSS output) in to separate files could be a failsafe for these concerns.

[asudoh]

I'm still concerned on creating a mechanism extracting out components' color definitions to apply flexibility there. Though we strive toward flexibile APIs, I see adding flexibility there comes with significant overhead in our codebase (e.g. how Carbon core authors components) without being cautious on what we do in detail and how.

That's why it's good to better understand what are the underlying use cases behind and work with our designers to see what is the best way to meet the requirement. CC @IBM/carbon-designers to let them take a note and to see a chance to chime in.

What I would imagine about theme zoning is something like applying white theme to the main portion and g10 theme to some portions. Two screenshots in @mattrosno's earlier comment seem to represent such use case. That said, need to understand why @mattrosno seems to be trying to fiddle with our lower-level API instead of our higher-level API (set).

[aagonzales]

Can we set up a meeting and talk about this in person, to make sure we're (designers) are correctly understanding what's being proposed.

[mattrosno]

That said, need to understand why @mattrosno seems to be trying to fiddle with our lower-level API instead of our higher-level API (set).

@asudoh changes to @carbon/elements/scss/themes as demonstrated in first commit necessary to (1) let app developers set default theme through global Sass variable and (2) let app developers define inline themes in their Sass builds.

Why modify lower-level component APIs? To optimize CSS output (reduce CSS bloat) for the most common use of inline-theming, which AFAIK is only colors. I have discussed the need with @photodow for marketing pages and with @elizabethsjudd for their portfolio's needs.

I guess we need more underlying use cases. No need to meet. @IBM/carbon-designers please share designs or supporting material for needing one theme inside another. After that, if we're in agreement that the primary purpose of inline theming is just for color changes, we then make the authorship vs CSS bloat decision to determine if we move CSS color declarations to mixins that only set colors.

[photodow]

Would it be too much of a stretch to keep colors where they are like you had them for default theme use, and then you could use the accordion--color mixin to overwrite those colors to optimize the code a little further?

[mattrosno]

But then it's not DRY... we'd have to always remember to include color overrides. Could be easier than having to split up declarations like border-top though... so ya, I'd support that as a viable option.

[sadekbazaraa]

@aagonzales and @jeanservaas have asked me to chime in here with some general thoughts about how the colors are intended to work in regards to our Dark and Light UIs. I’ve been wondering if referring to our default color system as having light and dark “UIs” as opposed to "themes" helps since "themes" seems to be causing confusion in this context.

Here’s a few foundational principles:

1. There are 2 distinct UIs—Dark and Light. We’ve intentionally avoided the use of midtones and skewed towards either end of the spectrum.
2. Within each UI, there are several degrees of nuance and flexibility. The background color of the “zone” that is being designed is the primary factor in determining how the rest of the colors are applied.
3. There are 5 global background colors for any of these zones in the default dark and light UIs. In light, we use White and Gray 10 and in dark we use Gray 100 / 90 / 80.

Light UI:

1. In general, components with Gray 10 backgrounds are applied to white zones and components with White backgrounds are applied to Gray 10 zones. While this should probably be the limiting case for a default set, there is actually a bit more flexibility within the system. For example, a White table may sit on top of a White zone OR a Gray 10 zone. Both options are viable and constitute the light UI. Similarly, a card component with a White background may sit on top of a White zone OR a Gray 10 zone. Furthermore, both scenarios may exist in the same experience, whether product or digital. Perhaps an alt or an override would be useful to classify these additional degrees of nuance.
2. The light UI does not use Gray 20 background zones, the nuances are achieved most commonly by alternating between White on Gray 10 and Gray 10 on White combinations. The dark UI is a different beast entirely with different behaviors.

Dark UI:

1. Contrary to the light UI with its alternating use of White / Gray 10 background layering, the dark UI always gets progressively lighter as layers are added. In other words, we never use a component background that is darker than the background zone it's being applied to. The same is true of interaction states, such as hover, selected and active.
2. In general, Gray 90 components are applied to Gray 100 background zones and Gray 80 components are applied to Gray 90 background zones.
3. Similar to the light UI, there is also the possibility of having a Gray 100 table sitting atop a Gray 100 background zone. The same applies to cards and various other components. To reiterate the possibility, perhaps the default set is Gray 90 on Gray 100 and Gray 80 on Gray 90 with alts and overrides being used to achieve combining the same component and background color as needed.
4. Another nuance within the system for dark UI is that one could also apply a Gray 80 component to a Gray 90 OR a Gray 100 background. One way to simplify may be to have the default case be 80 on 90 with an alt to use 80 on 100.
5. Because our layering gets progressively lighter in the dark UI, there are some occasions where we might use a Gray 70 component on a Gray 80 background. This scenario would be in the case of compound components specifically. For example, you may have a background zone of Gray 90 that you’ve applied a Gray 80 card too. Then on top of that Gray 80 card is an overflow menu with it’s own background color. In this case the overflow background would be Gray 70. The use of Gray 70 is only applicable in this compound component scenario.

[sadekbazaraa]

It's much easier to grasp the concepts written above with visual examples. Attached is the latest working version of the Color UI page on Design Language for reference.

[sadekbazaraa]

I'm going to do my best to outline some thinking around how our tokens and variables might work. Of course I have 0% experience as a developer so I know very little about how tokens work but in a few discussions with different devs early on it did not seem entirely out of the ordinary to have a set of tokens that were dependent on another variable.

In regards to our system, I've always contemplated the tokens being dependent on the primary background color that the component is being applied to—White / G10 / G100 / G90 / G80. The same token would give you different colors dependent on which of the 5 global background colors are being used.

Take links for example, there isn't a single link color across the board. Even in light and dark UIs respectively, link colors are different depending on which zone it's sitting on. Primary buttons may be the only component that is the same across all of our backgrounds, everything else has a high degree of nuance driven by accessibility requirements above all else.

With all of that in mind. I'll share an exploration from many months ago regarding how tokens might play out for links. Again, I have no idea how this works so it should be considered merely as a logical exercise. Potential token names on the right, background color across the top and the table of values in between.

The main thing to consider is how and if it's possible to have singular tokens return the correct value based on which global background it's sitting on. I think this was the whole notion of cascading tokens that we were talking about with the gal from the Lightning system a few weeks back.

Ok, hope some of this expose is useful...

S

[asudoh]

Thanks @mattrosno for explaining that the attempt to fiddle with lower-level API is for de-duping CSS rules, and @sadekbazaraa for outlining the theme zoning requirements in detail.

Starting with theme zoning requirements, though there are some constraints wrt what theme can be on what background, the set constraints are not as hard as I had imagined and I have an impression that it may not make sense to bake in the constraints to our Sass API level.

Wrt the requirements of de-duping CSS rules, I see the requirements is fair. My suggestion is utilizing toolchain instead of changing our Sass API. e.g. It's fairly easy to extract out non-color CSS rules with PostCSS. IIRC @joshblack has created JavaScript version of theme token table, and with that, I think we can extract out CSS rules just of theme colors.

In this way, we can focus on (possibly) defining theme-zoning API, without being worried about performance optimizations.

[asudoh]

My quick experiment showed that we can reduce the bundle including all components from 28K to 8K, minified/gzipped.

[mattrosno]

Thanks for sharing @sadekbazaraa. @asudoh regarding component mixins and the desire to not change them unless we need to... let me do this. Unless I hear otherwise, I'm under the impression that inline theming will be primarily done for only colors changes. (Components in inline themes can leverage modifiers if they need changes beyond color.)

I'll evaluate (1) baseline CSS bundle (minified/gzipped) all components as you did. Then (2) if a user defines an inline theme that includes all components using our mixins as-is. Then (3) as @photodow suggested, creating new color-only override mixins for each component to only use those in the inline theme.

I hope that will help give confidence in inline theming approach so we can make it happen.

[photodow]

@mattrosno thanks for the hard work on this. It's really looking great!

For Digital Design performance is critical. Especially where we are in development at the moment, and how it relates to theming. At the moment, it's looking like we'll need each variation for each component built out. As @mattrosno's work in progress here tries to avoid, I'd really like to avoid building out and delivering 4 copies of each component to our adopters. (That can get large fast even when you're using a minimum number of components) Anything we can shave off using these component color mixins would be very much appreciated. If padding isn't necessary in a g100 theme when it's already defined with the default white then why include it? With that said unless y'all have another solution in mind the separation of colors look like a great way to minimize the theming's impact on performance.

I don't know if y'all will support this in the future, but another need outside of color we have is updating the majority of the components to body-long-02 instead of the current default of body-long-01. I think @mattrosno addressed this need in this WIP as well. I have a hard time seeing at the moment we need it to be inline. After discussing with him things like this can be defined at the component level, and cross all theme variants.

If there is concern around governance. Like y'all don't want people like myself touching the lower level APIs. (e.g button--x, button--color--x) I wonder if adopters like myself could pass in the themes including potentially new themes to build it all vs. giving us the button--color--x and expecting us to build the themes. If possible this could potentially improve governance, simplicity from adopters like myself, and even enforce more consistency with the naming conventions and more. See example below...

Instead of adopters like myself doing the following that was proposed.

@import '@carbon/themes/scss/mixins.scss';
@import '~carbon-components/scss/components/accordion/accordion';

@if feature-flag-enabled('components-x') {
    @include button-colors--x; // default

    .my-theme-g10 {
        @include carbon--theme-overrides('g90');
        @include button-colors--x;
    }

    .my-theme-g90 {
        @include carbon--theme-overrides('g90');
        @include button-colors--x;
    }

    .my-theme-g100 {
        @include carbon--theme-overrides('g100');
        @include button-colors--x;
    }
}

We pass in the theme names we want to include, and y'all cycle through and build within the component?

// custom-pink theme defined earlier at the global level
$import-themes: ['g10', 'g90', 'g100', 'custom-pink'];

@import '~carbon-components/scss/components/accordion/accordion';

Just some thoughts, but maybe I'm getting ahead of the discussion here, or not have a full understanding of implications yet. Either way, if y'all still need more use cases after what @sadekbazaraa shared let me know, I'd be happy to track down some that we've worked directly on, and even some out in wild on IBM.com.

[elizabethsjudd]

I like @photodow's idea for the default themes (would make things even easier for the end user) but I do think that doesn't resolve the issue for our users that need to be able to white-label. We need the flexibility to call these mixins ourselves and make changes as needed without having to constantly change the name.

[mattrosno]

@photodow @elizabethsjudd thanks for the feedback! This is great. I'll crank out another commit to demonstrate how I see this working and get your feedback. Stay tuned!

[asudoh]

Just in case I was not clear enough - Even though I see theme zoning is mostly about colors, I do not think it's a good idea fiddling with e.g. button-theme mix-in for the purpose of theme zoning (BTW I think button-theme name is confusing, as it's for defining different button variant). Given the requirement around fiddling with such mix-in is eliminating redundant style rules, we can do it with additional toolstack instead.

Creating styles for alternate themes in an application can be done by building our Sass code with alternate settings, and we may define a higher-level API for that purpose.

[mattrosno]

Given the requirement around fiddling with such mix-in is eliminating redundant style rules, we can do it with additional toolstack instead.

@asudoh can you give an example? What specific tool/library could take CSS like:

.foo {
  height: 100px;
  width: 100px;
  position: relative;
  background-color: red;
  border: 1px solid blue;
}

.my-theme .foo {
  height: 100px;
  width: 100px;
  position: relative;
  background-color: yellow;
  border: 1px solid green;
}

And optimize as

.foo {
  height: 100px;
  width: 100px;
  position: relative;
  background-color: red;
  border: 1px solid blue;
}

.my-theme .foo {
  background-color: yellow;
  border-color: green;
}

Or something similar so an inline theme with all components included doesn't nearly double CSS filesize?

[asudoh]

@mattrosno It's PostCSS: https://postcss.org. It creates AST for CSS and where you can mangle - Very similar to Babel for JS. If we separate the former/latter rulesets, we can apply something like https://github.com/rsanchez/css-color-extractor, which is a PostCSS plugin. Extending that PostCSS plugin to apply color extraction only to ones with the selector beginning with .my-theme should be do-able, too.

[mattrosno]

Here are my findings. Using:

# get file size
du -h filename.css

# get file size when gzipped
gzip -c filename.css | wc -c

You can explore demo/scss/demo.scss to see the custom Sass builds for scenarios 1 - 4 below. I also made temporary changes to gulpfile.js so I had minified demo CSS.

Findings

File	Size	Gzipped
(1) Normal build all components
demo.css	272KB	30.0KB
demo.min.css	216KB	27.2KB
(2) With inline theme all components
demo.css	428KB	47.0KB
demo.min.css	352KB	43.2KB
(3) With inline theme all components using color override mixins
demo.css	328KB	35.4KB
demo.min.css	264KB	32.4KB
(4) With inline theme all components using PostCSS
demo.css	332KB	35.9KB
demo.min.css	272KB	32.7KB

It's clear that (3) file size is much better than (2). As shown in previous commit, color-only override mixins are very tedious and error-prone. (4) uses PostCSS to eliminate the need for authoring color-only override mixins. Using Gulp like so:

const postcss = require('postcss');
const colorsOnly = require('postcss-colors-only');
const removeSelectors = require('postcss-remove-selectors');

const inlineTheme = () =>
  through.obj((file, enc, callback) => {
    // 1. split up default and inline theme declarion blocks
    const defaultCSS = postcss()
      .use(
        removeSelectors({
          selectors: [/.my-dark-theme/],
        })
      )
      .process(file.contents.toString(enc)).css;

    const themeCSS = postcss()
      .use(
        removeSelectors({
          selectors: [/^((?!.my-dark-theme).)*$/],
        })
      )
      .process(file.contents.toString(enc)).css;

    // 2. only keep color declarations for the inline theme
    const themeColorsCSS = postcss()
      .use(colorsOnly())
      .process(themeCSS).css;

    // 3. concatenate default and optimized inline theme
    file.contents = Buffer.from(
      `${defaultCSS}
      ${themeColorsCSS}`,
      enc
    );

    callback(null, file);
  });

gulp.task('sass:dev:compiled', () =>
  gulp
    .src('demo/scss/demo.scss')
    .pipe(sourcemaps.init())
    .pipe(
      header(`
        $feature-flags: (
          components-x: true,
          breaking-changes-x: true,
          grid: true,
          ui-shell: true,
        );
      `)
    )
    .pipe(
      sass({
        includePaths: ['node_modules'],
        outputStyle: 'compressed',
      }).on('error', sass.logError)
    )
    .pipe(
      autoprefixer({
        browsers: ['> 1%', 'last 2 versions'],
      })
    )
    .pipe(inlineTheme())
    .pipe(
      rename(filePath => {
        filePath.extname = `.min${filePath.extname}`;
      })
    )
    .pipe(sourcemaps.write('.'))
    .pipe(gulp.dest('demo'))
    .pipe(browserSync.stream({ match: '**/*.css' }))
);

Recommendation

1. Create issue to update theme from @carbon/elements as shown in first commit. We don't need to touch any lower-level component Sass APIs.
2. Make sure all components are authored in mixins that can be included in inline themes. Also move feature flags around so the user doesn't have to include experimental --x mixins.
3. Document how to override default theme in Sass build and how to inline theme.
4. Document how to use PostCSS to de-dupe CSS when using inline theming.
5. Move component variables to better support whitelabelling to a new RFC.

To reiterate, inline theming works like so, where after primary styles are built, you set your namespace class, whatever global variables you want (or use a helper like carbon--theme-overrides('g90')) and include just the components that you want in that inline theme.

@import '../../src/globals/scss/styles';
@if feature-flag-enabled('components-x') {
  .my-dark-theme {
    @include carbon--theme-overrides('g90');
    @include accordion;
    @include breadcrumb;
    // other components here
  }
}

[photodow]

Just trying to understand, but if y'all decide to go the PostCSS route you're removing duplicate CSS on build and begin to dictate/influence adopter's build process? Am I understanding that option correctly?

Maybe y'all are already doing that, and I'm just improperly building the code base. 🤭

[elizabethsjudd]

@mattrosno Is the gulp work that you did going to actually be delivered to Carbon users? We do this a lot in WH (look at our tools package) and it looks like it's pretty repeatable that it could be distributed with Carbon to users that want it.

To be clear, the new recommendation is that there isn't any new mixins and it's to use PostCSS (btw this was a really interesting concept. I've used PostCSS but not this plugin specifically). My question that still remains about the accordion mixin is currently meant to be private mixins and the name needs changed based on the the feature flag. But the demo code specifically shows the "user" calling these mixins.

[mattrosno]

@photodow my opinion is that Carbon can't optimize product Sass builds, but we can share best practices on how to do so given product needs.

@elizabethsjudd I think it'd be great to define our build tools in an exportable way. Might need to be more of a post-v10 effort.

Correct, my recommendation is to leverage PostCSS and not create new mixins. Related to #1856, I understand the desire to not call --x mixins for inline theming. I'll add that to the recommended TODO list, moving the feature flag in the main mixin. E.g., from:

@mixin accordion {}

@mixin accordion--x {}

@include exports('accordion') {
  @if feature-flag-enabled('components-x') {
    @include accordion--x;
  } @else {
    @include accordion;
  }
}

To:

@mixin accordion {
  @if feature-flag-enabled('components-x') {
    @include accordion--x;
  } @else {
    // styles here
  }
}

@mixin accordion--x {}

@include exports('accordion') {
  @include accordion;
}

So accordion is public to be used in inline themes, and accordion--x is private. Is that what you're looking for?

[scottnath]

Hey @mattrosno, if there isn't a second mixin for colors, but a developer needs alternate color versions of a given component, but they do not have the skillset/permission/access/whatever to change the build process, doesn't that leave them with bloated code and no way to fix it?

This choice feels like it's mixing the skillsets required to use carbon's sass files. It's not abnormal for the front-end UI person to have no access to changing the build processes. Seems like this hurdle could be avoided if the white-label-able parts were in their own mixin.

[asudoh]

Great to hear that @mattrosno could achieve optimization to CSS output he needed! Given that, the only question here seems whether we want to make component mixins public. Given it was originally for stable/experimental switch and had no intention to make it public, we need to be careful to some extent. e.g.:

1. Should the component mixin take a theme token map as an optional argument, defaulting to the one of the applied theme?
2. Should we rename stable mixin so we can use that name (e.g. @mixin button) for entry-point purpose (doing stable/experimental switch inside)? - This discussion item will be stale once we do cleanup to eliminate stable code after v10 release, but just wanted to note

@scottnath

It's not abnormal for the front-end UI person to have no access to changing the build processes.

PostCSS we are discussing here is similar to Sass compiler from the perspective of the complexity of build toolchain setup - Instead of introducing a big leap there. PostCSS generates a mangled version of .css from a .css file, similar to Sass compiler that generates a .css file from a .scss file. Hope this makes sense.

[joshblack]

Hey @mattrosno! 👋 Seems like the RFC has gone quiet, are we down for closing it and moving forward with the theme work over in elements?