From 82d9faca8856c2dc0684974e6f8f484ad412808a Mon Sep 17 00:00:00 2001 From: Chris Burnell Date: Wed, 1 Feb 2023 22:48:56 +0000 Subject: [PATCH] tidy up README; bump version --- .editorconfig | 14 ++ .npmignore | 2 + .prettierrc | 4 + README.md | 463 +++++++++++++++++++++++++++++++++++++++++++++- package-lock.json | 4 +- package.json | 18 +- 6 files changed, 486 insertions(+), 19 deletions(-) create mode 100644 .editorconfig create mode 100644 .prettierrc diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..9f733c1 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,14 @@ +root = true + +[*] +charset = utf-8 +indent_style = tab +indent_size = 4 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +indent_style = space +indent_size = 4 +trim_trailing_whitespace = false diff --git a/.npmignore b/.npmignore index bb8d9c9..a8f7d8b 100644 --- a/.npmignore +++ b/.npmignore @@ -1,3 +1,5 @@ .github .vscode +.editorconfig +.prettier *.css diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..80d4346 --- /dev/null +++ b/.prettierrc @@ -0,0 +1,4 @@ +# .prettierrc +semi: false +printWidth: 9999 +tabWidth: 4 diff --git a/README.md b/README.md index 8ba8e97..b4d63f4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Bowhead -> Memorable and maintainable design tokens in SCSS +> Memorable and maintainable design tokens in SCSS. ## What? @@ -8,20 +8,467 @@ ## 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. +Implementing a design system or even 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. +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) +- **With npm:** `npm install @chrisburnell/bowhead` +- **Direct download:** [https://github.com/chrisburnell/bowhead/archive/master.zip](https://github.com/chrisburnell/bowhead/archive/master.zip) -## [Read the full Bowhead documentation on chrisburnell.com](https://chrisburnell.com/bowhead/). +## CSS Data Types -## Authors +> CSS data types define typical values (including keywords and units) accepted by CSS properties and functions. +> https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Types -So far, it’s just myself, [Chris Burnell](https://chrisburnell.com), but I welcome collaborators with ideas to bring to the table! +An important first step to using **Bowhead** is to understand how it categorises CSS properties by the different CSS data types. By and large, this is done by looking at what the _expected_ values for a given property are: + +```css +selector { + background-color: #b22222; + color: #3cb371; + outline-color: #d2b48c; + + padding: 0.5rem; + margin: 2rem; + + display: flex; + align-items: flex-start; + justify-content: flex-end; +} +``` + +If we take the above snippet as an example, we can quickly identify two types of values present: colors and sizes. _Colors_ typically stand out quite easily, and, historically, developers have done well to assign colors to variables to simplify their use throughout the codebase. _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 only because color is in their names, but because we can interchange the values between the properties and they still make sense. + +Sizes can take trickier forms to identify and categorise, and I recommend allowing for more sizes 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 size, 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 _data type of the values_ they expect, you end up with a map of _most properties_ against value types: + + + + + + + + + + + + + + + + + +
colorsizealignment…
+ 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_: + + + + + + + + + + + + + + + + + +
colorsizealignment…
+ #b22222
+ #3cb371
+ #d2b48c
+ … + 		+ 1em
+ 20px
+ 2px
+ … + 		+ flex-start
+ flex-end
+ center
+ … +
+ +## 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 data types each CSS property should map against.
$bowhead-type-map
(optional)		See below.Defines custom remapping to rename the built-in names for types.
$bowhead-tokensSee below.Defines the design token values, categorised by data types.
+ +

№ 1. Variable As Default

+ +```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; +} +``` + +

