Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bem/themekit
Build system of design-tokens for any platforms
https://github.com/bem/themekit
build-system design-system design-tokens design-tool style-dictionary style-tokens
Last synced: 3 months ago
JSON representation
Build system of design-tokens for any platforms
- Host: GitHub
- URL: https://github.com/bem/themekit
- Owner: bem
- License: other
- Created: 2020-04-21T14:44:44.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2022-12-11T11:58:33.000Z (about 2 years ago)
- Last Synced: 2024-10-29T22:58:26.359Z (3 months ago)
- Topics: build-system, design-system, design-tokens, design-tool, style-dictionary, style-tokens
- Language: TypeScript
- Homepage:
- Size: 1.01 MB
- Stars: 74
- Watchers: 23
- Forks: 11
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/bem/themekit)
[][npm] [][examples] [][node]
Themkit is a build system for design-tokens for any platform. This system is based on [style-dictionary](sd-github) API and [redefinition levels](#-platforms), 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
```sh
# via npm
npm i -DE @yandex/themekit
# or yarn
yarn add --dev @yandex/themekit
```
## Usage
A themekit is available as a CLI tool.
### `build`
```sh
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][examples].
### Tool configuration
First, you need to create a config file `themekit.config.json` at project root:
```json
{
"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](https://amzn.github.io/style-dictionary/#/config?id=configjson) config.
#### themekit config interface
```ts
{
/**
* Map with themes
*/
entry: Record
/**
* Map with output formats
*
* @see https://amzn.github.io/style-dictionary/#/config?id=configjson
*/
output: Record
}>
}
```
### 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).
```json
{
"sources": [
"./src/theme/tokens/typography.tokens.yml",
"./src/theme/tokens/color-light.tokens.yml",
"./src/components/**/*.tokens.yml"
]
}
```
#### theme config interface
```ts
{
/**
* Extendable theme
*/
extends?: string
/**
* Platforms that should be included in the theme (default common)
*/
platforms?: Array<'common' | 'deskpad' | 'desktop' | 'touch' | 'touch-pad' | 'touch-phone'>
/**
* 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](https://amzn.github.io/style-dictionary/#/properties).
A themekit support write tokens in `json` or `yaml` format:
#### yaml
```yml
component:
type:
base:
fillColor:
value: '#000'
typoColor:
value: '#fff'
danger:
fillColor:
value: '#f00'
typoColor:
value: '#fff'
```
#### json
```json
{
"component": {
"type": {
"base": {
"fillColor": {
"value": "#000"
},
"typoColor": {
"value": "#fff"
}
},
"danger": {
"fillColor": {
"value": "#f00"
},
"typoColor": {
"value": "#fff"
}
}
}
}
}
```
#### token interface
```ts
{
/**
* 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:
| platforms | 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 |
#### theme config
Platform should be written in file name after `@` symbol (exclude `common` level).
```json
{
"platforms": ["desktop", "touch"],
"sources": [
"./tokens/project.tokens.yml",
"./tokens/[email protected]",
"./tokens/[email protected]"
]
}
```
### 🌈 Color processing
A themekit supports [modifying colors](https://github.com/ianstormtaylor/css-color-function) 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:
```json
{
"output": {
"css": {
"actions": ["process-color"]
}
}
}
```
#### tokens
Just use a necessary modifier for your color:
```yml
component:
type:
base:
fillColor:
value: 'color(#000 a(80%))'
```
#### result
At result you get plain value with color:
```css
:root {
--component-type-base-fill-color: rgba(0, 0, 0, 0.8);
}
```
## Formats
### 🗂 css/variables
#### tool config
```json
{
"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][license]
[node]: https://nodejs.org/en/
[npm]: https://www.npmjs.com/package/@yandex/themekit
[license]: https://github.com/bem/themekit/blob/master/LICENSE.md
[examples]: https://github.com/bem/themekit/tree/master/examples
[sd-github]: https://github.com/amzn/style-dictionary