Skip to content

Commit

Permalink
📦 update documentation + dependency type
Browse files Browse the repository at this point in the history
  • Loading branch information
@chrisburnell
chrisburnell committed May 4, 2021
1 parent 13c5d61 commit 13d0717
Show file tree
Hide file tree
Showing 2 changed files with 266 additions and 43 deletions.
302 changes: 262 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,69 +17,255 @@ 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:

<table>
<thead>
<tr>
<th>color</th>
<th>measure</th>
<th>alignment</th>
<th>…</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>background-color</code><br>
<code>border-color</code><br>
<code>outline-color</code><br>
<code>color</code><br>
<code>fill</code><br>
<code>stroke</code><br>
<code>…</code>
</td>
<td>
<code>width</code><br>
<code>height</code><br>
<code>padding</code><br>
<code>margin</code><br>
<code>border-width</code><br>
<code>min-width</code><br>
<code>max-width</code><br>
<code>…</code>
</td>
<td>
<code>align-items</code><br>
<code>justify-content</code><br>
<code>…</code>
</td>
</tr>
</tbody>
</table>

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*:

<table>
<thead>
<tr>
<th>color</th>
<th>measure</th>
<th>alignment</th>
<th>…</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>#b22222</code><br>
<code>#3cb371</code><br>
<code>#d2b48c</code><br>
<code>…</code>
</td>
<td>
<code>1em</code><br>
<code>20px</code><br>
<code>2px</code><br>
<code>…</code>
</td>
<td>
<code>flex-start</code><br>
<code>flex-end</code><br>
<code>center</code><br>
<code>…</code>
</td>
</tr>
</tbody>
</table>

`$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

<table>
<thead>
<tr>
<th></th>
<th>Values</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<th><code>$bowhead-variable-as-default</code><br><em>(optional)</em></th>
<td style="white-space:nowrap">
<strong>true</strong> <em>(default)</em><br>
<strong>false</strong>
</td>
<td>Decides whether or not use the CSS Variable or raw value when calling the <samp>@v</samp> function.</td>
</tr>
<tr>
<th><code>$bowhead-show-fallback</code><br><em>(optional)</em></th>
<td style="white-space:nowrap">
<strong>true</strong> <em>(default)</em><br>
<strong>false</strong>
</td>
<td>Decides whether or not to show a fallback value for the CSS Variable. Only works when <samp>$bowhead-variable-as-default</samp> is also <samp>true</samp>.</td>
</tr>
<tr>
<th><code>$bowhead-generate</code><br><em>(optional)</em></th>
<td style="white-space:nowrap">
<strong>true</strong> <em>(default)</em><br>
<strong>false</strong>
</td>
<td>Decides whether or not to generate CSS Variables for you.</td>
</tr>
<tr>
<th><code>$bowhead-property-map</code><br><em>(optional)</em></th>
<td><a href="#property-map">See below.</a></td>
<td>Defines which "types of values" each CSS property should map against.</td>
</tr>
<tr>
<th><code>$bowhead-tokens</code></th>
<td><a href="#tokens">See below.</a></td>
<td>Defines the design token values, categorised by "types of values".</td>
</tr>
</tbody>
</table>

### 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 {
color: var(--color-desert);
}
```

### Generate
When <samp>$bowhead-variable-as-default</samp> is <samp>false</samp>, <samp>$bowhead-show-fallback</samp> 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 {
Expand All @@ -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,
Expand Down Expand Up @@ -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
)
);
```

--------

Expand Down
7 changes: 4 additions & 3 deletions package.json
View file
Original file line number Diff line number Diff line change
@@ -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",
Expand All @@ -22,6 +22,7 @@
},
"keywords": [
"design tokens",
"css",
"scss"
]
}

0 comments on commit 13d0717

Please sign in to comment.