Ci logo

Technology

Living Style Guide Technology

Our living style guide's technology can be split into three primary sections. Collectively we refer to them as StyleBitz. Please visit each sectoin below for more details.

  1. Sass Library - The lowest level building blocks. Details StyleBitz's CSS framework and how we build responsive pages.
  2. JavaScript Interfaces - To UI components that have behavior wrappers as well as top level JavaScript requirements.
  3. Rails Engine - How to use StyleBitz with Rails layouts, views, and assets.

Sass Library JavaScript Interfaces Rails Engine

Get Started

Here are a few high level quick starts when using StyleBitz with your project. If you are using Rails, please read that section linked above.

Node & JavaScript

Good news! libSass is a real thing and StyleBitz Sass framework passes all the tests.

We recommend that you wire up your Sass paths so that properly scoped and package independent imports work. What does this mean? It means that StyleBitz can not prefer any package manager over another. When we @import "bourbon"; it is up to you wire up the Sass paths. This is done for you automatically when using StyleBitz with RubyGems. Otherwise, you have to do this for each of our primary deps listed here.

Development

Setting up a development version of StyleBitz will allow you to easily edit documentation and make global framework contributions. You can also use StyleBitz' Rails engine to prototype new pages.

Project Setup

Clone the StyleBitz repository to your local drive. If you are new to git, we recommend using GitHub for Mac. To either develop StyleBitz or contribute to the living style guide's documentation, you will need Ruby installed, which is already present on OS X. If you use a Ruby version manager, we recommend developing StyleBitz with Ruby v2.1 or later.

StyleBitz uses Capybara for both its unit and integration tests. The following terminal commands need to be run from the root of the cloned StyleBitz repository if this is your first time setting up both Ruby and StyleBitz. Remember, do not type the $ symbol. It is there to indicate that that these are terminal commands only.

Install Homebrew if you do not already have it.

$ ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"

Install ruby gem dependencies.

$ brew install libxml2 libxslt phantomjs

Install ruby gems needed by StyleBitz.

$ gem install bundler
$ env NOKOGIRI_USE_SYSTEM_LIBRARIES=true bundle install

Project Overview

Our Sass resources can be found in the app/assets/stylesheets directory. From here everything related to StyleBitz proper is defined in the _style_bitz.scss main file or the adjacent style_bitz directory. From here Sass files are organized within a clean directory structure that follows our core/more philosophy. The living style guide uses StyleBitz to build itself. Its main Sass file is in the same stylesheets directory and it too has a matching directory named style_bitz_style_guide to keep them isolated.

The Rails Engine of the StyleBitz gem is organized like most Rails applications. We use an isolated namespace to keep our controllers, views, and helpers from negatively affecting host applications. As we develop new helpers it is important to maintain the sb_ method name prefixes since Rails mixes all helpers all the time.

Local Dev Server

You need a development server to see the local version of the StyleBitz living style guide. This way you can see what is changed at either the code or documentation level. For those that use the Pow rack server, you can symlink to the StyleBitz repository like a normal Rails app. If you do not have Pow installed, you can use the Rake command to start a development server. Once running, you can access StyleBitz at http://style_bitz.dev/ if you are using Pow or http://0.0.0.0:3000/ if using our Rake server.

$ bundle exec rake server

Documentation

The StyleBitz living style guide is authored in easy to use Markdown syntax. Specifically we use GitHub Flavored Markdown which allows us to embed syntax highlighted code examples. All style guide pages reside within the app/views/style_bitz/style_guide directory and have a .md file extension.

Any new new Markdown file added here will automatically be available to use. For example, the foo.md file would be accessed at the /style_bitz/foo URL path. Markdown files are automatically parsed and given a table of contents using semantic names for each <h2> tag which are given the special style guide presentation on each page. Please, <h4> tags within each documentation segment. For example:

## Primary Section

Some content...

#### Other Related Section

More content...

Please take the time to consider the content and contextual link to any other style guide pages as needed. For example, this [our Sass usage](/style_bitz/technology-sass#usage) will generate a link with the text of "our Sass usage" that links to our Sass Framework page. The #usage is called an anchor and is optional. In this example, it will jump to that section on the page.

If you are using images in the documentation, we recommend hosting them on GitHub's user content server. To do this, open this GitHub page and just drag your image to the comment input box. Your image will automatically upload and you can copy the URL into the HTML snippet below.

<img class="sg-Page-img sg-Page-img--half" alt="..." src="..." />

That image would take up half the right side of the page from the medium breakpoint upward. Full page for mobile first. Check out the style guides _page.scss for more classes or write your own.

Updates & Deploys

Updates to the StyleBitz master repository branch will trigger an automatic deploy to Heroku of the living style guide. This normally happens in only a few minutes. It is recommended that you run the tests before committing.

$ bundle exec rake test

Please check our Jenkins Builds for the complete run. Jenkins leverages our usage of the Appraisal gem to run all tests on supported Rails versions.

Change Log

Use this Keep a CHANGELOG article for a good reference on how we want to maintain ours.

v0.7.0

Added:

Removed:

v0.6.0

Added:

Removed:

v0.5.1

Added:

Changed:

v0.5.0

Added:

Changed:

Fixed:

Removed:

v0.4.0 - 2015-03-25

Added:

Changed:

Removed:

Fixed:

v0.3.0 - 2015-01-26

Milestone reached for initial launch of the new group order form.

Added:

Changed:

Fixed:

v0.2.0 - 2014-12-03

Milestone reached for launch and completion of new feedback form.

Added:

Changed:

v0.1.0