Improve CSS reuse by leveraging BEM and SASS.

[delapuente]

In #326 we resolved to use BEM while keeping scoped stylesheets as a methodology. Beyond using it as a merely naming convention, we started to use mixes to leverage composition when dealing with components.

However, as we get into creating more complex components, re-styling and adapting the Carbon Framework components or integrating with user-defined content (where we cannot control the classes the HTML elements have), we realized we need some way of reusing CSS code in different places. Right now, we copy and paste in several places, reducing maintainability.

We should be able to define something like:

.copy__paragraph {
  font-size: 16px;
  font-weight: light;
  color: #ddd;
}

And, in a different place, styling a Carbon component should not be harder than:

.user-content p {
  /* Same as .copy__paragraph */
}

Also, styling user-defined content should be as easy as:

.custom-component .carbon-button {
  /* Same as .copy__paragraph */
  color: purple;
}

This way, when .copy__paragraph changes, everything gets updated.

As a methodology, BEM is not intended to solve any of these problems. For that, we are using the CSS preprocessor SASS. Although almost unused right now, SASS has the means to create abstract portions of CSS code to be reused such as mixins or extension classes.

The former example could be written as:

/* copy.sass file */

@mixin copy__paragraph {
  font-size: 16px;
  font-weight: light;
  color: #ddd;
}

.copy__paragraph {
  @include copy__paragraph;
}

The Carbon component could be re-styled with:

@use './copy.sass';

.user-content p {
  @include copy__paragraph;
}

And the user-defined content with:

@use './copy.sass';

.custom-component .carbon-button {
  @include copy__paragraph;
  color: purple;
}

We need to better understand SCSS to leverage code reusing features like the ones mentioned above and aim at better reuse of CSS code.

[delapuente]

Open discussion: the correct level of abstraction

This is an open discussion, @y4izus @techtolentino please do some research and dump your thoughts before the refactor sprint starting on Monday, 21st. Also contribute with articles you read, methodologies you find or your personal experience. Accompany your comments with code examples if possible. I've left some interesting reads at the end of my comment.

BEM mixes enable the separation of concerns and the single-responsibility principles in CSS. A component can be seen as a composition of different classes:

<p class="card__author copy__paragraph ">
  <span class="card__author-name copy__paragraph">Salva</span>
  <span class="card__author-surname copy__paragraph">de la Puente</span>
</p>

BEM mixes are also semantic and easy to debug since they refer to different CSS classes combined with the native mechanisms of the Web. The different aspects of a component are right in front of you.

However, extensive use of BEM mixes can hinder the readability of the component. Arguibly, the following component is now harder to read than before although it makes clear what dimensions take part in styling the component:

<p
  class="
    card__author
    copy__paragraph
    layout__flex
    layout__flex_vertical
    layout__vertical-spacer
    layout__vertical-spacer_big
  "
>
  <span class="card__author-name">Salva</span>
  <span class="card__author-surname">de la Puente</span>
</p>

An extreme case would be using utility classes: useful for limiting the number of property combinations and write a well defined CSS API, also utterly verbose and hard to read:

<p
  class="
    bc-purple
    bw-1
    fnt-sz-16
    c-purple
    dp-flex
    dp-flex-v
    mg-b-160
  "
>
  <span class="fnt-sz-16 c-purple fnt-w-b">Salva</span>
  <span class="fnt-sz-16 c-purple fnt-st-i">de la Puente</span>
</p>

The other extreme case would be having everything under BEM classes and doing:

<p class="card__author">
  <span class="card__author-name">Salva</span>
  <span class="card__author-surname">de la Puente</span>
</p>

Then:

@use './copy.scss';
@use './layout.scss';
@use './utility.scss';

.card__author {
  @include copy__paragraph;
  @include layout__flex;
  @include layout__flex_vertical;
  @include layout__vertical-spacer;
  @include layout__vertical-spacer_big;
  border-color: $purple;
}

.card__author-name {
  @extend .copy__paragraph;
  font-weight: bold;
}

.card__author-surname {
  @extend .copy__paragraph;
  font-style: italics;
}

My preference is the latter, trying to hide the complexity in the lower layers of CSS and SASS. However, I somehow miss the components exposing their main constituents dimensions like in the first example:

<p class="card__author copy__paragraph ">
  <span class="card__author-name copy__paragraph">Salva</span>
  <span class="card__author-surname copy__paragraph">de la Puente</span>
</p>

What do you think?

More to read:

• In Defense of Utility-First CSS.
• CSS Utilit Classes and Separation Of Concerns

[delapuente]

I'd say this is XL since we need to do a small research, come up with an architecture, implement it and check we did not mess up with anything.

[eddybrando]

As part of this issue, I'd like to address the fact that we're currently importing global styles in components in order to avoid FOUC. But this is generating duplicated CSS.

We need to think about this when refactoring the CSS. If we import global styles only to scope them again, it's meaningless to have them be imported globally in the first place.

Here is an example of the current situation in the /learn page: