Kerosene

Kerosene is a set of SCSS shortcuts and tools for simpler design decisions without sacrificing control.

View Repo View Issues

Settings

Settings are at the core of everything in Kerosene. This is how any of the decisions in Kerosene can be overwritten. In each section below, the corresponding setting variables will be listed along with what they achieve.

Base

Base styles are just basic overrides that support kerosene features. Think of it like normalize or css reset. At the moment there isn't much here, I would suggest using your preferred css reset and loading it before kerosene.

Tools

Tools are the core of Kerosene. Here is where all the functions, maps, mixins, and extends are kept. Below you will find a key for each tool in kerosene along with examples of how to use them and instructions on how to modify them.

Color

The color tool utilizes a function that is dependent on a sass-map. First, the color function determine where a color falls on the hue spectrum and distributes new color values dynamically for lighter and darker variants. The color function takes three arguments (Color, gradient step form -9 to 9, and opacity from 0.0 to 1.0 eg color(blue, -5, 0.5);). Example below:


  .color-example-one {
    background: color(blue, 5);
    color: color(blue, -2);
  }
Color Example One

By default, kerosene supports all css3 color names. To add new colors such as your brand colors, you can append the sass-map using map-merge. Here is an example:


    $brand-colors: (
      facebookblue: #3b5999,
      twitterblue: #1fa1f3
    );

    $k-colors: map-merge($k-colors, $brand-colors);
  
Facebook Blue

Shadow

The shadow function does a lot of the gruntwork in designing nice shadows without sacrificing control. It takes four arguements: Depth level (-9 through 9), color, color variant (-9 through 9), and intensity (1 through 5).


  .shadow-example-one {
    background: color(purple);
    box-shadow: shadow(2);
  }
Shadow 01

Gradients

The Gradient function is fairly simple but useful if you need a quick linear gradient based on a single color input. lin-gradient() takes two arguments, color and lightness. Lightness has a total of seven options: Darkest, darker, dark, base, light, lighter, and lightest. You can use it like this: background: lin-gradient(purple, dark);.

Gradient Example

typography

The type function(s) is one of the more complex tools in Kerosene. Each one of the 8 functions sets the font-family, font-size, font-weight, style, and line-height. They each accept three arguments: scale size, weight, and style. The functions are as follows: type-masthead(), type-display(), type-text(), type-code(), type-ui(), type-caption(), type-aside(), and type-blockquote(). Below is an example of how it is used:


  .example {
    font: type-text(2, bold);
  }

  // output {
    font: normal normal bold 1.125rem/1.6 -apple-system, BlinkMacSystemFont, Roboto, Droid Sans, Segoe UI, Helvetica Neue, Helvetica, Arial, sans-serif;
  }

There are a number of variables that are utilized by the type function. Below is a list that can be modified:

focusable

Admittedly, focusable-only is pretty rarely used but I've found myself going back to this a few times. Focusable-only hides content unless you navigate your focus onto the dom element in question. Only then will the css properties you've written go into effect. This is great if you want to create a keyboard-focus-only navigation like the New York Times. You can add it via the mixin like so: @include focusable-only. Make sure you're styling the focus state!

Units

The unit functions serve various purposes. strip-unit() removes leaves just the number without its unit. remPx() converts a pixel value (without its unit) into rem. pow() is a power function, it accepts two arguments. The first is the base number and the second is the exponent. For example, pow(2, 3) = 8.

Disable Text Select

Disable Text select is an extention for disabling the ability to select text, this can be especially helpful if you want to avoid accidentally highlighting the text in an interactive element such as a button. You can use it by either using scss extend or applying the class to an element in your html.

Utilities

Utilities are small css classes that perform very specific functions. Currently this portion of kerosene is rather sparse to cut down on the total amount of compiled css but it should grow slightly over time.

Screen Reader Only

.u-sr-only overrides most specificity to make certain content is read by screenreaders but otherwise not visable. In addition to that, there is also [disabled] and [area-disabled="true"] for disabling content as well as [hidden] and [aria-hidden="true"] for changing visibility to hidden.