CSS Documentation Guidelines - Entropic-Visio/swe-pioneers GitHub Wiki

What is CSS?

CSS or Cascading Style Sheets is a language which helps us specify the presentation and design of a documents which are typically written in markup languages such as HTML. CSS can be used for very basic document styling, some examples of things you can do in CSS are changing the colour and size of headings, links and texts. CSS can also be used for animation and effects.[1]

CSS is typically a rule based language. You define rules by specifying groups of styles that should be applied to particular elements or groups of elements on your web-page.[1]

What is BEM?

BEM stands for Block, Element, Modifier. The philosophies behind BEM is to increase the speed of development and ease the teamwork for developers by arranging CSS classes into independent modules. An example of BEM is header__form--search. [1]

Block

A block is a standalone component or module which has a meaningful function. Blocks tend to be larger sections of web-pages, and typically used for headers, navigation-menus, sidebar, footers and many other components of websites. In BEM block names are written in lowercase and are separated with hyphens(-).

Examples

.header { /* Styles for header block */ }
.menu { /* Styles for menu block */ }

Element

An element by itself does not have a meaning, and only becomes meaningful when it is within the context of a block. A element should be tied to a block. Elements are denoted by two underscores(__) following the block name, which is followed by the element name.

Example

.header__logo { /* Styles for header's logo element */ }
.menu__item { /* Styles for menu items within the menu block */ }

Modifier

Modifiers are typically flags which modify or change the appearance or behaviour of a given block or element. Modifiers are prefixed with two hyphens (--), they are usually added to a block or element. Modifiers allow the variation of blocks or elements without the need of duplicating CSS code.

Example

.header--highlighted { /* Styles for highlighted header block */ }
.menu__item--active { /* Styles for active menu items */ }

Examples of BEM, Good Practices and Bad Practices

Here are some more examples, to give you a better understanding of what to do and what to avoid. If you ever feel like your stuck on understanding BEM please skim through this and apply it in your work.

Good Practice

/* Block */
.menu{   } 

/* Block__Element */
.menu__menuOption {   } /* We -- to seperate the element from the block

/* Block--Modifier*/
.menu--black {   }  /* We __ to seperate the modifer from the block

/* Block__Element--Modifier */
.menu__menuOption--black {   }

/* Block Level Modifier */
.menu--black .menu__menuoption {   }

Bad Practice

/* Block--Element */
.menu .menu--menuOption {   } /* We -- to seperate the element from the block */
div.menu--menuOption {  }

/* Block__Modifier*/

.menu__black {  }  /* We __ to seperate the modifer from the block */
div.menu__black {  }

/* Block--Element__Modifier */
div.menu--menuOption__black {   }

Semantics and Structure

As a collaborative project we must maintain semantic class names and a structured approach to all our CSS documents. This is completely vital for readability and maintainability of this repository.[2]

Class and ID Naming

It is vital that you prioritize purpose over aesthetics when naming classes and IDs, this is to ensure that there is clarity and maintainability. Therefore we can produce self documenting CSS code which requires less documentation.[2]

Example

.featuredContent { /* Styles for featured content */ }
.featuredArticle { /* Styles for featured articles */ }

Order of Styles

Arrange your CSS styles strategically and logically mirroring the flow and structure of the HTML file. Group styles based on components/modules and differentiate between structural(layout and positioning) and skin(colours and fonts) styles.

Example

<body>
    <header> 
        <h1>My Website</h1>
    </header>
    
    <nav>
        <ul>
            <li><a href="#">Home</a></li>
            <li><a href="#">About</a></li>
            <li><a href="#">Contact</a></li>
        </ul>
    </nav>
</body>
header { /* links to the header in html file */
    background-color: #333;
    color: #fff;
    padding: 20px;
    text-align: center;
}

nav { /* links to the nav in html file */
    background-color: #444;
    padding: 10px;
}

Responsive Design

All types of technology is out than can view a webpage and so we want to adapt our layout and styling of the webpage based of the screen size or device.

Ensure that CSS practice conform to all devices and can be adjusted to different layouts and screen sizes and devices to ensure optimal user experience across various platforms and mediums.

Commenting

Ensure that you are using self-documenting code for example descriptive block names, element names and modifiers, and ensure you are clearly explaining the purpose of your code enhancing code readability, understanding and maintainability.

Storage and Implementation of CSS files

Implementation of CSS files

External CSS files should be implemented to keep code well organized and maintainable.

Example

<head>
    <link rel="stylesheet" href="styles/example.css">
</head>

References

[1]M. MDN, “What Is CSS?,” MDN Web Docs, Feb. 12, 2024. https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/What_is_CSS ‌

[2]“What Makes For a Semantic Class Name?,” CSS-Tricks, Aug. 04, 2011. https://css-tricks.com/semantic-class-names/ (accessed Feb. 12, 2024).

[3]R. Dodson, “CSS Semantics: Best Practices,” Rob Dodson, Jun. 09, 2012. https://robdodson.me/posts/css-semantics/#:~:text=Perhaps%20an%20easier%20way%20to (accessed Feb. 12, 2024).

[4]R. Jebin, “What are the best practices for naming CSS classes and IDs in front-end development?,” www.linkedin.com, Nov. 18, 2023. https://www.linkedin.com/advice/0/what-best-practices-naming-css-classes-ids-front-end-ecv7e (accessed Feb. 12, 2024).

Contributors:

@Entropic-Visio @Cinnamon-Bread @MVita11 @waterismm @Abshiry

⚠️ **GitHub.com Fallback** ⚠️