Bowhead

Memorable and maintainable design tokens in SCSS

A lovely bowhead whale. I’d love other suggestions! 😅

What?

Bowhead is a small SCSS framework on which to implement your design tokens, spitting out CSS Variables with optional fallbacks.

Why?

Implementing a design system or even just a series of simple design tokens can come with some unpredictable mental overhead. Bowhead aims to reduce that mental overhead by abstracting the specifics of design tokens into human-sensible formats and nomenclature.

This has a positive effect that ranges from giving the colours in your design system fun and memorable names, to the time and effort saved when communicating about these colours with collaborators without getting bogged down by details, because let’s be real: you don’t want or need to memorise the six-character hex value for all your colours, nor does anyone else! Now imagine that scenario when applied to multiple times more design tokens.

Installation

Yoink it from npm:
npm install @chrisburnell/bowhead

You can also just download it directly from GitHub:
https://github.com/chrisburnell/bowhead/archive/master.zip

Usage

There are three main moving parts to this set-up, and an optional fourth:

  1. $bowhead-tokens
  2. $bowhead-show-fallback
  3. $bowhead-generate
  4. $bowhead-property-map

01. Tokens

$bowhead-tokens expects an SCSS map of "types" of tokens. These types could be a measure, color, opacity, z-index, etc.

$bowhead-tokens: (
measure: (
small: 0.5rem,
medium: 1rem,
large: 2rem,
),
color: (
brick: #b22222,
plankton: #3cb371,
desert: #d2b48c
),
opacity: (
alpha: 0.8,
beta: 0.5,
gamma: 0.2
),
z-index: (
below: -1,
root: 0,
default: 1,
above: 2
)
);

02. Show Fallback Value

$bowhead-show-fallback is either true (default) or false and determines whether or not Bowhead should print fallback values for browsers that do not support CSS Variables.

$bowhead-show-fallback: true;

body {
color: #b22222;
color: var(--color-desert);
}

$bowhead-show-fallback: false;

body {
color: var(--color-desert);
}

03. Generating CSS Variables

$bowhead-generate is either true (default) or false and determines whether or not Bowhead should print CSS Variables for you, like so:

:root {
--measure-small: 0.5rem;
--measure-medium: 1rem;
--measure-large: 2rem;
--color-brick: #b22222;
--color-plankton: #3cb371;
--color-desert: #d2b48c;
--opacity-alpha: 0.8;
--opacity-beta: 0.5;
--opacity-gamma: 0.2;
--z-index-below: -1;
--z-index-root: 0;
--z-index-default: 1;
--z-index-above: 2;
}

04. Property Map (optional)

$bowhead-property-map is another map that contains mappings from CSS properties (padding-left, border-bottom-right-radius, etc.) to our defined design token "types" (measure, color, etc.), i.e.

(
width: measure,
min-width: measure,
max-width: measure,
height: measure,
min-height: measure,
max-height: measure,
...
)

If you wish, you can create new mappings or overwrite existing defaults by defining your own property map, e.g.

$bowhead-property-map: (
vertical-align: alignments
);

Where alignments would be one of your design token "types", e.g.

$bowhead-tokens: (
alignments: (
default: baseline,
alternate: middle
),
...
);

Bowhead will merge your defined map into its own defaults automatically!


Then you’ll have to include Bowhead in your SCSS somehow. You could use Webpack or something like that, or if you’re using npm, the below code snippet should suffice.

Take note that you need to define any of your Bowhead variables ($bowhead-tokens, $bowhead-show-fallback, $bowhead-generate(, $bowhead-property-map)) before importing Bowhead into your SCSS!

$bowhead-tokens: (
...
);
$bowhead-show-fallback: true;
$bowhead-generate: true;
$bowhead-property-map: (
...
);

@import "node_modules/@chrisburnell/bowhead/bowhead";

Finally, you can use either Bowhead's @v function, @v mixin, both, or just the CSS Variables it can spit out. However you use it is totally up to you! :)

.thing {
@include v(background-color, desert);
@include v(color, brick);
border: v(measure, small) solid v(color, plankton);
padding: v(measure, medium) v(measure, large);
@include v(z-index, above);
opacity: var(--opacity-alpha);
// 1. if you just want the raw value, this is not really recommended:
text-decoration-color: map-get(map-get($bowhead-tokens, "color"), "brick");
// 2. this does the same for you:
text-decoration-color: v(color, brick, true);
// 3. so does this, although it includes the CSS Variable too:
@include v(text-decoration-color, brick, true);
}

will generate…

.thing {
background-color: #d2b48c;
background-color: var(--color-desert);
color: #b22222;
color: var(--color-brick);
border: var(--measure-small) solid var(--color-plankton);
padding: var(--measure-medium) var(--measure-large);
z-index: 2;
z-index: var(--z-index-above);
opacity: var(--opacity-alpha);
/* 1 */
text-decoration-color: #b22222;
/* 2 */
text-decoration-color: #b22222;
/* 3 */
text-decoration-color: #b22222;
text-decoration-color: var(--color-brick);
}

28 Responses

  1. Avatar for hankchizljawAndy Bell
  2. Avatar for MicheBarksMichelle Barker
  3. Avatar for monovoceMichael Bernth
  4. Avatar for EpwnazJess 🏳️‍🌈
  5. Avatar for mpdecampMatt DeCamp
  6. Avatar for fractaledmindStephen Margheim
  7. Avatar for MikeRiethmullerMike Riethmuller
  8. Avatar for drjeckerJennifer Ecker
  9. Avatar for bulltwittingBill Rafferty
  10. Avatar for felipesereFelipe Sere
  11. Avatar for cooldezigntanangular
  12. Avatar for blobduffBobby Duff
  13. Avatar for bulltwittingBill Rafferty
  14. Avatar for drjeckerJennifer Ecker
  15. Avatar for koitakiChristopher Adams
  16. Avatar for bloqheadDaryn St. Pierre
  17. Avatar for BrianDMilneBrian Milne
  18. Avatar for hexagoncircleRyan Mulligan
  19. Avatar for forstar_ikkeSashko
  20. Avatar for jhwllsJack Howells
  21. Avatar for murbmaarten brouwers 🇺🇳
  22. Avatar for thejeffbyrnesJeff Byrnes
  23. Avatar for jasonleecookseyJason Lee Cooksey
  24. Avatar for jamcowJamCow
  25. Avatar for JakeDChampionJake
Replies:
  1. 📦 Packaged up a bit of SCSS I’ve been happily using into a thing called Bowhead (it’s a whale, but I totally swear the filesize is tiny) and I’d love your feedback!

  2. Avatar for hankchizljaw
    This is exceptionally smart stuff by Chris. Love to see anything related to making tokens easier—especially with Sass.
  3. 🚚 Bowhead is now at version 0.1.8, which adds a few things and fixes others, namely cleaning up what files are packaged for npm so as to send as little as necessary. If you're looking for a barebones SCSS solution for managing design tokens or even for a tool that will generate CSS Variables for you, I’d be honoured if you gave it a try.