Gorko

A tiny, Sass-powered design-token led utility class generator, with handy helpers, that helps you to power your front-ends with a single source of truth.

Table of contents

• Gorko
  • Getting started
  • Configuration
    • Base size (optional)
    • Size scale (optional)
    • Colors (optional)
    • Gorko config (required)
    • Breakpoints
  • Utility Class Generator
    • Example outputs
  • Generating Utility Classes On Demand
  • Using CSS Custom Properties
    • Using themes
  • Sass functions
    • Get color
      • Example
    • Get utility value
      • Example
    • Get size
      • Example
  • Sass mixins
    • Apply utility
      • Example
    • Media query
      • Example
  • Contributing
  • Pull Request Process
  • Code of Conduct
    • Our Pledge
    • Our Standards
    • Our Responsibilities
    • Scope
    • Enforcement
    • Attribution

Getting started

First up, install Gorko:

npm install gorko

In your Sass (SCSS in this case), import Gorko like so:

@import '../path/to/your/node_modules/gorko/gorko.scss';

This will generate utility classes based on the default configuration. To configure it for yourself, take this default, and create your own. Once it is created import your config before Gorko, like this:

@import 'config';

Configuration

This is the default configuration. It is recommended that you use it as your base for your own configuration.

/// BASE SIZE
/// All calculations are based on this. It’s recommended that
/// you keep it at 1rem because that is the root font size. You
/// can set it to whatever you like and whatever unit you like.
///
$gorko-base-size: 1rem;

/// SIZE SCALE
/// This is a Major Third scale that powers all the utilities that
/// it is relevant for (font-size, margin, padding). All items are
/// calcuated off the base size, so change that and cascade across
/// your whole project.
///
$gorko-size-scale: (
  '300': $gorko-base-size * 0.8,
  '400': $gorko-base-size,
  '500': $gorko-base-size * 1.25,
  '600': $gorko-base-size * 1.6,
  '700': $gorko-base-size * 2,
  '900': $gorko-base-size * 3
);

/// COLORS
/// Colors are shared between backgrounds and text by default.
/// You can also use them to power borders, fills or shadows, for example.
///
$gorko-colors: (
  'dark': #1a1a1a,
  'light': #f3f3f3
);

/// CORE CONFIG
/// This powers everything from utility class generation to breakpoints
/// to enabling/disabling pre-built components/utilities.
///
$gorko-config: (
  'bg': (
    'items': $gorko-colors,
    'output': 'standard',
    'property': 'background'
  ),
  'color': (
    'items': $gorko-colors,
    'output': 'standard',
    'property': 'color'
  ),
  'box': (
    'items': (
      'block': 'block',
      'flex': 'flex',
      'hide': 'none',
      'show': 'inherit'
    ),
    'output': 'responsive',
    'property': 'display'
  ),
  'font': (
    'items': (
      'base': 'Helvetica, Arial, sans-serif'
    ),
    'output': 'standard',
    'property': 'font-family'
  ),
  'gap-top': (
    'items': $gorko-size-scale,
    'output': 'standard',
    'property': 'margin-top'
  ),
  'gap-right': (
    'items': $gorko-size-scale,
    'output': 'standard',
    'property': 'margin-right'
  ),
  'gap-bottom': (
    'items': $gorko-size-scale,
    'output': 'standard',
    'property': 'margin-bottom'
  ),
  'gap-left': (
    'items': $gorko-size-scale,
    'output': 'standard',
    'property': 'margin-left'
  ),
  'pad-top': (
    'items': $gorko-size-scale,
    'output': 'standard',
    'property': 'padding-top'
  ),
  'pad-right': (
    'items': $gorko-size-scale,
    'output': 'standard',
    'property': 'padding-right'
  ),
  'pad-bottom': (
    'items': $gorko-size-scale,
    'output': 'standard',
    'property': 'padding-bottom'
  ),
  'pad-left': (
    'items': $gorko-size-scale,
    'output': 'standard',
    'property': 'padding-left'
  ),
  'stack': (
    'items': (
      '300': 0,
      '400': 10,
      '500': 20,
      '600': 30,
      '700': 40
    ),
    'output': 'standard',
    'property': 'z-index'
  ),
  'text': (
    'items': $gorko-size-scale,
    'output': 'responsive',
    'property': 'font-size'
  ),
  'weight': (
    'items': (
      'light': '300',
      'regular': '400',
      'bold': '700'
    ),
    'output': 'standard',
    'property': 'font-weight'
  ),
  'width': (
    'items': (
      'full': '100%',
      'half': percentage(1/2),
      'quarter': percentage(1/4),
      'third': percentage(1/3)
    ),
    'output': 'responsive',
    'property': 'width'
  ),
  'breakpoints': (
    'sm': '(min-width: 36em)',
    'md': '(min-width: 48em)',
    'lg': '(min-width: 62em)'
  )
);

