USS Writing style sheets

To keep things organized, UI Toolkit has adopted BEM as the methodology for styling elements. While using BEM is not mandatory, it is recommended.

About BEM

BEM stands for Block Element Modifier. BEM is a simple system that helps you write structured, non-ambiguous, easy to maintain selectors. With BEM, you assign classes to elements and then use these classes as the selectors in style sheets.

BEM classes have up to three components:

• Block name: a block is a meaningful, standalone entity or control. For example, menu, button, list-view
• Element name: a part of a block that has no standalone meaning and is semantically tied to its block. Element names are appended to the block name using two underscores. For example, menu__item, button__icon, or list-view__item
• Modifier: a flag that changes the appearance or behavior of a block or element. Append a modifier to a block or element name with two dashes. For example, menu--disabled, menu__item--disabled, button--small, or list-view__item--selected.

Each name part may consist of Latin letters, digits, and dashes. Each name part is joined together with either a double underscore __ or a double dash --.

The following example shows XML code for a menu:

<VisualElement class="menu">
    <Label class="menu__item" text="Banana" />
    <Label class="menu__item" text="Apple" />
    <Label class="menu__item menu__item--disabled" text="Orange" />
</VisualElement>

Selectors

Since each element is equipped with classes that describe its role and appearance, you can write most of your selectors with only one class name:

.menu {
}

.menu__item {
}

.menu__item--disabled {
}

You should be able to style elements using a single class name. However, in some cases, you may need to use complex selectors. For example, you could use a complex selector when the style of an element depends on the modifier of its block:

.button {
}

.button__icon {
}

.button--small {
}

.button--small .button__icon {
}

Be careful that you do not specify long selectors. A long selector could indicate inconsistencies in the graphic design of your UI. You should also avoid using type names (Button, Label) or element names (#my-button) in your BEM selectors.

Making VisualElement BEM-friendly

UI Toolkit adheres to BEM. Each visual element has the necessary class names attached. For example, all TextElement have the unity-text-element class. Each instance of Button, which derives from TextElement, has its class list populated with the unity-button and unity-text-element classes.

If you derive a new element from VisualElement or one of its descendants, following these guidelines to ensure that your element is easy to style using the BEM methodology:

• Use AddToClassList() in the constructor to add the relevant USS classes to your element instances.
• If your new element instantiates child elements in its constructor, assign the relevant classes to the children. For example, my-block__first-child, my-block__other-child.
• If your element supports multiple states or variants, such as small and large, add and remove relevant classes when the element state changes or when the element variant is selected.
• If your element is meant to be used in other projects, consider prefixing your classes to avoid conflicts with existing user class names.