[carbon-components]: component tokens.scss files import CSS reset and base styles

[vronjec]

What package(s) are you using?

• carbon-components
• carbon-components-react

Detailed description

Describe in detail the issue you're having.

We are trying to create a global theme file (containing multiple themes) that can be used across independent microservices. Ideally, the theme file should only contain CSS variables that can be consumed by any microservice without altering their base (h1, p, img) styles.

Our approach to creating such a theme file:

// theme.scss
@import 'carbon-components/scss/globals/scss/feature-flags';
$feature-flags: map-merge($feature-flags, ('enable-css-custom-properties': true));

@import '@carbon/themes/scss/themes';
@import 'carbon-components/scss/globals/scss/import-once';

// components that emit tokens
@import 'carbon-components/scss/components/tags/tokens'; // <--- imports reset and base styles
@import 'carbon-components/scss/components/notification/tokens'; // <--- imports reset and base styles

@include exports('theme') {
  :root {
    @include carbon--theme($carbon--theme--g10, true) {
      @include emit-component-tokens($tag-colors);
      @include emit-component-tokens($notification-colors);
    }
  }

  body.dark-theme {
    @include carbon--theme($carbon--theme--g100, true) {
      @include emit-component-tokens($tag-colors);
      @include emit-component-tokens($notification-colors);
    }
  }
}

Unfortunately, the component imports (e.g. carbon-components/scss/components/tags/tokens, carbon-components/scss/components/notification/tokens, etc) also include CSS reset and base styles.

So the resulting CSS will look like this:

@charset "UTF-8";
html,
body,
div,
span,
applet,
object,
iframe,
h1,
h2,
h3,
h4,
h5,
h6,
p,
blockquote,
pre,
a,
abbr,
acronym,
address,
big,
cite,
code,
del,
dfn,
em,
img,
ins,
kbd,
q,
s,
samp,
small,
strike,
strong,
sub,
sup,
tt,
var,
b,
u,
i,
center,
dl,
dt,
dd,
ol,
ul,
li,
fieldset,
form,
label,
legend,
table,
caption,
tbody,
tfoot,
thead,
tr,
th,
td,
article,
aside,
canvas,
details,
embed,
figure,
figcaption,
footer,
header,
hgroup,
menu,
nav,
output,
ruby,
section,
summary,
time,
mark,
audio,
video {
  margin: 0;
  padding: 0;
  font: inherit;
  font-size: 100%;
  vertical-align: baseline;
  border: 0; }

...

h1 {
  font-size: var(--cds-productive-heading-06-font-size, 2.625rem);
  font-weight: var(--cds-productive-heading-06-font-weight, 300);
  line-height: var(--cds-productive-heading-06-line-height, 1.199);
  letter-spacing: var(--cds-productive-heading-06-letter-spacing, 0); }

h2 {
  font-size: var(--cds-productive-heading-05-font-size, 2rem);
  font-weight: var(--cds-productive-heading-05-font-weight, 400);
  line-height: var(--cds-productive-heading-05-line-height, 1.25);
  letter-spacing: var(--cds-productive-heading-05-letter-spacing, 0); }

...

