Atomic Builder is a lightweight and flexible CSS front-end framework based on ITCSS architecture and built with Sass.
Atomic Builder does its best to provide zero cosmetic styling. That means Atomic Builder can be used on any and all types of project without suggesting a look-and-feel. If you do require a UI out of the box, then Atomic Builder is probably not the best tool for you. I’d recommend looking at a UI Toolkit such as Bootstrap.
All modern browsers are supported (except Internet Explorer).
You can use Atomic Builder in your project by installing it using a package manager (recommended):
npm:
$ npm install atomic-builder
yarn:
$ yarn add atomic-builder
Copy/paste (not recommended):
You can download Atomic Builder and save it
into your project’s css/
directory. This method is not recommended because you lose the ability to easily and quickly
manage and update Atomic Builder as a dependency.
Atomic Builder follows a specific folder structure based on ITCSS, which you should follow as well in your own CSS directory:
settings/
: Used with Sass and contain global variables, colors definitions, etc.tools/
: Globally used mixins and functions.generic/
: Reset and normalize styles.elements/
: Unclassed HTML elements (like<h1>
,<a>
, etc.).objects/
: Class-based selectors which define undecorated design patterns.components/
: Specific UI components. Because Atomic Builder does no cosmetic styling, it is up to you to author this layer.utilities/
: Helper classes with high-specificity.
Atomic Builder is written using BEM (Block, Element, Modifier) methodology for building component-based user interfaces.
It also provides some classes with specific namespace:
.o-
: Signify that something is an Object, and that it may be used in any number of unrelated contexts to the one you can currently see it in..c-
: Signify that something is a Component. This is a concrete, implementation-specific piece of UI..u-
: Signify that this class is a Utility class. It has very specific role and should not be bound onto or changed. It can be reused and is not tied to any specific piece of UI.
Every class in either of these three directories (layers) gets the appropriate prefix in its class name. Be sure to follow this convention in your own code as well to keep a consistent naming convention across your code base.
As much as possible, avoid modifying Atomic Builder’s core files. The best way to do this is to import Atomic Builder’s source Sass files in your own project.
You have two options : include all of Atomic Builder, or pick the parts you need.
We encourage the latter, though be aware that settings/
and tools/
folders are required.
// Settings (required)
@import 'node_modules/atomic-builder/scss/settings/colors';
@import 'node_modules/atomic-builder/scss/settings/global';
// Tools (required)
@import 'node_modules/atomic-builder/scss/tools/functions';
@import 'node_modules/atomic-builder/scss/tools/mixins';
// Generic (optional)
@import 'node_modules/atomic-builder/scss/generic/normalize';
@import 'node_modules/atomic-builder/scss/generic/box-sizing';
@import 'node_modules/atomic-builder/scss/generic/reset';
@import 'node_modules/atomic-builder/scss/generic/shared';
// Elements (optional)
@import 'node_modules/atomic-builder/scss/elements/root';
@import 'node_modules/atomic-builder/scss/elements/page';
@import 'node_modules/atomic-builder/scss/elements/heading';
@import 'node_modules/atomic-builder/scss/elements/forms';
@import 'node_modules/atomic-builder/scss/elements/tables';
// Objects (optional)
@import 'node_modules/atomic-builder/scss/objects/grid';
@import 'node_modules/atomic-builder/scss/objects/container';
// Utilities (optional)
@import 'node_modules/atomic-builder/scss/utilities/position';
@import 'node_modules/atomic-builder/scss/utilities/display';
@import 'node_modules/atomic-builder/scss/utilities/flex';
@import 'node_modules/atomic-builder/scss/utilities/alignment';
@import 'node_modules/atomic-builder/scss/utilities/float';
@import 'node_modules/atomic-builder/scss/utilities/clear';
@import 'node_modules/atomic-builder/scss/utilities/sizing';
@import 'node_modules/atomic-builder/scss/utilities/spacing';
@import 'node_modules/atomic-builder/scss/utilities/overflow';
@import 'node_modules/atomic-builder/scss/utilities/colors';
@import 'node_modules/atomic-builder/scss/utilities/text';
@import 'node_modules/atomic-builder/scss/utilities/visibility';
@import 'node_modules/atomic-builder/scss/utilities/cursors';
@import 'node_modules/atomic-builder/scss/utilities/reset';
@import 'node_modules/atomic-builder/scss/utilities/helper';
Every Sass variable in Atomic Builder includes the !default
flag allowing you to override the variable’s default value
in your own Sass file without modifying Atomic Builder’s source code. Your overrides must come before you import Atomic
Builder’s setting files.
You will find the complete list of Atomic Builder’s variables in
scss/settings/_colors.scss
and
scss/settings/_global.scss
.
To modify an existing variable $container-max-width
, add the following to your custom Sass file:
$container-max-width: 96rem;
To modify an existing key in our $spacers
map, add the following to your custom Sass file:
$spacers: (
'base': 2rem,
);
To add a new key and value to $spacers
map, add the following to your custom Sass file:
$spacers: (
'custom-spacer': 1rem,
);
To remove an existing key from $spacers
map, add the following to your custom Sass file:
$spacers: (
'base': null,
);
Atomic builder also provides some features and tools that should be of great help to you.
CSS custom properties allow you to store and retrieve values from properties you define yourself.
They follow the same rules as other CSS properties, so you are able to define and use them at multiple levels, following standard CSS cascading and specificity rules.
Atomic Builder includes CSS custom properties in it’s compiled CSS. These CSS custom properties are based on Atomic
Builder’s variables in
scss/settings/_colors.scss
and
scss/settings/_global.scss
and are generated in our
scss/elements/_root.scss
file.
For example, this Sass map:
$spacers: (
'lg': 4.8rem,
'base': 2.4rem,
'sm': 1.2rem,
);
will automatically add these custom properties in the root element:
:root {
--spacer-lg: 4.8rem;
--spacer-base: 2.4rem;
--spacer-sm: 1.2rem;
}
You can now retrieve these custom properties like this:
.c-custom-component {
margin: var(--spacer-base);
padding: var(--spacer-sm);
}
You may have noticed that Atomic Builder provides a default map of breakpoint values:
$breakpoints: (
'phone': 47.9375em,
'tablet': 64em,
);
Like any other Atomic Builder’s variables, it is possible to override this Sass map to modify, add or remove some responsive breakpoint keys:
$breakpoints: (
'phone': null,
'tablet': null,
'sm': 47.9375em,
);
It is even possible to delete all responsive breakpoint keys if your website doesn’t require to be responsive:
$breakpoints: ();
These responsive breakpoints are available via Sass mixin @mixin media($keys...)
by adding optional suffixes: -up
or
-down
.
It is important to note that the suffix -up
is exclusive while the suffix -down
is inclusive.
This Sass mixin with ($key)
name:
@include media('tablet') {
.c-custom-component {
margin: var(--spacer-base);
}
}
will generate these responsive breakpoints:
@media (max-width: 64em) and (min-width: 48em) {
.c-custom-component {
margin: var(--spacer-base);
}
}
This Sass mixin with ($key-up)
name:
@include media('tablet-up') {
.c-custom-component {
margin: var(--spacer-base);
}
}
will generate this responsive breakpoint:
@media (min-width: 64.0625em) {
.c-custom-component {
margin: var(--spacer-base);
}
}
This Sass mixin with ($key-down)
name:
@include media('tablet-down') {
.c-custom-component {
margin: var(--spacer-base);
}
}
will generate this responsive breakpoint:
@media (max-width: 64em) {
.c-custom-component {
margin: var(--spacer-base);
}
}
This Sass mixin with multiple ($key1, $key2)
names:
@include media('phone', 'tablet-up') {
.c-custom-component {
margin: var(--spacer-base);
}
}
will generate these responsive breakpoints:
@media (max-width: 47.9375em) {
.c-custom-component {
margin: var(--spacer-base);
}
}
@media (min-width: 64.0625em) {
.c-custom-component {
margin: var(--spacer-base);
}
}
Key | Phone | Tablet | Desktop |
---|---|---|---|
phone |
✓ | ✗ | ✗ |
tablet-down |
✓ | ✓ | ✗ |
tablet |
✗ | ✓ | ✗ |
phone-up |
✗ | ✓ | ✓ |
tablet-up |
✗ | ✗ | ✓ |
Atomic Builder includes a lightweight and fully responsive grid system built with flexbox.
This grid system uses custom properties based on Atomic Builder’s variables in
scss/settings/_global.scss
.
(The following examples are based on 12-column grids.)
To declare a grid, the syntax is really easy:
<div class="o-grid">
<div class="o-grid__col">Column one (auto)</div>
<div class="o-grid__col">Column two (auto)</div>
</div>
By default, the columns are based on the width of their content, but it’s also possible to define a grid with regular column widths:
<div class="o-grid">
<div class="o-grid__col o-grid__col--6">1/2</div>
<div class="o-grid__col o-grid__col--6">1/2</div>
</div>
...or even with irregular column widths:
<div class="o-grid">
<div class="o-grid__col o-grid__col--4">1/3</div>
<div class="o-grid__col o-grid__col--8">2/3</div>
</div>
Finally, to declare a responsive grid, just add a suffix based on breakpoint key name, as noted above, in the column class name:
<div class="o-grid">
<div class="o-grid__col o-grid__col--6 o-grid__col--4@phone-up">1/1 and 1/3 for tablets and desktops</div>
<div class="o-grid__col o-grid__col--6 o-grid__col--8@phone-up">1/1 and 2/3 for tablets and desktops</div>
</div>
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
We use SemVer for versioning. For the versions available, see the tags on this repository.
Jonathan Levaillant - Initial work - jonathanlevaillant.
See also the list of contributors who participated in this project.
This project is licensed under the MIT License - see the LICENSE.md file for details.
Open Source time sponsored by JoliCode