patternfly-sass 3.23.2 → 3.31.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e81d0ebaad077cfbb1a9265b1fe9c411087b994d
-  data.tar.gz: 4e8d54f943d959c7708e1b9c437b707a7db05ccb
+  metadata.gz: 88a43d6ed897d6b49b0a799a16a1c7bca2ac712c
+  data.tar.gz: 7f2930941f99ef87f84aeddd8b63c4a0fa796724
 SHA512:
-  metadata.gz: bac8de8b35048b1834d5a66bd1072c2f553cb3185bc36e6d4f9fe18b9d0b523e31266d694fe096f69b890412a30e751285a7cb2d0ef98da8c72a53dca88da9d4
-  data.tar.gz: 4834a3c98af6fd07fcd7b129000b7aeadc20ef1f0e5419bb38e3be91c1c70bd65d55b703cc7a0bccd6217066391334216be3d83a10e9a8bf78c35d4e66518d7a
+  metadata.gz: 45aa99de98bce8caa49ca5e761660524a5f9ee0a8e80c0c8e0ab6fded19fb48fa9f789aee5d8402027787acba06c310a87e27668b8bd3df904849172a54d2d6b
+  data.tar.gz: 3cd7b30b2894756c49bfbdbfb350810df46a4dddc9c45340840d1875a695e8c1563a6e49b5f84ecc0f34f1df240cc821f93850293920e43a8c562be5ad28ff69

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+This project is governed by the [Contributor Covenant version 1.4][1]. All contributors and participants agree to abide by its terms. To report violations, send an email to [patternfly@redhat.com][2].
+
+ [1]: http://contributor-covenant.org/version/1/4/code_of_conduct.md
+ [2]: mailto:patternfly@redhat.com

data/QUICKSTART.md

@@ -0,0 +1,165 @@
+# Using [PatternFly](https://www.patternfly.org) - Quick Start Guide
+
+This reference implementation of PatternFly is based on [Bootstrap v3](http://getbootstrap.com/).  Think of PatternFly as a "skinned" version of Bootstrap with additional components and customizations. PatternFly is meant to be used as a replacement for Bootstrap, so please don't include the Bootstrap CSS if you are including the PatternFly CSS in your project.
+
+### What's Included
+
+Within the download you'll find the following directories and files, logically grouping common assets and providing both compiled and minified variations. You'll see something like this:
+
+```
+patternfly/
+├── dist/
+│   ├── css/
+│   │   │── patternfly.min.css (* need to include)
+│   │   │── patternfly-additions.min.css (* need to include)
+│   └── fonts/
+│   │   │── font and icon libraries (included via above CSS)
+│   └── img/
+│   │   │── branding materials and loading indicators
+│   └── js/
+│   │   │── patternfly.min.js (may need to include if you are using PatternFly jQuery Sidebar, Popovers or Datatables)
+├── less/
+│   ├── variables, mixin, and component Less files (may need to include if you want to customize the already built CSS)
+└── test-src/
+    ├── example markup source files
+```
+
+We provide compiled CSS and JS (`patternfly.*`), as well as compiled and minified CSS and JS (`patternfly.min.*`). CSS [source maps](https://developer.chrome.com/devtools/docs/css-preprocessors) (`patternfly.*.map`) are available for use with certain browsers' developer tools. Fonts from OpenSans, FontAwesome, PatternFly Icons are included, as well as numerous other 3rd party JS components and libraries.
+
+## Using PatternFly In Your Application
+
+1. Ensure you have installed the following utilities:
+    - [Git](http://git-scm.com/downloads): a free and open source distributed version control system.
+        - Unfamiliar with Git? Try using [GitHub for Windows](https://windows.github.com/) or [GitHub for Mac](https://mac.github.com/).
+    - [Node.js](http://nodejs.org/download/): a software platform that is used to build server-side applications.
+    - [Grunt](http://gruntjs.com/getting-started): a JavaScript task runner.
+
+            $ sudo npm install -g grunt-cli
+
+
+2. Add PatternFly as a dependency for your project and you'll receive all the libraries you'll need:
+
+        $ npm install patternfly --save
+
+    For full install options see the [README](README.md)
+
+3. Add the following CSS includes to your HTML file(s), adjusting path where needed:
+
+        <!-- PatternFly Styles -->
+        <!-- Note: No other CSS files are needed regardless of what other JS packages located in patternfly/components that you decide to pull in -->
+        <link rel="stylesheet" href="node_modules/patternfly/dist/css/patternfly.min.css">
+        <link rel="stylesheet" href="node_modules/patternfly/dist/css/patternfly-additions.min.css">
+
+4. Add the following script includes to your HTML file(s), adjusting where necessary to pull in only what you need:
+
+        <!-- jQuery -->
+        <script src="node_modules/patternfly/node_modules/jquery/dist/jquery.min.js"></script>
+
+        <!-- Bootstrap JS -->
+        <script src="node_modules/patternfly/node_modules/bootstrap/dist/js/bootstrap.min.js"></script>
+
+        <!-- C3, D3 - Charting Libraries -->
+        <script src="node_modules/patternfly/node_modules/c3/c3.min.js"></script>
+        <script src="node_modules/patternfly/node_modules/d3/d3.min.js"></script>
+
+        <!-- Datatables, jQuery Grid Component -->
+        <!-- Note: jquery.dataTables.js must occur in the html source before patternfly*.js.-->
+        <script src="node_modules/patternfly/node_modules/datatables/media/js/jquery.dataTables.min.js"></script>
+        <script src="node_modules/patternfly/node_modules/drmonty-datatables-colvis/js/dataTables.colVis.js"></script>
+        <script src="node_modules/patternfly/node_modules/datatables.net-colreorder/js/dataTables.colReorder.js"></script>
+
+        <!-- PatternFly Custom Componets -  Sidebar, Popovers and Datatables Customizations -->
+        <!-- Note: jquery.dataTables.js must occur in the html source before patternfly*.js.-->
+        <script src="node_modules/patternfly/node_modules/patternfly/dist/js/patternfly.min.js"></script>
+
+        <!-- Bootstrap Combobox -->
+        <script src="node_modules/patternfly/node_modules/patternfly-bootstrap-combobox/js/bootstrap-combobox.js"></script>
+
+        <!-- Bootstrap Date Picker -->
+        <script src="node_modules/patternfly/node_modules/bootstrap-datepicker/dist/js/bootstrap-datepicker.min.js"></script>
+
+        <!-- Moment - required by Bootstrap Date Time Picker -->
+        <script src="node_modules/patternfly/node_modules/moment/min/moment.min.js"></script>
+
+        <!-- Bootstrap Date Time Picker - requires Moment -->
+        <script src="node_modules/patternfly/node_modules/eonasdan-bootstrap-datetimepicker/build/js/bootstrap-datetimepicker.min.js"></script>
+
+        <!-- Bootstrap Select -->
+        <script src="node_modules/patternfly/node_modules/bootstrap-select/dist/js/bootstrap-select.min.js"></script>
+
+        <!-- Bootstrap Switch -->
+        <script src="node_modules/patternfly/node_modules/bootstrap-switch/dist/js/bootstrap-switch.min.js"></script>
+
+        <!-- Bootstrap Touchspin -->
+        <script src="node_modules/patternfly/node_modules/bootstrap-touchspin/dist/jquery.bootstrap-touchspin.min.js"></script>
+
+        <!-- Bootstrap Tree View -->
+        <script src="node_modules/patternfly/node_modules/patternfly-bootstrap-treeview/dist/bootstrap-treeview.min.js"></script>
+
+        <!-- Google Code Prettify - Syntax highlighting of code snippets -->
+        <script src="node_modules/patternfly/node_modules/google-code-prettify/bin/prettify.min.js"></script>
+
+        <!-- MatchHeight - Used to make sure dashboard cards are the same height -->
+        <script src="node_modules/patternfly/node_modules/jquery-match-height/jquery.matchHeight-min.js"></script>
+
+        <!-- Angular Application? You May Want to Consider Pulling Angular-PatternFly And Angular-UI Bootstrap instead of bootstrap.js -->
+        <!-- See https://github.com/patternfly/angular-patternfly for more information -->
+
+5. Prefer to use Bower? You can install patternfly using Bower (although NPM is recommended). Add the following style and script includes from `bower_components` to your HTML file(s), adjusting where necessary to pull in only what you need:
+
+        <!-- PatternFly Styles -->
+        <!-- Note: No other CSS files are needed regardless of what other JS packages located in patternfly/components that you decide to pull in -->
+        <link rel="stylesheet" href="bower_components/patternfly/dist/css/patternfly.min.css">
+        <link rel="stylesheet" href="bower_components/patternfly/dist/css/patternfly-additions.min.css">
+
+        <!-- jQuery -->
+        <script src="bower_components/jquery/dist/jquery.min.js"></script>
+
+        <!-- Bootstrap JS -->
+        <script src="bower_components/bootstrap/dist/js/bootstrap.min.js"></script>
+
+        <!-- C3, D3 - Charting Libraries -->
+        <script src="bower_components/c3/c3.min.js"></script>
+        <script src="bower_components/d3/d3.min.js"></script>
+
+        <!-- Datatables, jQuery Grid Component -->
+        <!-- Note: jquery.dataTables.js must occur in the html source before patternfly*.js.-->
+        <script src="bower_components/datatables/media/js/jquery.dataTables.min.js"></script>
+        <script src="bower_components/datatables-colvis/js/dataTables.colVis.js"></script>
+        <script src="bower_components/datatables-colreorder/js/dataTables.colReorder.js"></script>
+
+        <!-- PatternFly Custom Componets -  Sidebar, Popovers and Datatables Customizations -->
+        <!-- Note: jquery.dataTables.js must occur in the html source before patternfly*.js.-->
+        <script src="bower_components/patternfly/dist/js/patternfly.min.js"></script>
+
+        <!-- Bootstrap Combobox -->
+        <script src="bower_components/bootstrap-combobox/js/bootstrap-combobox.js"></script>
+
+        <!-- Bootstrap Date Time Picker - requires Moment -->
+        <script src="bower_components/moment/min/moment.min.js"></script>
+        
+        <!-- Bootstrap Date Picker -->
+        <script src="bower_components/bootstrap-datepicker/dist/js/bootstrap-datepicker.min.js"></script>
+
+        <!-- Bootstrap Select -->
+        <script src="bower_components/bootstrap-select/dist/js/bootstrap-select.min.js"></script>
+
+        <!-- Bootstrap Switch -->
+        <script src="bower_components/bootstrap-switch/dist/js/bootstrap-switch.min.js"></script>
+
+        <!-- Bootstrap Touchspin -->
+        <script src="bower_components/bootstrap-touchspin/dist/jquery.bootstrap-touchspin.min.js"></script>
+
+        <!-- Bootstrap Tree View -->
+        <script src="bower_components/patternfly-bootstrap-treeview/dist/bootstrap-treeview.min.js"></script>
+
+        <!-- Google Code Prettify - Syntax highlighting of code snippets -->
+        <script src="bower_components/google-code-prettify/bin/prettify.min.js"></script>
+
+        <!-- MatchHeight - Used to make sure dashboard cards are the same height -->
+        <script src="bower_components/matchHeight/jquery.matchHeight-min.js"></script>
+
+        <!-- Angular Application? You May Want to Consider Pulling Angular-PatternFly And Angular-UI Bootstrap instead of bootstrap.js -->
+        <!-- See https://github.com/patternfly/angular-patternfly for more information -->
+
+6. Enjoy!!!

data/README.md

@@ -1,192 +1,434 @@
-#patternfly-sass
+[![Build Status](https://travis-ci.org/patternfly/patternfly.svg?branch=master)](https://travis-ci.org/patternfly/patternfly)
+[![Dependency Status](https://gemnasium.com/badges/github.com/patternfly/patternfly.svg)](https://gemnasium.com/github.com/patternfly/patternfly)
+[![Code Climate](https://codeclimate.com/github/patternfly/patternfly/badges/gpa.svg)](https://codeclimate.com/github/patternfly/patternfly)
+[![npm version](https://badge.fury.io/js/patternfly.svg)](https://badge.fury.io/js/patternfly)
 
-[![Gem Version](https://badge.fury.io/rb/patternfly-sass.svg)](http://badge.fury.io/rb/patternfly-sass)
-[![Dependency Status](https://gemnasium.com/patternfly/patternfly-sass.svg)](https://gemnasium.com/patternfly/patternfly-sass)
-[![Build Status](https://travis-ci.org/patternfly/patternfly-sass.svg)](https://travis-ci.org/patternfly/patternfly-sass)
-[![Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/patternfly/patternfly-sass?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Gitter](https://badges.gitter.im/patternfly/patternfly.svg)](https://gitter.im/patternfly/patternfly?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
-`patternfly-sass` is a Sass-powered version of [PatternFly](http://github.com/patternfly/patternfly), ready to drop right into your Sass powered applications.
 
-## Installation
+# [PatternFly](https://www.patternfly.org) reference implementation
 
-Please see the appropriate guide for your environment of choice:
+This reference implementation of PatternFly is based on [Bootstrap v3](http://getbootstrap.com/).  Think of PatternFly as a "skinned" version of Bootstrap with additional components and customizations.  For information on how to quickly get started using PatternFly, see the [Quick Start Guide](QUICKSTART.md).  If you wish to contribute to PatternFly, please follow the instructions under "Contributing to PatternFly".
 
-* [Ruby on Rails](#a-ruby-on-rails).
 
-### a. Ruby on Rails
+# Installation
 
-`patternfly-sass` is easy to drop into Rails with the asset pipeline.
+### Install with NPM
 
-In your Gemfile you need to add the `patternfly-sass` gem, and ensure that the `sass-rails` gem is present - it is added to new Rails applications by default.
+PatternFly can be installed and managed through [NPM](https://www.npmjs.com/). To do so, either add `patternfly` as a dependency in your `package.json` or run the following:
 
-```ruby
-gem 'patternfly-sass', '~> 3.0.0'
-gem 'sass-rails', '>= 3.2'
 ```
+npm install patternfly --save
+```
+
+PatternFly stays up to date with the Node LTS [Release Schedule](https://github.com/nodejs/LTS#lts_schedule). If you're using PatternFly downstream, we suggest the use of an actively supported version of Node/NPM, although prior versions of Node may work.
+
+### Install with Bower
+
+PatternFly can be installed and managed through [Bower](http://bower.io/). To do so, either add `patternfly` as a dependency in your `bower.json` or run the following:
+
+```
+bower install patternfly --save
+```
+
+#### Using Wiredep?
+
+Are you using [Wiredep](https://github.com/taptapship/wiredep)?  PatternFly's CSS includes the CSS of its dependencies.  As a result, you'll want to add the following to your [Wiredep configuration](https://github.com/taptapship/wiredep#configuration) so you don't end up with duplicate CSS.
+
+```
+exclude: [
+  "node_modules/patternfly/node_modules/patternfly-bootstrap-combobox/css/bootstrap-combobox.css",
+  "node_modules/patternfly/node_modules/bootstrap-datepicker/dist/css/bootstrap-datepicker.css",
+  "node_modules/patternfly/node_modules/bootstrap-datepicker/dist/css/bootstrap-datepicker3.css",
+  "node_modules/patternfly/node_modules/bootstrap-select/dist/css/bootstrap-select.css",
+  "node_modules/patternfly/node_modules/bootstrap-switch/dist/css/bootstrap3/bootstrap-switch.css",
+  "node_modules/patternfly/node_modules/patternfly-bootstrap-treeview/dist/bootstrap-treeview.min.css",
+  "node_modules/patternfly/node_modules/c3/c3.css",
+  "node_modules/patternfly/node_modules/datatables/media/css/jquery.dataTables.css",
+  "node_modules/patternfly/node_modules/datatables.net-colreorder-bs/css/colReorder.bootstrap.css",
+  "node_modules/patternfly/node_modules/drmonty-datatables-colvis/css/dataTables.colVis.css",
+  "node_modules/patternfly/node_modules/eonasdan-bootstrap-datetimepicker/build/css/bootstrap-datetimepicker.min.css",
+  "node_modules/patternfly/node_modules/font-awesome/css/font-awesome.css",
+  "node_modules/patternfly/node_modules/google-code-prettify/bin/prettify.min.css"
+],
+```
+
+### Sass and/or Rails
+
+**Patternfly now supports Sass natively!**
+Sass is included in the `dist/sass` directory. Just add `node_modules` to your build tool's Sass include paths then `@import 'patternfly/dist/sass/patternfly';` in your Sass to get started!
+
+Please note that the packages listed below are no longer supported and will not include any features or fixes introduced after Patternfly 3.23.2  
+- NPM package: [patternfly-sass 3.23.2](https://github.com/patternfly/patternfly-sass)
+- Ruby Gem: [patternfly-sass 3.23.2](https://rubygems.org/gems/patternfly-sass)
+
+### AngularJS
+
+A set of [common AngularJS directives](https://github.com/patternfly/angular-patternfly) for use with PatternFly is available.
+
+# Contributing to PatternFly
+
+The following sections provide information on how to get started as a developer or designer in the PatternFly codebase.  In order to set up your environment, two different types of dependencies will need to be set up.  Please follow the instructions under "Development - Build Dependencies" (Node.js/Ruby) and "Development - Code Dependencies" below.  If you wish to use PatternFly in your project, please follow the [Quick Start Guide](QUICKSTART.md) instead.
+
+## Development - Build Dependencies
+
+Development setup requires Node.js and Ruby. If you do not already have Node.js, npm, and Ruby installed on your system, see https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager and https://www.ruby-lang.org/en/downloads.
+
+## Development - Code Dependencies
+
+The PatternFly code includes a number of dependencies that are not committed to this repository.  To add them, follow the instructions below under "Install NPM Dependencies".  Please make sure you keep them updated (see [Keeping NPM Dependencies Updated](#keeping-npm-dependencies-updated)).
+
+## Development - Updating Dependencies
+
+The npm-check-updates tool is available and configured to apply dependency updates to the project by running the command `npm run ncu`.  The package.json changes will have to be committed and a PR created.
+
+## Autoprefixer
+
+Patternfly uses [Autoprefixer](https://github.com/postcss/autoprefixer) to auto add prefixes to its output CSS. Since Patternfly extends some of the core Bootstrap3 less which contains prefixes, we also explicitly add prefixes in these cases to ensure backwards compatibility with Bootstrap3. If consuming Patternfly LESS and compiling, you can define your own target prefixes using [browserlist](https://github.com/ai/browserslist).
+
+### Install NPM Dependencies
+
+The development includes the use of a number of helpful tasks. In order to setup your development environment to allow running of these tasks, you need to install the local nodejs packages declared in `package.json`.
+
+To do this clone, and change directories into PatternFly:
+
+```
+cd [PathToYourRepository]
+```
+
+then
+
+```
+npm install
+```
+
+This should take care of the majority of dependencies.
+
+Since PatternFly is shrink wrapped, npm 3 will install all necessary development packages into `node_modules/patternfly/node_modules`. At this point, the gruntjs tasks are available for use such as starting a local development server or building the master CSS file.
+
+If you prefer a flat dependency structure, you can define your own dependencies explicitly. That will flatten out the node_modules structure and place dependencies in the root node_modules directory.
+
+Additionally you may need to install the grunt command line utility.  To do this run:
+
+    npm install -g grunt-cli
+
+Test pages are optionally generated using [Jekyll](http://jekyllrb.com/). To use jekyll to build the test pages, ensure Ruby is installed and available then run:
+
+```
+npm run jekyll
+```
+
+or
+
+```
+gem install bundle
+bundle install
+```
+
+During the install you may be asked for your password as part of the [Ruby](https://www.ruby-lang.org/en/documentation/installation/) installation process.
+
+Next, set the environment variable PF_PAGE_BUILDER=jekyll.  eg.:
+    PF_PAGE_BUILDER=jekyll grunt build
+
+#### Keeping NPM Dependencies Updated
+
+Anytime you pull a new version of PatternFly, make sure you also run
+
+```
+npm update
+```
+
+so you get the latest version of the dependencies specified in package.json.
 
-`bundle install` and restart your server to make the files available through the pipeline.
+### Live Reload Server
 
-Import Bootstrap styles in `app/assets/stylesheets/application.scss`:
+A local development server can be quickly fired up by using the Gruntjs server task:
 
-```scss
-// "patternfly-sprockets" must be imported before "patternfly" and "patternfly/variables"
-@import "patternfly-sprockets";
-@import "patternfly";
+```
+npm start
+```
+
+or
+
+```
+grunt server
 ```
 
-`patternfly-sprockets` must be imported before `patternfly` for the icon fonts to work.
+This local static asset server (i.e., [http://localhost:9000](http://localhost:9000)) has the advantage of having livereload integration. Thus, if you start the Gruntjs server, any changes you make to `.html` or `.less` files will be automatically reloaded into your browser and the changes reflected almost immediately. This has the obvious benefit of not having to refresh your browser and still be able to see the changes as you add or remove them from your development files.  Additionally, any changes made to Jekyll source files (`tests/pages/`) will trigger a Jekyll build.
 
-Make sure the file has `.scss` extension (or `.sass` for Sass syntax). If you have just generated a new Rails app,
-it may come with a `.css` file instead. If this file exists, it will be served instead of Sass, so rename it:
+### Coding Style
+
+See [http://codeguide.patternfly.org/](http://codeguide.patternfly.org/).
+
+### Commiting changes
+
+PatternFly uses the [semantic-release tool](https://github.com/semantic-release/semantic-release) to provide a continuous release mechanism for PatternFly.  In order for this tool to correctly increment the project version, and include your changes in the generated release notes, you will have to format your commit messages according to a well-defined commit message format.
+
+We have configured the [commitizen tool](https://github.com/commitizen/cz-cli) to assist you in formatting your commit messages corrctly.  To use this tool run the following command instead of `git commit`:
 
-```console
-$ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss
+```
+npm run commit
 ```
 
-Then, remove all the `//= require` and `//= require_tree` statements from the file. Instead, use `@import` to import Sass files.
+#### Git Commit Guidelines
 
-Do not use `//= require` in Sass or your other stylesheets will not be [able to access][antirequire] the PatternFly mixins or variables.
+Alternatively, if you are familiar with the commititzen message format you can format the message manually.  A summary of the commit message format is as follows:
 
-Require PatternFly Javascripts in `app/assets/javascripts/application.js`:
+Each commit message consists of a **header**, a **body** and a **footer**.  The header has a special
+format that includes a **type**, a **scope** and a **subject** ([full explanation](https://github.com/stevemao/conventional-changelog-angular/blob/master/convention.md)):
 
-```js
-//= require jquery
-//= require bootstrap
-//= require patternfly
 ```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+##### Patch Release
 
-#### Rails 4.x
+```
+fix(pencil): stop graphite breaking when too much pressure applied
+```
 
-Please make sure `sprockets-rails` is at least v2.1.4.
+##### Feature Release
 
-#### Rails 3.2.x
+```
+feat(pencil): add 'graphiteWidth' option
+```
 
-patternfly-sass is no longer compatible with Rails 3.
+##### Breaking Release
 
-### Configuration
+```
+perf(pencil): remove graphiteWidth option
+```
+The tool will prompt you with several questions that it will use to correctly format your commit message.  You can then proceed with your PR as you normally would.
 
-#### Sass
+## Build
 
-By default all of PatternFly is imported.
+### CSS
 
-You can also import components explicitly. To start with a full list of modules copy
-[`_patternfly.scss`](assets/stylesheets/_patternfly.scss) file into your assets as `_patternfly-custom.scss`.
-Then comment out components you do not want from `_patternfly-custom`.
-In the application Sass file, replace `@import 'patternfly'` with:
+In development, styling is written and managed through multiple Less files. In order to generate a CSS file of all styling, run the build Gruntjs task:
 
-```scss
-@import 'patternfly-custom';
+```
+npm run build
 ```
 
-#### Sass: Number Precision
+or
 
-patternfly-sass [requires](https://github.com/twbs/bootstrap-sass/issues/409) minimum [Sass number precision][patternfly-precision] of 8 (default is 5).
+```
+grunt build
+```
 
-Precision is set for Rails automatically.
-When using ruby Sass compiler standalone you can set it with:
+This task will compile and minify the Less files into CSS files located at `dist/css/patternfly.min.css` and `dist/css/patternfly-additions.min.css`.
 
-```ruby
-::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max
+### Less to Sass Conversion
+Any time style changes are introduced, the Sass code will need to be updated to reflect those changes. The conversion is accomplished as part of the build, but in order to test the CSS you will need to build it from Sass:
+
+```
+npm start -- --sass
 ```
+*Note the extra ` -- ` between `npm start` and the `--sass` flag. This syntax passes the flag on to the underlying grunt process instead of the npm command itself.*
 
-#### Sass: Autoprefixer
+or
 
-PatternFly requires the use of [Autoprefixer][autoprefixer].
-[Autoprefixer][autoprefixer] adds vendor prefixes to CSS rules using values from [Can I Use](http://caniuse.com/).
+```
+grunt build --sass
+```
 
-#### JavaScript
+These tasks will run a Less to Sass conversion, then compile and minify the resulting Sass into CSS, creating a `dist/css/patternfly.css` file. Note that building from Sass does not create the `dist/css/patternfly-additions.css` file, which is the expected behavior.
 
-[`assets/javascripts/patternfly.js`](/assets/javascripts/patternfly.js) contains all of PatternFly JavaScript,
-concatenated in the correct order.
+The Less to Sass Conversion step will be accomplished and managed as a part of any Pull Request which includes Less file changes. Although contributors may want to build and test their style changes with Sass before submitting a Pull Request, this step should always be tested and validated by reviewers before a style change is merged and released. If a contributor is having issues with Sass conversion that they cannot resolve, Pull Request reviewers will need to ensure that the Sass conversion step is successfully accomplished, tested, and included in the Pull Request before it is approved and merged.
 
-#### Fonts
+### Scenarios to Avoid when Making Less Style Updates
 
-The fonts are referenced as:
+Sass and Less do not have perfect feature parity, which can sometimes throw a wrench into the conversion process described above. Furthermore, a failed conversion may be somewhat transparent since it may create Sass that will compile to unexpected, but valid CSS. The following are a few known scenarios that can be easily avoided to prevent failures in the Less to Sass conversion process.
 
-```scss
-"#{$icon-font-path}#{$icon-font-name}.eot"
+#### Non-parametric Mixins
+Sass does not support non-parametric mixins in the same way that Less does. Mixins must be explictly declared in Sass, whereas any class definition in Less can be used as a non-parametric mixin. Sass does not have a feature that perfectly parallels this behavior, so we have to use the closest thing which is the `@extend` statement. However, an edge case exists where `@extend` statements are not allowed within media queries in Sass. This creates a scenario where uncompilable Sass code can be generated from perfectly acceptable Less. For example:  
+**Less:**
+```
+  .applauncher-pf {
+    .applauncher-pf-title {
+        .sr-only();
+    }
+  }
+
+  @media (min-width: @screen-sm-min) {
+   .applauncher-pf;
+  }
 ```
 
-`$icon-font-path` defaults to `patternfly/` if asset path helpers are used, and `../fonts/patternfly/` otherwise.
+**Converts to Sass:**
+```
+  .applauncher-pf {
+    .applauncher-pf-title {
+      @extend .sr-only;
+    }
+  }
+
+  @media (min-width: @screen-sm-min) {
+    @extend applauncher-pf; //Invalid Sass
+  }
+```
 
-When using patternfly-sass with Sprockets, you **must** import the relevant path helpers before PatternFly itself, for example:
+This breaks for two reasons. We cannot use the `@extend` statement directly inside a media query, and even if we are able to work around that by making applauncher-pf into a mixin and using the `@include` directive, `.applauncher-pf .applauncher-pf-title` uses the `@extend` directive, which would still fall within the media query via the mixin invocation. To fix this, the Less would need to be adjusted like this:
 
-```scss
-@import "patternfly-sprockets";
-@import "patternfly";
+**Less**
+```
+  // Explicitly define a non-parametric sr-only mixin.
+  .sr-only() {
+    // sr-only rules;
+  }
+
+  // Explicitly define a non-parametric applauncher-pf mixin.
+  .applauncher-pf() {
+    .applauncher-pf-title {
+      // Explicitly invoke sr-only mixin.
+      .sr-only();
+    }
+  }
+
+  // Define the .applauncher-pf class and explicitly invoke the applauncher-pf
+  // mixin.
+  .applauncher-pf {
+    .applauncher-pf();
+  }
+
+  @media (min-width: @screen-sm-min) {
+    // Explicitly invoke applauncher-pf mixin inside of media query
+   .applauncher-pf();
+  }
 ```
 
-## Usage
+**Converts to Sass:**
+```
+  @mixin sr-only() {
+    // sr-only rules
+  }
+
+  @mixin applauncher-pf() {
+    .applauncher-pf-title {
+      @include sr-only();
+    }
+  }
+
+  .applauncher-pf {
+    @include applauncher-pf();
+  }
+
+  @media (min-width: @screen-sm-min) {
+    @include applauncher-pf();
+  }
+```
 
-### Sass
+#### Tilde-Escaped Strings
+Strings that are escaped using the tilde in Less get converted to the Sass `unquote()` function. This causes Sass compilation issues when using escaped strings inside native CSS functions like `calc()`. Here is what happens:  
+Less:
+```
+height: calc(~"100vh - 20px");
+```
+Converts to Sass:
+```
+height: calc(unqoute("100vh - 20px")):
+```
+Which compiles directly to CSS and does not work as expected:
+```
+height: calc(unqoute("100vh - 20px")):
+```
 
-Import PatternFly into a Sass file (for example, application.scss) to get all of PatternFly's styles, mixins and variables!
+To fix this, move the tilde operator outside of the `calc()` statement:
 
-```scss
-@import "patternfly";
+Less:
+```
+height: ~"calc(100vh - 20px)";
+```
+Converts to Sass:
+```
+height: unqoute("calc(100vh - 20px)");
+```
+Compiles to CSS:
+```
+height: calc(100vh - 20px);
 ```
 
-The full list of patternfly variables can be found [here](/assets/stylesheets/patternfly/_variables.scss). You can override these by simply redefining the variable before the `@import` directive, e.g.:
+#### Comma Separated CSS Rules
+Using complex, comma separated rules in things like box shadows or backgrounds will cause conversion problems if they are not properly escaped. These rules should be escaped, and mixins and variables should not be used inline. For example, this statement should not be used in Less:
+```
+box-shadow: inset 0 1px 1px fade(@color-pf-black, 7.5%), 0 0 6px lighten(@state-danger-text, 20%);
+```
 
-```scss
-$navbar-default-bg: #312312;
-$light-orange: #ff8c00;
-$navbar-default-color: $light-orange;
+Instead, mixins should be assigned to variables, and variables should be interpolated in an escaped string like this:
 
-@import "patternfly";
 ```
+@color1: fade(@color-pf-black, 7.5%);
+@color2: lighten(@state-danger-text, 20%);
+box-shadow: ~"inset 0 1px 1px @{color1}, 0 0 6px @{color2}";
+```
+
+This is especially important when passing a complex rule to a mixin.
+
+### PatternFlyIcons Font
 
-## Version
+PatternFlyIcons font is generated using [IcoMoon](http://icomoon.io/app). Go to [manage projects](https://icomoon.io/app/#/projects) and import the project `PatternFlyIcons-webfont.json`. Load it and update as necessary. When finished, return to manage projects, and download the updated `PatternFlyIcons-webfont.json` file. Also generate the fonts. Please commit the updated `PatternFlyIcons-webfont.json` file, the updated font files and supporting LESS/CSS changes.
+For detailed instructions, please see our [PatternFly Icon Guide](PFICONS.md)
 
-PatternFly for Sass version may differ from the upstream version in the last number, known as
-[MINOR](http://semver.org/spec/v2.0.0.html). The minor version may be ahead of the corresponding upstream minor.
-This happens when we need to release Sass-specific changes.
+## Tests
 
-Always refer to [CHANGELOG.md](/CHANGELOG.md) when upgrading.
+The `tests/` directory contains HTML pages with component and pattern examples in order to facilitate development.  Please consult the official documentation (see below) for full details on how to use PatternFly.  The latest PatternFly test directory examples can be seen at [https://rawgit.com/patternfly/patternfly/master-dist/dist/tests/](https://rawgit.com/patternfly/patternfly/master-dist/dist/tests/).
 
----
+If you are developing on PatternFly and would like to provide a link to a test directory from your fork, TravisCI can be configured to create a copy of your branch with the dist files generated for you.  No code changes are necessary to enable this, all that is needed is to login to [TravisCI](https://travis-ci.org/) and configure it to point at your PatternFly fork.  The first three steps at their [Getting Started page](https://docs.travis-ci.com/user/for-beginners) provide instructions on how to do this.  You will also need to add an AUTH_TOKEN variable to Travis generated in your GitHub account to allow Travis to connect to your fork.
 
-## Development and Contributing
+The HTML pages in `dist/tests` are generated using Jekyll.  Do *not* edit these files directly.  See `tests/pages` to change these files.
 
-If you'd like to help with the development of patternfly-sass itself, read this section.
+### Unit Testing
+Unit tests are written for [Karma test server] (https://karma-runner.github.io/1.0/index.html) with [Jasmine](http://jasmine.github.io/)
+
+```
+npm test
+```
+
+or
+
+```
+grunt karma
+```
+### Visual Regression Testing
 
-### Upstream Converter
+Visual regression tests provide a way to detect if unintended visual changes have
+occured as a result of changes in the code. They work by taking screenshots of
+what components or pages should look like in a browser (known as references), and then comparing the references to screenshots of those components or pages with your code changes applied. Once the tests are complete, you will be a shown the test results in a browser.
 
-Keeping patternfly-sass in sync with upstream changes from PatternFly used to be an error prone and time consuming manual process. With Bootstrap 3 we have introduced a converter that automates this.
+You can run all of the test scenarios with `npm run regressions`.
 
-**Note: if you're just looking to *use* PatternFly, see the [installation](#installation) section above.**
+You can run specific test scenarios with `npm run regressions <scenario-name>`. This
+will probably be most useful while you are doing active development and only want
+to check a few scenarios without running the entire suite.
+(Ex. `npm run regressions alerts buttons`)
 
-Upstream changes to the PatternFly project can now be pulled in using the `convert` rake task.
+To approve conflicts run: `npm run approve-conflicts`. This is the command you want to run
+when the tests find conflicts, but the conflicts are intended. This command
+will replace the base image, so if you run the regression tests again, the
+tests should pass.
 
-Here's an example run that would pull down the master branch from the main [patternfly/patternfly](https://github.com/patternfly/patternfly) repo:
+## Documentation
 
-    rake convert
+See [https://www.patternfly.org](https://www.patternfly.org) and [http://getbootstrap.com/](http://getbootstrap.com/).
 
-This will convert the latest LESS to Sass and update to the latest JS.
-To convert a specific branch or version, pass the branch name or the commit hash as the first task argument:
+### Browser and Device Support
 
-    rake convert[tags/v1.2.1]
+Since PatternFly is based on Bootstrap, PatternFly supports [the same browsers as Bootstrap](http://getbootstrap.com/getting-started/#support) **excluding Internet Explorer 8**, plus the latest version of [Firefox for Linux](https://support.mozilla.org/en-US/kb/install-firefox-linux).
 
-The latest converter script is located [here][converter] and does the following:
+*Important:*  starting with the v2.0.0 release, **PatternFly no longer supports Internet Explorer 8**.
 
-* Converts upstream patternfly LESS files to its matching SCSS file.
-* Copies all upstream JavaScript into `assets/javascripts/patternfly`, a Sprockets concatenation at `assets/javascripts/patternfly.js`.
-* Copies all upstream font files into `assets/fonts/patternfly`.
-* Sets `Patternfly::PATTERNFLY_SHA` in [version.rb][version] to the branch sha.
+### Product Backlog
 
-This converter fully converts original LESS to SCSS. Conversion is automatic but requires instructions for certain transformations (see converter output).
-Please submit GitHub issues tagged with `conversion`.
+See [https://patternfly.atlassian.net/secure/RapidBoard.jspa?projectKey=PTNFLY&rapidView=4&view=planning](https://patternfly.atlassian.net/secure/RapidBoard.jspa?projectKey=PTNFLY&rapidView=4&view=planning).
 
-## Credits
+### Bug List
 
-patternfly-sass's converter is a fork of [bootstrap-sass](https://github.com/twbs/bootstrap-sass). The modifications and all other code is made by:
+Official tracking of bugs occurs in Jira.  See https://patternfly.atlassian.net/issues/?filter=10304
 
-<!-- feel free to make these link wherever you wish -->
-* [Alex Wood](https://github.com/awood)
-* [Dávid Halász](https://github.com/skateman)
+## License
 
-[converter]: https://github.com/patternfly/patternfly-sass/blob/master/tasks/converter.rb
-[version]: https://github.com/patternfly/patternfly-sass/blob/master/lib/patternfly-sass/version.rb
-[contrib]: https://github.com/patternfly/patternfly-sass/graphs/contributors
-[antirequire]: https://github.com/bootstrap/bootstrap-sass/issues/79#issuecomment-4428595
-[autoprefixer]: https://github.com/ai/autoprefixer
+Modifications to Bootstrap are copyright 2013 Red Hat, Inc. and licensed under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).