:root {
  --cds-interactive-01: #0f62fe;
  --cds-interactive-02: #393939;
  --cds-interactive-03: #0f62fe;
  --cds-interactive-04: #0f62fe;
  --cds-ui-background: #f4f4f4;
  --cds-ui-01: #ffffff;
  --cds-ui-02: #f4f4f4;
  --cds-ui-03: #e0e0e0;
  --cds-ui-04: #8d8d8d;
  --cds-ui-05: #161616;
  --cds-text-01

...

This causes various styling issues across the consuming microservices, and as such, we can't rely on any component _tokens.scss for theming purposes right now.

Is this issue related to a specific component?

It is related to all Carbon component that use their own tokens for styling (e.g. tag, notification, etc).

What did you expect to happen? What happened instead? What would you like to
see changed?

We would like to be able to include component _tokens.scss files without any additional styling changes.

Alternatively, component tokens could be part of the theme imports, so that there is no need to import _tokens.scss separately at all.

What version of the Carbon Design System are you using?

• carbon-components: 10.33.0
• carbon-components-react: 7.33.0

What offering/product do you work on? Any pressing ship or release dates we
should be aware of?

Related issue on Cloud PAL: https://github.ibm.com/ibmcloud/pal/issues/4430

[finken2]

A few other references:
i talked through the token import w/ @tw15egan here: #8196
and the PR that originally tokenized: #7808

[tw15egan]

You can also set $css--reset: false above the imports if you do not wish to include the reset file

[joshblack]

As @tw15egan noted, I believe you will need to set $css--reset to false to exclude any reset styles for this kind of use case.

Unfortunately having these files not bring in the reset would be considered a breaking change (since the emitted CSS would change) but we could totally look at having this behavior in v11 where component modules don't necessarily bring in the reset.

[vronjec]

Setting $css--reset: false; above @import 'carbon-components/scss/components/tags/tokens'; will still print the base styles like so:

@charset "UTF-8";
h1 {
  font-size: var(--cds-productive-heading-06-font-size, 2.625rem);
  font-weight: var(--cds-productive-heading-06-font-weight, 300);
  line-height: var(--cds-productive-heading-06-line-height, 1.199);
  letter-spacing: var(--cds-productive-heading-06-letter-spacing, 0); }

h2 {
  font-size: var(--cds-productive-heading-05-font-size, 2rem);
  font-weight: var(--cds-productive-heading-05-font-weight, 400);
  line-height: var(--cds-productive-heading-05-line-height, 1.25);
  letter-spacing: var(--cds-productive-heading-05-letter-spacing, 0); }

... 

:root {
  --cds-interactive-01: #0f62fe;
  --cds-interactive-02: #393939;
  --cds-interactive-03: #0f62fe;
  --cds-interactive-04: #0f62fe;
  --cds-ui-background: #f4f4f4;
  --cds-ui-01: #ffffff;
  --cds-ui-02: #f4f4f4;
  --cds-ui-03: #e0e0e0;
  --cds-ui-04: #8d8d8d;
  --cds-ui-05: #161616;
  --cds-text-01: #161616;
  --cds-text-02: #525252;

...

So I went ahead and set $css--default-type: false; as well, and the token import will then only print:

@charset "UTF-8";
@-webkit-keyframes skeleton {
  0% {
    -webkit-transform: scaleX(0);
            transform: scaleX(0);
    -webkit-transform-origin: left;
            transform-origin: left;
    opacity: 0.3; }
  20% {
    -webkit-transform: scaleX(1);
            transform: scaleX(1);
    -webkit-transform-origin: left;
            transform-origin: left;
    opacity: 1; }
  28% {
    -webkit-transform: scaleX(1);
            transform: scaleX(1);
    -webkit-transform-origin: right;
            transform-origin: right; }

... 

:root {
  --cds-interactive-01: #0f62fe;
  --cds-interactive-02: #393939;
  --cds-interactive-03: #0f62fe;
  --cds-interactive-04: #0f62fe;
  --cds-ui-background: #f4f4f4;
  --cds-ui-01: #ffffff;
  --cds-ui-02: #f4f4f4;
  --cds-ui-03: #e0e0e0;
  --cds-ui-04: #8d8d8d;
  --cds-ui-05: #161616;
  --cds-text-01: #161616;
  --cds-text-02: #525252;

...

I'm not sure how to turn off the keyframes though. We could assume that the keyframe definitions are unlikely to cause many issues in "third-party" code, so let's leave it at that.

However, the issue with this approach is that now we have disabled the Carbon reset and base styles globally outside the theme file as well (which also brakes styling in microservices). I tried setting $css--reset and $css--default-type back to true at the end of the theme file, but the reset and base styles still won't be part of other component's CSS:

// theme.scss
@import 'carbon-components/scss/globals/scss/feature-flags';
$feature-flags: map-merge($feature-flags, ('enable-css-custom-properties': true));

@import '@carbon/themes/scss/themes';
@import 'carbon-components/scss/globals/scss/import-once';

$css--reset: false;
$css--default-type: false;

@import 'carbon-components/scss/components/tags/tokens'; // <--- no longer imports reset and base styles
@import 'carbon-components/scss/components/notification/tokens'; // <--- no longer imports reset and base styles

@include exports('theme') {
  :root {
    @include carbon--theme($carbon--theme--g10, true) {
      @include emit-component-tokens($tag-colors);
      @include emit-component-tokens($notification-colors);
    }
  }

  body.dark-theme {
    @include carbon--theme($carbon--theme--g100, true) {
      @include emit-component-tokens($tag-colors);
      @include emit-component-tokens($notification-colors);
    }
  }
}

$css--reset: true;
$css--default-type: true;

// <-- reset and base styles are still not being imported outside the theme file

Is this because import-once still applies to the reset and base styles? Is there a way to get around it?

[joshblack]

@vronjec thanks for the detailed response! It helps a ton when tracking this stuff down.

Could you speak more to the output that you would expect from including the tokens file? is it that no CSS should be emitted and that it's used for only variables?

[vronjec]

Yes, the intent with the theme file is that it contains color related CSS variables only, so it can be served globally to all microservices. Any additional styles would conflict with various services: https://github.ibm.com/Bluemix/core-dev/issues/10513.

So to reiterate, our issue is that we were hoping to acquire the component specific tokens for tags and notifications through the _tokens.scss files, but received additional styles along with the CSS variables. Disabling those styles using $css--reset and $css--default-type seems to disable them outside the theme file as well, which is also not what we would want.

[joshblack]

Awesome, thanks so much @vronjec that helps a ton 🙏

I think the reset is ultimately coming from the import to scss/globals/scss/theme in component-tokens. I think we can have the component token files for tag/notification import from theme-tokens directly instead of the component-tokens file / theme file directly and it should get around this reset issue.

Curious what you think @tw15egan 🤔

[tw15egan]

@joshblack Yeah I think that may do the trick