Base size (optional)

$gorko-base-size

The base size for the size ratio calculations. It is only required for the default configuration.

Size scale (optional)

$gorko-size-scale

This takes the base size and by default, generates a major third size scale. This can be set to whatever scale you like.

If this is not set, the get-size function will use the default configuration.

Colors (optional)

$gorko-colors

A collection of key/value pairs that by default, generate text and background colour utilities.

If this is not set, the get-color function will use the default configuration.

Gorko config (required)

$gorko-config

🚨 Without this set, Gorko won’t work. 🚨

It contains all of the utility class definitions and breakpoint definitions that the generator and mixins use.

You can add as many or as little utility class definitions as you like—likewise for breakpoint definitions.

Breakpoints

The breakpoints map in $gorko-config defines media queries for the utility class generator. By default, the are set as follows:

'breakpoints': (
	'sm': '(min-width: 36em)',
	'md': '(min-width: 48em)',
	'lg': '(min-width: 62em)'
)

You can add as many or as little of these as you like and call them whatever you like. The only requirement is that the value is a valid media query.

Utility Class Generator

The utility class generator loops through $gorko-config looking for items that have a valid utility class structure. The following structure is required to generate a utility class:

'width':('items':('full':'100%','half': '50%'
  ),
  'output': 'standard',
  'property': 'width'
),;

The first key is the name of the utility and that contains a Sass map. Inside that map, you need to have the following:

• items: a map of key/value pairs which link a utility class to a CSS property’s value. If you want to use CSS Custom Properties, this should be the string key, referencing the 'css-vars' $gorko-config group that you want to use
• output: this must be responsive or standard. If you set it to responsive, it will generate the same utility class for every breakpoint that is defined.
• property: the CSS property that this utility controls.

Example outputs

The above structure would output the following utility classes:

.width-full {
  width: 100%;
}

.width-half {
  width: 50%;
}

If we set the output to be responsive, with the default breakpoints defined, the output would be as follows:

.width-full {
  width: 100%;
}

.width-half {
  width: 50%;
}

@media (min-width: 36em) {
  .sm\:width-full {
    width: 100%;
  }

  .sm\:width-half {
    width: 50%;
  }
}

@media (min-width: 48em) {
  .md\:width-full {
    width: 100%;
  }

  .md\:width-half {
    width: 50%;
  }
}

@media (min-width: 62em) {
  .lg\:width-full {
    width: 100%;
  }

  .lg\:width-half {
    width: 50%;
  }
}

Generating Utility Classes On Demand

The default behaviour of Gorko is to generate utility classes, but in the spirit of being as flexible as possible, you can stop it doing that by setting $generate-utility-classes to false when you pull Gorko into your project, like this:

$generate-utility-classes: false;
@import 'config';
@import '../path/to/your/node_modules/gorko/gorko.scss';

We might want to generate those utility classes later on in the CSS, though, so we use the generate-utility-classes() mixin anywhere after Gorko has been pulled in.

$generate-utility-classes: false;
@import 'config';
@import '../path/to/your/node_modules/gorko/gorko.scss';

// Standard authored CSS
body {
  display: grid;
  place-items: center;
}

// Generate utilities after everything else
@include generate-utility-classes();

Using CSS Custom Properties

See a demo repo

You might want to use CSS Custom Properties instead of static references to tokens. To do so with Gorko, you need to make a couple of adjustments to your $gorko-config.

Firstly, at the top, you need to add a css-vars group which has a key and a value, which should be a map of tokens.

$gorko-config: (
  'css-vars': (
    'color': $gorko-colors,
    'weight': (
      'bold': 700,
      'black': 900
    )
  )
);

In this example, we have defined a 'color' group which uses $gorko-colors, but also a 'weight' group where we have defined key value pairs, just like we do in the utility class generator.

This will now generate a collection of CSS Custo