diff --git a/README.md b/README.md index 8d75b88..c325aa3 100644 --- a/README.md +++ b/README.md @@ -17,59 +17,213 @@ This has a positive effect that ranges from giving the colours in your design sy - **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 +## What are "types of values"? -There are three main moving parts to this set-up and an optional fourth: +```css +selector { + property: value; +} +``` -1. [`$bowhead-tokens`](#tokens) -2. [`$bowhead-show-fallback`](#fallback) -3. [`$bowhead-generate`](#generate) -4. [`$bowhead-property-map`](#property-map) +An important first step to using *Bowhead* is to understand how it organises CSS properties into different "types". By and large, this is done by looking at what the *expected* values for a given property are: -### Tokens +```css +selector { + background-color: #b22222; + color: #3cb371; + outline-color: #d2b48c; -`$bowhead-tokens` expects an *SCSS* `map` of "types" of tokens. These types could be a *measure*, *color*, *opacity*, *z-index*, etc.: + padding: 0.5rem; + margin: 2rem; -```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 - ) -); + display: flex; + align-items: flex-start; + justify-content: flex-end; +} ``` -### Fallback +If we take the above snippet as an example, we can quickly identify two "types" of values present: colors and measures. *Colors* typically stand out quite easily, and, historically, developers have done well to assign colors to variables to simplify their use throughout the codebase. *Measures* (or *sizes*), on the other hand, are rarely seen reflected as design tokens in *CSS* despite their frequent prescence in other forms of design tokens, e.g. the space around a logo or iconography is usually defined in a brand's guidelines. + +Despite being presented in different formats, we can confidently say that `background-color`, `color`, and `outline-color` expect a *color*-type value, not just because "color" is in their names, but because we can interchange the values between the properties and they still make sense. + +Measures can take trickier forms to identify and categorise, and I recommend allowing for more measures than you might expect at first and paring it back later. Getting everything categorised is the hard part; swapping tokens later becomes very trivial off the back of this up-front effort. Regardless, I attach any kind of distance-related value to a measure, and, once again, we could interchange any of the values between `padding`, `margin`, `border-width`, or `width` and the CSS still makes sense. + +Extrapolating from here across the vast variety of CSS *properties* and the *types of values* they expect, you end up with a map of *most properties* against value types: + + + + + + + + + + + + + + + + + +
colormeasurealignment…
+ background-color
+ border-color
+ outline-color
+ color
+ fill
+ stroke
+ … + 		+ width
+ height
+ padding
+ margin
+ border-width
+ min-width
+ max-width
+ … + 		+ align-items
+ justify-content
+ … +
+ +With this knowledge under our belt, we can begin to define the design tokens for our particular project by fleshing out what *values* are available underneath each *type*: + + + + + + + + + + + + + + + + + +
colormeasurealignment…
+ #b22222
+ #3cb371
+ #d2b48c
+ … + 		+ 1em
+ 20px
+ 2px
+ … + 		+ flex-start
+ flex-end
+ center
+ … +
-`$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. +## Usage + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValuesDescription
$bowhead-variable-as-default
(optional)		 + true (default)
+ false + 		Decides whether or not use the CSS Variable or raw value when calling the @v function.
$bowhead-show-fallback
(optional)		 + true (default)
+ false + 		Decides whether or not to show a fallback value for the CSS Variable. Only works when $bowhead-variable-as-default is also true.
$bowhead-generate
(optional)		 + true (default)
+ false + 		Decides whether or not to generate CSS Variables for you.
$bowhead-property-map
(optional)		See below.Defines which "types of values" each CSS property should map against.
$bowhead-tokensSee below.Defines the design token values, categorised by "types of values".
+ +### Variable As Default -**`$bowhead-show-fallback: true;`** +```scss +$bowhead-variable-as-default: true; +body { + color: v(color, brick); +} +``` + +```css +body { + color: var(--color-brick); +} +``` + +```scss +$bowhead-variable-as-default: false; +body { + color: v(color, brick); +} +``` ```css body { color: #b22222; +} +``` + +### Show Fallback Value + +```scss +$bowhead-variable-as-default: true; +$bowhead-show-fallback: true; +body { + @include v(color, desert); +} +``` + +```css +body { + color: #d2b48c; color: var(--color-desert); } ``` -**`$bowhead-show-fallback: false;`** +```scss +$bowhead-variable-as-default: true; +$bowhead-show-fallback: false; +body { + @include v(color, desert); +} +``` ```css body { @@ -77,9 +231,41 @@ body { } ``` -### Generate +When $bowhead-variable-as-default is false, $bowhead-show-fallback has no effect. -`$bowhead-generate` is either `true` *(default)* or `false` and determines whether or not **Bowhead** should print CSS Variables for you, like so: +```scss +$bowhead-variable-as-default: false; +$bowhead-show-fallback: true; +body { + @include v(color, desert); +} +``` + +```css +body { + color: #d2b48c; +} +``` + +```scss +$bowhead-variable-as-default: false; +$bowhead-show-fallback: false; +body { + @include v(color, desert); +} +``` + +```css +body { + color: #d2b48c; +} +``` + +### Generating CSS Variables + +```scss +$bowhead-generate: true; +``` ```css :root { @@ -99,12 +285,18 @@ body { } ``` +```scss +$bowhead-generate: false; +``` + +Nothing is generated! + ### Property Map `$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. ```scss -( +$bowhead-property-map: ( width: measure, min-width: measure, max-width: measure, @@ -135,7 +327,37 @@ $bowhead-tokens: ( ); ``` -**Bowhead** will merge your defined map into its own defaults automatically! +**Bowhead** will merge new types in your defined map into its own defaults automatically! Any that you re-declare will overwrite what exists as a default from *Bowhead*. + +### Tokens + +`$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 + ) +); +``` -------- diff --git a/package.json b/package.json index a8498c2..7f39f27 100644 --- a/package.json +++ b/package.json @@ -1,15 +1,15 @@ { "name": "@chrisburnell/bowhead", - "version": "0.1.9", + "version": "0.2.0", "description": "Memorable and maintainable design tokens in SCSS", "main": "bowhead.scss", "scripts": { "test": "npx sass bowhead.scss bowhead.css --no-source-map" }, - "dependencies": { + "dependencies": {}, + "devDependencies": { "sass": "^1.26.10" }, - "devDependencies": {}, "license": "MIT", "author": "Chris Burnell", "homepage": "https://github.com/chrisburnell/bowhead#readme", @@ -22,6 +22,7 @@ }, "keywords": [ "design tokens", + "css", "scss" ] }