№ 2. 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); +} +``` + +```scss ++$bowhead-variable-as-default: true; ++$bowhead-show-fallback: false; + +body { + @include v(color, desert); +} +``` + +```css +body { + color: var(--color-desert); +} +``` + +When $bowhead-variable-as-default is false, $bowhead-show-fallback has no effect. + +```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; +} +``` + +

№ 3. Generating CSS Variables

+ +```scss +$bowhead-generate: true; +``` + +```css +:root { + --size-small: 0.5rem; + --size-medium: 1rem; + --size-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; +} +``` + +```scss +$bowhead-generate: false; +``` + +Nothing is generated! + +

№ 4. 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 (`size`, `color`, etc.), i.e. + +```scss +$bowhead-property-map: ( + width: size, + min-width: size, + max-width: size, + height: size, + min-height: size, + max-height: size, + ..., +); +``` + +If you wish, you can create new mappings or overwrite existing defaults by defining your own property map, e.g. + +```scss +$bowhead-property-map: ( + vertical-align: alignments, +); +``` + +Where `alignments` would be one of your design token types, e.g. + +```scss +$bowhead-tokens: ( + alignments: ( + default: baseline, + alternate: middle, + ), + ..., +); +``` + +**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**. + +

№ 5. Type Map (optional)

+ +`$bowhead-type-map` is a `map` that allows defining alternate names for the data types, e.g. + +```scss +$bowhead-type-map: ( + size: measure, + ..., +); +``` + +

№ 6. Tokens

+ +`$bowhead-tokens` expects an _SCSS_ `map` of types of tokens. These types could be a _size_, _color_, _opacity_, _z-index_, etc. + +```scss +$bowhead-tokens: ( + size: ( + 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, + ), +); +``` + +--- + +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! + +```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 the CSS Variables it can spit out on their own. However you use it is totally up to you! 😄 + +```scss +.thing { + @include v(background-color, desert); + @include v(color, brick); + border: v(size, small) solid v(color, plankton); + padding: v(size, medium) v(size, large); + @include v(z-index, above); + opacity: var(--opacity-alpha); + // 1. if you only 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… + +```css +.thing { + background-color: #d2b48c; + background-color: var(--color-desert); + color: #b22222; + color: var(--color-brick); + border: var(--size-small) solid var(--color-plankton); + padding: var(--size-medium) var(--size-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); +} +``` + +## Extras + +Need a negative value? Use `calc()`: + +```scss +.thing { + margin-left: calc(#{v(size, medium)} * -1); +} +``` + +Combining values? Same idea: + +```scss +.thing { + margin-left: calc(#{v(size, medium)} + #{v(size, small)}); +} +``` + +What about multiple values in a function? Make sure you're using the _raw_ values from the `v()` function: + +```scss +.thing { + background-color: rgba(v(color, desert, true), v(opacity, alpha, true)); +} +``` + +## Read more + +- [Variables for Both](https://chrisburnell.com/article/variables-for-both/) +- [Deep Dive into Colour](https://chrisburnell.com/article/deep-dive-into-colour/) + +## Contributing + +Contributions of all kinds are welcome! Please [submit an Issue on GitHub](https://github.com/chrisburnell/bowhead/issues) or [get in touch with me](https://chrisburnell.com/about/#contact) if you’d like to do so. ## License diff --git a/package-lock.json b/package-lock.json index 07988d7..94fce70 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@chrisburnell/bowhead", - "version": "0.2.2", + "version": "0.3.2", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@chrisburnell/bowhead", - "version": "0.2.2", + "version": "0.3.2", "license": "MIT", "devDependencies": { "sass": "^1.49.9" diff --git a/package.json b/package.json index 9d50884..5baf81a 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,9 @@ { "name": "@chrisburnell/bowhead", - "version": "0.3.2", + "version": "0.3.3", "description": "Memorable and maintainable design tokens in SCSS", - "author": "Chris Burnell", + "author": "Chris Burnell ", "license": "MIT", - "homepage": "https://chrisburnell.com/bowhead/", "repository": { "type": "git", "url": "git+ssh://git@github.com/chrisburnell/bowhead.git" @@ -12,15 +11,16 @@ "bugs": { "url": "https://github.com/chrisburnell/bowhead/issues" }, + "keywords": [ + "css", + "design tokens", + "scss" + ], "devDependencies": { "sass": "^1.49.9" }, + "dependencies": {}, "scripts": { "test": "npx sass bowhead.scss bowhead.css --no-source-map" - }, - "keywords": [ - "design tokens", - "css", - "scss" - ] + } }