scpr-style-guide

KPCC Style Guide

This repository houses scpr-style-guide, a shared style library for KPCC web products. Major HT to the US Web Design Standards project and their cg-style project; the code and structure for KPCC's style guide are based in large part on their work.

The scpr-style-guide provides the assets (CSS, SCSS, JS, images and font declarations) to design KPCC-branded, consumer-facing, editorial websites. This allows multiple sites, built in separate repositories and with different languages, to share a unified global style. The scpr-style-guide library is distributed on the node/npm ecosystem.

Installation and usage

scpr-style-guide can be consumed by a project by installing it via npm. Run the following command on a computer with node/npm installed to install scpr-style-guide into your project:

npm install scpr-style-guide --save

Once installed, all the assets from scpr-style-guide have to be consumed by your project. This can be done in multiple ways depending on what assets and your project setup. For example, a simple site could copy over the relevant assets with build commands and include them from the html with link tags.

# build commands
cp ./node_modules/scpr-style-guide/js/* ./public/js
cp ./node_modules/scpr-style-guide/css/* ./public/css
cp -R ./node_modules/scpr-style-guide/img/**/* ./public/img
cp -R ./node_modules/scpr-style-guide/font/**/* ./public/font

Another possibility for importing the JS and SCSS is to use Browserify and SASS to import them into the project.

require('scpr-style-guide');

@import './node_modules/scpr-style-guide/src/css/main.scss';

Configuring asset paths for your project

scpr-style-guide sometimes references relative paths to assets in its javascript modules, and has a configuration variable set up to allow you to define the relative path to assets, since your relative asset paths will likely vary depending on your project/framework. Somewhere in your project before you load scpr-style.js, you'll want to declare the local path to assets in your project, which will look something like:

<script>
  ASSETS_PATH = "<your-path-to-scpr-style-guide-assets>";
</script> 

If ASSETS_PATH isn't defined anywhere in your project, then scpr-style-guide sets a default path of /.

Using svg images

Images that are part of the scpr-style-guide project are available as one central SVG sprite with each image consisting of a SVG <symbol>. To use these images, you can use the SVG xlink attribute as follows:

  <svg class="icon">
    <use xlink:href="/public/img/scpr-sprite.svg#i-share"/>
  </svg>

Contributing to the style guide

Anyone at SCPR can contribute improvements to scpr-style-guide. Making changes/improvements typically involves getting the repo set up for local development, adding/refactoring one or more patterns, committing those changes, and then publishing a new version of the style guide to npm.

Local Development

To get scpr-style-guide up and running for local development:

1. clone the repo to your machine: git clone [e-mail]:SCPR/scpr-style-guide.git
2. cd into the scpr-style-guide directory.
3. Run npm install to install javascript dependencies.
4. Run bundle install to install Ruby gem dependencies.
5. To get the documentation site running locally, fire up Middleman by running bundle exec middleman server and navigate to http://localhost:4567.
6. To have the project watch for file changes and recompile CSS, JS and image assets on the fly, run npm run watch in another terminal window.

Adding a new CSS pattern

Adding a new CSS pattern to the style guide looks something like:

1. Create a new SCSS partial in src/css/*, (e.g. a new modal component would be created at src/css/components/_modals.scss).
2. Import the new SCSS partial into the all.scss file in the same directory (e.g. src/css/components/all.scss).
3. Author your CSS inside the partial for the new pattern, taking care to use BEMIT conventions and KSS at the top of each file to document your CSS.
4. To document your new pattern, add one or more new HTML file(s) at documentation/web/patterns. File naming conventions should follow BEMIT conventions (e.g. c-modal.html, c-modal--large.html).
5. In the html file, add YAML Frontmatter at the top of the file (see other files in documentation/web/patterns/ for examples). Below the Frontmatter, add the markup that corresponds to your new CSS pattern.
6. View your new pattern in the Middleman documentation site, and confirm that its appearance and behavior is as expected.
7. Commit your changes (typically in a feature branch) and issue a Pull Request.

Publishing a new version of the style guide to npm

scpr-style-guide uses Travis CI to test builds, and also can publish passing builds to npm automatically using git tags and releases. When you're ready to release a new version of the style guide, follow these steps:

1. Make sure the changes that make up your release have been merged into master.
2. Update the project's version number in package.json (https://github.com/SCPR/scpr-style-guide/blob/master/package.json#L3).
3. Commit the update to the package.json file.
4. On master, create a new tag and give it a brief description, e.g.: git tag -a v1.4 -m "my version 1.4".
5. Push the tag to Github: git push origin v1.4.
6. The push to Github will kick off a new build on Travis CI. Once that succeeds, Travis should automatically publish the new version to npm.
7. Verify that your new version has published to npm: https://www.npmjs.com/package/scpr-style-guide.
8. Create a new Release in Github that corresponds to your tag: https://github.com/SCPR/scpr-style-guide/releases/new

Running the style guide documentation

The style guide allows you to see changes to components from the scpr-style-guide project and is used for visual regression testing of components. To get the Middleman style guide site working:

• Ensure you have ruby and bundler installed
• Install ruby gems by running bundle install
• Build and run the Middleman server by running bundle exec middleman serve