twitch-styles1 v1.23.3

Twitch Styles

This repo contains CSS for web & web-client.

• Requirements
• Setup
• Syntax, Rules, and Class Naming
• Core UI
• Living Style Guide
• Grunt Tasks
• Development on Twitch (web, web-client)
• Testing Ads
• Testing on Staging
• Release

Requirements

Homebrew

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Node, Yarn and Grunt

$ brew update
$ brew install homebrew/versions/node6-lts
$ brew install yarn
$ npm install grunt-cli -g

Updating packages

We are using yarn to manage our projects dependencies (see https://yarnpkg.com/ for info on the benefits over npm). This means there are a few differences to updating dependencies that you may need to know.

• Updating a specific dependency: yarn upgrade <package-name-here>. This will update both yarn.lock and package.json to the newest version.
• Updating deps to newer versions: yarn upgrade-interactive. This will provide a nice set of prompts for each outdated package in the project, and make updating both package.json and yarn.lock much easier.

General Rules of Contribution

• Comment all new features regardless of implied clarity based on naming.
• When retiring or modifying a feature to move to a new pattern, ensure that web-client and web are accounted for.
• Use our color variables and always account for accessibility when developing color combinations. The colors page will help with this greatly.
• Avoid nesting to increase scope strength if not absolutely necessary.
• When developing a new feature, test to see if current patterns can achieve most of what you are looking for. Avoid rebuilding again for minute changes.
• Stage everything. All pull requests require a staging enviroment.
• Ask for help!

Setup

Clone styles and install node modules

$ git clone git@git-aws.internal.justin.tv:web/styles.git
$ cd styles
$ yarn install

If you receive a node-binding error with node-sass and node 6 you may have an outade version of yarn. Please update yarn to 0.17.8 using brew update && brew upgrade yarn

Upgrading dependencies

When dependecies have upgraded use yarn install to update.

Syntax, Rules, and Class Naming

CSS on twitch is written in original sass syntax using BEM (Block Element Modifier) class naming. Hyphens for separating words, __ for elements and -- for modifiers. Word separations are done with -. Although much of our legacy styles have a mix of naming strategies we use all lower case naming, no upper-case, title case or camelCase.

BEM

Block class-name Elements class-name__element Modifier class-name--modifier

Styles uses BEM as it helps ensure immediate class dependency recognition, reduces run-time overwrites due to class name collision, and also reduces selector count by encouraing the use of low selector cohesion.

We do not use double nesting of the element syntax in our naming structure. .base__element__element (don't do this) as this implies structure of html syntax which could change at any time.

3 selectors (BEM) vs 6 selectors (traditional)

// This is how we should be writting our css
.button { }
.button--large { }
.button--red{ }

// High probability of overwrites. Names are too generalized and selector count creep risk
.button { }
.button.large{ }
.button.large.red{ }

Some Resources on BEM

• http://getbem.com/
• https://css-tricks.com/bem-101/
• http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/

JS and QA elements

Dom elements that need to be manipulated or accessed by JS or our QA tools need to be prefixed with js- or qa- respectively.

IDs or class?

IDs never. No exceptions. Older IDs are being refactored. Insert long explanation here about troubles with scoping and DOM manipulation with IDs.

Extends

Using the @extend function is not allowed on styles. Extends are difficult to track down, add selector bloat, and modern gzipping already compresses common word patterns. Use mixins or the actual class name that already exists for your markup. Legacy @extends will be removed on an ongoing basis.

Core UI

https://git-aws.internal.justin.tv/web/core-ui

Core UI (core-ui) is a component library and functional Sass framework for building Twitch UI.

This library includes modular, React-based, responsive components as well as a functional CSS framework containing global helpers, variables and mixins. The goal is to provide a toolkit of foundational building blocks to bootstrap new projects and provide the structural underpinning of larger front-end systems.

Living Style Guide

https://git-aws.internal.justin.tv/pages/web/styles/

Styles uses Nunjucks templating. A javascript port of Jinja2/Django.

http://mozilla.github.io/nunjucks/templating.html

Linting

sass-lint runs on commit and if linting fails the commit will be rejected. If you absolutely must commit sass that fails lint, add the path to the ignore section of .sass-lint.yml in styles root.

sass-lint can also be run at any time via the grunt lint command.

Grunt Tasks

Default - Compile All CSS and Watch for Sass Changes

$ grunt

The basic grunt task will run libsass on all sass files found within the sass folder and then process the compiled css using autoprefixer. A watch task will auto generate css on any sass changes.

Styleguide Creation (CSS and Nunjunk Templating)

$ grunt styles

This task will run all of the sass specific tasks plus run a local runserver to view the styleguide. Styleguide pages are created using nunjunks/django templates found in the views folder. Template saves will auto generate the static files which will live in /stylgeuides. This task also creates a livereload instance with the local server which will auto refresh the browser on css and html changes.

No livereload server option

$ grunt styles --live-reload false

CSS Stats

$ grunt stats

This uses CSScount and Stylestats to give you a very quick assessment of your rules and selector counts. Includes a thorough rundown of fonts, colors, selectors, cohesion and other applicable stats from your css files.

Production Task

$ grunt prod

Grunt task for building files just for production. Similar to default but this adds the combine_mq task to combine all similar media queries and does not create a watch task.

Auto Update GH Pages

$ grunt gh-pages

This task will:

• Delete all files found in /styleguide
• Generate all css files from sass directories
• Copy all /static/** files to /styleguide/static/**
• Generate static html files from nunjunk templates
• Runs the buildGHpages task which will auto push all files found in /styleguide to the gh-pages branch of /web/styles and update the living styleguide: https://git-aws.internal.justin.tv/pages/web/styles/

Development on Twitch

While modifying the styles locally you may wish to see the changes reflected in web and web-client. In order for that to work, you need to checkout and run a local version of those repos and have them point at your local version of CSS. The process is unfortunately different between web and web-client.

Testing CSS in web-client

To test just web client, you will need to have a checked out and build able version of web-client. To have web-client use your version you must:

In the styles repo:

npm link

In web-client:

npm link twitch-styles

In the styles repo:

grunt

Serve web-client

ember serve

Serve web-client without livereload (if you want to use the LR app)

ember serve --live-reload false

Testing CSS in web

If web is checked out into the same directory as styles you can just run

$ grunt link

If however you've gotten clever with your paths you must run

$ grunt link --link-path=/PATH/TO/WEB/app/assets/stylesheets/twitch

Testing Ads

In order to ensure that ads are properly aligned on the site use the ?campaign= variable in urls.

Homepage Takeovers - Static https://www.twitch.tv/?campaign=jpg https://twitch.tv/?campaign=uxteam3

Sizzle only https://twitch.tv/?campaign=uxteam4

Testing on Staging

Since staging has no concept of NPM link and twitch-styles you will need to change the NPM dependency in web-client to point to your feature branch.

Create a feature/styles/bugfix branch in web-client (if you have not already done so)

cd ~/twitch/web-client/
git checkout master
git pull
git checkout -b new-branch-name

Update the yarn.lock and package.json from the command line using yarn in web-client to point to your branch in styles.

yarn upgrade twitch-styles@git+ssh://git@git-aws.internal.justin.tv/web/styles.git#branch-name

On subsequent updates you will need to forcefully update the commit hash for this branch by running the following. This is due to yarn assuming the hash url will never update on a release and one of the reasons Yarn is as fast as it is.

yarn remove twitch-styles
yarn add twitch-styles@git+ssh://git@git-aws.internal.justin.tv/web/styles.git#branch-name

Claim a staging server

https://docs.google.com/spreadsheets/d/1Unh6ySneYOb3nD8sM3Fy7yXv2hhzd-G197OG73ukfig/edit#gid=0

Deploy your web-client feature branch to stagingmarkd

https://clean-deploy.internal.justin.tv/#/web/web-client

Release

Styles is bundled and released with a version of web-client. As such to release a version of the styles you must make the CSS available to be imported by web-client. When you are ready to release a version you should:

Submit a Pull Request

Styles uses GitHub pull requests to manage our code reviews. Submit a PR directly through the compare branch name flows directly on GitHub or using the git request-pull method.

For major changes pull requests should be done well in advance of the intended launch date.

Please include a web-client (or other repo that uses this css) branch and a staging url to properly PR these changes.

Creating a release

Ensure you have followed the install setup process for styles and that you have properly compiling css files in /static/css. This entire release process must be done in one go. Once you merge into master you must publish your release. Not doing so will put the responsiblity of your merge into the hands of the next.

Double check that you are authenticated with the private NPM registry: npm login --registry http://npm-registry-prod-def.internal.justin.tv User name and password are both npm_user. Use your justin.tv email when prompted (read here for troubleshooting).

1. Have your code reviewed and approved as per above.
2. Merge your release into master using GitHub's Pull Request page.
3. From the master branch of styles
4. git pull
5. grunt prod and ensure that styles builds correcltly. If you run into an error you may need to run yarn install (this happens when master has bumped a dependency since you last had master).
6. Use one of the following yarn version commands to automatically upgrade the styles version and publish to our npm registry

• For an update to the patch version (the x in 1.2.x) use: npm version patch
• For an update to the minor version (the x in 1.x.0) use: npm version minor

1. Visit the release page https://git-aws.internal.justin.tv/web/styles/releases and click on your new tag and edit. Add title and release notes. Thorough release notes are a must as they are an important aspect in allowing us to keep an eye on styles across the site. =^.^=
2. Ensure release is seen here: http://npm-registry-prod-def.internal.justin.tv/twitch-styles under dist-tags: { latest: "0.x.x"},

If your release is not found in the versions node of this json file, styles has not properly been released. In most cases you were probably not properly authenticated with the private NPM registry. Authenticate yourself with the registry and run npm publish to ensure the tag release is published.

Deploying with web-client

You have now released a version of Web Styles. However it is not being consumed by our various properties yet. To get it in use you must deploy it with web-client. To release a tagged build for use follow these steps:

• Checkout web-client
• Modify the entry in yarn.lock and package.json for twitch-styles using yarn and making sure to point to your published package version:

yarn upgrade twitch-styles@x.x.x

• Commit your change into a new or wip branch and create a pull request in web-client.
• Merge to master after approval and web-client will auto deploy with the new styles dependency.