@projectwallace/css-design-tokens 0.3.2 → 0.4.1

package/dist/index.d.ts

@@ -1,30 +1,16 @@
-import { DestructuredShadow } from './destructure-box-shadow.js';
-import { ColorToken, CssAnalysis, CubicBezierToken, DimensionToken, DurationToken, FontFamilyToken, NumberToken, BaseToken, UnparsedToken } from './types.js';
-export declare function css_to_tokens(css: string): {
-    color: Record<string, UnparsedToken | ColorToken>;
-    font_size: Record<string, UnparsedToken | DimensionToken>;
-    font_family: Record<string, FontFamilyToken>;
-    line_height: Record<string, UnparsedToken | DimensionToken | NumberToken>;
-    gradient: Record<string, UnparsedToken>;
-    box_shadow: Record<string, UnparsedToken | (BaseToken & {
-        $type: "shadow";
-        $value: DestructuredShadow | DestructuredShadow[];
-    })>;
-    radius: Record<string, UnparsedToken>;
-    duration: Record<string, DurationToken | UnparsedToken>;
-    easing: Record<string, UnparsedToken | CubicBezierToken>;
-};
-export declare function analysis_to_tokens(analysis: CssAnalysis): {
-    color: Record<string, UnparsedToken | ColorToken>;
-    font_size: Record<string, UnparsedToken | DimensionToken>;
-    font_family: Record<string, FontFamilyToken>;
-    line_height: Record<string, UnparsedToken | DimensionToken | NumberToken>;
-    gradient: Record<string, UnparsedToken>;
-    box_shadow: Record<string, UnparsedToken | (BaseToken & {
-        $type: "shadow";
-        $value: DestructuredShadow | DestructuredShadow[];
-    })>;
-    radius: Record<string, UnparsedToken>;
-    duration: Record<string, DurationToken | UnparsedToken>;
-    easing: Record<string, UnparsedToken | CubicBezierToken>;
+import { CubicBezierToken, DimensionToken, DurationToken, FontFamilyToken, NumberToken, UnparsedToken, ColorToken, CssAnalysis, ShadowToken } from './types.js';
+export declare function css_to_tokens(css: string): Tokens;
+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>;
 };
+export declare function analysis_to_tokens(analysis: CssAnalysis): Tokens;
+export {};

package/dist/keyword-set.d.ts

@@ -3,6 +3,6 @@
  */
 export declare class KeywordSet {
     private set;
-    constructor(items: string[]);
+    constructor(items: Lowercase<string>[]);
     has(item: string): boolean;
 }

package/dist/types.d.ts

@@ -1,10 +1,11 @@
 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 type Easing = [number, number, number, number];
 export type BaseToken = {
     $extensions?: {
-        [EXTENSION_AUTHORED_AS]?: string;
+        [EXTENSION_AUTHORED_AS]: string;
     };
 };
 export type DurationToken = BaseToken & {
@@ -52,4 +53,8 @@ export type FontFamilyToken = BaseToken & {
     $type: 'fontFamily';
     $value: string[] | string;
 };
+export type ShadowToken = BaseToken & {
+    $type: 'shadow';
+    $value: DestructuredShadow | DestructuredShadow[];
+};
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@projectwallace/css-design-tokens",
   "description": "Generate spec-compliant Design Tokens from CSS.",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "license": "EUPL-1.2",
   "author": "Bart Veneman <bart@projectwallace.com>",
   "repository": {
@@ -34,7 +34,7 @@
     "check": "tsc --noEmit"
   },
   "dependencies": {
-    "@projectwallace/css-analyzer": "^7.5.0",
+    "@projectwallace/css-analyzer": "^7.5.1",
     "color-sorter": "^7.0.0",
     "colorjs.io": "^0.6.0-alpha.1",
     "css-time-sort": "^3.0.0",
@@ -42,7 +42,7 @@
   },
   "devDependencies": {
     "@types/css-tree": "^2.3.10",
-    "vite": "^7.0.0",
+    "vite": "^7.0.4",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.2.4"
   }

package/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