@designid/tokens v0.3.1

@designid/tokens

This package provides a set of design system tokens for your projects.

The tokens are defined in a JSON file according to the Design Tokens Community Group specification. They can be used to define colors, typography, spacing, and other design-related values consistently across your codebase.

The build tokens can be used in various ways, such as in CSS files, CSS-in-JS libraries, CSS preprocessors, or even directly in your JavaScript or TypeScript code.

You can also use the tokens in your design tools, like Figma, Sketch, Adobe XD, etc., to ensure that your design system is consistent across all platforms.

Get started

Install

pnpm add -D @designid/tokens

Using tokens-build and tokens-watch binaries

To build the design system tokens, you need to run the pnpm tokens-build or pnpm tokens-watch binary with pnpm installed on your node-modules. You can then run the following commands:

Quick Start

Copy the example folder in this project. To be able to configure it, you need to customize designid.config.js based on your setup.

Building tokens

If you have the designid.config.js in your root project folder you can execute the following build script.

pnpm tokens-build

Alternatively you can specify the configuration file directly, this file should be according to the TConfigFile interface and located in the design system base directory.

Building tokens with a specific configuration file

pnpm tokens-build --config=./example/tokens/base.tokens.json

Working in development mode

To build the design system tokens in development mode, you can use the tokens-watch command. This will watch for changes in your token files and rebuild them automatically.

pnpm tokens-watch

TConfigFile $paths Properties

File structure

The file structure of the design system tokens is as follows in a typical web application project:

./root
  ├── package.json // Project's package.json file
  ├── ...
  ├── designid.config.js // Configuration file for the design system tokens
  └── styles/ // Directory for the design system
         ├── tokens/
         │     ├── base.tokens.json
         │     ├── colors.tokens.json
         │     ├── typography.tokens.json
         │     ├── ... // However you want to structure your tokens.
         │     ├── ... // The file names should end with `.tokens.json`
         │     └── icons/
         │           ├── icon1.svg
         │           └── icon2.svg
         │
         ├── fonts/
         │     ├── font-directory-1/
         │     │     ├── bold.woff2
         │     │     └── regular.woff2
         │     │
         │     └── font-directory-2/
         │           └── variable.otf
         │      
         ├── icons/
         │     ├── icon1.svg
         │     └── icon2.svg
         │
         ├── fonts/
         │     ├── font1.woff
         │     └── font2.woff
         │
         ├── dist/
         │     ├── {namespace}-design-system-raw.tokens.json
         │     ├── {namespace}-design-system.tokens.css
         │     ├── css/
         │     │     ├── base.css
         │     │     └── colors.css
         │     │
         │     ├── js/
         │     │     ├── base.js
         │     │     └── colors.js
         │     │
         │     ├── assets/
         │     │
         │     └── fonts/
         │           ├── ...// All the font files will be copied
         │           └── ...// here or specified in the `fontsDistAssetsDir`. 
         │                   
         └── build/
               ├── icons/   // Aggregated icons grouped by directory in single `.json` files
               │     ├── icons-group-1
               │     │     └── svg.{icons-group-1}.tokens.json
               │     │
               │     ├── icons-group-2
               │     │     └── svg.{icons-group-2}.tokens.json
               │     │
               │     └── icons-group-n
               │
               └── tokens/  // Aggregated tokens in a single `.json` file
                     │      // all tokens compiled in value no references
                     ├── {namespace}-design-system.tokens.config.json
                     │      // all icons compiled in value no references
                     └── {namespace}-design-system.tokens.svg.json 

Integration with a simple Next.js project

To integrate the design system tokens into a simple Next.js project, you can follow these steps:

1. Install the package:

   pnpm add -D @designid/tokens

2. Create a configuration file: Create a designid.config.js file in the root of your project with the following content:

   module.exports = {
     paths: {
       baseDir: './src/styles',
       tokensDir: './tokens',
       distDir: './dist',
       buildDir: './build',
       iconsDir: './icons',
       fontsDir: './fonts',
       fontsDistAssetsDir: './assets/fonts',
     },
   };

3. Create your tokens: Create a directory structure as described above, and add your token files in the tokens directory. For example, you can create a base.tokens.json file with the following content:

   {
     "namespace": {
       "path": {
        "to": {
          "token": {
            "$type": "color",
            "$description": "Base color for the design system",
            "$value": "#ffffff",
          }
        }
       }
     },
     "path2": {
       "to": {
         "token": {
           "$type": "color",
           "$description": "Secondary color for the design system",
           "$value": "#000000",
           "$extensions": {
            "mode": {
              "dark": "dark-color-value-for-token"
            }
           }
         }
       }
     }
   }

4. Build the tokens: Run the following command to build the tokens:

    pnpm tokens-build

5. Use the tokens in your Next.js project: You can now import the generated CSS or JavaScript files in your Next.js project. For example, you can import the CSS file in your _app.js file:

   @import './dist/{namespace}-design-system.tokens.css';
   
   html, body {
     background-color: var(--{namespace}-design-system-path-to-token);
     color: var(--{namespace}-design-system-path2-to-token);
   }
   
   .my-component {
     color: var(--{namespace}-design-system-path-to-token);
   }

   Import the JavaScript file in your components:

   import tokens from '../dist/{namespace}-design-system.tokens.js';
   
   const MyComponent = () => {
     return (
       <div style={{ color: tokens['path.to.token'] }}>
         This is my component
       </div>
     );
   };
   
   const Div = styled.div`
     color: ${tokens['path.to.token']};
   `;

   Or you can use all the tokens in the theme provider of your choice, such as @stitches/react, styled-components, or emotion.

   import lightThemeConfig, { cssVars as lightCssVars } from '../dist/js/tokens.default.config.mjs'
   import darkThemeConfig, { cssVars as darkCssVars } from '../dist/js/tokens.dark.config.mjs'
   
   export const theme = {
     cssVars: {
       light: lightCssVars,
       dark: darkCssVars,
     },
     config: {
       light: lightThemeConfig,
       dark: darkThemeConfig,
     },
   }

Token Specification

The tokens are defined according to the Design Tokens Community Group specification. Each token should have the following properties:

• $type: The type of the token, such as color, font, size, etc.
• $description: A description of the token.
• $value: The value of the token.

Custom properties

• $extensions: Optional extensions for the token, such as mode for dark mode support.
• $extensions.mode: An object containing the dark mode value for the token.
• $extensions.mode.dark: The value of the token in dark mode.
• $extensions.mode.light: The value of the token in light mode.
• $extensions.generators: Creates new tokens based on the current one. Currently only supports color and alpha manipulations.

• $extensions.breakpoints: An object containing the breakpoints for the token. This is useful for responsive design.

More information about this plugin will be available in the future.

Thanks for using our design system tokens package! If you have any questions or suggestions, feel free to contact me at @isaozler.