Style Guidelines
🎨 | Mumble Style Guide
The main goal of this style guide is providing the contributors a set of instructions about how he should approach writing codes and what are the excepted when a PR has been placed. This guide will walk you through the codebase, conventions, and principles we are currently following. We, the mumble community, do not want to enforce with all kinds of code conventions to anyone, but as the project gets larger, and there are many contributors are joining each days, it'll get quiet messy very quickly unless there is a set of instructions to follow for maintaining the consistency and improving the code readability. We also believe that, having some kinds of conventions to follow is much better than having no conventions at all; without some kinds conventions 100 different people can write code 100 different ways, which will be results in messy codebase. That's why, we are introducing you to the Mumble Style Guide. We highly recommends you to go through the guideline time to time. We will keep this file up to date with any changes in projects.
Table of Contents
🎭 Mumble CSS Style Guide
The below specifications are all about writing clean and modular css codes for the project. While this is not a hard requirement but we love to see contributors respect to follow the style guides for maintaining the consistency throughout the project. All the styles (css files) live on frontend/src/styles
directory. On the styles
directory, you will find index.css
that imports other stylesheet modules and responsible for applying application-wide the styles. styles/common
- has all the basic and global plus the common components' stylesheets and styles/components
- has all components' and pages' stylesheets.
📦 Modularity
Modularity in CSS provides a guideline-based approach for breaking down pages into generic reusable CSS code. It follows consistent naming conventions and allow us easy to read and maintain. There are several approach to accomplish this like using css module
, css in js
and good old css architecture
. Although, create-react-app
has the built-in support for CSS Modules pattern and CSS in JS sounds cool, but there are always some pitfalls to this, which can be extra burden-some to maintain and has a huge learning curve for beginners. That's why we are going to take a different approach. We are going to follow a most popular CSS Architecture called BEM (Block Element Modifier) throughout the project. BEM is beginner friendly, has almost zero learning curve. And besides that, it help us do accomplish two more things:
Provides consistency and no-naming collisions throughout the project and
In future, BEM will play a major role when the project will incorporate CSS preprocessor like SASS or PostCSS.
Inline styles are not recommended to style a components but it can useful for conditional rendering in some cases.
🎹 Pattern and Naming
The Mumble project uses the Block Element Modifier methodology (commonly referred to as BEM) which is a popular naming convention for classes in HTML and CSS. BEM provides a modular structure to your CSS project. Because of its unique naming scheme, we won't run into conflicts with other CSS names. Besides that, it helps developers better understand the relationship between the HTML and CSS in a given project. You can learn more about the BEM methodology on getbem.com.
BEM in Practice:
And the markup will look like this:
What happen when the names make sense with two different naming parts. Well, can you fit into one? Take an example of naming a element
below.
🎨 Colors
We are going to use css variables everywhere. Using CSS variables give us the flexibility of refactoring anytime and also help us switching between themes. Our application has two color pallettes which you can find under frontend/src/styles/common/_variables.css
file. Variables under :root{}
- for the light theme, and .dark-theme{}
- for the dark theme. We recommend to use color from the color pallettes. If there is a necessary to introduce new color, add the color variables on _variables.css
file under :root{}
, may be a dark version under .dark-theme{}
as well.
You can use these colors anywhere on the stylesheets using CSS Variables. You can learn more about CSS variables on MDN website.
✍️ Fonts
The default font we are going to use is Poppins
. It's a free font and available on Google Fonts. We have three variants for this default font. Also, if you need to use monospace font, there is another font available to use called Fira Code
which is also freely available on Google Font. On the frontend/src/styles/common/_variables.css
file, there are variables for fonts and their variants to use under :root{}
.
🧰 UI Kits
If you're just beginning and want to know about different components that are available to compose a reusable components, (a) either go to frontend/src/common
folder and explore codes or (b) you can sneak peak a preview of that components by opening frontend/src/uikit/index.html
on the browser.
🟢 You can also visit the Mumble UI Kit online -
Stylelint
Last thing, we are going to talk about is the style linter. Although we do not want to enforce people attach to some conventions, but as the project was growing into a mess and becoming hard to manage with all the different people committing their own styles and preferences, we've decided to enforce a bare minimum styles with stylelint
. You can run npm run stylelint
or npm run stylelint:fix
to ensure you code is a sync with the linter. If stylelint
failed, the github actions will be failed, which means your code will be a subject to merge.
Last updated