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)"
Yarn and Grunt
Node,$ 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 bothyarn.lock
andpackage.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 bothpackage.json
andyarn.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
usingbrew 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).
- Have your code reviewed and approved as per above.
- Merge your release into
master
using GitHub's Pull Request page. - From the
master
branch ofstyles
git pull
-
grunt prod
and ensure that styles builds correcltly. If you run into an error you may need to runyarn install
(this happens when master has bumped a dependency since you last had master). - 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
- 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. =^.^=
- 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
andpackage.json
fortwitch-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.