
Structuring CSS in React Boilerplate
When creating many projects in a short period of time, it can be very useful to use a pre-existing template as a base, as they drastically reduce the workload of setting up a new project. One such is React Boilerplate, which our tech team has been implementing across a number of different builds in the past few months.
As an opinionated framework, React Boilerplate uses several libraries out-of-the-box, such as redux, react-router and redux-saga. For CSS-handling it uses styled-components which (amongst other things) allows you to keep your CSS and component code in the same file.
Without following some conventions around how to structure these components and CSS, your project can quickly become a mess of duplicated styles. In a recent conversation amongst our team we discussed methods for ensuring a clean codebase, which are shared below.
Style variables
Before Styled Components, we had SASS/SCSS and LESS. These CSS pre-processors revolutionised how we could write CSS as (among other things) it introduced variables into styles. Rather than having to find all references to a particular shade of red your designer decided to change, it was now possible to declare a single $red: #F00; which meant one change, in one place.
In our React Boilerplate project, we should be using the same convention. Unlike SCSS, we don’t declare our variable in a CSS file however, but rather use standard Javascript objects to contain our variables. This should be kept in the root /app folder of the project for easy access.
const margins = {
page: '20px'
}const colors = {
border: '#CCC',
text: '#333'
}const fonts = {
serif: '"Droid Serif", serif',
sansSerif: '"Open Sans", sans-serif'
}const widths = {
container: '1200px'
}export {
margins,
colors,
fonts,
widths
}
We then simply import the required variables from our global variables.js file into our component.
import styled from 'styled-components'
import { margins, colors } from 'variables'const Text = styled.p`
color: ${colors.text};
margin: 0 ${margins.page};
`
Creating this variables file keeps your styling consistent across components, and means that design changes are much simpler to implement.
Think Atomically
One of the great benefits that React brought to web development was the ability to create reusable components. We create these constantly, however the components we build are often still too bloated and could be broken down more.
In 2013, Brad Frost suggested a new approach to thinking about the design system of a webpage. ‘Atomic Design’ breaks down the page into its smallest pieces (atoms), and then looks at how these are combined to create what the user sees.

If we apply the same thinking to our React project designs, we can start creating components for each element on the page, and then building out further components which are combinations of these atoms. An atom may be an HTML tag (eg. H2, A, Input), or it may be a particular styling of one of those tags which is repeated throughout the page design (eg. a Subtitle, Description paragraph, etc.). Each base atom should be styled individually.
Our folder structure in React Boilerplate starts to look like this:
app
-- components
-- H1
-- H2
-- H3
-- H4
-- P
-- A
-- Subtitle
-- Description
-- Input
-- TextArea
-- Button
-- Section
-- containers
-- tests
-- utilsFrom here we can create ‘molecules’, which are combinations of ‘atoms’ that always appear together. For instance, you may have a page where every paragraph of copy is always preceded by a title. Our Copy molecule would then be:
import React, { PropTypes } from 'react';import H2 from 'components/H2'
import P from 'components/P'function Copy(props) {
return (
<div>
<H2>{ title }</H2>
<P>{ text }</P>
</div>
);
}Copy.PropTypes = {
title: PropTypes.string,
text: PropTypes.string
}export default Copy;
When you receive a new design, we suggest first defining what all the atoms, molecules, etc. are on the page and building these components in isolation. You will find that over time, it becomes very simple to construct a new page as you will already have most of the components you need, while also ensuring styling consistency across your project.
Extend base components
For cases where an element differs slightly in its style due to a particular application, we want to think about extending upon the base component. An example of this could be an inline label next to an input, rather than on top of it. The base label component has the same styling, however its use within the molecule requires extra CSS rules.

As announced with V2 of Styled Components, there is a simple helper for this functionality. After importing the base component (eg. Label), we can use .extend to include extra styles. There is no need to import styled into your component, as styled-components is exposed by the base component.
const InlineLabel = Label.extend`
...
`Note however, that this helper is only available in V2 of Styled Components, which is not the version included as base in React Boilerplate. You will need to upgrade to the new version to use .extend in your project.
This helper creates the same visual effect as the styled(Label) syntax which is available in V1, however functions differently under the hood. As stated by the docs, “Calling extend creates a new stylesheet by extending the old one, and thus doesn’t generate two classes.”
In amongst creating the next big thing, it can be easy to focus on functionality and think about design systems and CSS structure as secondary. However, by following the conventions outlined above, you will save yourself many lines of duplicate code, and headaches down the road!
The example app for React Boilerplate (installed as default) is a good place to start if you want to see some of these ideas in practise. If you have suggestions for extensions and improvements to structuring CSS in a React Boilerplate project, please let us know in the comments below!

Tech at Founders Factory builds businesses that will define the future. We are engineering polyglots, solution hackers and prototyping visionaries. Join Us.

