@projectwallace/css-design-tokens 0.5.0 → 0.7.0

package/dist/destructure-box-shadow.d.ts

@@ -1,10 +1,10 @@
-import { ColorToken, UnparsedToken } from './types.js';
+import { ColorValue } from './types.js';
 type CssLength = {
     value: number;
     unit: string;
 };
 export type DestructuredShadow = {
-    color: ColorToken | UnparsedToken | undefined;
+    color: ColorValue | undefined;
     offsetX: CssLength | undefined;
     offsetY: CssLength | undefined;
     blur: CssLength | undefined;

package/dist/destructure-easing.d.ts

@@ -1,2 +1,2 @@
 import { Easing } from './types.js';
-export declare function destructure_easing(easing: string): Easing | undefined;
+export declare function destructure_easing(easing: string): Easing | null;

package/dist/types.d.ts

@@ -2,18 +2,22 @@ import { analyze } from '@projectwallace/css-analyzer';
 import { DestructuredShadow } from './destructure-box-shadow';
 export type CssAnalysis = ReturnType<typeof analyze>;
 export declare const EXTENSION_AUTHORED_AS = "com.projectwallace.css-authored-as";
+export declare const EXTENSION_USAGE_COUNT = "com.projectwallace.usage-count";
+export declare const EXTENSION_CSS_PROPERTIES = "com.projectwallace.css-properties";
 export type Easing = [number, number, number, number];
 export type BaseToken = {
-    $extensions?: {
+    $extensions: {
         [EXTENSION_AUTHORED_AS]: string;
+        [EXTENSION_USAGE_COUNT]: number;
     };
 };
+type DurationValue = {
+    value: number;
+    unit: 'ms';
+};
 export type DurationToken = BaseToken & {
     $type: 'duration';
-    $value: {
-        value: number;
-        unit: 'ms';
-    };
+    $value: DurationValue;
 };
 export type UnparsedToken = BaseToken & {
     $value: string;
@@ -31,15 +35,16 @@ export type ColorToken = BaseToken & {
     $type: 'color';
     $value: ColorValue;
     $extensions: {
-        [EXTENSION_AUTHORED_AS]: string;
+        [EXTENSION_CSS_PROPERTIES]: Array<string>;
     };
 };
+export type DimensionValue = {
+    value: number;
+    unit: string;
+};
 export type DimensionToken = BaseToken & {
     $type: 'dimension';
-    $value: {
-        value: number;
-        unit: string;
-    };
+    $value: DimensionValue;
 };
 export type NumberToken = BaseToken & {
     $type: 'number';
@@ -51,7 +56,7 @@ export type CubicBezierToken = BaseToken & {
 };
 export type FontFamilyToken = BaseToken & {
     $type: 'fontFamily';
-    $value: string[] | string;
+    $value: string[];
 };
 export type ShadowToken = BaseToken & {
     $type: 'shadow';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@projectwallace/css-design-tokens",
   "description": "Generate spec-compliant Design Tokens from CSS.",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "license": "EUPL-1.2",
   "author": "Bart Veneman <bart@projectwallace.com>",
   "repository": {
@@ -34,7 +34,7 @@
     "check": "tsc --noEmit"
   },
   "dependencies": {
-    "@projectwallace/css-analyzer": "^7.5.1",
+    "@projectwallace/css-analyzer": "^7.6.0",
     "color-sorter": "^7.0.0",
     "colorjs.io": "^0.6.0-alpha.1",
     "css-time-sort": "^3.0.0",

package/readme.md

@@ -2,6 +2,23 @@
 
 Create Design Tokens by going through CSS to find colors, font-sizes, gradients etcetera and turn them into a [Design Tokens spec](https://tr.designtokens.org/)-compliant token format.
 
+## Table of contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Token types](#token-types)
+  - [Color](#color)
+  - [Font-size](#font-size)
+  - [Font-family](#font-family)
+  - [Line-height](#line-height)
+  - [Gradient](#gradient)
+  - [Box-shadow](#box-shadow)
+  - [Radius](#radius)
+  - [Duration](#duration)
+  - [Easing](#easing)
+- [Extensions](#extensions)
+- [Acknowledgements](#acknowledgements)
+
 ## Installation
 
 ```sh
@@ -59,9 +76,397 @@ let { color } = css_to_tokens(
 // }
 ```
 
-### Getting authored values
+## Token types
+
+### Color
+
+['Color' Design Token format](https://www.designtokens.org/tr/third-editors-draft/color/#format)
+
+Only fully compliant colors are listed. Colors that can't be parsed by [colorjs.io](https://colorjs.io/) are ignored, like `rgb(var(--red) var(--green) var(--blue))` or CSS system colors like `ButtonText`.
+
+- The optional `alpha` property is _always_ present.
+- The optional `hex` fallback property is _never_ present.
+- In addition to other tokens all colors have a `com.projectwallace.css-properties` extension that contains all the CSS properties that a specific color was used for.
+
+```js
+let { color } = css_to_tokens(`.my-design-system { color: green; }`)
+
+let color = {
+  'green-5e0cf03': {
+    $type: 'color',
+    $value: {
+      colorSpace: 'srgb',
+      components: [0, 0.5019607843137255, 0],
+      alpha: 1,
+    },
+    $extensions: {
+      'com.projectwallace.css-authored-as': 'green',
+      'com.projectwallace.usage-count': 2,
+      'com.projectwallace.css-properties': ['color', 'border-color'],
+    }
+  }
+}
+```
+
+### Font-size
+
+['Dimension' Design Token format](https://www.designtokens.org/tr/third-editors-draft/format/#dimension)
+
+Font-sizes are listed as `$type: 'dimension'` types if the font-size is declared with either `px` or `rem` or as plain type-less tokens otherwise.
+
+```js
+let { font_size } = css_to_tokens(`.my-design-system {
+  .my-design-system {
+    font-size: 16px;
+    font-size: 1rem;
+    font-size: 20vmin;
+  }
+}`)
+
+let font_size = {
+  'fontSize-171eed': {
+    $type: 'dimension',
+    $value: {
+      value: 16,
+      unit: 'px'
+    },
+    $extensions: {
+      'com.projectwallace.css-authored-as': '16px',
+      'com.projectwallace.usage-count': 1,
+    }
+  },
+  'fontSize-582e015a': {
+    $value: '20vmin',
+    $extensions: {
+      'com.projectwallace.css-authored-as': '20vmin',
+      'com.projectwallace.usage-count': 1,
+    }
+  },
+}
+```
+
+### Font-family
+
+['fontFamily' Design Token format](https://www.designtokens.org/tr/third-editors-draft/format/#font-family)
+
+Font-families are _always_ listed as `$type: 'fontFamily'`.
+
+```js
+let { font_family } = css_to_tokens(`.my-design-system {
+  .my-design-system {
+    font-family: 'Inter';
+    font-family: Arial Black, sans-serif;
+  }
+}`)
+
+let font_family = {
+  'fontFamily-3375cf09': {
+    $type: 'fontFamily',
+    $value: ['\'Inter\''],
+    $extensions: {
+      'com.projectwallace.css-authored-as': '\'Inter\'',
+      'com.projectwallace.usage-count': 1,
+    }
+  },
+  'fontFamily-582e015a': {
+    $value: ['Arial Black', 'sans-serif'],
+    $extensions: {
+      'com.projectwallace.css-authored-as': 'Arial Black, sans-serif',
+      'com.projectwallace.usage-count': 1,
+    }
+  },
+}
+```
+
+### Line-height
+
+Line heights can either be `dimension` or `number` types, or a plain type-less token. This depends on how well the value can be mapped to a valid token.
+
+```ts
+let { line_height } = css_to_tokens(`
+  .my-design-system {
+    line-height: 1.5rem; /* rem -> type=dimension */
+    line-height: 1.5; /* no unit -> type=number */
+    line-height: 20vmin; /* can not be mapped to valid token type */
+  }
+`)
+
+let line_height = {
+  'lineHeight-563f7fe2': {
+    $type: 'dimension',
+    $value: {
+      value: 1.5,
+      unit: 'rem'
+    },
+    $extensions: {
+      'com.projectwallace.css-authored-as': '1.5rem',
+      'com.projectwallace.usage-count': 1,
+    }
+  },
+  'lineHeight-bdb8': {
+    $type: 'number',
+    $value: 1.5,
+    $extensions: {
+      'com.projectwallace.css-authored-as': '1.5',
+      'com.projectwallace.usage-count': 1,
+    }
+  },
+  'lineHeight-582e015a': {
+    $value: '20vmin',
+    $extensions: {
+      'com.projectwallace.css-authored-as': '20vmin',
+      'com.projectwallace.usage-count': 1,
+    }
+  }
+}
+```
+
+### Gradient
+
+Gradients are passed as-is, no mapping is done. This is because the spec is currently too limited in expressing a CSS gradient.
+
+```ts
+let { gradient } = css_to_tokens(`
+  .my-design-system {
+    background: linear-gradient(to right, red, blue);
+  }
+`)
+
+let gradient = {
+  'gradient-2aec04e5': {
+    $value: 'linear-gradient(to right, red, blue)',
+    $extensions: {
+      'com.projectwallace.css-authored-as': 'linear-gradient(to right, red, blue)',
+      'com.projectwallace.usage-count': 1,
+    }
+  }
+}
+```
+
+### Box-shadow
+
+['Shadow' Design Token type](https://www.designtokens.org/tr/third-editors-draft/format/#shadow)
+
+- Multiple shadows can be mapped, so beware that `$value` van either be a single object or an array.
+- Only if a box-shadow has a valid `color` type it will be mapped as a `box-shadow` type
+
+```ts
+let { box_shadow } = css_to_tokens(`
+  .my-design-system {
+    box-shadow: 0 0 10px 0 rgba(0, 0, 0, 0.5);
+    box-shadow: 0 0 10px 0 rgba(0, 0, 0, 0.5), 0 0 10px 0 rgba(0, 0, 0, 0.5);
+    box-shadow: 0 0 0 0 var(--red);
+  }
+`)
+
+let box_shadow = {
+  'boxShadow-6f90da6b': {
+    $type: 'shadow',
+    $value: {
+      offsetX: {
+        value: 0,
+        unit: 'px'
+      },
+      offsetY: {
+        value: 0,
+        unit: 'px'
+      },
+      blur: {
+        value: 10,
+        unit: 'px'
+      },
+      spread: {
+        value: 0,
+        unit: 'px'
+      },
+      inset: false,
+      color: {
+        colorSpace: 'srgb',
+        components: [0, 0, 0],
+        alpha: 0.5,
+      },
+    },
+    $extensions: {
+      'com.projectwallace.css-authored-as': '0 0 10px 0 rgba(0, 0, 0, 0.5)',
+      'com.projectwwallace.usage-count': 1,
+    }
+  },
+  'boxShadow-be2751ac': {
+    $type: 'shadow',
+    $value: [
+      {
+        offsetX: {
+          value: 0,
+          unit: 'px'
+        },
+        offsetY: {
+          value: 0,
+          unit: 'px'
+        },
+        blur: {
+          value: 10,
+          unit: 'px'
+        },
+        spread: {
+          value: 0,
+          unit: 'px'
+        },
+        inset: false,
+        color: {
+          colorSpace: 'srgb',
+          components: [0, 0, 0],
+          alpha: 0.5,
+        },
+      },
+      {
+        offsetX: {
+          value: 0,
+          unit: 'px'
+        },
+        offsetY: {
+          value: 0,
+          unit: 'px'
+        },
+        blur: {
+          value: 10,
+          unit: 'px'
+        },
+        spread: {
+          value: 0,
+          unit: 'px'
+        },
+        inset: false,
+        color: {
+          colorSpace: 'srgb',
+          components: [0, 0, 0],
+          alpha: 0.5,
+        },
+      }
+    ],
+    $extensions: {
+      'com.projectwwallace.css-authored-as': '0 0 10px 0 rgba(0, 0, 0, 0.5), 0 0 10px 0 rgba(0, 0, 0, 0.5)',
+      'com.projectwwallace.usage-count': 1,
+    }
+  },
+  'boxShadow-j4h5gas5h': {
+    $value: '0 0 0 0 var(--red)',
+    $extensions: {
+      'com.projectwwallace.css-authored-as': '0 0 0 0 var(--red)',
+      'com.projectwwallace.usage-count': 1,
+    }
+  }
+}
+```
+
+### Radius
+
+Radii are passed as-is, no mapping is done.
+
+```ts
+let { radius } = css_to_tokens(`
+  .my-design-system {
+    border-radius: 10px;
+  }
+`)
+
+let radius = {
+  'radius-170867': {
+    $value: '10px',
+    $extensions: {
+      'com.projectwwallace.css-authored-as': '10px',
+      'com.projectwwallace.usage-count': 1,
+    }
+  }
+}
+```
+
+### Duration
+
+['Duration' Design Token type](https://www.designtokens.org/tr/third-editors-draft/format/#duration)
 
-The tokens output parses most CSS into Design Tokens but in most cases it also provides a way to get the authored CSS via the `$extensions` property. The custom identifier for this project is `com.projectwallace` and the authored values can be found with `com.projectwallace.css-authored-as` on the `$extensions` object.
+Durations can either be animation- or transition-durations or -delays. Even though `s` is a valid unit we _always_ map to `ms`.
+
+```ts
+let { duration } = css_to_tokens(`
+  .my-design-system {
+    animation-duration: 1s;
+  }
+`)
+
+let duration = {
+  'duration-17005f': {
+    $type: 'duration',
+    $value: {
+      value: 1000,
+      unit: 'ms'
+    },
+    $extensions: {
+      'com.projectwwallace.css-authored-as': '1s',
+      'com.projectwwallace.usage-count': 1,
+    }
+  }
+}
+```
+
+### Easing
+
+['Cubic Bézier' Design Token type](https://www.designtokens.org/tr/third-editors-draft/format/#cubic-bezier)
+
+Easings are mapped to cubic béziers when possible or represented as plain type-less tokens otherwise. [CSS Easing keywords](https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function) are also converted to cubic béziers.
+
+```ts
+let actual = css_to_tokens(`
+  .my-design-system {
+    animation-timing-function: ease-in-out;
+    animation-timing-function: cubic-bezier(0, 0, 0.5, .8);
+    animation-timing-function: var(--test);
+  }
+`)
+
+let easing = {
+  'easing-ea6c7565': {
+    $type: 'cubicBezier',
+    $value: [
+      0.42,
+      0,
+      0.58,
+      1
+    ],
+    $extensions: {
+      'com.projectwwallace.css-authored-as': 'ease-in-out',
+      'com.projectwwallace.usage-count': 1,
+    }
+  },
+  'easing-90111eba': {
+    $type: 'cubicBezier',
+    $value: [
+      0,
+      0,
+      0.5,
+      0.8
+    ],
+    $extensions: {
+      'com.projectwwallace.css-authored-as': 'cubic-bezier(0, 0, 0.5, .8)',
+      'com.projectwwallace.usage-count': 1,
+    }
+  },
+  'easing-12bb7f36': {
+    $value: 'var(--test)',
+    $extensions: {
+      'com.projectwwallace.css-authored-as': 'var(--test)',
+      'com.projectwwallace.usage-count': 1,
+    }
+  }
+}
+```
+
+## Extensions
+
+This library adds a couple of potentially extensions to the design token values via the `com.projectwallace` namespace on the `$extensions` property of all generated design tokens.
+
+### Authored CSS values
+
+This package parses CSS into Design Tokens but also provides a way to get the authored CSS via the `$extensions['com.projectwallace.css-authored-as']` property on any of the tokens:
 
 ```ts
 let { color } = css_to_tokens(`.my-design-system { color: green; }`)
@@ -80,6 +485,50 @@ let authored_green = color['green-5e0cf03']['$extensions']['com.projectwallace.c
 // 'green'
 ```
 
+### Usage count
+
+If you need to know how often a particalur design token was found in the CSS you can use the `$extensions['com.projectwallace.usage-count']` property on any of the tokens:
+
+```ts
+let { color } = css_to_tokens(`.my-design-system { color: green; }`)
+
+// {
+//   'green-5e0cf03': {
+//     ...
+//     $extensions: {
+//       'com.projectwallace.usage-count': 1
+//     }
+//   },
+// }
+
+let green_count = color['green-5e0cf03']['$extensions']['com.projectwallace.usage-count']
+
+// 1
+```
+
+### CSS property usage
+
+__For color tokens only__
+
+You can read the `$extensions['com.projectwallace.css-properties']` property to see for which CSS properties a color was used:
+
+```ts
+let { color } = css_to_tokens(`.my-design-system { color: green; }`)
+
+// {
+//   'green-5e0cf03': {
+//     ...
+//     $extensions: {
+//       'com.projectwallace.css-properties': ['color']
+//     }
+//   },
+// }
+
+let properties = color['green-5e0cf03']['$extensions']['com.projectwallace.css-properties']
+
+// ['color']
+```
+
 ## Acknowledgements
 
 - [CSSTree](https://github.com/csstree/csstree) does all the heavy lifting of parsing CSS
@@ -88,7 +537,7 @@ let authored_green = color['green-5e0cf03']['$extensions']['com.projectwallace.c
 ## Related projects
 
 - [Design Tokens analyzer](https://www.projectwallace.com/design-tokens) - Online CSS to Design Tokens convernter, uses this package
-- [CSS Analyzer](https://github.com/projectwallace/css-analyzer) - The best CSS analyzer that powers all analysis on [projectwallace.com](https://www.projectwallace.com?utm_source=github&utm_medium=wallace_format_css_related_projects)
+- [CSS Analyzer](https://github.com/projectwallace/css-analyzer) - The best CSS analyzer that powers all analysis on [projectwallace.com](https://www.projectwallace.com?utm_source=github&utm_medium=wallace_css_design_tokens_related_projects)
 - [Color Sorter](https://github.com/projectwallace/color-sorter) - Sort CSS colors
   by hue, saturation, lightness and opacity
 - [CSS Time Sort](https://github.com/projectwallace/css-time-sort) - Sort an array of `<time>` values

package/dist/keyword-set.d.ts

@@ -1,8 +0,0 @@
-/**
- * @description A Set-like construct to search CSS keywords in a case-insensitive way
- */
-export declare class KeywordSet {
-    private set;
-    constructor(items: Lowercase<string>[]);
-    has(item: string): boolean;
-}