beef up README, tidy up code some more

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.

bowhead.scss

@@ -1,12 +1,9 @@
-@charset "UTF-8";
-
 ////
 /// Bowhead
 /// @link https://github.com/chrisburnell/bowhead
 ////
 
 @import "src/config";
 @import "src/functions";
-@import "src/maps";
 @import "src/mixins";
 @import "src/generator";

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"

src/_config.scss

@@ -1,32 +1,136 @@
-// 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.
 $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,
  default: 1,
  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;

src/_functions.scss

@@ -1,7 +1,3 @@
-////
-/// Functions
-////
-
 ///
 /// Output a property's CSS Cariable or SCSS value
 ///

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));
-// }
-// }
-// }
-// }
-// }
-// }