CSS Architecture Guidelines

  • lack of clarity — what bring tons of confusions e.g. not clear dependency (we are afraid about removing and adding things),
  • no maintainability — inefficiency while creating new and improve existed code,
  • duplications — makes things very bloated and has negative impact for performance,
  • lot’s of problems with scalability, consistency and on-boarding new developers.


.page-quick-sidebar-wrapper .page-quick-sidebar .page-quick-sidebar-chat .page-quick-sidebar-chat-user .page-quick-sidebar-chat-user-messages .post.out .message .arrow {


Creating selectors


  • name something based on what it is, not how it looks or behaves.
  • in general it’s better to have longer class name than more complex specificity.
  • .u-hide-text (“u” communicates that it’s utility class with a specific purpose. It may be used in many places and should not be extended. Typically you want to make sure that utility class will always win specificity battle. Therefore using !important it’s not bad practice for that case.)
  • .l-main-nav (“l” means layout or component class. Used to group modules into components and position them within the page)
  • .b-main-nav (“b” prefix can be applied to main blocks/modules wrappers)
  • .js-header-animate (“js” communicates that it’s class used only by JavaScript. It prevents from accidentally breaking behavior or breaking tests based on class name)


  • you want to use only classes to build your selectors. In most cases your selector is one unique & meaningful class.
  • class name starts with name of block/module, next one is name of element (preceded by two underscores), ends with modifier name (preceded by two dashes). e.g. .main-nav__item — current
  • modifiers can be applied either to blocks and elements.
  • can’t have element outside it’s block
  • you can nest elements within its block, but in that case do not write selectors like .block__element1__element2. Always use: .block__element1 .block__element2
  • block are independent and share only most common styles (resets and a few base styles). This reduce amount of code and make it reusable.
  • you don’t want to apply positioning styles directly to block/module. This is why we want to use layout classes.
  • modular CSS code. It makes CSS easy to convert to React world where you often want to have separate css file for each component.
  • very low specificity,
  • decoupled HTML structure from CSS,
  • improved readability (you can understand much more about CSS while looking at HTML)
  • no more naming collisions (isolated modules helps to avoid putting CSS into global scope).
  • clear rules how to name new elements inside a block
  • no more problems with cascade inherited styles (accidental leaking of styles to places where you don’t want them).
  • smaller HTML by reducing classes and making HTML reusable.

Mobile First

Components, Modules and Elements

Files & catalogs structure organisation

  1. vendor styles (frameworks, plugins styles)
  2. Next ones are our utils. We want to load all variables, mixins and other helpers (classes, placeholders).
  3. If we don’t use a frameworks which provides CSS reset then we definitely want to include normalize.css (or similar) plus our custom resets and base styles.
  4. Finally we can include layout and modules styles.




Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Andrzej Perliński

Andrzej Perliński

More from Medium

First Blog Post

CSS Preprocessors

CSS Specificity

CSS Grid Layout