Skip to main content
U.S. Flag

An official website of the United States government

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

Diagram explaining the parts of an example CSS class '.ds-c-button--outline' where DS is namespace, C is the type prefix, and the rest follows BEM syntax


To avoid conflicting with other libraries and existing code, the design system namespaces its CSS class names with ds-.


Prefixes are added to class names to make it more apparent what job the class is doing.

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.


The CSS naming convention outlined here was heavily influenced by: