Purple

A UI kit for Heroku's web interfaces. To get started, check out https://purple.herokuapp.com!

Quickstart

Developing

Dependencies

1. nodejs + npm

New Releases

Please follow the instructions in the HIT repo when making a new release.

https://github.com/heroku/hit/blob/master/purple-deployment-instructions.md

Spinning it up locally

npm install
npm start

Now open localhost:5000 in your browser.

See the Private Repo Resolution section below.

Live development in npm package consumer

With this package installed locally, you can make changes to the source and have them reflected on the fly in a bower-based consumer. There is no need to manage and push to remote branches to test.

1. in your purple directory run bower link
2. then run gulp watch to automatically compile changes
3. cd into your other bower-based project
4. run bower link purple
5. ensure that any task runner you have (grunt, gulp, etc.) is watching for changes to your node_modules directory and recompiling that projects own assets. In grunt this would look like:

watch: {
    purpleScripts: {
        files: ['node_modules/purple/dist/js/*.js'],
        tasks: ['concat:bower']
    },
    styles: {
        files: ['assets/styles/**/*.scss', 'node_modules/purple/dist/css/*.css'],
        tasks: ['sass']
    }
}

6. To revert back to that project's bower.json specified version of purple, run bower uninstall purple and then bower install

Now you should be all set.

Private Repo Resolution

As long as this is a private repo, we must take a few steps in order to be able to smoothly deploy this on the Heroku platform

Local setup

Make sure you have GitHub password caching setup.

If you have enabled 2-Factor Auth on GitHub (and you should!) your GitHub password will not authenticate https remotes. You must get an OAuth token to do so. Follow these steps:

• On GitHub, open your Account settings.
• Go to the Applications tab.
• Generate a new Personal Access Token. Name it appropriately.
• Copy the generated token and paste it into some secure password manager like 1Password or LastPass.
• When you try to clone a https repo, paste in your token rather than typing your GitHub password.
• The git credential.manager configured above will store your OAuth token for all future HTTPS interaction with GitHub.

Production Setup

In order to access this repo via bower in production, do the following (assuming you already have a buildpack set):

1. heroku buildpacks:add https://github.com/timshadel/heroku-buildpack-github-netrc
2. ask Jack to generate a new read-only token for you from the heroku github read-only team Alternatively, create a new github user, add them to the read-only github team and then generate a personal access token for them.
3. run heroku config:set GITHUB_AUTH_TOKEN=<my-read-only-token> for the production app

Rails setup

Using Sprockets

Ruby projects can include purple from our internal gem server. Be sure to specify the correct source.

gem 'purple'

Run bundle install and add the following line to your application.scss or equivalent file:

@import 'purple/rails';

Also add the following line to your application.js or equivalent file:

//= require purple/rails

That's all!

Notice: you'll still need to configure Github password caching.

Deploying

1. run heroku config:add BUILDPACK_URL=https://github.com/ddollar/heroku-buildpack-multi.git to setup multi buildpacks
2. create a .buildpacks file and add:

https://github.com/timshadel/heroku-buildpack-github-netrc.git
https://github.com/heroku/heroku-buildpack-ruby.git

3. Follow the directions here to allow bower to download from the private purple repo.

CDN

The fastest way to get started is to use our CDN:

<link rel="stylesheet" href="//www.herokucdn.com/purple/1.0.0/purple.min.css">
<script src="//www.herokucdn.com/purple/1.0.0/purple.min.js"></script>

For a list of available purple versions, see herokucdn.com/purple/.