# SendGrid Style Guide

`style-guide` contains all of SendGrid's styles for customer facing applications, such as Mako and Marketing Campaigns. It also hosts a living style guide at [sendgrid.github.io/style-guide](http://sendgrid.github.io/style-guide).

## Installing

```sh
git clone git@github.com:sendgrid/style-guide.git
cd style-guide
npm install
```

Depending on your locally installed gems, you may also need to install [scss_lint](https://github.com/brigade/scss-lint).

```sh
gem install scss_lint
```

## Local Development

```sh
npm start
```

## Contributing

Before contributing code, make sure you are familiar with our standards:

### OOCSS

The primary driving philosophy behind style-guide is [OOCSS](http://www.smashingmagazine.com/2011/12/an-introduction-to-object-oriented-css-oocss/):

- **Separate structure from skin**: Define repeating visual features (like `background` and `border` styles) as separate "skins" that you can mix-and-match with your various objects to achieve a large amount of visual variety without much code

- **Separate container and content**: Essentially, this means "rarely use location-dependent styles". An object should look the same no matter where you put it. Don't deeply nest your selectors.  Only use the SCSS `&` symbol for tightly coupled selectors, such as `:hover` or `:before` pseudo selectors

### SCSS Organization

We use [SMACSS](https://smacss.com/book/categorizing) for categorizing our SCSS files. We organize files into three directories: `global`, `tiara`, and `components`.

### SCSS Conventions

We follow the conventions outlined in [codeguide.co](http://codeguide.co/#css).

### Pull Requests

All pull requests should get reviewed by the style-guide owner (Jason Walker). If you are modifying existing styles, you need a cross-team front-end developer from the Mako or Marketing Applications team to also review.

When you open a pull request, you'll see a provided checklist of things to do before merging, which are:

- [ ] CSS is organized and follows common patterns
- [ ] SCSS Linting errors have been resolved
- [ ] Components are displayed and explained on the demo page
- [ ] CR'd by Jason Walker
- [ ] CR'd by cross-team member (only needed if updating an existing style)

## Deploying

To create production assets, you can run:

```sh
npm run build
```

The build task will compress and concatenate all the .css, .js, optimize images, and copy the fonts directory over to the dist folder. Once the build task has completed running, you can copy the contents of dist into the gh-pages branch of style-guide. Pushing gh-pages will automatically update the demo site.
