Watt is a shared js/css/img asset library for some Artsy ruby apps.
- State: production (in Volt, Ohm, Induction, Lattice, Helix, & Vibrations)
- Style Guide: http://partner-engineering-style-guide.s3-website-us-east-1.amazonaws.com/
- Github: https://github.com/artsy/watt/
- CI: CircleCI (such as it is)
- Point People: @oxaudo, @gib
Ideally, Watt is a very thin layer on top of Bootstrap (3.0.3 at the moment). Bootstrap is primarily useful as a series of good defaults; there are many thousands of pretty smart people thinking about reasonable responsive breakpoints--we shouldn't force ourselves to re-invent triangular wheels. Let's be clear about what we are including (Grid & navbar, for example) and lets clearly not include the bits of the framework we choose to not use in production (jumbotron, buttons, modals, carousels, et c).
Watt's relationship to Bootstrap's Javascript and Stylesheet files should follow the same approach here. _bootstrap_base.scss is a good example of removing the components we don't presently need. The goal should be to avoid adding bit of the framework (jumbotron), but if a project using Watt really wants to leverage a Bootstrap jumbotron, it can be safely included with an @import 'bootstrap/jumbotron.
We'll additioanlly set global variable overrides in _bootstrap_variables.scss and, predictably, _bootstrap_overrides.scss.erb.
All of three of these files are imported in base.scss.
It's often useful to reference global variables used by Bootstrap. This file is the LESS flavor, but the same variable names are overwritten by bootstrap-sass.
Bourbon is a Thoughbot joint. Bourbon is a library of SASS mixins that are authored solely with SASS. Unlike Bootstrap, including Bourbon does not add CSS, but mixins that help to quickly build the CSS defined by the project.
Use Bourbon and Neat mixins to help creating new Watt components.
It would be very surprising if you don't find yourself needing, Avant Garde &/or Garamond from Fonts.com. We are using the "Art.sy" kit in the [email protected] account (password in 1password).
Make sure to include the following in the head of your layout file. It ought to work in most development setups (localhost for Rails and 0.0.0.0 for middleman) and in production on *.artsy.net domains.
Something like this should do the trick (haml):
- unless Rails.env == 'test'
= javascript_include_tag "https://fast.fonts.net/jsapi/f7f47a40-b25b-44ee-9f9c-cfdfc8bb2741.js"
Note that we shouldn't include the asset in Test mode for fear of incurring extra costs.
Like artsy.net projects, we host our own font for icons. This gives us vector graphics for sharp scaling and allows us to use CSS for colors and transitions just like any other typeface. See the Joule project for more details.
The effort in adding a new icon to Joule can be higher than expected. SVGs are proving to be a great alternative and should be considered first.
Watt includes a static style guide, generated by Middleman. Its accessible on the web at http://partner-engineering-style-guide.s3-website-us-east-1.amazonaws.com/. The style guide groups samples in two sections:
- Interface - the UI in practice; find for example a sample list of items here
- Elements - the things broken down into components; find for example a rundown of button styles here
PRs merged to artsy/watt#main are automatically deployed to the partner-engineering-style-guide S3 bucket by CircleCI.
Watt is a private gem and hosted on Github. To include Watt, add this line to your application's Gemfile, substituting USRNME:PSSWRD for the proper credentials:
gem 'watt', git: 'https://USRNME:[email protected]/artsy/watt.git'
And then execute:
$ bundle
Here is an example of adding Watt to existing project: https://github.com/artsy/vortex/pull/18
Run middleman to see your Watt changes locally:
cd style-guide
bundle exec middleman server
TODO: More about usage and how to setup a new project with Watt.
Watt's goal is to maximize re-use of common UI components. To do this, we follow some core tenets. See this excellent write up by Phillip Walton on CSS Architecture. While we don't expect to be too rigid on the naming-schemes presented here, asking ourselves how we measure against the following goals when adding CSS to Watt is a great start:
- Predictable
- Reusable
- Maintainable
- Scalable
Alphabetical ordering of style definition rules. It's consistent and helps in quickly parsing what's included in a style.
.chevron-list-link {
}Namespacing instead of nesting for components. There is a lengthy class name cost associated with this, but the benefit balance of maintainance and reuse tips the scales. May be my favorite CSS metaphor of all time: Grenande vs Sniper Rifle:
/* Grenade */
#main-nav ul li ul { }
/* Sniper Rifle */
.subnav { }
/**
* Extend components with modifier class names (extend the namespace)
*/
/* Bad */
.widget { }
#sidebar .widget { }
/* Good */
.widget { }
.widget-sidebar { }(From CSS Architecture by Pillip Walton)
.chevron-list {
...
}
.chevron-list-link {
...
&::after {
...
}
}
.chevron-list-link-label {
...
}
.chevron-list-link-body {
...
}Also note that tags are not included (again CSS Architecture by Pillip Walton) for wins on reuse and maintenance. This scales as the component does not rely on specific parents:
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request