The design system favors clarity over succinctness. This means the design system may be verbose, but it should deliver clarity, predictability, and legibility in exchange.
CSS class naming convention
Namespace
To avoid conflicting with other libraries and existing code, the design system namespaces its CSS class names with ds-.
Prefix
Prefixes are added to class names to make it more apparent what job the class is doing.
| Prefix | Description |
|---|---|
l- | Indicates layout-related styles. Example: .ds-l-container |
c- | Indicates a component. Example: .ds-c-button |
u- | Indicates a utility. Example: .ds-u-color--base |
These prefixes can sometimes be followed by a "breakpoint prefix". Learn more about breakpoint prefixes.
BEM syntax
Following the namespace and prefix is a name conforming to BEM syntax.
Put all together, a CSS class can be broken down to these key parts: [NAMESPACE]-[PREFIX]-[BLOCK]__[ELEMENT]--[MODIFIER]
- Block is a standalone entity that is meaningful on its own. For example:
.ds-c-card,.ds-c-button - Element is a part of a block that has no standalone meaning and is semantically tied to its block, such as
.ds-c-card__title - Modifier is a flag on a block or element and is used to change appearance or behavior. For example:
.ds-c-button--primary,.ds-u-color--base,.ds-l-col--3
BEM’s strict naming rules can be found here.
Credits
The CSS naming convention outlined here was heavily influenced by:
- CSS Architecture for Design Systems, by Brad Frost
- Thoughtful CSS Architecture, by Nathan Rambeck
- More Transparent UI Code with Namespaces, by Harry Roberts