CSS architecture

As websites can get bigger, keeping your CSS codebase clean, scalable, maintainable, and light is critical to support performance and speed-up development time.

Problem: Bad CSS structure leads to chaos

Without a clear logic for organising your CSS, it's easy to end up with a chaotic system and heavy CSS files — with duplicated properties — that highly impact your site's performance and user experience.

Also, without a consistent CSS architecture, navigating through the CSS can become a nightmare for you or any other developer that needs to work on your stylesheets.

Solution: Organise your CSS files

To gain efficiency and optimise your CSS for performance, architect your CSS files in a way that embraces CSS Cascading and inheritance.

The main idea of this approach is to build your pages from components. Think at component level—or blocks when you work with styles to build your UI. Only use page-specific CSS to adjust layout styles.

Our process of writing and structuring CSS files is based on SASS and takes inspiration from the CUBE CSS Methodology.

We use this approach to build a clean CSS codebase, by using the power of the CSS cascade algorithm and inheritance.

Overview of our CSS files architecture

Sass/
        
1. base/
        _mixins.scss
        _reset.scss
        _settings.scss
        _system.scss
        
        page/
          _global.scss
          _header.scss
          _footer.scss
        
        typography/
          _links.scss
          _paragraphs.scss
          _headings.scss
          _lists.scss
          _tables.scss
          _other.scss
          
2. utilities/
        _colour.scss
        _center.scss
        _container.scss
        _dropcap.scss
        _grid.scss
        _radius.scss
        …
        
3. blocks/
        _buttons
        _hero.scss
        _footer
        _header.scss
        …
        
4. site-specific/
        _about.scss
        _article.scss
        …
        
styles.scss

File structure breakdown

Let’s detail each folder and files:

• 1. Base

  This layer includes the high-level CSS rules, the foundation styles and global custom properties variables of the design.

  _settings.scss:

  This file contains the global variables for foundation styles of the website(e.g. spacing, color, typography…).

  _mixings.scss

  This file includes chunks of reusable CSS rules like media query breakpoints or a rule for specifying static font sizes.

  _reset.scss

  This file contains the Modern CSS Reset file from Andy Bell to reset the default browsers’ styles and avoid any inconsistencies across different browsers.

  _system.scss

  This file contains all the CSS rules required to adjust the styles of the admin interface of your website.

  page/

  This folder contains page global, header and footer layout styles. These rules are organised under the following partial files:

  • _global.scss
  • _header.scss
  • _footer.scss

  typography/

  This folder contains partial files with CSS rules of common typographic elements such as paragraphs, links or headings.

  • _links.scss
  • _paragraphs.scss
  • _headings.scss
  • _lists.scss
  • _tables.scss
  • _other.scss

• 2. Utilities

  This layer includes a list of helper classes that consist of a single CSS rule or a group of related CSS rules useful to style multiple elements consistently and quickly.

  To avoid repeating CSS rules, we use utility classes when appropriate to style HTML elements consistently.

  Utility classes can contain a single property or a group of related CSS properties to define text colors, background colours, border radius, drop caps, borders or any other reusable style.

• 3. Blocks

  This layer contains files with specific CSS rules for each Building blocks that compose the layout.

  Blocks refer to a simple UI element like a button or a group of UI elements like a card, hero section or menu. The CSS rules are applied using the parent block class.

  The benefit of styling a component using the block class is that the block will maintain its original style, regardless of the context it's placed in.

• 4. Site specific

  This layer contains the CSS rules applied with the parent body class to style specific page—or content type layouts.

  This folder contains the partials files of individual pages, content-types or templates, including their specific CSS rules required to adjust/override the layout styles.

• styles.scss

  This file includes the imported partials to generate the final style.css file.

  The style.scss file is the source file where we import the required .scss partials to create the final style.css file that the browser will use to load the styles of your website.

  ➜  assets sass --watch sass:css

  This command tells SASS to preprocess the SASS files that are located inside /assets and output the final css inside the folder /css.

Takeaways

• Write high-level CSS and global variables inside /base
• Use utility classes to style common elements consistently
• Add content-block styles inside their partial file inside /blocks
• Add page or template-specific CSS inside /site-specific
• Keep your CSS styles light

Resources

• Andy Bell: Browser’s Mentor, Not Micromanager + Cube CSS
• CUBE CSS Methodology
• Why are we bad at CSS?

Don't Start With Visuals

By Jerome Kalumbu

A creative approach with UX design tips to help you design effective and engaging websites.

Discover E-book