Documentation update #103
Documentation update #103
Conversation
|
Sorry for the lateness on this. I'll review tomorrow |
docs/config.md
Outdated
|
|
||
| Style dictionaries are configuration driven. Your config file defines what executes and what to output when the style dictionary builds. | ||
|
|
||
| The default is to use a config.json file in the root of your package, but you can also specify a custom location when you use the [`CLI`](how_to_build#cli) or when creating a [`custom build system`](how_to_build#cli). | ||
| By default, Style Dictionary looks for a config.json file in the root of your package. You can also specify a custom location when you use the [CLI](how_to_build#cli). If you are using a [custom build system](how_to_build#custom-build-system), you can specify a custom location for a configuration file or use an inline configuration JSON object. |
There was a problem hiding this comment.
Maybe change "or use an inline configuration JSON object" to "or use a plain Javascript object"
|
|
||
| 1. When you call the [`extend`](api.md#extend) method, you can either pass it a path to a JSON config file, or give it a plain object that has the configuration. This will perform steps 1-3 above. | ||
| 1. When you call the [extend](api.md#extend) method, you can either pass it a path to a JSON config file, or give it a plain object that has the configuration. This will perform steps 1-3 above. |
There was a problem hiding this comment.
With #114 we should change anything saying "JSON config" to "JSON or javascript config file". Actually, elliot's PR includes this change right here :) So maybe lets wait until we merge is PR and then sync this branch.
| @@ -195,7 +195,7 @@ const StyleDictionary = require('style-dictionary').extend('config.json'); | |||
| 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. | |||
| The `.extend()` method is an overloaded method that can also take a [configuration](config) object. | |||
There was a problem hiding this comment.
I don't think this is a valid link in markdown.
docs/README.md
Outdated
| @@ -19,9 +19,11 @@ When you are managing user experiences, it can be quite challenging to keep styl | |||
| __A style dictionary consists of:__ | |||
| 1. [Style properties](#style-properties) organized in JSON files | |||
| 1. Static assets that can be used across platforms | |||
| 1. A configuration that defines how to modify and manipulate those properties and assets into deliverables | |||
|
|
||
| This is how Style Dictionary works under the hood. | ||
|
|
||
| ## TODO |
There was a problem hiding this comment.
I'll take a crack at it this week.
docs/properties.md
Outdated
| @@ -0,0 +1,123 @@ | |||
| # Definitions and Properties | |||
There was a problem hiding this comment.
We should have the h1 be the same as the URL/link label in the sidebar.
docs/properties.md
Outdated
| @@ -0,0 +1,123 @@ | |||
| # Definitions and Properties | |||
|
|
|||
| Properties are specific style information that you want to use in your deliverables. From a programmatic point of view, the property of size.font.small is an object containing multiple attributes, with each attribute providing specific information about size.font.small. | |||
There was a problem hiding this comment.
We should talk about "design tokens" as that is the term a lot of people are familiar with. Also it is a bit confusing to say "the property of size.font.small" without first having that example in code.
There was a problem hiding this comment.
@dbanksdesign @chazzmoney Plus one for "design tokens". *
- I think that as maintainers/contributors we should have a "dictionary" somewhere (pun intended :) with what we should call when we write documentation and readme/examples for "design token", "property", "attribute" and "value". Personally, that's the mental schema that I tend to use:
(the reason why a property is not a design token, is that a property may not necessarily be present in the output. for example I use some properties only as pure aliases, pointers to values, and they are never converted to actual design tokens).
|
|
||
| Properties are specific style information that you want to use in your deliverables. From a programmatic point of view, the property of size.font.small is an object containing multiple attributes, with each attribute providing specific information about size.font.small. | ||
|
|
||
| Attributes are the key/object pairs in a definition. The most important (and only required) attribute is "value", which provides the data that will be used throughout the build process (and ultimately used for styling in your deliverables). You can include any custom attributes you would like (e.g. "comment" with a string or "metadata" as an object with its own attributes). |
There was a problem hiding this comment.
This paragraph is confusing because we use an 'attributes' object on style properties to hold additional information about the property.
docs/properties.md
Outdated
| } | ||
| ``` | ||
|
|
||
| Any property which is a string is a shorthand for that property having a value of that string. E.g this |
There was a problem hiding this comment.
This wouldn't work in Style Dictionary today
| } | ||
| ``` | ||
|
|
||
| You can reference (alias) Attributes by wrapping the reference chain in brackets |
There was a problem hiding this comment.
We should probably just say you can reference any part of a style dictionary with the reference/alias syntax.
|
Created #198 to replace this. |
Updating documentation to match expected changes for the next major release as well as make things a bit more clear.
We should make sure that we get everything we need in #49 as well.
This is NOT ready to be merged. I specifically want feedback. It also contains TODOs on the Architecture page that Danny and I need to work through together.