Skip to main content

Design System

Code conventions

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: