From 7c1f80000bde114e123bad01e1044ac8bf4fadab Mon Sep 17 00:00:00 2001 From: Chris Burnell Date: Tue, 25 Aug 2020 17:16:05 +0100 Subject: [PATCH] beef up README, tidy up code some more --- README.md | 126 +++++++++++++++++++++++++++++++++++++++----- bowhead.scss | 3 -- package.json | 4 +- src/_config.scss | 124 +++++++++++++++++++++++++++++++++++++++---- src/_functions.scss | 4 -- src/_maps.scss | 23 -------- src/_mixins.scss | 30 ----------- 7 files changed, 229 insertions(+), 85 deletions(-) delete mode 100644 src/_maps.scss diff --git a/README.md b/README.md index c76e14a..9244c07 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,130 @@ # Bowhead -## A small framework on which to build your design tokens in SCSS. +> Memorable and maintainable design tokens in SCSS -I wrote more about this here: [https://chrisburnell.com/bowhead](https://chrisburnell.com/bowhead/). +## What? -You’ll want to jump into `src/_config.scss` and make some changes: add your own tokens, etc. +**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 + +- **With npm:** `npm install @chrisburnell/bowhead` +- **Direct download:** [https://github.com/chrisburnell/bowhead/archive/master.zip](https://github.com/chrisburnell/bowhead/archive/master.zip) + +## Usage + +There are three main moving parts to this set-up: + +0. `$bowhead-tokens` +0. `$bowhead-show-fallback` +0. `$bowhead-generate` + +`$bowhead-tokens` expects an *SCSS* `map` of “types” of tokens. These types could be a *measure*, *color*, *opacity*, *z-index*, etc.: + +```scss +$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 + ) +); +``` + +`$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. + +**`true`:** + +```css +body { + color: #b22222; + color: var(--color-desert); +} +``` + +**`false`:** + +```css +body { + color: var(--color-desert); +} +``` + +`$bowhead-generate` is either `true` *(default)* or `false` and determines whether or not **Bowhead** should print CSS Variables for you, like so: + +```css +: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; +} +``` + +Finally, you can use either the `@v` function or `@v` mixin (or both) however is most comfortable to you: ```scss body { @include v(background-color, desert); @include v(color, brick); - border: v(measure, tiny) solid v(color, plankton); - padding: v(measure, medium) v(measure, gigantic); + border: v(measure, small) solid v(color, plankton); + padding: v(measure, medium) v(measure, large); @include v(z-index, above); } ``` ```css body { - background-color: tan; - background-color: var(--color-desert); - color: firebrick; - color: var(--color-brick); - border: var(--measure-tiny) solid var(--color-plankton); - padding: var(--measure-medium) var(--measure-gigantic); - z-index: 2; - z-index: var(--z-index-above); + 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); } ``` + +## Learn more + +I wrote more about this here: [https://chrisburnell.com/bowhead/](https://chrisburnell.com/bowhead/). + +## Authors + +So far, it’s just myself, [Chris Burnell](https://chrisburnell.com), but I welcome collaborators with ideas to bring to the table! + +## License + +This project is licensed under an MIT license. diff --git a/bowhead.scss b/bowhead.scss index bc8b6be..57e79c3 100644 --- a/bowhead.scss +++ b/bowhead.scss @@ -1,5 +1,3 @@ -@charset "UTF-8"; - //// /// Bowhead /// @link https://github.com/chrisburnell/bowhead @@ -7,6 +5,5 @@ @import "src/config"; @import "src/functions"; -@import "src/maps"; @import "src/mixins"; @import "src/generator"; diff --git a/package.json b/package.json index 8ec6c4c..fa97777 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@chrisburnell/bowhead", - "version": "0.1.0", - "description": "A small framework on which to build your design tokens in SCSS.", + "version": "0.1.1", + "description": "Memorable and maintainable design tokens in SCSS", "main": "bowhead.scss", "scripts": { "test": "npx sass bowhead.scss bowhead.css --no-source-map" diff --git a/src/_config.scss b/src/_config.scss index d484a75..b763ee0 100644 --- a/src/_config.scss +++ b/src/_config.scss @@ -1,4 +1,4 @@ -// Decides whether or not to show a non-CSS Variable fallback value. +// Decides whether or not to show a fallback value for the CSS Variable. $bowhead-show-fallback: true !default; // Decides whether or not to generate CSS Variables for you. @@ -6,23 +6,20 @@ $bowhead-generate: true !default; $bowhead-tokens: ( measure: ( - tiny: 0.125rem, small: 0.5rem, medium: 1rem, - large: 2.25rem, - gigantic: 4rem + large: 2rem, + ), + color: ( + brick: #b22222, + plankton: #3cb371, + desert: #d2b48c ), opacity: ( alpha: 0.8, beta: 0.5, gamma: 0.2 ), - color: ( - transparent: rgba(0, 0, 0, 0), - brick: #b22222, - plankton: #3cb371, - desert: #d2b48c - ), z-index: ( below: -1, root: 0, @@ -30,3 +27,110 @@ $bowhead-tokens: ( above: 2 ) ) !default; + +$bowhead-property-map: ( + width: measure, + min-width: measure, + min-inline-size: measure, + max-width: measure, + max-inline-size: measure, + height: measure, + min-height: measure, + min-block-size: measure, + max-height: measure, + max-block-size: measure, + padding: measure, + padding-block: measure, + padding-inline: measure, + padding-top: measure, + padding-block-start: measure, + padding-right: measure, + padding-inline-end: measure, + padding-bottom: measure, + padding-block-end: measure, + padding-left: measure, + padding-inline-start: measure, + margin: measure, + margin-block: measure, + margin-inline: measure, + margin-top: measure, + margin-block-start: measure, + margin-right: measure, + margin-inline-end: measure, + margin-bottom: measure, + margin-block-end: measure, + margin-left: measure, + margin-inline-start: measure, + outline-offset: measure, + flex-basis: measure, + gap: measure, + grid-gap: measure, + column-gap: measure, + row-gap: measure, + top: measure, + bottom: measure, + left: measure, + right: measure, + background-color: color, + color: color, + caret-color: color, + border-color: color, + border-block-color: color, + border-inline-color: color, + border-top-color: color, + border-block-start-color: color, + border-right-color: color, + border-inline-start-color: color, + border-bottom-color: color, + border-block-end-color: color, + border-left-color: color, + border-inline-end-color: color, + outline-color: color, + fill: color, + stroke: color, + text-decoration-color: color, + text-emphasis-color: color, + border-style: border-style, + border-block-style: border-style, + border-inline-style: border-style, + border-top-style: border-style, + border-block-start-style: border-style, + border-right-style: border-style, + border-inline-start-style: border-style, + border-bottom-style: border-style, + border-block-end-style: border-style, + border-left-style: border-style, + border-inline-end-style: border-style, + outline-style: border-style, + border-width: border-width, + border-block: border-width, + border-inline: border-width, + border-top-width: border-width, + border-block-start-width: border-width, + border-right-width: border-width, + border-inline-start-width: border-width, + border-bottom-width: border-width, + border-block-end-width: border-width, + border-left-width: border-width, + border-inline-end-width: border-width, + outline-width: border-width, + text-decoration-thickness: border-width, + text-underline-offset: border-width, + border-radius: border-radius, + border-top-left-radius: border-radius, + border-start-start-radius: border-radius, + border-top-right-radius: border-radius, + border-start-end-radius: border-radius, + border-bottom-right-radius: border-radius, + border-end-end-radius: border-radius, + border-bottom-left-radius: border-radius, + border-end-start-radius: border-radius, + opacity: opacity, + font-family: font-family, + font-weight: font-weight, + letter-spacing: letter-spacing, + line-height: line-height, + transition-duration: transition-duration, + transition-function: transition-function, + z-index: z-index +) !default; diff --git a/src/_functions.scss b/src/_functions.scss index a6a3225..96af6b7 100644 --- a/src/_functions.scss +++ b/src/_functions.scss @@ -1,7 +1,3 @@ -//// -/// Functions -//// - /// /// Output a property's CSS Cariable or SCSS value /// diff --git a/src/_maps.scss b/src/_maps.scss deleted file mode 100644 index a4a5e5a..0000000 --- a/src/_maps.scss +++ /dev/null @@ -1,23 +0,0 @@ -//// -/// Maps -//// - -/// @type Map -$bowhead-property-map: ( - width: measure, - min-width: measure, - max-width: measure, - height: measure, - min-height: measure, - max-height: measure, - padding: measure, - margin: measure, - background-color: color, - color: color, - border-color: color, - outline-color: color, - fill: color, - stroke: color, - opacity: opacity, - z-index: z-index -) !default; diff --git a/src/_mixins.scss b/src/_mixins.scss index 4904331..0b217db 100644 --- a/src/_mixins.scss +++ b/src/_mixins.scss @@ -1,7 +1,3 @@ -//// -/// Mixins -//// - /// /// Output a property, CSS Variable, and, optionally, SCSS value /// @@ -29,29 +25,3 @@ } #{$property}: v($property, $value); } - - -/// -/// Output properties and values for all defined themes -/// -// @mixin t($properties...) { -// @each $theme, $data in $themes { -// @if $theme == "light" { -// @each $property in $properties { -// @if map-has-key($data, $property) { -// $property-clean: nth(str-split($property, "--"), 1); // first item in the array -// @include v($property-clean, map-get($data, $property)); -// } -// } -// } @else { -// .theme--#{$theme} & { -// @each $property in $properties { -// @if map-has-key($data, $property) { -// $property-clean: nth(str-split($property, "--"), 1); // first item in the array -// @include v($property-clean, map-get($data, $property)); -// } -// } -// } -// } -// } -// }