Writing CSS styles could be a nightmare for a lot of programmers, but it gets worse if they’re not well organized or defined. You’re not only worried about how things look, but also where things are in the code, which things you have to change and not breaking the page. Having a style guide could help not only you, but your team as well, to understand, modify and add new code in an easier, faster and less stressful way. When the time comes and a new project setup has to be made, take into consideration the following points. This will help you decide how you and your team will distribute the style files to make working side by side easier.

Think of scalability

One of the most common errors when starting a new project is assuming that it will be static. Let's face it: projects can and will change. Either if it is caused by design feedback or new features, our code and styles will have to evolve and we have to make sure we can make changes without moving everything around throughout our app.

Use atomic and styled components, views, helpers and mixins. Keep your styles organized in an understandable, logical way. This will reduce the possibility that you may have to rewrite a component to fit in with new code.

Define clear variables

One of the perks of using a preprocessor for CSS (like SASS or LESS) is that it allows us to write styles in a way that is more akin to logical code. This makes using variables to store our frequently used values really helpful. However, naming variables is not a straightforward science, and can be a difficult thing to do.

Try to always be descriptive of what you are storing in the variable. Is it being used for typography, spacing or size? Will it change with the resolution or theme? Is it relevant for the entire app, or do we just need it for a specific component or purpose? You don’t need to include details of every question in the name of the variable (since it will probably be to long) but try to be as clear as you can.

For example: when defining color variables, my advice is to use a color-naming page (NameThatColor is an example) and make an agreement so everyone in the team can use the same tool. You don’t want to end up in a situation where the same color is defined multiple times with a different name across the app.

Order

An ordered file schema will guide all the developers to locate and easily modify the files and lines they need to. Having the files grouped by components, views or general styles gives more readability to which ones are being imported and if they're dependent on something else. There are a lot of ways to order the files (in a separated styles folder, or in the component folder along with the js file, etc). It’s important to keep in mind that this scheme should be defined from the beginning and be consistent throughout the lifetime of the project.

In Maniak we like to use the following structure:

Base: In this folder we define the global styles for our site giving them a specific file.

  • global: We all know some browsers mark its territory making some buttons, inputs or selects look a certain way. To make that possible, the basic html elements contain some margins that we might not need, so we have to clear out all the browser default styles that we don’t want and could mess up how our project looks.
  • variables: Creating a file for exclusive variable declarations for sizes, breakpoints and colors makes adding or updating one value easier, instead of changing it in every file throughout our project (It really can save you a LOT of time).
  • typography: Most of the time, we have to recreate a design with a specific typography. We can create classes that will make applying font-size, line-height and letter spacing to all texts easier, instead of adding the same properties to each element inside of other classes. TIP: it’s very useful to use our defined variables for the font-sizes.
  • mixins: The UI should be compatible in shapes, colors and spacings but also has to be consistent in transitions & animations. The mixins feature allows us to write functions inside our styles to which we can pass parameters. Just like with typography, having these blocks of code centralized is really helpful to easily identify reusable properties for our components, like states (hover, active, focus), animations, keyframes etc.

Components: Here we create the files for our reusable components (if we have any). In their own style file, we include their modifiers and variations. What constitutes a reusable component? An alert, avatar, hero, etc. These elements should always look and behave the same way, regardless of where they are in our application.

Vendors: This is an optional folder that you can use to import and customize CSS from 3rd party components. For example if you're using Foundation or Bootstrap but want to modify the space between columns or the grid maximum width, you can have those settings in this folder. Whenever you do these customizations, have a file for each 3rd party.

To conclude, nothing is written in stone about how the files should be organized for all projects, but your team should discuss and decide a structure that can work for you.  Take into account the scalability and expected growth of the project. Having a consistent schema could decrease the time of on-boarding when new people join the team and help to avoid one or two headaches whenever the design changes, because believe me, it happens.