@yandex/themekit v2.0.0-alpha.1

Themkit is a build system for design-tokens for any platform. This system is based on style-dictionary API and redefinition levels, which allows you to describe platform-specific values. Themkit provides you to extend existing themes in order to supplement or redefine existing tokens, it also allows you to use the basic theme set and add it to the service.

Features

• 🔍 Clear format (json or yaml) for developers and designers.
• 📚 Define tokens once and get result for any format, for example js, css or json.
• 🛠 Every part of the theme or some of the tokens is extendable and overridable.
• 💻 Tokens may be defined for several web platforms, for example desktop and touch.

Installation

# via npm
npm i -DE @yandex/themekit
# or yarn
yarn add --dev @yandex/themekit

Usage

A themekit is available as a CLI tool.

build

Builds themes for configured formats.

USAGE
  $ themekit build

OPTIONS
  -c, --config=config  [default: themekit.config.{js,json,yml}] The path to a themekit config file.
  -e, --entry=entry    Builds selected entries.
  -o, --output=output  Builds selected outputs.
  -w, --watch          Auto rebuilds themes after change sources.

Get started

More usage cases you can see in examples.

Tool configuration

First, you need to create a config file themekit.config.json at project root:

{
  "entry": {
    "light": "./src/theme/light.theme.json"
  },
  "output": {
    "css": {
      "transforms": ["name/cti/kebab"],
      "buildPath": "./src/theme/themes",
      "files": [
        {
          "destination": "[entry]/[platform]/root.css",
          "format": "css/variables"
        }
      ]
    }
  }
}

A output section based on style-dictionary platforms config.

themekit config interface

{
  /**
   * Map with themes
   */
  entry: Record<string, string>
  /**
   * Map with output formats
   *
   * @see https://amzn.github.io/style-dictionary/#/config?id=configjson
   */
  output: Record<string, {
    /**
     * List of transforms should be applied for each token
     *
     * @see https://amzn.github.io/style-dictionary/#/transforms
     */
    transforms: string[]
    /**
     * A preset that contains the transforms set
     *
     * @see https://amzn.github.io/style-dictionary/#/transform_groups
     */
    transformGroup?: string
    /**
     * Output directory for building results
     */
    buildPath: string
    /**
     * @see https://amzn.github.io/style-dictionary/#/actions
     */
    actions: string[]
    /**
     * List of files to get at the output
     */
    files: Array<{
      /**
       * Output filepath, also supports helper placeholders:
       * [entry] — theme name
       * [platform] — platform name
       */
      destination: string
      /**
       * Output format
       *
       * @see https://amzn.github.io/style-dictionary/#/formats
       */
      format: string
      /**
       * Filter applied for each tokens
       */
      filter: any
    }>
  }>
}

Theme configuration

The basic theme configuration consists of the sources section, which lists which tokens should include to this theme (you can specify the full path or glob).

{
  "sources": [
    "./src/theme/tokens/typography.tokens.yml",
    "./src/theme/tokens/color-light.tokens.yml",
    "./src/components/**/*.tokens.yml"
  ]
}

theme config interface

{
  /**
   * Extendable theme
   */
  extends?: string
  /**
   * Platforms that should be included in the theme (default common)
   */
  platforms?: Array<'common' | 'deskpad' | 'desktop' | 'touch' | 'touch-pad' | 'touch-phone'>
  /**
   * Whitepaper selectors (only for css)
   */
  whitepaper?: Record<string, string>
  /**
   * Mappers list
   */
  mappers?: string[]
  /**
   * Sources list
   */
  sources: string[]
}

Tokens

Tokens can include additional properties such as comment or group for documentation or meta information for processing, also can be used as aliases, see more at style-dictionary properties.

A themekit support write tokens in json or yaml format:

yaml

component:
  type:
    base:
      fillColor:
        value: '#000'
      typoColor:
        value: '#fff'
    danger:
      fillColor:
        value: '#f00'
      typoColor:
        value: '#fff'

json

{
  "component": {
    "type": {
      "base": {
        "fillColor": {
          "value": "#000"
        },
        "typoColor": {
          "value": "#fff"
        }
      },
      "danger": {
        "fillColor": {
          "value": "#f00"
        },
        "typoColor": {
          "value": "#fff"
        }
      }
    }
  }
}

token interface

{
  /**
   * Token value
   */
  value: string
  /**
   * Token group
   */
  group?: string
  /**
   * Token comment
   */
  comment?: string
}

Additional features

💻 Platforms

A themekit supports platforms allows you to collect tokens for a specific platform such as desktop or touch, by default tokens included only from common platform.

Each platform contains a several levels:

theme config

Platform should be written in file name after @ symbol (exclude common level).

{
  "platforms": ["desktop", "touch"],
  "sources": [
    "./tokens/project.tokens.yml",
    "./tokens/project@desktop.tokens.yml",
    "./tokens/project@touch.tokens.yml"
  ]
}

🌈 Color processing

A themekit supports modifying colors for token values. Available next modifiers:

• h — change hue
• s — change saturation
• l — change lightness
• a — change alpha channel

tool config

Need define process-color for output actions:

{
  "output": {
    "css": {
      "actions": ["process-color"]
    }
  }
}

tokens

Just use a necessary modifier for your color:

component:
  type:
    base:
      fillColor:
        value: 'color(#000 a(80%))'

result

At result you get plain value with color:

:root {
  --component-type-base-fill-color: rgba(0, 0, 0, 0.8);
}

Formats

🗂 css/whitepaper

A themekit supports separation of the tokens into multiple result files.

tool config

At themekit config you should define for output files css/whitepaper format and whitepaper/[color|root] filter:

{
  "output": {
    "css": {
      "transforms": ["name/cti/kebab"],
      "buildPath": "./src/theme/themes",
      "files": [
        {
          "destination": "[entry]/[platform]/color.css",
          "format": "css/whitepaper",
          "filter": "whitepaper/color",
          "options": {
            // default: false
            "useAliasVariables": true
          }
        },
        {
          "destination": "[entry]/[platform]/root.css",
          "format": "css/whitepaper",
          "filter": "whitepaper/root",
          "options": {
            // default: false
            "useAliasVariables": true
          }
        }
      ]
    }
  }
}

theme config

At theme config you should define whitepaper for css selectors:

{
  "whitepaper": {
    "color": "default-[platform]",
    "root": "default-[platform]"
  }
}

🗂 css/variables

tool config

{
  "output": {
    "css": {
      "transforms": ["name/cti/kebab"],
      "buildPath": "./src/theme/themes",
      "files": [
        {
          "destination": "[entry]/[platform]/root.css",
          "format": "css/variables",
          "options": {
            // default: ":root"
            "selector": ".MyTheme",
            // default: false
            "useAliasVariables": true
          }
        }
      ]
    }
  }
}

License

MPL-2.0