@yandex/themekit
Build system of design-tokens for any platforms.
Last updated 10 days ago by yarastqt .
MPL-2.0 · Original npm · Tarball · package.json
$ cnpm install @yandex/themekit 
SYNC missed versions from official npm registry.

@yandex/themekit

Themkit is a build system for design-tokens on any platform. This system is based on redefinition levels, which allows you to describe platform-specific values in a single place. 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.

Contents

Features

  • ???? 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 each platforms, for example desktop and touch.
  • ???? Supports typescript extension with type checking.
  • ????️ Available extends for new formats or transformations.

Installation

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

Getting start

You can use Themekit as cli or node api.

cli

Builds tokens for configured formats:

themekit build

Call this in the root directory of your project. The only thing needed is a themekit.config.js file. There are also arguments:

Flag Description
--config -c [path] The path to a themekit config file.
--help Show help with usage.
--version Show current package version.

node

Coming soon.

Configuration

type Config = {
  src: string
  platforms?: 'common' | 'deskpad' | 'desktop' | 'touch' | 'touch-pad' | 'touch-phone'
  formats: {
    [key: string]: {
      outDir: string
      fileName?: string
      transforms: string[]
    }
  }
}

You can add your own formats, platforms and transforms, see more at extending section.

platforms

Each platform contains one or more levels, and tokens declared on these levels will be combined in this specified order.

Default set of available platforms:

platform levels
common common
deskpad common, deskpad
desktop common, deskpad, desktop
touch common, touch
touch-pad common, deskpad, touch, touch-pad
touch-phone common, touch, touch-phone

formats

Formats are responsible for the type and content of files.

css.whitepaper

Coming soon.

json.whitepaper

Coming soon.

css.flat

Coming soon.

js.esm

Coming soon.

transforms

Transforms are responsible for changing tokens' names and values. It depends on the type.

name.param

Convert token name to param-case for usage at css or json, example:

# input
button_space_all: '20px'
# output
button-space-all: '20px'

name.const

Convert token name to CONST_CASE for usage at js, example:

# input
button_space_all: '20px'
# output
BUTTON_SPACE_ALL: '20px'

color.hex

Convert color to hex format or use rgba scheme, you can also process color by hsl scheme, for example:

# input
button_bg_color: 'color(#04b h(+22) s(-80%) l(+13%))'
# output
button_bg_color: 'rgb(102, 102, 153)'

Example

More examples you can see in examples.

Consider case with css.whitepaper format:

prepare fs

It doesn't matter where you put your files on the fs. Here is our example of how we do it:

├── themekit.config.js
└── src
    └── themes
        └── tokens
            ├── capacity.tokens.ts
            ├── color.tokens.ts
            ├── cosmetic.tokens.ts
            ├── size.tokens.ts
            └── space.tokens.ts

themekit.config.js

Add base config with css.whitepaper format and css.name and color.nex transforms:

/**
 * @type {import('@yandex/themekit/lib/core/config').Config}
 */
module.exports = {
  src: ['./src/themes/tokens/*.tokens.ts'],
  platforms: ['desktop'],
  formats: {
    'css.whitepaper': {
      outDir: './src/themes',
      transforms: ['name.param', 'color.hex'],
    },
  },
}

theme tokens

Add tokens for two platforms common and desktop, we also need to add meta section for define result CSS selector:

// src/themes/tokens/space.tokens.ts
import { withTokens } from '@yandex/themekit'

export const tokens = {
  space_m: '20px',
}

export type Tokens = typeof tokens

export default withTokens<Tokens>(($tokens) => ({
  common: {
    input_space_all: $tokens.space_m,
  },
  desktop: {
    meta: { css: '.Theme_space_desktop' },
    button_space_all: $tokens.space_m,
  },
}))(tokens)

result

Here is the result:

├── themekit.config.js
└── src
    └── themes
        ├── space.tokens
        │   └── desktop
        │       └── index.css
        └── tokens
            └── space.tokens.ts

and file with styles:

/* src/themes/space.tokens/desktop/index.css */
.Theme_space_desktop {
  --input-space-all: 20px;
  --button-space-all: 20px;
}

Tokens

interface

A token may full or short record, and may be nested:

type Primitive = string | number
type TokenType = 'color' | 'size' | 'unknown'

type Token = {
  value: Primitive
  type: TokenType
  comment?: string
}

type TokensMap = {
  [key: string]: TokensMap | Token | Primitive
}

full:

button_space_all: {
  value: '20px',
  type: 'size',
  comment: 'Space inside button',
},

short:

button_space_all: '20px',

nested:

button: {
  space: {
      all: '20px',
    },
  },
},

platforms

Coming soon.

extends & overrides

Coming soon.

Extending

Coming soon.

License

MPL-2.0

Current Tags

  • 0.0.0-alpha.4                                ...           latest (10 days ago)

5 Versions

  • 0.0.0-alpha.4                                ...           10 days ago
  • 0.0.0-alpha.3                                ...           18 days ago
  • 0.0.0-alpha.2                                ...           a month ago
  • 0.0.0-alpha.1                                ...           a month ago
  • 0.0.0-alpha.0                                ...           a month ago
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 37
Dependencies (11)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |