For Developers

ST UI is a set of SCSS partials defining component and utility classes. You can import partials into your project to quickly build consistent UIs across The Seattle Times' web products.

Installation

You have the option of using npm to install the st-ui package in your project or simply downloading the minified, compiled code.

Using npm

If you have node installed on your machine, you can use npm to install the ST UI. Add st-ui to your project’s package.json as a dependency by installing it from the Github repository:

npm install --save seattletimes/st-ui

If you want a specific version of `st-ui`, append `@tag` to grab a specific release.

The package will be installed in node_modules/st-ui. You will find SCSS partials in the scss/ directory.

Using CSS Classes

With ST UI installed, you will need to load the SCSS partials into your project. You can load each partial individually, or load the entire bundle, depending on what you may need.

Now, in your markup, you can use the ST UI classes to style your components and build your user interfaces. We will quickly overview some classes here but the Pattern Library is the best place to find example and usages of these classes.

Component classes

All component classes are prefixed with st-. For example, you can style a button or input with .st-button and .st-input. Components can be modified with component modifier classes like .button--small or .input--block.

Utility classes

Most utility classes are prefixed with u- to assist in findability and naming collisions. You can change the color of a component with .u-blue or change the font size with .font-small. Check the Utilities page to find more examples and explanation.

Customizing

Often times, ST UI will only get you far enough in your project. With this in mind, ST UI aims to be fairly customizable.

Most configuration and component styles are generated with Sass variables. For example, the following creates responsive spacing classes:

st-ui/scss/_variables.scss ... $spacer : 10px; $spacer-xs : $spacer * .5; $spacer-sm : $spacer * 1; $spacer-md : $spacer * 1.5; $spacer-lg : $spacer * 2; $spacer-xl : $spacer * 3; $spacers: ( 0: 0, 1: $spacer-xs, 2: $spacer-sm, 3: $spacer-md, 4: $spacer-lg, 5: $spacer-xl ); ...

Maybe you only need a few spacing classes, or different sizes. Here is what your variables partial might look like:

your-project/scss/_variables.scss ... $spacer : 10px; $spacer-sm : $spacer * 1; $spacer-md : $spacer * 2.7; $spacer-lg : $spacer * 3.5; $spacers: ( 0: 0, 1: $spacer-sm, 2: $spacer-md, 3: $spacer-lg ); ...

Now, in your main Sass file, you can import your variables after ST UI’s variable, and the resulting classes will use your configuration. We recommend duplicating the entire _variables.scss partial from ST UI and placing it in your project. You can customize as you see fit from there.

your-project/scss/main.scss ... @import 'st-ui/scss/variables'; // ST UI variables @import 'variables'; // Your variables ...

Contributing

ST UI is a living toolkit, constantly evolving. If you have edits, revisions, or contributions of any kind, first, consult our Best Practices and Philosophy for writing CSS and the submit a PR!