readme and types improvements (#9)

* readme and types improvements

* unduplictae imports

Author: bartveneman

readme.md

@@ -1,6 +1,6 @@
 # css-design-tokens
 
-Create Design Tokens by going through CSS to find colors, font-sizes, gradients etcetera and turn them into a spec-compliant token format.
+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.
 
 ## Installation
 
@@ -13,26 +13,82 @@ npm install @projectwallace/css-design-tokens
 ```js
 import { css_to_tokens } from '@projectwallace/css-design-tokens'
 
-let tokens = css_to_tokens(`.my-design-system { color: green; }`)
+let {
+  color,
+  font_size,
+  font_family,
+  line_height,
+  gradient,
+  box_shadow,
+  radius,
+  duration,
+  easing,
+} = css_to_tokens(`.my-design-system { color: green; }`)
 
-// Or if you already have done CSS analysis with @projectwallace/css-analyzer:
-// NOTE: it is important that `useLocations` is true
+// Or if you already have done CSS analysis with @projectwallace/css-analyzer
 import { analyze } from '@projectwallace/css-analyzer'
 import { analysis_to_tokens } from '@projectwallace/css-design-tokens'
 
 let analysis = analyze(`.my-design-system { color: green; }`, {
-  useLocations: true // MUST be true
+  useLocations: true // may be `true` or `false`, it works either way
 })
 let tokens = analysis_to_tokens(analysis)
 ```
 
+### Stable unique token ID's
+
+All tokens have a stabe unique ID using a very simple hashing algorithm. This is helpful when you run analysis multiple times over your project and lets you identify removed or added tokens easily.
+
+```ts
+let { color } = css_to_tokens(
+  `.my-design-system {
+    color: green;
+    color: rgb(100 100 100 / 20%);
+  }`
+)
+
+// {
+//   'green-5e0cf03': {
+//     $type: 'color',
+//     ...
+//   },
+//   'grey-8139d9b': {
+//     $type: 'color',
+//     ...
+//   }
+// }
+```
+
+### Getting authored values
+
+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.
+
+```ts
+let { color } = css_to_tokens(`.my-design-system { color: green; }`)
+
+// {
+//   'green-5e0cf03': {
+//     ...
+//     $extensions: {
+//       'com.projectwallace.css-authored-as': 'green'
+//     }
+//   },
+// }
+
+let authored_green = color['green-5e0cf03']['$extensions']['com.projectwallace.css-authored-as']
+
+// 'green'
+```
+
 ## Acknowledgements
 
 - [CSSTree](https://github.com/csstree/csstree) does all the heavy lifting of parsing CSS
-- [ColorJS.io](https://colorjs.io/) powers all color conversions necessary for grouping and sorting
+- [ColorJS.io](https://colorjs.io/) powers all color conversions necessary for grouping and sorting and converting into Color tokens
 
 ## 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)
 - [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

src/index.ts

@@ -1,22 +1,23 @@
 import { analyze } from '@projectwallace/css-analyzer'
 import { convert as convert_duration } from 'css-time-sort'
 import { group_colors, color_dict } from './group-colors.js'
-import { destructure_box_shadow, type DestructuredShadow } from './destructure-box-shadow.js'
+import { destructure_box_shadow } from './destructure-box-shadow.js'
 import { destructure_easing } from './destructure-easing.js'
 import { destructure_font_family } from './destructure-font-family.js'
 import { hash } from './hash.js'
 import { destructure_line_height } from './destructure-line-height.js'
 import { parse_length } from './parse-length.js'
-import type { ColorToken, CssAnalysis } from './types.js'
 import {
 	EXTENSION_AUTHORED_AS,
 	type CubicBezierToken,
 	type DimensionToken,
 	type DurationToken,
 	type FontFamilyToken,
 	type NumberToken,
-	type BaseToken,
 	type UnparsedToken,
+	type ColorToken,
+	type CssAnalysis,
+	type ShadowToken,
 } from './types.js'
 import { color_to_token } from './colors.js'
 
@@ -27,17 +28,31 @@ export function css_to_tokens(css: string) {
 
 // TODO: get @projectwallace/css-analyzer types in order
 type UniqueCount = Record<string, number>
-type UniqueWithLocations = Record<string, {
+type CssLocation = {
 	line: number
 	column: number
 	offset: number
 	length: number
-}[]>
+}
+type UniqueWithLocations = Record<string, CssLocation[]>
 type Collection = {
 	unique: UniqueCount
 } | {
 	uniqueWithLocations: UniqueWithLocations
 }
+type TokenID = string
+
+type Tokens = {
+	color: Record<TokenID, ColorToken | UnparsedToken>
+	font_size: Record<TokenID, UnparsedToken | DimensionToken>
+	font_family: Record<TokenID, FontFamilyToken>
+	line_height: Record<TokenID, UnparsedToken | DimensionToken | NumberToken>
+	gradient: Record<TokenID, UnparsedToken>
+	box_shadow: Record<TokenID, ShadowToken | UnparsedToken>
+	radius: Record<TokenID, UnparsedToken>
+	duration: Record<TokenID, DurationToken | UnparsedToken>
+	easing: Record<TokenID, UnparsedToken | CubicBezierToken>
+}
 
 /**
  * Function to get the unique values from a collection regardless of whether the analysis was run with
@@ -50,7 +65,7 @@ function get_unique(collection: Collection) {
 	return collection.unique
 }
 
-export function analysis_to_tokens(analysis: CssAnalysis) {
+export function analysis_to_tokens(analysis: CssAnalysis): Tokens {
 	return {
 		color: (() => {
 			let colors = Object.create(null) as Record<string, ColorToken | UnparsedToken>
@@ -165,11 +180,6 @@ export function analysis_to_tokens(analysis: CssAnalysis) {
 			return gradients
 		})(),
 		box_shadow: (() => {
-			type ShadowToken = BaseToken & {
-				$type: 'shadow'
-				$value: DestructuredShadow | DestructuredShadow[]
-			}
-
 			let shadows = Object.create(null) as Record<string, ShadowToken | UnparsedToken>
 			let unique = get_unique(analysis.values.boxShadows)
 
@@ -183,15 +193,15 @@ export function analysis_to_tokens(analysis: CssAnalysis) {
 						$extensions: {
 							[EXTENSION_AUTHORED_AS]: box_shadow
 						}
-					} as UnparsedToken
+					}
 				} else {
 					shadows[name] = {
 						$type: 'shadow',
-						$value: parsed.length === 1 ? parsed[0] : parsed,
+						$value: parsed.length === 1 ? parsed[0]! : parsed,
 						$extensions: {
 							[EXTENSION_AUTHORED_AS]: box_shadow
 						}
-					} as ShadowToken
+					}
 				}
 			}
 			return shadows

src/types.ts

@@ -1,4 +1,5 @@
 import type { analyze } from '@projectwallace/css-analyzer'
+import type { DestructuredShadow } from './destructure-box-shadow'
 
 export type CssAnalysis = ReturnType<typeof analyze>
 
@@ -65,3 +66,8 @@ export type FontFamilyToken = BaseToken & {
 	$type: 'fontFamily'
 	$value: string[] | string
 }
+
+export type ShadowToken = BaseToken & {
+	$type: 'shadow'
+	$value: DestructuredShadow | DestructuredShadow[]
+}