Feathr HTML/CSS Styleguide and CSS Framework

A mostly reasonable, SUIT-based approach to HTML and CSS

The way we author HTML and CSS at Feathr is built on the foundation of SUITCSS. As far as I can tell, the 'SUIT' in SUITCSS does not stand for anything in particular, but its tagline is "Style tools for UI components". SUIT is more or less a flavor of BEMCSS with tooling built on PostCSS. This means it is a methodology and toolset for writing CSS that works with a component-based application architecture, which matches well with any sort of MVC/MVVM framework, where HTML is broken up into individual view templates which should be reusable and independent of each other.

Wait, what's PostCSS?

PostCSS is the css preprocessor/processor of the future. It's like Babel in that it makes future css syntax and features available today. It's like ESlint in that it is pluggable and infact is built almost entirely out of plugins - PostCSS is more or less a framework onto which you can attach various processes that move your CSS from one state to another until it's packaged and ready for the browser. PostCSS solves a lot of the same problems that standalone preprocessors such as Less and Sass have in the past, as well as many others, but in a way that is future-facing and configurable. The SUITCSS project that Feathr's css styleguide, linting and workflow is built on, uses PostCSS to process dev-authored CSS into a browser-ready css file.

Usage

Frontend/Web components at Feathr should include the following npm packages:

• suitcss
• stylelint
• stylelint-config-feathr
• grunt-stylelint
• stylelint-selector-bem-pattern

npm install --save-dev suitcss suitcss-preprocessor stylelint-config-feathr

Next the project needs a configuration file to tell stylelint to use the Feathr-flavored stylelint configuration and to enforce BEM conformance in a SUITCSS flavor. Make a .stylelintrc file with the following configuration:

{
  "extends": "stylelint-config-feathr",
  "plugins": [
    "stylelint-selector-bem-pattern"
  ],
  "rules": {
    "plugin/selector-bem-pattern": {
      "preset": "suit",
      "utilitySelectors": "^\\.u-[a-zA-Z0-9]+$"
    }
  }
}

Finally Gruntfile.js needs to be set up to process all the css files in the project into a built output file for the browser. Configure your stylelint task like so:

stylelint: {
  options: {
    configFile: '.stylelintrc'
  },
  src: 'app/**/*.css',
},

This will setup your linting process. To set up the complete build process to pack all of the linted/validated css into a minified file, you have to setup a postcss task in your Gruntfile.js which uses the plugins you need to transform your css according to what PostCSS features you use. This will vary based on the project, but a basic postcss task might look like this:

function noop() {}

function getFileContent(filename) {
  return pify(fs.readFile)(filename, 'utf8');
}

grunt.initConfig({
  // ...
  postcss: {
      options: {
          map: true,
          processors: [
              require('postcss-easy-import')({
                  load: getFileContent,
                  onImport: noop,
              }),
              require('autoprefixer')({
                  browsers: `> 1%, last 2 versions, safari > 6, ie > 9, ios > 6, android > 4.3, samsung > 3, chromeandroid > 50`
              }),
              require('cssnano')({
                  calc: false,
                  autoprefixer: false,
                  mergeRules: false,
                  safe: true
              }),
          ]
      },
      dev: {
          src: 'app/src/index.css',
          dest: 'app/dist/out.min.css'
      }
  },
  // ...
}