RFC: naming classes

[joneff]

Long story short: our class names are ambiguous enough to not be clear which class name means what... Not always, mind you, but close enough.

For instance, previously we used k-button-icon to denote a button that only has icon. However, when it came to adding a class name to icons inside the button we also icon k-button-icon, which was mildly confusing.

In other words, we need some order in the chaos. As of now, the best idea seems to be almost BEM or BEM with exceptions. What do I mean by that? Let's first see what BEM is.

BEM stands for:

• Block -- Standalone entity that is meaningful on its own;
• Element -- A part of a block that has no standalone meaning and is semantically tied to its block;
• Modifier -- A flag on a block or element. Use them to change appearance or behavior.

It's a convention that aims to name things in a way that is not confusing and is clearly distinguishable what is what in a web page"

// Block
.block {}

// Element
.block__element {}

// Modifiler
.block--modifier {}
.block__element--modifier {}

Before I get to how it may applies to us, I will try to answer a couple of questions that may already be coming this way:

Why should we use BEM?

We don't have to use BEM. We can use anything as long as the class names are easily read. Here a couple of other instances:

MUI (ex Material UI) are using a very interesting combination of PascalCase for their components: MuiButton-root MuiButton-contained MuiButton-containedPrimary MuiButton-sizeMedium MuiButton-containedSizeMedium MuiButtonBase-root.

Amazon are using something similar to what we are currently: a-button a-button-selected a-button-thumbnail a-button-toggle. DevExpress are also using simple dash notation.

Who is using BEM?

Yandex, Material Components for Web, Carbon Design System. Is this argument valid at all?

How do we apply it to Kendo UI?

Well, it's simple, really -- every component is a block and its parts are elements. Of course, any child can also be a block too, like the icon is, so it must have classes for both. Modifiers could be the component options.

// a simple button
.k-button {}

// text inside button
.k-button__text {}

// a text button
.k-text-button {}

// a text button with wrong wording, but still distinguishable from text inside a button
.k-button-text {}

// And some examples I don't fully agree

// a hovered menu item
.k-menu__item--hover {}

// a menu item in hovered menu
.k-menu--hover__item {}

The last two rules is not something I fully agree with:

• to me, hover stats should be a separate class like k-disabled, k-hover, k-required etc...
• if we need to target a child item in a parent with state, we should use that selector, and not a modifier one e.g. k-menu.k-hover .k-menu__item

Apart from that, BEM suits us.

I am aware that this is a much bigger change than simple tweaking a few class names... Thoughts?

cc @telerik/web-components-and-tools

[Stamo-Gochev]

Can you provide additional examples, so we can better evaluate some more complex scenarios? From the currently provided examples, it seems to me that there isn't a "strongly" established naming convention that fits the scenarios (or hasn't been followed strictly enough due to problems), e.g. considering the above:

// a simple button
.k-button {}

// text inside button
.k-button__text {}

// a text button
.k-text-button {}

// a text button with wrong wording, but still distinguishable from text inside a button
.k-button-text {}

I would expect k-button-text to be used for the text element (probably a span) inside a button, and k-text-button for a different type of button that we call "text button". Thus the selector follows the structure of the component - k-button-text is button > text. The same applies to a button with an icon (k-button-icon) and an "icon button" (if such a thing exists at all) - k-icon-button. We tend to follow a convention, but maybe we have introduced some conflicting classes along the way that might need a revision, but the general structure seems applicable - k-{component-name}-{component-element}.

As for the states - I suppose having separate classes like k-focused, etc. are necessary not only for syntax reasons but also to make an explicit distinction as modifiers as well as imply a common technique for applying states - you need to add the state's class instead of a longer alternative like k-grid-command-button--focused. Whether we agree with this approach can be reconsidered though - I might not have all the details here.

Regarding the syntax - my very opinionated view is that BEM syntax (I agree we are using it as a reference, the exact syntax can be different, but I will still refer to it) is a bit verbose to read. I also do not like the other approach with mixed PascalCase and kebab-case - I find it harder to read and understand. If we really really want to use a mixed approach, then mixing kebab-case and snake_case might be better (something similar to what BEM does, but with doubling the delimiter), e.g. k-grid_content, although k-grid-content is expressive enough to me.

In addition, is there a real benefit for us of having an explicit delimiter to separate the k-{component-name}-... from the rest of its children? Looking at k-grid-content, it is not hard to get that there isn't a "grid content" component, but rather a grid component with a content element.

Seems like it boils down more to the order of words rather than strictly looking for some delimiters, e.g. k-button__icon might still be confused with k-button-icon (or it is not distinguishable enough), but k-button-icon and k-icon-button are more distinctive. We do have the separation of state classes, which might mean we can skip the --{modifier} convention and make a revision of word order only. This might also mean softer breaking changes compared to fully migrating to a new naming convention.

[tsvetomir]

The BEM convention seems to be geared towards components, which is great. As noted, that puts it at odds with the idea of global selectors, e.g. for state, that we use in the theme.

So we get a watered-down version of BEM at a huge cost for both us and customers. Doesn't look like a great deal.