atomic-scss

Atomic SCSS library

What is this?

This projecect contains SCSS that generates atomic CSS when certain configuration variables are present in the SCSS.

For this it helps to think of CSS an API that your application will use for styling. The CSS class names are the methods provided by this API. Ultimately, this SCSS generates this API for you based on variables that you set (See Configuring section below).

What is atomic CSS?

Atomic CSS (often called functional CSS, or utility classes) is an approach to CSS where every class has only one attribute in it. For example:

.padding10 { padding: 10px; }
.fontSizeSmall { font-size: 12px; }

How to use

Install with npm

npm install --save atomic-scss

Import the scss into your own project from node_modules or copy the files into your own project.

(See example usage here)

It is highly recommended that you also copy the scss from one of the default configuration files found here into your project and use it as a starting point to configure atomic-scss.

Configuring

Here is some sample configuration:

//        : (name: '<api-media-query>', cond: '<media-query-condition>');
$bp-sm-mx : (name: '\\@sm',             cond: 'all and (max-width: 500px)');

$width: (
//(vals: ('<api-value>': <value>,), bp: $<breakpoint-variable>),
  (vals: ('1': 1px, '2': 2px,)),
  (vals: ('1': 1px, '2': 2px), bp: $bp-sm-mx,),
);

$width-perc: (
  (vals: ('10': 10%, '20': 20%,)),
  (vals: ('10': 10%, '20': 20%,), bp: $bp-sm-mx,),
);

// This is the variable atomic-scss uses to generate the styles
$atomic-config:(
//('<attribute>', '<api-base>', '<api-unit>','<api-post>', $<sass-variable>),
  ('width',       'w',          '',          '',           $width),
  // generate percentages
  ('width',       'w',          '\\%',       '',           $width-perc),
  // generate hover styles
  ('width',       'w',          '\\%\\:h',   ':hover',     $width-perc),
);

This would generate:

.w1 {
  width: 1px;
}

.w2 {
  width: 2px;
}

.w10\% {
  width: 10%;
}

.w20\% {
  width: 20%;
}

.w10\%\:h:hover {
  width: 10%;
}

.w20\%\:h:hover {
  width: 20%;
}

@media all and (max-width: 500px) {
  .w1\@sm {
    width: 1px;
  }

  .w2\@sm {
    width: 2px;
  }

  .w10\%\@sm {
    width: 10%;
  }

  .w20\%\@sm {
    width: 20%;
  }

  .w10\%\:h\@sm:hover {
    width: 10%;
  }

  .w20\%\:h\@sm:hover {
    width: 20%;
  }
}

Classes are generated on this formula:

// styles generated without media queries
.<api-base><api-unit><api-post> {
  <attribute>: <value>;
}

// and for styles generated in media queries
@media <media-query-condition> {
  .<api-base><api-unit><api-media-query><api-post> {
    <attribute>: <value>;
  }
}

On Version 4

Breaking Change: The file you @import into your project (scss/atomic.scss) no longer refers to a default config.

YOU MUST DEFINE YOUR OWN CONFIGURATION.

If you would like to use the default config still, @import the file scss/atomic-default.scss instead.

I have provided constructs for CSS custom properties and container queries.

The scss/atomic/_atomic.scss file that generates the resulting css has been rewritten to provide some messaging and not break if variables are missing.

Contemplating cascade layers for a future version, but this will not introduce any breaking change.

On Version 3

I felt that the helper classes should be moved out into their own package.

Look in scss-functional-helpers for these helper functions.

On Version 2

In this version 2 release configuration is a bit more complicated, but the trade off was:

• Now extensible
  • Add or remove whatever styles you want!
  • Add as many breakpoints as you want for each style
• Now there is greater control over breakpoints
  • min-width or max-width. Why not both? Also height.
• Now you can control the syntax of the classNames generated
  • I use p10 for padding: 10px, but maybe you want p(10px) or p-small. Now you can do this.
• (Self-servicing bonus: code is much shorter and so easier to maintain for me.)

Why use this library atomic-scss?

I think the sweet spot for this is for individuals or teams that work on many different projects and want to minimize the number of CSS APIs that one needs to learn or study. (Yes, CSS classes are like style APIs).

It is fully expected that you will pair this with semantic class names following whatever methodology you want. You can choose to use as much or as little classes generated by atomic-scss as you want, and makes sense to you.

It also would be easy to use this along with styled-components.

What makes sense to me (the author)?

While I use semantic class names, I try to do as much as possible with atomic classes. This is perhaps an extreme, but it works for me very well. (The most useful thing about semantic class names in my workflow is actually how I'm able to highlight them and then use command + d to select all of the elements in sublime text...)

When I return to old projects that I haven't touched in a while - even when they are very large - there are usually only 250 lines of sass (including mostly lines that are just }). This makes it easier for me or a co-worker to jump onto an old project to do a quick layout fix. It also gives me higher confidence that what I add to the CSS isn't going to break anything.

Why atomic-scss and not some other atomic library?

Use what makes sense for you. This project was optimized for a workflow where I don't know what frameworks, libraries or platforms I will be working on in the future. That is, I don't want to assume that I will be using gulp or React or whatever other platform. As long as I have a way of building SCSS I know that this will work.

Other Recommendations

Import atomic into your scss above just about everything else so the atomic classes are overrided by anything else in the cascade.

This framework comes with some variables it defines for colors and breakpoints. But you can override them by defining them before the import of the atomic (that is, include your variables higher than you import atomic-scss).

If possible, pair with unCSS (or some other package) in some form in order to remove unused styles in the end. However, if this doesn't work for you, you can just configure out the styles you aren't using (time consuming if you want to be perfect, but you can probably get a high percentage of the stuff you don't use very quickly).

If you're using webpack and want to remove unused styles, try the purifycss-webpack plugin.

Here are some projects I have that use atomic-scss so you can work by example:

• static-site-boilerplate
  • A boilerplate for making static websites

Older versions of atomic-scss used in these projects:

• keystone4-universal-react
  • A boilerplate for universal react websites/apps on keystone
• atomic-scss-starter-kit
  • Really just a demo of atomic-scss

Thanks

Thanks to yahoo for pioneering this technique (as far as I know).

Also see acss.

License

MIT license