Fetching contributors…
Cannot retrieve contributors at this time
37 lines (22 sloc) 2.59 KB



We need a method of managing CSS complexity at scale, as many developers contribute and share styling across many applications. Styles must not overlap or conflict inadvertently, which causes non-deterministic behaviour and defects. It must be easy for developers to do the right thing, even if they are not experts at CSS.


In a component architecture, co-locating styles with components is an appropriate strategy to deal with this complexity.


An often-used methodology is an agreed-upon naming convention for CSS classes, such as BEM (Block-Element-Modifier). While conventions are useful, everyone must always remember to follow the BEM rules. This results in a manual process that is prone to mistakes.


The preferred approach is to use automated build-time style scoping in combination with co-location of styles and components. With minimal tooling, styles are scoped automatically as part of the application's build process. This allows the developer to use the class names that make the most sense for each component (or to stop manually writing class names altogether), without worrying about style conflicts or inadvertent class name overriding.


While we do not currenly have a standardized technology to handle automated build-time style scoping, there are a few libraries in use today, including styled-components and CSS Modules. We hope to soon agree on a recommended technology.

We also have some best practices to follow when styling applications:

  • Always try to reuse existing styles and components (such as TDS components) before creating new styles.
  • Write styles in JavaScript (CSS-in-JS) rather than using a pre-processor such as Sass or plain CSS.
  • Follow the "styled component" pattern by attaching styles directly to components.
  • Push logic out of CSS into JavaScript (such as animations, pseudo-states such as :hover/:focus, media queries) so that the code is easier to reason about, test, and maintain.
  • Share functionality via components instead of CSS classes (even layout or animations can be created as components).