Atomic Starter

Folder structure for atomic design projects inspired by Brad Frost's book. (WIP)

Installation

To get started, make sure you have node.js installed. Open the terminal and change directory to atomic-starter/.

• Install npm dependencies.

npm install

• Run all the default gulp tasks.

gulp

• Open project in browser and watch for file changes.

gulp watch

Start coding

You need to work in the src folder, where all your source files should be located. The project structure looks something like this:

atomic-starter/
└── src/
		├── assets/
		│		├── fonts/
		│		├── icons/
		│		└── img/
		├── css/
		├── html/
		└── js/

Inside the src/css and src/html folders we have a similar folder structure that follows the atomic design principles:

css/
	├── __00-toolbox/
	├── __01-elements/
	├── __02-components/
	├── __03-layouts/
	└── __04-pages/

We have 4 levels of abstraction in this proposal based on http://bradfrost.com/blog/post/atomic-web-design/

Level 1: Elements (Atoms)
Level 2: Components (Molecules)
Level 3: Layouts (Organisms)
Level 4: Pages (Templates/pages)

For any other tool or utility we might need in the css or html folders we have a Level 0: Toolbox which has parts of the css or html that are not directly useable on their own. This could be mixins, variables like colors and sizes, partials or settings.

To have a better understanding of the atomic design pattern and how it helps maintain and scalate better large projects, check the next Related posts section.

Related posts:

• Atomic design
• CSS architecture for design systems - Important read!!!
• SUIT CSS utilities
• UI code with namespaces
• http://cssguidelin.es/
• BEM Methodology

Gulp tasks

In the terminal make sure you are in the atomic-starter/ directory.

Compile Sass

gulp css

This will compile all the .scss files in src/css/ and concatenate them to a single file located in dist/css/styles.css, except for fonts.scss which will be compiled to a separared css file dist/css/fonts.css.

Compile Pug

gulp html

This will compile to html all the .pug files in src/html/ and place them into the folder located in dist/.

Compile Javascript

gulp js

This will transpile all the .js files in src/js/ export it to a file located in dist/js/app.js. It supports ES6. You can install js plugins with bower.

Generate sprites

gulp sprite

This task will create the sprite.png located at dist/img/ which will also be the optimized (minified) image version. In order to use the mixin that this task creates you have to follow this structure in any of your .scss files.

.icon {
	@include sprite($iconName);
}

Which will render to css. Notice that the $iconName variable name has to be the same as your image file name src/assets/img/sprite/iconName.png.

Generate icons

gulp icons

This task will generate the iconFont font for the icons that you can place in the src/assets/icons/ with the *.svg extension.

Generate font styles

gulp fonts

This task will generate the styles for the fonts placed in the src/assets/fonts/ folder.

Minimize images

gulp imagemin

This task will create a copy of all your image files located in src/assets/img/ and create an optimized and lighter version in the folder dist/img/.

Run all tasks

gulp

This task runs all the previous tasks.

Styleguide

npm run styleguide

This will generate a living styleguide with Nucleus in the styleguide/ folder based on your DocBlock annotations. For more information visit:

https://holidaypirates.github.io/nucleus/

Resources

• Pug
• Sass also uses Lost (Grid System) and Breakpoint Slicer (Media queries)
• Nucleus
• Gulp
• Bower