The common css for all of the bitcrowd projects
Clone or download
planktonic [#164] add ci tests (#277)
* Second approach to getting VRTs on travis, creating a local master.

* Removes the reference images.

* Some cleanup:
- added gitignores for the reference directories
- removed debugging echo statements from the VRT bash script

* Removed the checkbox for running `npm run checks` from the github PR template as it’s not needed when the tests are run on travis.

* Caching the reference images if master hasn’t changed.

* Styleguide processes now killed using the PID, not grepping the name out of ps.

* Linted the shell script

* removed VRT browser report

* Clean up
Latest commit f34e9a2 Jun 8, 2017
Permalink
Failed to load latest commit information.
.github [#164] add ci tests (#277) Jun 8, 2017
bin [#102] Distribution of Bitstyles (#144) Sep 23, 2016
build Removes built output, keeps the folder as it’s used by the build proc… Mar 23, 2016
lib Bumped version for rubygem version. (#283) Feb 27, 2017
scripts [#164] add ci tests (#277) Jun 8, 2017
scss [#261] add object fit cover object (#264) Feb 22, 2017
styleguide/assets [#261] add object fit cover object (#264) Feb 22, 2017
test [#164] add ci tests (#277) Jun 8, 2017
.eslintignore Moves `.o-expander` object to a `.c-expander` component. (#217) Nov 9, 2016
.eslintrc Single task runner (#208) Oct 18, 2016
.gitignore [#164] add ci tests (#277) Jun 8, 2017
.nvmrc Make Travis use the NodeJS environment & yarn (#275) Jan 30, 2017
.stylelintrc Stylelint config (#216) Nov 14, 2016
.travis.yml [#164] add ci tests (#277) Jun 8, 2017
CODE_OF_CONDUCT.md [#102] Distribution of Bitstyles (#144) Sep 23, 2016
Gemfile [#102] Distribution of Bitstyles (#144) Sep 23, 2016
LICENSE.txt [#102] Distribution of Bitstyles (#144) Sep 23, 2016
README.md [#259] Add Yarn Support (#270) Jan 30, 2017
Rakefile [#102] Distribution of Bitstyles (#144) Sep 23, 2016
bitstyles.gemspec Bumped version for rubygem version. (#283) Feb 27, 2017
bower.json Bump version & remove private flag (#224) Nov 10, 2016
package.json [#164] add ci tests (#277) Jun 8, 2017
postcss_build.json Single task runner (#208) Oct 18, 2016
postcss_lint.json Issue/207 rename the bitstyles folder (#215) Nov 9, 2016
yarn.lock [#259] Add Yarn Support (#270) Jan 30, 2017

README.md

Bitstyles

Build Status npm version bower version Gem Version

A collection of tiny Sass CSS objects and helpers, Bitstyles is intended to be used by reasonably CSS- & HTML-aware frontend developers. This is no simple drop-in solution to skin a website, like Bootstrap or Foundation, rather a collection of focused object-classes, each defining just a single visual aspect. By using these simple building blocks in your HTML, it’s possible to construct complex layouts without repeating CSS.

For a certain set of elements in your UI, this strategy of applying multiple atomic classes eventually becomes untenable. This is generally for one of two reasons:

  • the elements are very often-repeated, so using one class instead of many would reduce chances of inconsistency or errors e.g. buttons, cards
  • the number of object classes on an element becomes unreadable in the HTML. This often also results in the appearance of the element becoming hard to reason about just from the HTML source, negating a large advantage of this approach in the first place.

For components which match these criteria it may make more sense to create component classes in your project to compose several of the simpler object classes (and whatever styling you may need on top). For this reason, all the object classes are also provided as Sass mixins — @include them in your own Sass components as needed.

Again unlike Bootstrap and Foundation, there are no javascript widgets or plugins included in Bitstyles.

See the Bitcrowd frontend styleguide for more details of the technical principles on which Bitstyles is built. The TL;DR: it’s a variation of the BEMATOMICOOCSS methodology:

  • BEM naming convention
  • Atomic CSS-inspired, the object classes aim to provide most functionality needed to create whichever layout or UI you need. Trump classes create the exceptions that inevitably occur.

Using Bitstyles in a project

Bitstyles can be added to your project via npm, Bower, or RubyGems.

Bower

bower install bitstyles --save

Once installed, you need to provide your sass installation with the path for bitstyles’ sass. This should be:

bower_components/bitstyles/scss

If you’re using gulp-sass, you can provide this path when pipeing to sass:

gulp.task('stylesheet', function(){
  return gulp.src('app/css/main.scss')
    .pipe(sass({
      includePaths: ['bower_components/bitstyles/scss']
    }).on('error', sass.logError));
}

If you’re using Rails 4+, you can add this path to the asset pipeline in config/initializers/assets.rb where you see the commmented-out lines

# Add additional assets to the asset load path
# Rails.application.config.assets.paths << Emoji.images_path

Add the following:

Rails.application.config.assets.paths << Rails.root.join("bower_components", "bitstyles", "bitstyles")

If you’re using a version of Rails previous to 4, you must instead add the path to the asset pipeline in config/application.rb:

config.assets.paths << Rails.root.join("bower_components", "bitstyles", "bitstyles")

npm

npm install bitstyles --save

Once installed, you need to provide your sass installation with the path for bitstyles’ sass. This should be:

node_modules/bitstyles/scss

If you’re using gulp-sass, you can provide this path when pipeing to sass:

gulp.task('stylesheet', function(){
  return gulp.src('app/css/main.scss')
    .pipe(sass({
      includePaths: ['node_modules/bitstyles/scss']
    }).on('error', sass.logError));
}

If you’re using Rails 4+, you can add this path to the asset pipeline in config/initializers/assets.rb where you see the commmented-out lines

# Add additional assets to the asset load path
# Rails.application.config.assets.paths << Emoji.images_path

Add the following:

Rails.application.config.assets.paths << Rails.root.join("node_modules", "bitstyles", "bitstyles")

If you’re using a version of Rails previous to 4, you must instead add the path to the asset pipeline in config/application.rb:

config.assets.paths << Rails.root.join("node_modules", "bitstyles", "bitstyles")

Rails gem

Add this line to your application's Gemfile:

gem 'bitstyles'

And then execute:

bundle

Or install it yourself as:

gem install bitstyles

Install an unpublished version

If you need to install a version of bitstyles that’s so far unpublished (e.g. there’s a bugfix or feature that’s not in a published package yet), you can use the following:

npm install --save git+https://github.com/bitcrowd/bitstyles.git#master

Importing the sass to your project

Copy the contents of the bitstyles manifest file (bitstyles.scss) to your project’s own sass manifest file (e.g. app.scss, main.scss) to make use of the entire library. Most likely you’ll not need everything in there, so comment-out the lines of objects you don’t need:

@import 'bitstyles/settings/global.setup';
@import 'bitstyles/settings/global.layout';
@import 'bitstyles/settings/global.breakpoints';
@import 'bitstyles/settings/global.animation';
@import 'bitstyles/settings/global.color-base';
@import 'bitstyles/settings/global.color-theme';
@import 'bitstyles/settings/global.typography';

// …

@import 'bitstyles/objects/icon';
// @import 'bitstyles/object/button';
// @import 'bitstyles/object/button-icon';
@import 'bitstyles/objects/absolute-center';

To change the css output by the library (e.g. standard margins, typographic scale, column count of the grid system…) you must override the variables used to build it. To do this declare any variables with your own values before including the bitstyles settings:

@import 'settings/icon-overrides';
@import 'settings/grid-overrides';

@import 'bitstyles/settings/global.setup';
@import 'bitstyles/settings/global.layout';
@import 'bitstyles/settings/global.breakpoints';
@import 'bitstyles/settings/global.animation';
@import 'bitstyles/settings/global.color-base';
@import 'bitstyles/settings/global.color-theme';
@import 'bitstyles/settings/global.typography';

@import 'bitstyles/objects/icon';
// @import 'bitstyles/object/button';
// @import 'bitstyles/object/button-icon';
@import 'bitstyles/objects/absolute-center';

For the complete list of variables you can override, look through the various files in the bitstyles/settings/ folder.

Contributing

Bitstyles requires node v5.7.0 or higher. If you have nvm installed:

nvm use

will switch to the correct version of nodejs.

Clone this repository, cd into the folder created, then install dependencies:

git clone https://github.com/bitcrowd/bitstyles.git
cd bitstyles
yarn

It is recommended to use yarn instead of npm install to ensure version consistency across dependencies.

Build

To ensure your changes do not break the build, run

npm run watch

to recompile sass on every change.

For a single one-off build, run

npm run build

Testing

Installation

CasperJS, PhantomJS, & BackstopJS all need to be installed globally:

npm install -g phantomjs casperjs backstopjs

Run tests

The project uses the visual regression testing system BackstopJS to compare screenshots of each object before & after changes are made. For existing objects, if there is no visual difference between the reference images and the newly-generated images, your changes are good. For new objects, create new reference images (see below) and commit them to the repo.

Existing objects

If you haven’t added a new object to the backstop.json file, you can simply run the tests against the already-existing reference images:

Start the styleguide server and leave it running:

npm run styleguide

To test your changes against the known-good reference images run the tests:

npm run test

Results from the comparison will be displayed in your browser in an automatically-opened window.

Before you create your PR

Start up the styleguide (see the section below on testing for more information on this):

npm run styleguide

…then run the checks:

npm run checks

If you’ve made changes to the Sass source, also update the stats:

npm run css:stats

Once all tests pass, you’re good to go.

New objects

If you add new object scenarios to the backstop.json, backstop will complain if you try to run these tests without creating reference images for them.

Start the styleguide server:

npm run styleguide

Then recreate the reference images:

npm run test:build

Check the new reference images match what you expect, then commit them and you’re done.