Skip to content

Commit

Permalink
chore(docs): v3 docs update (#617)
Browse files Browse the repository at this point in the history 
Fixes #571 #159 #605
* Renamed "style properties" to "design tokens"
    * Adding tokens and allTokens to the core internal data structure to be consistent with this change. This is purely additional, properties and allProperties still exist and this should not break existing code. Moving forward examples should use tokens rather than properties.
    * properties.md -> tokens.md
    * Adding more content in this doc page about:
        * All potential attributes #605
        * Default attributes Style Dictionary adds
        * More info on what categories the CTI currently supports #571
        * Information on file formats for token files, including JS modules #159, and custom parsers for token files
* Updated broken links (linking to "master" branch instead of "main")
* Updated the examples page with all new examples
* Added a page on custom parsers
* Added information about transitive transforms
* Removed "docs/build_process.md" in favor of "docs/architecture.md" because the content was mostly the same.
* Cleaned up configuration content
    * Updated language around config file formats and how to define the configuration
    * Added information about configuration attributes and separated it out into sections: top-level config attributes including customization, platform attributes, and file attributes, for readability
* Cleaning up some spacing and headers in markdown files
  • Loading branch information
@dbanksdesign
dbanksdesign authored May 12, 2021
1 parent 35de14c commit 048bbab
Show file tree
Hide file tree
Showing 179 changed files with 2,224 additions and 969 deletions.
6 changes: 3 additions & 3 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ We use npm as our package manager. After downloading the repo, please use the co
We use ESLint on the code to ensure a consistent style. Any new code committed must pass our ESLint tests. Take a look at our [ESLint file][eslint].

### Code Rules
1. **Do not mutate property names or values in a format.** Mutations like this should happen in a transformer.
1. **Do not mutate token names or values in a format.** Mutations like this should happen in a transformer.
1. **Be as generic as possible.** Do not hard-code any values or configuration in formats.
1. **Fail loudly.** Users should be aware if something is missing or configurations aren't correct. This will help debug any issues instead of failing silently.
1. **Rely on few dependencies.** This framework is meant to be extended and allows for customization. We don't want to bring a slew of dependencies that most people don't need.
Expand Down Expand Up @@ -82,6 +82,6 @@ We use [docsify](https://docsify.js.org/#/) to transform the markdown files into

[issues]: https://github.com/amzn/style-dictionary/issues
[pr]: https://github.com/amzn/style-dictionary/pulls
[license]: https://github.com/amzn/style-dictionary/blob/master/LICENSE
[license]: https://github.com/amzn/style-dictionary/blob/main/LICENSE
[cla]: http://en.wikipedia.org/wiki/Contributor_License_Agreement
[eslint]: https://github.com/amzn/style-dictionary/blob/master/.eslintrc.json
[eslint]: https://github.com/amzn/style-dictionary/blob/main/.eslintrc.json
58 changes: 33 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,16 @@

[![npm version](https://img.shields.io/npm/v/style-dictionary.svg?style=flat-square)](https://badge.fury.io/js/style-dictionary)
![license](https://img.shields.io/npm/l/style-dictionary.svg?style=flat-square)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/amzn/style-dictionary/blob/master/CONTRIBUTING.md#submitting-pull-requests)
<br/>
[![Build Status](https://img.shields.io/travis/amzn/style-dictionary.svg?style=flat-square)](https://travis-ci.org/amzn/style-dictionary)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/amzn/style-dictionary/blob/main/CONTRIBUTING.md#submitting-pull-requests)
[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/amzn/style-dictionary/Test?style=flat-square)](https://github.com/amzn/style-dictionary/actions/workflows/test.yml)
[![downloads](https://img.shields.io/npm/dm/style-dictionary.svg?style=flat-square)](https://www.npmjs.com/package/style-dictionary)

# Style Dictionary
> *Style once, use everywhere.*
A Style Dictionary uses design tokens to define styles once and use those styles on any platform or language. It provides a single place to create and edit your styles, and exports these properties to all the places you need - iOS, Android, CSS, JS, HTML, sketch files, style documentation, etc. It is available as a CLI through npm, but can also be used like any normal node module if you want to extend its functionality.
A Style Dictionary uses design tokens to define styles once and use those styles on any platform or language. It provides a single place to create and edit your styles, and exports these tokens to all the places you need - iOS, Android, CSS, JS, HTML, sketch files, style documentation, etc. It is available as a CLI through npm, but can also be used like any normal node module if you want to extend its functionality.

When you are managing user experiences, it can be quite challenging to keep styles consistent and synchronized across multiple development platforms and devices. At the same time, designers, developers, PMs and others must be able to have consistent and up-to-date style documentation to enable effective work and communication. Even then, mistakes inevitably happen and the design may not be implemented accurately. StyleDictionary solves this by automatically generating style definitions across all platforms from a single source - removing roadblocks, errors, and inefficiencies across your workflow.
When you are managing user experiences, it can be quite challenging to keep styles consistent and synchronized across multiple development platforms and devices. At the same time, designers, developers, PMs and others must be able to have consistent and up-to-date style documentation to enable effective work and communication. Even then, mistakes inevitably happen and the design may not be implemented accurately. Style Dictionary solves this by automatically generating style definitions across all platforms from a single source - removing roadblocks, errors, and inefficiencies across your workflow.

For detailed usage head to https://amzn.github.io/style-dictionary

Expand All @@ -24,7 +23,7 @@ For detailed usage head to https://amzn.github.io/style-dictionary
* [Usage](#usage)
* [Example](#example)
* [Quick Start](#quick-start)
* [Style Properties](#style-properties)
* [Design Tokens](#design-tokens)
* [Extending](#extending)
* [Contributing](#contributing)
* [License](#license)
Expand Down Expand Up @@ -73,7 +72,7 @@ StyleDictionary.buildAllPlatforms();
The `.extend()` method is an overloaded method that can also take an object with the configuration in the same format as a config.json file.
```javascript
const StyleDictionary = require('style-dictionary').extend({
source: ['properties/**/*.json'],
source: ['tokens/**/*.json'],
platforms: {
scss: {
transformGroup: 'scss',
Expand All @@ -93,10 +92,11 @@ StyleDictionary.buildAllPlatforms();
## Example
[Take a look at some of our examples](examples/)

A style dictionary is a collection of style properties, key/value pairs that describe stylistic attributes like colors, sizes, icons, motion, etc. A style dictionary defines these style properties in JSON files, and can also include static assets like images and fonts. Here is a basic example of what the package structure can look like:
A style dictionary is a collection of design tokens, key/value pairs that describe stylistic attributes like colors, sizes, icons, motion, etc. A style dictionary defines these design tokens in JSON or Javascript files, and can also include static assets like images and fonts. Here is a basic example of what the package structure can look like:

```
├── config.json
├── properties/
├── tokens/
│ ├── size/
│ ├── font.json
│ ├── color/
Expand All @@ -108,10 +108,11 @@ A style dictionary is a collection of style properties, key/value pairs that des
```

### config.json
This tells the style dictionary build system how and what to build. The default file path is config.json in the root of the project, but you can name it whatever you want, you can pass in the `--config` flag.
This tells the style dictionary build system how and what to build. The default file path is `config.json` or `config.js` in the root of the project, but you can name it whatever you want by passing in the `--config` flag to the [CLI](https://amzn.github.io/style-dictionary/#/using_the_cli).

```json
{
"source": ["properties/**/*.json"],
"source": ["tokens/**/*.json"],
"platforms": {
"scss": {
"transformGroup": "scss",
Expand All @@ -132,21 +133,23 @@ This tells the style dictionary build system how and what to build. The default
}
}
```

| Attribute | Type | Description |
| :--- | :--- | :--- |
| source | Array | Paths to the property json files. Can have globs. |
| source | Array | An array of file path [globs](https://github.com/isaacs/node-glob) to design token files. Style Dictionary will do a deep merge of all of the token files, allowing you to organize your files files however you want. |
| include | Array | An array of file path [globs](https://github.com/isaacs/node-glob) to design token files that contain default styles. The Style Dictionary uses this as a base collection of tokens. The tokens found using the "source" attribute will overwrite tokens found using include. |
| platforms | Object | Sets of platform files to be built. |
| platforms | Array | Paths to the property json files. Can have globs. |
| platform.transformGroup | String (optional) | Apply a group of transforms to the properties, must either define this or `transforms`. |
| platform.transforms | Array (optional) | Transforms to apply sequentially to all properties. Can be a built-in one or you can create your own. |
| platform.transformGroup | String (optional) | Apply a group of transforms to the tokens, must either define this or `transforms`. |
| platform.transforms | Array (optional) | Transforms to apply sequentially to all tokens. Can be a built-in one or you can create your own. |
| platform.buildPath | String (optional) | Base path to build the files, must end with a trailing slash. |
| platform.files | Array (optional) | Files to be generated for this platform. |
| platform.file.destination | String (optional) | Location to build the file, will be appended to the buildPath. |
| platform.file.format | String (optional) | Format used to generate the file. Can be a built-in one or you can create your own. [More on formats](https://amzn.github.io/style-dictionary/#/formats) |
| platform.file.options | Object (optional) | A set of extra options associated with the file. |
| platform.file.options.showFileHeader | Boolean | If the generated file should have a "Do not edit + Timestamp" header (where the format supports it). By default is "true". |

### Properties
### Design Tokens

```json
{
"size": {
Expand All @@ -160,7 +163,7 @@ This tells the style dictionary build system how and what to build. The default
}
```

Here we are creating some basic font size properties. The style definition size.font.small.value is "10px" for example. The style definition size.font.base.value is automatically aliased to the value found in size.font.medium.value and both of those resolve to "16px".
Here we are creating some basic font size design tokens. The style definition size.font.small.value is "10px" for example. The style definition size.font.base.value is automatically aliased to the value found in size.font.medium.value and both of those resolve to "16px".

Now what the style dictionary build system will do with this information is convert it to different formats, enabling these values to be used in any type of codebase. From this one file you can generate any number of files like:

Expand All @@ -187,16 +190,21 @@ float const SizeFontBase = 16.00f;


## Quick Start

The style dictionary framework comes with some example code to get you stared. Install the node module globally, create a directory and `cd` into it.

```
$ npm i -g style-dictionary
$ mkdir MyStyleDictionary
$ cd MyStyleDictionary
```

Now run:

```
$ style-dictionary init basic
```

This command will copy over the example files found in [example](examples/) in this repo. Now you have an example project set up. You can make changes to the style dictionary and rebuild the project by running:

```
Expand All @@ -206,13 +214,13 @@ $ style-dictionary build
Take a look at the documentation for the example code.


## Style Properties
## Design Tokens

A style property is an attribute to describe something visually. It is atomic (it cannot be broken down further). Style properties have a name, a value, and optional attributes or metadata. The name of a property can be anything, but we have a proposed naming structure that works really well in the next section.
A design token is an attribute to describe something visually. It is atomic (it cannot be broken down further). Design tokens have a name, a value, and optional attributes or metadata. The name of a token can be anything, but we have a proposed naming structure that we find works really well in the next section.

### Category/Type/Item Structure

While not exactly necessary, we feel this classification structure of style properties makes the most sense semantically. Style properties can be organized into a hierarchical tree structure with the top level, category, defining the primitive nature of the property. For example, we have the color category and every property underneath is always a color. As you proceed down the tree to type, item, sub-item, and state, you get more specific about what that color is. Is it a background color, a text color, or a border color? What kind of text color is it? You get the point. Now you can structure your property json files like simple objects:
While not exactly necessary, we feel this classification structure of design tokens makes the most sense semantically. Design tokens can be organized into a hierarchical tree structure with the top level, category, defining the primitive nature of the token. For example, we have the color category and every token underneath is always a color. As you proceed down the tree to type, item, sub-item, and state, you get more specific about what that color is. Is it a background color, a text color, or a border color? What kind of text color is it? You get the point. Now you can structure your token json files like simple objects:

```
{
Expand All @@ -225,15 +233,15 @@ While not exactly necessary, we feel this classification structure of style prop
}
```

The CTI is implicit in the structure, the category and type is 'size' and 'font', and there are 2 properties 'base' and 'large'.
The CTI is implicit in the structure, the category and type is 'size' and 'font', and there are 2 tokens 'base' and 'large'.

Structuring style properties in this manner gives us consistent naming and accessing of these properties. You don't need to remember if it is button_color_error or error_button_color, it is color_background_button_error!
Structuring design tokens in this manner gives us consistent naming and accessing of these tokens. You don't need to remember if it is button_color_error or error_button_color, it is color_background_button_error!

You can organize and name your style properties however you want, there are no restrictions. But we have a good amount of helpers if you do use this structure, like the 'attribute/cti' transform which adds attributes to the property of its CTI based on the path in the object. There are a lot of name transforms as well for when you want a flat structure like for Sass variables.
You can organize and name your design tokens however you want, there are no restrictions. But we have a good amount of helpers if you do use this structure, like the 'attribute/cti' transform which adds attributes to the token of its CTI based on the path in the object. There are a lot of name transforms as well for when you want a flat structure like for Sass variables.

Also, the CTI structure provides a good mechanism to target transforms for specific kinds of properties. All of the transforms provided by the framework use the CTI of a property to know if it should be applied. For instance, the 'color/hex' transform only applies to properties of the category 'color'.
Also, the CTI structure provides a good mechanism to target transforms for specific kinds of tokens. All of the transforms provided by the framework use the CTI of a token to know if it should be applied. For instance, the 'color/hex' transform only applies to tokens of the category 'color'.

You can also add a _comment_ to a style property:
You can also add a _comment_ to a design token:

```
{
Expand Down
Loading

0 comments on commit 048bbab

Please sign in to comment.