From 3d0d1c0356d42fc83f905a7e7e4b1c662c77de0b Mon Sep 17 00:00:00 2001 From: Manish Acharya Date: Thu, 24 Oct 2019 22:23:57 +0545 Subject: [PATCH] docs: remove bad words from the documentation (#332) Replaced following words with other relevant words so that gist of the sentence won't differ that much, from all the documentation within the project. Words include: just, simply, clearly, of course, easy, so, basically, technically, very, in order to, everyone knows. Also, some of the grammatical improvement has been checked and corrected. related to #328 --- .jsdoc.json | 2 +- CONTRIBUTING.md | 4 ++-- README.md | 12 ++++++------ docs/README.md | 2 +- docs/api.md | 8 ++++---- docs/architecture.md | 2 +- docs/config.md | 4 ++-- docs/extending.md | 2 +- docs/formats.md | 10 +++++----- docs/properties.md | 12 ++++++------ docs/quick_start.md | 6 +++--- docs/transforms.md | 6 +++--- docs/using_the_npm_module.md | 2 +- examples/advanced/auto-rebuild-watcher/README.md | 4 ++-- examples/advanced/component-cti/README.md | 6 +++--- examples/advanced/create-react-app/README.md | 6 +++--- .../advanced/create-react-app/src/serviceWorker.js | 2 +- .../custom-formats-with-templates/README.md | 8 ++++---- .../advanced/custom-formats-with-templates/build.js | 2 +- examples/advanced/custom-transforms/README.md | 8 ++++---- examples/advanced/custom-transforms/build.js | 10 +++++----- .../advanced/multi-brand-multi-platform/README.md | 2 +- .../node-modules-as-config-and-properties/README.md | 2 +- .../node-modules-as-config-and-properties/config.js | 13 ++++++------- examples/advanced/referencing_aliasing/README.md | 6 +++--- examples/advanced/s3/README.md | 4 ++-- examples/basic/README.md | 4 ++-- .../amazon/styledictionaryexample/BaseActivity.java | 2 +- .../amazon/styledictionaryexample/ColorAdapter.java | 4 ++-- .../property/PropertiesActivity.java | 2 +- .../android/demo/src/main/res/values/strings.xml | 4 ++-- ...s-StyleDictionary_Demo-acknowledgements.markdown | 2 +- ...Pods-StyleDictionary_Demo-acknowledgements.plist | 2 +- .../Pods-StyleDictionary_Demo-frameworks.sh | 4 ++-- examples/complete/ios/README.md | 2 +- index.js | 2 +- lib/common/formats.js | 12 ++++++------ lib/common/templates/ios-swift/class.swift.template | 4 ++-- lib/common/templates/ios-swift/enum.swift.template | 4 ++-- lib/common/transforms.js | 8 ++++---- lib/extend.js | 2 +- lib/filterProperties.js | 9 ++++----- lib/register/action.js | 6 +++--- lib/register/transform.js | 4 ++-- lib/transform/config.js | 2 +- lib/transform/object.js | 4 ++-- lib/transform/propertySetup.js | 6 +++--- lib/utils/flattenProperties.js | 2 +- lib/utils/resolveObject.js | 10 +++++----- scripts/handlebars/templates/formats.hbs | 6 +++--- scripts/handlebars/templates/transforms.hbs | 4 ++-- scripts/version.js | 2 +- 52 files changed, 128 insertions(+), 130 deletions(-) diff --git a/.jsdoc.json b/.jsdoc.json index eb2d99645..c245201b0 100644 --- a/.jsdoc.json +++ b/.jsdoc.json @@ -1,3 +1,3 @@ { "plugins": ["./node_modules/jsdoc-escape-at"] -} \ No newline at end of file +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0974fc995..ef1293cd8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,7 @@ We use ESLint on the code to ensure a consistent style. Any new code committed m ### Commit Rules We follow [conventional commits'](https://www.conventionalcommits.org/en/v1.0.0-beta.2/#specification) specification. -Please follow the spec in order to have a successful commit. +Please follow the spec to have a successful commit. ## What should be included? @@ -50,7 +50,7 @@ Anything that contributes to the idea of creating cross-platform styles. ### What transforms/transform groups/formats should be included? -If it has a generic and flexible enough use-case, it can be included. We would like to keep this type of code to a minimum because we don't want to be a swiss army knife that does everything out of the box. Instead, we want to focus on core tasks that are useful to the largest number of projects. The spirit of this framework is to allow flexibility and modularity so that anyone can fit it to their needs. This is why you can write your own transforms, and formats with the register methods. +If it has a generic and flexible enough use-case, it can be included. We would like to keep this type of code to a minimum because we don't want to be a swiss army knife that does everything out of the box. Instead, we want to focus on core tasks that are useful to the largest number of projects. The spirit of this framework is to allow flexibility and modularity which helps anyone fit it to their needs. This is why you can write your own transforms, and formats with the register methods. ### Where do things go? diff --git a/README.md b/README.md index 77eb6576a..265753633 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ If you want to use the CLI, you can install it globally via npm: $ npm install -g style-dictionary ``` -Or you can install it like a normal npm dependency. This is a build tool so you are most likely going to want to save it as a dev dependency: +Or you can install it like a normal npm dependency. This is a build tool and you are most likely going to want to save it as a dev dependency: ```bash $ npm install -D style-dictionary ``` @@ -108,7 +108,7 @@ 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, just pass in the `--config` flag. +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. ```json { "source": ["properties/**/*.json"], @@ -160,9 +160,9 @@ 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, so both of those resolve to "16px". +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". -Now what the style dictionary build system will do with this information is convert it to different formats so that you can use these values in any type of codebase. From this one file you can generate any number of files like: +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: ```scss $size-font-small: 10px; @@ -229,7 +229,7 @@ While not exactly necessary, we feel this classification structure of style prop 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! - Technically, 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 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. 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'. @@ -257,7 +257,7 @@ The comment will appear in the output files, where relevant or the output forma ## Extending -The style dictionary build system is made to be extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why it is easy to create custom transforms and formats. +The style dictionary build system is made to be extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why you can create custom transforms and formats. ```javascript const StyleDictionary = require('style-dictionary').extend('config.json'); diff --git a/docs/README.md b/docs/README.md index 54f22dbd2..8ec130d96 100644 --- a/docs/README.md +++ b/docs/README.md @@ -39,7 +39,7 @@ __Things you can build with a style dictionary:__ **The value of using Style Dictionary to build all of these is that they are all consistent and up to date.** -The Style Dictionary framework is fully extensible and modular so you can create any type of file from a style dictionary. +The Style Dictionary framework is fully extensible and modular. You can create any type of file from a style dictionary. If there is a new language, platform, or file type you need, you can easily [extend](extending.md) the style dictionary framework to create the necessary files. diff --git a/docs/api.md b/docs/api.md index 34efb1528..3929be229 100644 --- a/docs/api.md +++ b/docs/api.md @@ -148,8 +148,8 @@ base64'ing files, running other build scripts, etc. After you register a custom action, you then use that action in a platform your config.json -Actions run after the files in a platform are generated so you -can perform operations on files generated by the style dictionary. +You can perform operations on files generated by the style dictionary +as actions run after these files are generated. Actions are run sequentially, if you write synchronous code then it will block other actions, or if you use asynchronous code like Promises it will not block. @@ -274,9 +274,9 @@ Transforms can manipulate a property's name, value, or attributes | --- | --- | --- | | transform | Object | Transform object | | transform.type | String | Type of transform, can be: name, attribute, or value | -| transform.name | String | Name of the transformer so a transformGroup can call a list of transforms. | +| transform.name | String | Name of the transformer (used by transformGroup to call a list of transforms). | | [transform.matcher] | function | Matcher function, return boolean if transform should be applied. If you omit the matcher function, it will match all properties. | -| transform.transformer | function | Performs a transform on a property object, should return a string or object depending on the type. Will only update certain properties so you can't mess up property objects on accident. | +| transform.transformer | function | Performs a transform on a property object, should return a string or object depending on the type. Will only update certain properties by which you can't mess up property objects on accident. | **Example** ```js diff --git a/docs/architecture.md b/docs/architecture.md index 8d35eb9db..37c7dda10 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -20,7 +20,7 @@ Style Dictionary takes all the files it found and performs a deep merge. This al ## 4. Iterate over the platforms -For each platform defined in your [config](config.md), Style Dictionary will do a few steps to get it ready to be consumed on that platform. Everything that happens in a platform is non-destructive so you don't need to worry about one platform affecting another. +For each platform defined in your [config](config.md), Style Dictionary will do a few steps to get it ready to be consumed on that platform. Everything that happens in a platform is non-destructive; you don't need to worry about one platform affecting another. ## 4a. Transform the tokens diff --git a/docs/config.md b/docs/config.md index 46dc086ed..e99c937ed 100644 --- a/docs/config.md +++ b/docs/config.md @@ -38,9 +38,9 @@ You can find out more about creating configurations in JS in our documentation a | Attribute | Type | Description | | :--- | :--- | :--- | | include | Array[String] (optional) | An array of path [globs](https://github.com/isaacs/node-glob) to Style Dictionary property files that contain default styles. The Style Dictionary uses this as a base collection of properties. The properties found using the "source" attribute will overwrite properties found using include. | -| source | Array[String] | An array of path [globs](https://github.com/isaacs/node-glob) to JSON files that contain style properties. The Style Dictionary will do a deep merge of all of the JSON files so you can separate your properties into multiple files. | +| source | Array[String] | An array of paths that can be [globs](https://github.com/isaacs/node-glob) to JSON files that contain style properties. This allows you to separate your properties into multiple files as Style Dictionary will do a deep merge of all of the JSON files to create the dictionary. | | platforms | Object | An object containing platform config objects that describe how the Style Dictionary should build for that platform. You can add any arbitrary attributes on this object that will get passed to formats and actions (more on these in a bit). This is useful for things like build paths, name prefixes, variable names, etc. | -| platform.transforms | Array[String] (optional) | An array of [transforms](transforms.md) to be performed on the style properties object. These will transform the properties in a non-destructive way so each platform can transform the properties. Transforms to apply sequentially to all properties. Can be a built-in one or you can create your own. | +| platform.transforms | Array[String] (optional) | An array of [transforms](transforms.md) to be performed on the style properties object. These transform the properties in a non-destructive way as each platform can transform the properties in a unique manner. Transforms to apply sequentially to all properties. Can be a built-in one or you can create your own. | | platform.transformGroup | String (optional) | A string that maps to an array of transforms. This makes it easier to reference transforms by grouping them together. You must either define this or [transforms](transforms.md). | | 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. | diff --git a/docs/extending.md b/docs/extending.md index e16adcd1f..83a8c76a5 100644 --- a/docs/extending.md +++ b/docs/extending.md @@ -1,6 +1,6 @@ # Extending -The style dictionary build system is easily extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why we made it easy to create custom transforms and formats. +There is a straightforward way to extend Style Dictionary to meet your needs - since we don't know exactly how everyone will want to use style dictionaries in their project, we created custom transforms and formats as a manner to add your desired functionality. ## Extension Functions in the API * [registerTransform](api.md#registertransform) diff --git a/docs/formats.md b/docs/formats.md index dffc1dffe..6737daa22 100644 --- a/docs/formats.md +++ b/docs/formats.md @@ -33,7 +33,7 @@ There is an extensive (but not exhaustive) list of [included formats](#pre-defin ### Format configuration -Formats can take configuration to make them more flexible. This allows you to re-use the same format multiple times with different configuration or to allow the format to use data not defined in the tokens themselves. To configure a format add extra attributes on the file object in your configuration like so: +Formats can take configuration to make them more flexible. This allows you to re-use the same format multiple times with different configurations or to allow the format to use data not defined in the tokens themselves. To configure a format, add extra attributes on the file object in your configuration like the following: ```json { @@ -73,7 +73,7 @@ A special file configuration is `filter`, which will filter the tokens before th ### Creating formats -You can create custom formats using the [`registerFormat`](api.md#registerformat) function. If you want to add configuration to your custom format, `this` is bound to the file object so you can access attributes on the file object with `this.myCustomAttribute` if the file object looks like: +You can create custom formats using the [`registerFormat`](api.md#registerformat) function. If you want to add configuration to your custom format, `this` is bound to the file object. Using this, you can access attributes on the file object with `this.myCustomAttribute` if the file object looks like: ```json { @@ -86,7 +86,7 @@ You can create custom formats using the [`registerFormat`](api.md#registerformat ### Using a template / templating engine to create a format -A formatter is just a simple function and created easily with most templating engines. Templates are useful if there is a lot of boilerplate code to insert (e.g. ObjectiveC files). If the output consists of just the values (e.g. a flat SCSS variables file), writing a formatter function directly may be easier. +Formatters are functions and created easily with most templating engines. Formats can be built using templates if there is a lot of boilerplate code to insert (e.g. ObjectiveC files). If the output consists of only the values (e.g. a flat SCSS variables file), writing a formatter function directly may be easier. Any templating language can work as there is a node module for it. All you need to do is register a format that calls your template and returns a string. @@ -622,7 +622,7 @@ Creates a JSON file of the style dictionary. ### json/asset -Creates a JSON file of just the assets defined in the style dictionary. +Creates a JSON file of the assets defined in the style dictionary. **Example** ```js @@ -695,7 +695,7 @@ Creates a sketchpalette file of all the base colors Creates a sketchpalette file compatible with version 2 of -the sketchpalette plugin. To use this you should use the +the sketchpalette plugin. To use this you should use the 'color/sketch' transform to get the correct value for the colors. **Example** diff --git a/docs/properties.md b/docs/properties.md index 99bbc5682..81f99b28b 100644 --- a/docs/properties.md +++ b/docs/properties.md @@ -2,15 +2,15 @@ > Synonyms: design tokens, design variables, design constants, atoms -Style properties are stored in a collection of JSON or JS module files. We usually keep them in a `properties` directory, but you can put them wherever you like, they just need to be referenced in the `source` attribute on your `config.json` file. +Style properties are stored in a collection of JSON or JS module files. We usually keep them in a `properties` directory, but you can put them wherever you like, they need to be referenced in the `source` attribute on your `config.json` file. A property is a collection of attributes that describe any fundamental/atomic visual style. Each attribute is a `key:value` pair. A property name and its value are considered a design token (or design variable/constant/atom). ![Terminology for different parts of a JSON property](assets/property-definitions.png) -A property is transformed for use in different platforms, languages, and contexts. A simple example is a color. A color can be represented in many ways, all of these are the same color: `#ffffff`, `rgb(255,255,255)`, `hsl(0,0,1)`. +A property is transformed for use in different platforms, languages, and contexts. A simple example is color. A color can be represented in many ways, all of these are the same color: `#ffffff`, `rgb(255,255,255)`, `hsl(0,0,1)`. -A property file organizes properties in a structured way for easy access. Property files are organized as a deep object with the leaf nodes being the style key:value pairs. +A property file organizes properties in a structured way for quick access. Property files are organized as a deep object with the leaf nodes being the style key:value pairs. ## Examples @@ -29,7 +29,7 @@ A property file organizes properties in a structured way for easy access. Proper } ``` -Any object in the JSON that has a `value` attribute on it is a property, so in this example there are 4 style properties: `color.font.base`, `color.font.secondary`, `color.font.tertiary`, and `color.font.inverse.base`. +Any object in the JSON that has a `value` attribute on it is a property; in this example there are 4 style properties: `color.font.base`, `color.font.secondary`, `color.font.tertiary`, and `color.font.inverse.base`. For any properties you wish to output, the "value" attribute is required. This provides the data that will be used throughout the build process (and ultimately used for styling in your deliverables). You can optionally include any custom attributes you would like (e.g. "comment" with a string or "metadata" as an object with its own attributes). @@ -88,7 +88,7 @@ Style properties are organized into a hierarchical tree structure with 'category ![](assets/cti.png) -Now you can structure your property json files like simple objects: +Now you can structure your property JSON files like simple objects: ```json { @@ -105,7 +105,7 @@ The CTI is implicit in the structure, the category is 'size' and the type is 'fo 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`! -You can organize and name your style properties however you want, **there are no restrictions**. But there are 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 style properties however you want, **there are no restrictions**. But there are 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 names 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 structure to know if it should be applied. For instance, the 'color/hex' transform only applies to properties of the category 'color'. diff --git a/docs/quick_start.md b/docs/quick_start.md index 877614b17..527637512 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -8,7 +8,7 @@ If you want to use the CLI, you can install it globally via npm: $ npm install -g style-dictionary ``` -Or you can install it like a normal npm dependency. Style Dictionary is a build tool, so you are most likely to use it as a dev dependency: +Or you can install it like a normal npm dependency. Style Dictionary is a build tool, and you are most likely to use it as a dev dependency: ```bash $ npm install -D style-dictionary ``` @@ -52,7 +52,7 @@ ios-swift-separate-enums ✔︎ build/ios-swift/StyleDictionarySize.swift ``` -Pat yourself on the back, you just built your first style dictionary! Take a look at what you built. This should have created a build directory and it should look like this: +Pat yourself on the back, you built your first style dictionary! Take a look at what you built. This should have created a build directory and it should look like this: ``` ├── README.md ├── config.json @@ -199,7 +199,7 @@ $color-font-tertiary: #cccccc; [UIColor colorWithRed:0.800f green:0.800f blue:0.800f alpha:1.000f] ``` -That's it! There is a lot more you can do with your style dictionary than just generate some files with color values. Take a look +That's it! There is a lot more you can do with your style dictionary than generating files with color values. Take a look at some [examples](examples.md) or take a deeper dive into [package structure](package_structure.md), [extending](extending.md), or how the [build process](build_process.md) works. ## Basic Usage diff --git a/docs/transforms.md b/docs/transforms.md index 1d423ddfa..e06492048 100644 --- a/docs/transforms.md +++ b/docs/transforms.md @@ -4,7 +4,7 @@ EDIT scripts/handlebars/templates/api.hbs OR JSDOC COMMENT INSTEAD! --> # Transforms -Transforms are functions that transform a property so that each platform can consume the property in different ways. A simple example is changing pixel values to point values for iOS and dp or sp for Android. Transforms are applied in a non-destructive way so each platform can transform the properties. Transforms are performed sequentially, so the order you use transforms matters. Transforms are used in your [configuration](config.md), and can be either [pre-defined transforms](transforms.md?id=defining-custom-transforms) supplied by Style Dictionary or [custom transforms](transforms.md?id=defining-custom-transforms). +Transforms are functions that transform a property - this enables each platform to consume the property in different ways. A simple example is changing pixel values to point values for iOS and dp or sp for Android. Transforms are applied in a non-destructive way thus each platform can transform the properties. Transforms are performed sequentially, therfore the order you use transforms matters. Transforms are used in your [configuration](config.md), and can be either [pre-defined transforms](transforms.md?id=defining-custom-transforms) supplied by Style Dictionary or [custom transforms](transforms.md?id=defining-custom-transforms). ## Using Transforms You use transforms in your config file under platforms > [platform] > transforms @@ -29,7 +29,7 @@ There are 3 types of transforms: attribute, name, and value. **Name:** A name transform transform the name of a property. You should really only be apply one name transformer because they will override each other if you use more than one. -**Value:** The value transform is the most important as this is the one that changes the representation of the value. Colors can be turned into hex values, rgb, hsl, hsv, etc. Value transforms have a matcher function so that they only get run on certain properties. This allows us to only run a color transform on just the colors and not every property. +**Value:** The value transform is the most important as this is the one that changes the representation of the value. Colors can be turned into hex values, rgb, hsl, hsv, etc. Value transforms have a matcher function that filter which properties that transform runs on. This allows us to only run a color transform on only the colors and not every property. ## Defining Custom Transforms You can define custom transforms with the [`registerTransform`](api.md#registertransform). @@ -173,7 +173,7 @@ Creates a constant-style name based on the full CTI of the property. If you defi ### name/ti/constant -Creates a constant-style name on just the type and item of the property. This is useful if you want to create different static classes/files for categories like `Color.BACKGROUND_BASE`. If you define a prefix on the platform in your config, it will prepend with your prefix. +Creates a constant-style name on the type and item of the property. This is useful if you want to create different static classes/files for categories like `Color.BACKGROUND_BASE`. If you define a prefix on the platform in your config, it will prepend with your prefix. ```js // Matches: all diff --git a/docs/using_the_npm_module.md b/docs/using_the_npm_module.md index 4f495b88f..de87a979d 100644 --- a/docs/using_the_npm_module.md +++ b/docs/using_the_npm_module.md @@ -4,7 +4,7 @@ The Style Dictionary npm module exposes an [API](api.md) to interact with style # Installation -To use the npm module, install it like a normal npm dependency. This is a build tool so you are most likely going to want to save it as a dev dependency (The -D option): +To use the npm module, install it like a normal npm dependency. This is a build tool therefore you are most likely going to want to save it as a dev dependency (The -D option): ```bash $ npm install -D style-dictionary ``` diff --git a/examples/advanced/auto-rebuild-watcher/README.md b/examples/advanced/auto-rebuild-watcher/README.md index 076cd1068..18f71d32a 100644 --- a/examples/advanced/auto-rebuild-watcher/README.md +++ b/examples/advanced/auto-rebuild-watcher/README.md @@ -2,7 +2,7 @@ This example shows how to use a "watcher" to rebuild automatically the files every time a property file is updated. -This is very handy when there are continuous changes to the token values (e.g. during development) and we want to avoid to run the "build" command at every update. +This is quite handy when there are continuous changes to the token values (e.g. during development) and we want to avoid to run the "build" command at every update. #### Running the example @@ -28,4 +28,4 @@ The command that we automatically run at every update is the `npm run build` com #### What to look at -Open the `package.json` file and see how in the "scripts" block there is an additional entry for "watch". This is the way the "watch" mode is invoked and run. \ No newline at end of file +Open the `package.json` file and see how in the "scripts" block there is an additional entry for "watch". This is the way the "watch" mode is invoked and run. diff --git a/examples/advanced/component-cti/README.md b/examples/advanced/component-cti/README.md index 33e86512e..940c33891 100644 --- a/examples/advanced/component-cti/README.md +++ b/examples/advanced/component-cti/README.md @@ -1,6 +1,6 @@ ## Component CTI Structure -This example will show you one way to define component tokens in an easy way while still using the CTI attributes for transforming the tokens. The CTI structure for Style Dictionary tokens makes defining component-level tokens really cumbersome and not user-friendly. This is because the CTI of tokens are based on the object path of the token. So if you wanted to write tokens for a button component it would have to look something like this: +This example will show you one way to define component tokens in a simple way while still using the CTI attributes for transforming the tokens. The CTI structure for Style Dictionary tokens makes defining component-level tokens cumbersome and not user-friendly. This is because the CTI of tokens is based on the object path of the token. Now, if you wanted to write tokens for a button component it would have to look something like this: ```json { @@ -65,7 +65,7 @@ At this point, if you want to build the tokens run `npm run build`. This command All of the built-in transforms target tokens using the CTI attributes. The built-in [`attribute/cti`](https://amzn.github.io/style-dictionary/#/transforms?id=attributecti) transform adds the CTI attributes to each token based on the object path of the token. In this example we override the default behavior of the [`attribute/cti`](https://amzn.github.io/style-dictionary/#/transforms?id=attributecti) transform to apply CTI attributes based on token's key, or last part of the object path to generate the equivalent category and type. This way we can correctly map a token with an object path of `component.button.background-color` to a category of `color` and type of `background`. -Style Dictionary allows for extensibility through [monkey patching](https://en.wikipedia.org/wiki/Monkey_patch). This allows you to override default behavior of the Style Dictionary library, and any built-in transforms and formats. You can override built-in transforms and formats by adding ones with the same name. Also, all of the built-in transforms, transformGroups, and formats are available by accessing them in the Style Dictionary library under the attributes `transform`, `transformGroup`, and `format` respectively. For example: +Style Dictionary allows for extensibility through [monkey patching](https://en.wikipedia.org/wiki/Monkey_patch). This allows you to override the default behavior of the Style Dictionary library, and any built-in transforms and formats. You can override built-in transforms and formats by adding ones with the same name. Also, all of the built-in transforms, transformGroups, and formats are available by accessing them in the Style Dictionary library under the attributes `transform`, `transformGroup`, and `format` respectively. For example: ```javascript const StyleDictionary = require('style-dictionary'); @@ -86,4 +86,4 @@ For example, if the key of the token (the last part of the object path) is "back * `config.js`: * `propertiesToCTI`: A plain object where we map the CSS property name to the proper category and type. * `CTITransform`: A transform object that defines a transformer method, which will override the default `attribute/cti` transform. This is similar to creating a child class with some custom logic and then calling `super`. In the transformer function it first looks at the top-level namespace, the first item in the object path, and if it is 'component' we run our custom logic using the `propertiesToCTI` map. If it is not 'component', use the built-in `attribute/cti`. -* `tokens/component/button.json`: Take a look at how it defines the component tokens and uses the last part of the object path as the CSS property. Notice how we can define token values in here that are not references, but they still get transformed properly: font-size uses 'rem' and background-color uses hex in the output. \ No newline at end of file +* `tokens/component/button.json`: Take a look at how it defines the component tokens and uses the last part of the object path as the CSS property. Notice how we can define token values in here that are not references, but they still get transformed properly: font-size uses 'rem' and background-color uses hex in the output. diff --git a/examples/advanced/create-react-app/README.md b/examples/advanced/create-react-app/README.md index 5ac6fbd78..f735ceda7 100644 --- a/examples/advanced/create-react-app/README.md +++ b/examples/advanced/create-react-app/README.md @@ -14,7 +14,7 @@ This is what you should see: screenshot of the React application -If instead you want to build just the tokens you can run `npm run build-dictionary`. This command will generate the files in the `src/style-dictionary-dist` folder, inside the CRA source folder. +If instead you want to build the tokens only, you can run `npm run build-dictionary`. This command will generate the files in the `src/style-dictionary-dist` folder, inside the CRA source folder. **Important**: the file `.env` in this folder is to have CRA run inside another project; if want to use this example as standalone codebase please remove it. @@ -37,9 +37,9 @@ The file **`App.js`** is the main app file. You can see the three component in t The folder `components` contains the code for the three components used in the app: -- The **`components/with-sass`** folder contains the example React component, styled using CSS/Sass. Look at how the design tokens are consumed inside the Sass file as Sass variables. The Sass file is then imported in the component, so that can be compiled to CSS at build time and included in the resulting web app page. +- The **`components/with-sass`** folder contains the example React component, styled using CSS/Sass. Look at how the design tokens are consumed inside the Sass file as Sass variables. The Sass file is then imported in the component which will be compiled to CSS at build time and included in the resulting web app page. -- The **`components/with-css-modules`** folder contains the example React component, styled using CSS Modules. Look at how the styles are imported in the component, and the class names are applied to the HTML elements. The CSS styles are declared in Sass, so that the design tokens can be consumed directly as Sass variables.
*If you want to know more about how CSS Modules works with React, and how it applies CSS styles to the JSX elements, [please refer to the documentation](https://github.com/css-modules/css-modules/blob/master/docs/css-modules-with-react.md).* +- The **`components/with-css-modules`** folder contains the example React component, styled using CSS Modules. Look at how the styles are imported in the component, and the class names are applied to the HTML elements. The CSS styles are declared in Sass by which the design tokens can be consumed directly as Sass variables.
*If you want to know more about how CSS Modules works with React, and how it applies CSS styles to the JSX elements, [please refer to the documentation](https://github.com/css-modules/css-modules/blob/master/docs/css-modules-with-react.md).* * The **`components/with-styled-components`** folder contains the example React component, styled using Styled Components. Look at how in this case the styles are declared directly in the component, as template literal "objects", and how the design tokens are consumed as JavaScript variables.
*If you want to know more about how Styled Components works, and how it applies CSS styles to the HTML elements, [please refer to the documentation](https://www.styled-components.com/docs/basics#getting-started).* diff --git a/examples/advanced/create-react-app/src/serviceWorker.js b/examples/advanced/create-react-app/src/serviceWorker.js index 2283ff9ce..f384f9b0f 100644 --- a/examples/advanced/create-react-app/src/serviceWorker.js +++ b/examples/advanced/create-react-app/src/serviceWorker.js @@ -47,7 +47,7 @@ export function register(config) { ); }); } else { - // Is not localhost. Just register service worker + // Is not localhost. register service worker only registerValidSW(swUrl, config); } }); diff --git a/examples/advanced/custom-formats-with-templates/README.md b/examples/advanced/custom-formats-with-templates/README.md index e3078c07c..1ff963280 100644 --- a/examples/advanced/custom-formats-with-templates/README.md +++ b/examples/advanced/custom-formats-with-templates/README.md @@ -1,6 +1,6 @@ ## Custom formats using templates -This example shows how to generate design tokens files with custom formats using "custom" template files/engines. This is useful when you need to distribute your design tokens and integrate them with custom pipelines or scripts, that expect specific formats, or if you have very specific needs that are not covered out-of-the-box by Style Dictionary. +This example shows how to generate design tokens files with custom formats using "custom" template files/engines. This is useful when you need to distribute your design tokens and integrate them with custom pipelines or scripts, that expect specific formats, or if you have any specific needs that are not covered out-of-the-box by Style Dictionary. **Notice**: before starting to dig into all the possible customisations that you can have, try the default settings offered by the library, look at the output files, and see if they can suit your needs. Probably they will do. If they don't, think how you want the output files generated, and see which one of the API methods you can use for that specific scope. @@ -21,7 +21,7 @@ StyleDictionary.registerFormat({ }); ``` -As you can see, the `registerFormat` [API method](https://amzn.github.io/style-dictionary/#/api?id=registerformat) is invoked, passing a custom name for the format (you can choose whatever you like, it's just a string) and a formatting function that returns the content to be saved to file. +As you can see, the `registerFormat` [API method](https://amzn.github.io/style-dictionary/#/api?id=registerformat) is invoked, passing a custom name for the format (you can choose whatever string you like) and a formatting function that returns the content to be saved to file. The format is then used in the `config.js` file and passed to a `file` declaration for a platform (look at the `config.js` file in the example to see how it is used). @@ -50,7 +50,7 @@ Now open the `build.js` script and look at how these custom formats are declared Finally, look at the different template files in the `templates` folder and see how they are built to generate custom file formats in output: * **web-scss.template**: this is a template that uses [Lodash](https://lodash.com/docs/4.17.10#template), and shows how you can create a custom format for Sass ".scss" files. The same approach can be used if you need other custom formats for the web (or other platforms too). -* **android-xml.template**: this template too uses Lodash, and shows how to create a custom XML format for Android, that can be read as "resource file". This is just one of the many possible formats for Android, so if you need to create one speak with your developers to agree on the format they want. +* **android-xml.template**: this template uses Lodash as well, and shows how to create a custom XML format for Android, that can be read as "resource file". This is one of the many possible formats for Android that you could create. * **android-xml_alt.hbs**: this is an alternative example of custom XML format for Android, that uses [Handlebar](https://handlebarsjs.com) as templating language. -* **ios-plist.template**: this template too uses Lodash, and shows how to create a custom PLIST format for iOS, that can be read as "resource file". This is just one of the many possible formats for iOS, so if you need to create one speak with your developers to agree on the format they want. +* **ios-plist.template**: this template uses Lodash as well, and shows how to create a custom PLIST format for iOS, that can be read as "resource file". This is one of the many possible formats for iOS that you could create. * **ios-plist_alt.pug**: this is an alternative example of custom XML format for Android, that uses [Pug](https://pugjs.org/api/getting-started.html) as templating language. diff --git a/examples/advanced/custom-formats-with-templates/build.js b/examples/advanced/custom-formats-with-templates/build.js index ae703bbad..e7bc05e18 100644 --- a/examples/advanced/custom-formats-with-templates/build.js +++ b/examples/advanced/custom-formats-with-templates/build.js @@ -37,7 +37,7 @@ StyleDictionary.registerFormat({ name: 'custom/format/android-xml-alt', formatter: function(dictionary, platform) { return templateCustomXml({ - // this is just to show that the formatter function takes a "dictionary" and "platform" parameters + // this is to show that the formatter function only takes a "dictionary" and "platform" parameters // (and dictionary has a "properties" and "allProperties" attributes) // and returns a string. for more details about the "formatter" function refer to the documentation allProperties: dictionary.allProperties, diff --git a/examples/advanced/custom-transforms/README.md b/examples/advanced/custom-transforms/README.md index 67ec35710..bfd2afcb7 100644 --- a/examples/advanced/custom-transforms/README.md +++ b/examples/advanced/custom-transforms/README.md @@ -4,9 +4,9 @@ This example shows how to use custom transforms (and transformGroups) to apply c Transforms are functions that transform a property (in a non-destructive way). The reason for *transforms* is that in this way each platform can consume the property in different ways (eg. changing *pixel* values to *pt* values for iOS, and *dp* or *sp* for Android). -**Remember**: transforms are performed sequentially, so the order you use transforms matters. +**Remember**: transforms are performed sequentially, hence the order you use transforms matters. -The need for custom transforms is that Style Dictionary expects the properties to be declared according to certain criteria, in order to use the pre-defined transforms and formats/templates. For example, the *web* transformGroup consists of the *attribute/cti*, *name/cti/kebab*, *size/px* and *color/css* transforms. +The need for custom transforms is that Style Dictionary expects the properties to be declared according to certain criteria, to use the pre-defined transforms and formats/templates. For example, the *web* transformGroup consists of the *attribute/cti*, *name/cti/kebab*, *size/px* and *color/css* transforms. The *size/px* adds 'px' to the end of the number, and is applied only if `prop.attributes.category === 'size'`. This means that your property needs to be expressed without units, and be under the *'size'* "category. If you need a different logic or you want to organise your properties differently, probably you can't use the out-of-the-box transformation groups, but you have to declare your custom ones. If [custom formats](../custom-formats-with-templates/) are the way to allow users to customise the format of the *output* of Style Dictionary, custom transforms are the way to allow them to customise both the *input* (the property names/values/attributes) and the *output* (the actual values expressed in the design tokens). For this reasons, custom transforms are probably one of the **most powerful features** of Style Dictionary: they make it extremely versatile, allowing limitless possibilities of extension and customisation of the entire pipeline from properties to design tokens. @@ -36,7 +36,7 @@ StyleDictionary.registerTransform({ More information can be found on the [documentation](https://amzn.github.io/style-dictionary/#/api?id=registertransform). -Since the transformGroups provided by Style Dictionary are pre-defined lists of transform, this means that in order to be used, this transform needs to be included in a new list of transforms. +To use this new custom transform, we need to create a new custom transformGroup that references it. To register this custom **transformGroup** , you have to call the `registerTransformGroup` method: @@ -81,7 +81,7 @@ Now open the `build.js` script and look at how these custom transforms/transform A few things to notice in the file: -- the name of a custom "transform" can be the same as an existing pre-defined method; in that case the pre-defined method is simply overwritten +- the name of a custom "transform" can be the same as an existing pre-defined method; in that case, the pre-defined method is overwritten - beyond the existing attributes, you can use custom attributes to create **matcher** functions, used to filter the properties and apply the transform only to those that match the filter condition. - if you don't specify a **matcher**, the transformation will be applied to all the properties - the transformation can be applied not only to the **value** of a property, but also to its **name** (and also to its attributes) diff --git a/examples/advanced/custom-transforms/build.js b/examples/advanced/custom-transforms/build.js index 7a1741fa1..a299ad0a6 100644 --- a/examples/advanced/custom-transforms/build.js +++ b/examples/advanced/custom-transforms/build.js @@ -10,7 +10,7 @@ StyleDictionary.registerTransform({ name: 'size/px', // notice: the name is an override of an existing predefined method (yes, you can do it) type: 'value', matcher: function(prop) { - // this is just an example of a possible filter (based on the "cti" values) to show how a "matcher" works + // this is an example of a possible filter (based on the "cti" values) to show how a "matcher" works return prop.attributes.category === 'font' || prop.attributes.category === 'margin'; }, transformer: function(prop) { @@ -55,7 +55,7 @@ StyleDictionary.registerTransform({ } }); -StyleDictionary.registerTransform({ // this is just a silly example, to show how you can apply transform to +StyleDictionary.registerTransform({ // this is a silly example, to show how you can apply transform to names name: 'name/squiggle', type: 'name', // notice: if you don't specify a matcher, the transformation will be applied to all the properties @@ -78,8 +78,8 @@ StyleDictionary.registerTransformGroup({ StyleDictionary.registerTransformGroup({ name: 'custom/scss', - // this is just to show a possibility, if you want to add a few transforms to a pre-defined group - // (even so, we suggest to use the previous approach, which is more explicit and clear) + // this is to show one possibility for adding a few transforms to a pre-defined group + // (however, we suggest to use the previous approach, which is more explicit and clear) transforms: StyleDictionary.transformGroup['scss'].concat(['size/px', 'ratio/%']) }); @@ -104,7 +104,7 @@ StyleDictionary.registerFormat({ // APPLY THE CONFIGURATION -// Very important: the registration of custom transforms +// IMPORTANT: the registration of custom transforms // needs to be done _before_ applying the configuration StyleDictionaryExtended = StyleDictionary.extend(__dirname + '/config.json'); diff --git a/examples/advanced/multi-brand-multi-platform/README.md b/examples/advanced/multi-brand-multi-platform/README.md index e46a47785..b2179d090 100644 --- a/examples/advanced/multi-brand-multi-platform/README.md +++ b/examples/advanced/multi-brand-multi-platform/README.md @@ -4,7 +4,7 @@ While it's pretty standard to use a common set of properties to generate the sam In this specific case it's necessary to use a **custom build script** to process the properties for each one of the possible brand/platform combinations. In the script the configuration used by Style Dictionary becomes parametric, with "brand" and "platform" used as arguments of a function that returns the "config" object used to extend Style Dictionary. -The properties are organised in **specific folders**, depending if they are "platform" dependent, "brand" dependent or "global" (independent of platform or brand). The organisation of the files used in this example is not strictly required, but has the advantage that it's easier to see what the properties depend on, and it's easy to use global paths to include the correct files for a specific combination of "brand" and "platform" (see the "source" declaration block in the `getStyleDictionaryConfig` function of the build script). +The properties are organised in **specific folders**, depending if they are "platform" dependent, "brand" dependent or "global" (independent of platform or brand). The organisation of the files used in this example is not strictly required, but has the advantage that it's easier to see what the properties depend on, and it's easier to use global paths to include the correct files for a specific combination of "brand" and "platform" (see the "source" declaration block in the `getStyleDictionaryConfig` function of the build script). #### Running the example diff --git a/examples/advanced/node-modules-as-config-and-properties/README.md b/examples/advanced/node-modules-as-config-and-properties/README.md index c115584cf..70c24edd0 100644 --- a/examples/advanced/node-modules-as-config-and-properties/README.md +++ b/examples/advanced/node-modules-as-config-and-properties/README.md @@ -12,7 +12,7 @@ At this point, if you want to build the tokens you can run `npm run build`. This Style Dictionary understands node modules that export a simple object for both a config file as well as the property source files. Using node module exports allows you to do some pretty cool things like generating properties programmatically (design tokens). -The `.extend()` method on the Style Dictionary module can take an object or a path to a JSON or node module and it copies the object attributes onto a new copy of the Style Dictionary object. The Style Dictionary object stores the transforms, transformGroups, and formats as attributes so you can override the defaults if you have the right attributes on your config object. This allows you to add custom transforms and formats without calling `.registerTransform()`! +The `.extend()` method on the Style Dictionary module can take an object or a path to a JSON or node module and it copies the object attributes onto a new copy of the Style Dictionary object. The Style Dictionary object stores the transforms, transformGroups, and formats as attributes on the SD object. You can override these defaults by directly adding these attributes to your config object. This allows you to add custom transforms and formats without calling `.registerTransform()`! #### What to look at diff --git a/examples/advanced/node-modules-as-config-and-properties/config.js b/examples/advanced/node-modules-as-config-and-properties/config.js index 6ce07ccd4..c17da6bb1 100644 --- a/examples/advanced/node-modules-as-config-and-properties/config.js +++ b/examples/advanced/node-modules-as-config-and-properties/config.js @@ -27,15 +27,14 @@ StyleDictionary.registerFormat({ // similar to webpack. module.exports = { // We are relying on node modules to merge all the objects together - // so we only want to reference top level node modules that export + // thus we only want to reference top level node modules that export // the whole objects. source: ['properties/index.js', 'components/index.js'], // If you don't want to call the registerTransform method a bunch of times - // you can just override the whole transform object. This works because + // you can override the whole transform object directly. This works because // the .extend method copies everything in the config - // to itself, so you can override things. It's also doing a deep merge - // so you don't have to worry about using Object.assign to not accidentally - // null out things. + // to itself, allowing you to override things. It's also doing a deep merge + // to protect from accidentally overriding nested attributes. transform: { // Now we can use the transform 'myTransform' below myTransform: { @@ -43,7 +42,7 @@ module.exports = { transformer: (prop) => prop.path.join('_').toUpperCase() } }, - // Same with formats, you can now just write them directly to this config + // Same with formats, you can now write them directly to this config // object. The name of the format is the key. format: { myFormat: (dictionary, platform) => { @@ -109,4 +108,4 @@ module.exports = { }] } } -} \ No newline at end of file +} diff --git a/examples/advanced/referencing_aliasing/README.md b/examples/advanced/referencing_aliasing/README.md index f05bffc65..ba57cdc47 100644 --- a/examples/advanced/referencing_aliasing/README.md +++ b/examples/advanced/referencing_aliasing/README.md @@ -2,7 +2,7 @@ This example shows how to use referencing (or "aliasing") to reference a value -or an attribute– of a property and assign it to the value –or attribute– of another property. -This is very handy when you want to create a system that uses some basic design definitions (base colors, base font sizes, base scales, etc) but then exposes them in a more complex and detailed set of design tokens, typically to describe a complete UI pattern library. +This is quite handy when you want to create a system that uses some basic design definitions (base colors, base font sizes, base scales, etc) but then exposes them in a more complex and detailed set of design tokens, typically to describe a complete UI pattern library. #### Running the example @@ -46,7 +46,7 @@ The reference can point to another property in a **different JSON file**. For ex ... ``` -It is also possible to create **chains of references**, where a value references an alias that is, in turn, another alias of a value, and so on. If you open `button/button.json` you can see that the value of the primary color for the button is an alias of `color.primary.value`, that we just saw above is an alias of `color.base.green.value`: +It is also possible to create **chains of references**, where a value references an alias that is also an alias of a value. If you open `button/button.json`, the value of the primary color for the button is an alias of `color.primary.value`, that is an alias of `color.base.green.value`: ``` { @@ -90,4 +90,4 @@ this at build time gets resolved to: "button-text-size": "16px" ``` -Of course this is just an example: the real applications can be the most different depending on the context and the needs. For example, look at the [multi-brand-multi-platform](../multi-brand-multi-platform) demo, to see how the aliasing is used to create a powerful theming system. \ No newline at end of file +This is an example: the real applications can be the most different depending on the context and the needs. For example, look at the [multi-brand-multi-platform](../multi-brand-multi-platform) demo, to see how the aliasing is used to create a powerful theming system. diff --git a/examples/advanced/s3/README.md b/examples/advanced/s3/README.md index 823ea1fc6..f403a3a29 100644 --- a/examples/advanced/s3/README.md +++ b/examples/advanced/s3/README.md @@ -6,7 +6,7 @@ The platforms can then pull these files down during their build process. #### Running the example -If you just want to see which files are generated, run the command `npm run build` in your local CLI environment. +If you only want to see which files are generated, run the command `npm run build` in your local CLI environment. If instead you want to see the full process, run the command `npm start`: this will start the style dictionary build process, save the output files and copy the assets into the `build` directory, then it will upload everything from the build directory into an S3 bucket. @@ -19,4 +19,4 @@ The asset files are copied into the folder `build` thanks to the action `copy_as #### The "upload" step -The upload to the S3 container in this example is done via a custom script, `upload.js`, which is not part of the standad Style Dictionary package. If you want you can adapt this script to your needs, or create a new custom script that will work with your specific storage solution. \ No newline at end of file +The upload to the S3 container in this example is done via a custom script, `upload.js`, which is not part of the standad Style Dictionary package. If you want you can adapt this script to your needs, or create a new custom script that will work with your specific storage solution. diff --git a/examples/basic/README.md b/examples/basic/README.md index 48cdd28fe..1571a81dc 100644 --- a/examples/basic/README.md +++ b/examples/basic/README.md @@ -1,6 +1,6 @@ # Basic Style Dictionary -This example code is bare-bones to show you what this framework can do. If you have the style-dictionary module installed globally, just cd into this directory and run: +This example code is bare-bones to show you what this framework can do. If you have the style-dictionary module installed globally, you can `cd` into this directory and run: ```bash style-dictionary build ``` @@ -35,7 +35,7 @@ ios-swift-separate-enums ✔︎ build/ios-swift/StyleDictionarySize.swift ``` -Pat yourself on the back, you just built your first style dictionary! Moving on, take a look at what we have built. This should have created a build directory and it should look like this: +Pat yourself on the back, you have now built your first style dictionary! Moving on, take a look at what we have built. This should have created a build directory and it should look like this: ``` ├── README.md ├── config.json diff --git a/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/BaseActivity.java b/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/BaseActivity.java index 7fc3aa229..966f811ef 100644 --- a/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/BaseActivity.java +++ b/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/BaseActivity.java @@ -34,7 +34,7 @@ public void startActivity(Intent intent) { @Override public boolean onOptionsItemSelected(MenuItem item) { // Handle action bar item clicks here. The action bar will - // automatically handle clicks on the Home/Up button, so long + // automatically handle clicks on the Home/Up button, as long // as you specify a parent activity in AndroidManifest.xml. int id = item.getItemId(); diff --git a/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/ColorAdapter.java b/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/ColorAdapter.java index cab305749..b8a0ea2c9 100644 --- a/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/ColorAdapter.java +++ b/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/ColorAdapter.java @@ -66,7 +66,7 @@ public View getView(int position, View convertView, ViewGroup parent) { ViewHolder holder; - // check if the view already exists if so, no need to inflate and findViewById again! + // no need to inflate and findViewById again, if the view already exists if (convertView == null) { // Inflate the custom row layout from your XML. @@ -82,7 +82,7 @@ public View getView(int position, View convertView, ViewGroup parent) { } else { - // skip all the expensive inflation/findViewById and just get the holder you already made + // skip all the expensive inflation/findViewById and get the holder you already made holder = (ViewHolder) convertView.getTag(); } diff --git a/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/property/PropertiesActivity.java b/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/property/PropertiesActivity.java index e1444688a..287c95ace 100644 --- a/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/property/PropertiesActivity.java +++ b/examples/complete/android/demo/src/main/java/com/amazon/styledictionaryexample/property/PropertiesActivity.java @@ -50,7 +50,7 @@ protected void onCreate(Bundle savedInstanceState) { public void onListFragmentInteraction(StyleDictionaryNode item) { if (item.isLeaf) { // Clone the path list because we don't want to - // add the properties key to the path so when the user goes back + // add the properties key to the path - when the user goes back // we don't need to try to pop off the last item ArrayList _path = new ArrayList<>(path); _path.add(item.name); diff --git a/examples/complete/android/demo/src/main/res/values/strings.xml b/examples/complete/android/demo/src/main/res/values/strings.xml index 16948d660..611eeb20b 100644 --- a/examples/complete/android/demo/src/main/res/values/strings.xml +++ b/examples/complete/android/demo/src/main/res/values/strings.xml @@ -90,8 +90,8 @@ "For example, a floating action button (FAB) can disappear or move off screen before a " "user picks up a card, or it can move if a snackbar appears.\n" "On the layout level, design your app layout to minimize opportunities for interference. " - "For example, position the FAB to one side of stream of a cards so the FAB won’t interfere " - "when a user tries to pick up one of cards.\n\n" + "For example, position the FAB to one side of the stream of cards which makes the FAB won’t interfere " + "when a user tries to pick up one of the cards.\n\n" Settings Icons diff --git a/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-acknowledgements.markdown b/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-acknowledgements.markdown index 215deb476..449a392d4 100644 --- a/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-acknowledgements.markdown +++ b/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-acknowledgements.markdown @@ -10,7 +10,7 @@ of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: +furnished to do such, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. diff --git a/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-acknowledgements.plist b/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-acknowledgements.plist index 110d2cc8a..e990d8fc7 100644 --- a/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-acknowledgements.plist +++ b/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-acknowledgements.plist @@ -21,7 +21,7 @@ of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: +furnished to do such, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. diff --git a/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-frameworks.sh b/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-frameworks.sh index 79122fbf9..03ceec92d 100755 --- a/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-frameworks.sh +++ b/examples/complete/ios/Demo/Pods/Target Support Files/Pods-StyleDictionary_Demo/Pods-StyleDictionary_Demo-frameworks.sh @@ -23,7 +23,7 @@ install_framework() source="$(readlink "${source}")" fi - # use filter instead of exclude so missing patterns dont' throw errors + # For missing patterns to not throw errors, use filter instead of exclude echo "rsync -av --filter \"- CVS/\" --filter \"- .svn/\" --filter \"- .git/\" --filter \"- .hg/\" --filter \"- Headers\" --filter \"- PrivateHeaders\" --filter \"- Modules\" \"${source}\" \"${destination}\"" rsync -av --filter "- CVS/" --filter "- .svn/" --filter "- .git/" --filter "- .hg/" --filter "- Headers" --filter "- PrivateHeaders" --filter "- Modules" "${source}" "${destination}" @@ -34,7 +34,7 @@ install_framework() binary="${destination}/${basename}" fi - # Strip invalid architectures so "fat" simulator / device frameworks work on device + # Strip invalid architectures therefore "fat" simulator / device frameworks work on device if [[ "$(file "$binary")" == *"dynamically linked shared library"* ]]; then strip_invalid_archs "$binary" fi diff --git a/examples/complete/ios/README.md b/examples/complete/ios/README.md index 133c79a22..1c56ae63f 100644 --- a/examples/complete/ios/README.md +++ b/examples/complete/ios/README.md @@ -14,7 +14,7 @@ To run the example project, clone the repo, and run `pod install` from the Examp ## Installation StyleDictionary is available through [CocoaPods](http://cocoapods.org). To install -it, simply add the following line to your Podfile: +it, you can add the following line to your Podfile: ```ruby pod "StyleDictionary" diff --git a/index.js b/index.js index a770173dc..9eb4e1077 100644 --- a/index.js +++ b/index.js @@ -90,7 +90,7 @@ Your current config uses the following templates: ⚠️ DEPRECATION WARNING ️️️️️⚠️ The registerTemplate method is deprecated and will be removed, please migrate to registerFormat. You can use any templating engine you would -like, you just need to require/import it. This is an example of how to +like, you only need to require/import it. This is an example of how to update your code using a lodash template (the template engine previously used by registerTemplate): diff --git a/lib/common/formats.js b/lib/common/formats.js index ce56f9890..9b3c80b45 100644 --- a/lib/common/formats.js +++ b/lib/common/formats.js @@ -49,7 +49,7 @@ function variablesWithPrefix(prefix, properties, commentStyle) { to_ret_prop = to_ret_prop.concat(' /* ' + prop.comment + ' */'); } } - + return to_ret_prop; }) .filter(function(strVal) { return !!strVal }) @@ -112,7 +112,7 @@ module.exports = { * Creates a SCSS file with a flat map based on the style dictionary * * Name the map by adding a 'mapName' attribute on the file object in your config. - * + * * @memberof Formats * @kind member * @example @@ -647,7 +647,7 @@ module.exports = { }, /** - * Creates a JSON file of just the assets defined in the style dictionary. + * Creates a JSON file of the assets defined in the style dictionary. * * @memberof Formats * @kind member @@ -739,12 +739,12 @@ module.exports = { .value(); return JSON.stringify(to_ret, null, 2); }, - + /** * Creates a sketchpalette file compatible with version 2 of - * the sketchpalette plugin. To use this you should use the + * the sketchpalette plugin. To use this you should use the * 'color/sketch' transform to get the correct value for the colors. - * + * * @memberof Formats * @kind member * @example diff --git a/lib/common/templates/ios-swift/class.swift.template b/lib/common/templates/ios-swift/class.swift.template index 780792559..5bb7469df 100644 --- a/lib/common/templates/ios-swift/class.swift.template +++ b/lib/common/templates/ios-swift/class.swift.template @@ -27,8 +27,8 @@ // <% // Filter to only those props wanted based on the filter, then sort - // them by category so we keep like props together, then by name - // so they are easier to find alphabetically. + // them by category to keep like props together, then by name + // to make them easier to find alphabetically. var props = _.sortBy(allProperties, item => item.attributes.category + item.name); %> diff --git a/lib/common/templates/ios-swift/enum.swift.template b/lib/common/templates/ios-swift/enum.swift.template index a19cce58d..f0b51f9fd 100644 --- a/lib/common/templates/ios-swift/enum.swift.template +++ b/lib/common/templates/ios-swift/enum.swift.template @@ -27,8 +27,8 @@ // <% // Filter to only those props wanted based on the filter, then sort - // them by category so we keep like props together, then by name - // so they are easier to find alphabetically. + // them by category to we keep like props together, then by name + // to make them easier to find alphabetically. var props = _.sortBy(allProperties, item => item.attributes.category + item.name); %> import UIKit diff --git a/lib/common/transforms.js b/lib/common/transforms.js index 2f6692d7e..ac31fe1e7 100644 --- a/lib/common/transforms.js +++ b/lib/common/transforms.js @@ -230,7 +230,7 @@ module.exports = { }, /** - * Creates a constant-style name on just the type and item of the property. This is useful if you want to create different static classes/files for categories like `Color.BACKGROUND_BASE`. If you define a prefix on the platform in your config, it will prepend with your prefix. + * Creates a constant-style name on the type and item of the property. This is useful if you want to create different static classes/files for categories like `Color.BACKGROUND_BASE`. If you define a prefix on the platform in your config, it will prepend with your prefix. * * ```js * // Matches: all @@ -415,13 +415,13 @@ module.exports = { } } }, - + /** - * + * * Transforms a color into an object with red, green, blue, and alpha * attributes that are floats from 0 - 1. This object is how Sketch stores * colors. - * + * * ```js * // Matches: prop.attributes.category === 'color' * // Returns: diff --git a/lib/extend.js b/lib/extend.js index ece6f97ee..2829014e2 100644 --- a/lib/extend.js +++ b/lib/extend.js @@ -95,7 +95,7 @@ function extend(opts) { } // Creating a new object and copying over the options - // Also keeping an options object just in case + // Also keeping an options object in case to_ret = deepExtend([{}, this, {options: options}, options]); // Update properties with includes from dependencies diff --git a/lib/filterProperties.js b/lib/filterProperties.js index 899bfc4af..e3564995b 100644 --- a/lib/filterProperties.js +++ b/lib/filterProperties.js @@ -28,11 +28,10 @@ function filterPropertyObject(properties, filter) { // Use reduce to generate a new object with the unwanted properties filtered // out return _.reduce(properties, (result, value, key) => { - // If the value is not an object, we don't know what it is so just return it - // it as-is. + // If the value is not an object, we don't know what it is. We return it as-is. if (!_.isObject(value)) { return result - // If the value has a `value` member we know it's a property, so pass it to + // If the value has a `value` member we know it's a property, pass it to // the filter function and either include it in the final `result` object or // exclude it (by returning the `result` object without it added). } else if (value.value) { @@ -44,7 +43,7 @@ function filterPropertyObject(properties, filter) { const filtered = filterPropertyObject(value, filter) // If the filtered object is not empty then add it to the final `result` // object. If it is empty then every property inside of it was filtered - // out, so exclude it entirely from the final `result` object. + // out, then exclude it entirely from the final `result` object. return _.isEmpty(filtered) ? result : _.assign(result, { [key]: filtered }) } }, {}) @@ -88,4 +87,4 @@ function filterProperties(dictionary, filter) { } } -module.exports = filterProperties \ No newline at end of file +module.exports = filterProperties diff --git a/lib/register/action.js b/lib/register/action.js index d0f8616a3..668359bf3 100644 --- a/lib/register/action.js +++ b/lib/register/action.js @@ -19,8 +19,8 @@ var chalk = require('chalk'); * After you register a custom action, you then use that * action in a platform your config.json * - * Actions run after the files in a platform are generated so you - * can perform operations on files generated by the style dictionary. + * You can perform operations on files generated by the style dictionary + * as actions run after these files are generated. * Actions are run sequentially, if you write synchronous code then * it will block other actions, or if you use asynchronous code like Promises * it will not block. @@ -53,7 +53,7 @@ function registerAction(options) { if (typeof options.do !== 'function') throw new Error('do must be a function'); // Don't throw an error for not having an undo action, - // we will just throw a warning when a user performs a clean. + // we will throw a warning only when a user performs a clean. this.action[options.name] = { do: options.do, diff --git a/lib/register/transform.js b/lib/register/transform.js index 602fee379..43c167f9c 100644 --- a/lib/register/transform.js +++ b/lib/register/transform.js @@ -23,9 +23,9 @@ var transformTypes = ['name', 'value', 'attribute']; * @function * @param {Object} transform - Transform object * @param {String} transform.type - Type of transform, can be: name, attribute, or value - * @param {String} transform.name - Name of the transformer so a transformGroup can call a list of transforms. + * @param {String} transform.name - Name of the transformer (used by transformGroup to call a list of transforms). * @param {Function} [transform.matcher] - Matcher function, return boolean if transform should be applied. If you omit the matcher function, it will match all properties. - * @param {Function} transform.transformer Performs a transform on a property object, should return a string or object depending on the type. Will only update certain properties so you can't mess up property objects on accident. + * @param {Function} transform.transformer Performs a transform on a property object, should return a string or object depending on the type. Will only update certain properties by which you can't mess up property objects on accident. * @returns {module:style-dictionary} * @example * ```js diff --git a/lib/transform/config.js b/lib/transform/config.js index 9cd89d252..d98323a25 100644 --- a/lib/transform/config.js +++ b/lib/transform/config.js @@ -32,7 +32,7 @@ function transformConfig(config, dictionary, platformName) { // The platform can define either a transformGroup or an array // of transforms. If given a transformGroup that doesn't exist, - // it will throw an error so the user is aware the transformGroup doesn't + // it will throw an error to make the user aware that the transformGroup doesn't // exist. A valid case is if the user defines neither, no transforms will be // applied. var transforms = []; diff --git a/lib/transform/object.js b/lib/transform/object.js index df9169aad..6e875c8bd 100644 --- a/lib/transform/object.js +++ b/lib/transform/object.js @@ -18,8 +18,8 @@ var _ = require('lodash'), /** * Applies transforms on all properties. This * does not happen inline, rather it is functional - * and returns a new object. We need to do this - * so we can perform transforms for different platforms + * and returns a new object. By doing this, + * we can perform transforms for different platforms * on the same style dictionary. * @private * @param {Object} obj diff --git a/lib/transform/propertySetup.js b/lib/transform/propertySetup.js index ea28eeb85..4f6876a38 100644 --- a/lib/transform/propertySetup.js +++ b/lib/transform/propertySetup.js @@ -37,13 +37,13 @@ function propertySetup(property, name, path) { // Only do this once if (!property.original) { // Initial property setup - // Keep the original object properties so we can key off them in the transforms + // Keep the original object properties; we will key off of them in the transforms to_ret.original = _.clone(property); - // Copy the name so we can have a base name to transform + // Copy the name - it will be our base name to transform to_ret.name = to_ret.name || name || ''; // Create an empty attributes object that we can transform on it later to_ret.attributes = to_ret.attributes || {}; - // An array of the path down the object tree so we can use it to build readable names + // An array of the path down the object tree; we will use it to build readable names // like color_font_base to_ret.path = _.clone(path); } diff --git a/lib/utils/flattenProperties.js b/lib/utils/flattenProperties.js index 6f3722154..cc98d85aa 100644 --- a/lib/utils/flattenProperties.js +++ b/lib/utils/flattenProperties.js @@ -19,7 +19,7 @@ var _ = require('lodash'); * be more generic. * @private * @param {Object} properties - The plain object you want flattened into an array. - * @param {Array} [to_ret=[]] - Properties array. This function is recursive so this is what gets passed along. + * @param {Array} [to_ret=[]] - Properties array. This function is recursive therefore this is what gets passed along. * @return {Array} */ function flattenProperties(properties, to_ret) { diff --git a/lib/utils/resolveObject.js b/lib/utils/resolveObject.js index 6658ee682..9c617e037 100644 --- a/lib/utils/resolveObject.js +++ b/lib/utils/resolveObject.js @@ -16,7 +16,7 @@ var _ = require('lodash'), var PROPERTY_REFERENCE_WARNINGS = GroupMessages.GROUP.PropertyReferenceWarnings; -var current_context = []; // To maintain the context so we can test for circular definitions +var current_context = []; // To maintain the context to be able to test for circular definitions var defaults = { opening_character: '{', closing_character: '}', @@ -55,8 +55,8 @@ function traverseObj(obj) { var key; for (key in obj) { - // We want to check for ignoredKeys, this is so - // we can skip over attributes that should not be + // We want to check for ignoredKeys, this is to + // skip over attributes that should not be // mutated, like a copy of the original property. if (obj.hasOwnProperty(key) && (options.ignoreKeys||[]).indexOf(key) < 0) { current_context.push(key); @@ -92,7 +92,7 @@ function compile_value(value, stack) { if (typeof ref === 'string') { to_ret = value.replace(match, ref); - // Recursive so we can compute multi-layer variables like a = b, b = c, so a = c + // Recursive, therefore we can compute multi-layer variables like a = b, b = c, eventually a = c if ( to_ret.indexOf('{') > -1 ) { var reference = to_ret.slice(1, -1); @@ -102,7 +102,7 @@ function compile_value(value, stack) { } else if(stack.indexOf(reference)!==-1) { // If the current stack already contains the current reference, we found a new circular reference - // chop down to just the circular part, save it to our circular reference info, and spit out an error + // chop down only the circular part, save it to our circular reference info, and spit out an error // Get the position of the existing reference in the stack var stackIndexReference = stack.indexOf(reference); diff --git a/scripts/handlebars/templates/formats.hbs b/scripts/handlebars/templates/formats.hbs index 1062c1433..03ea71029 100644 --- a/scripts/handlebars/templates/formats.hbs +++ b/scripts/handlebars/templates/formats.hbs @@ -29,7 +29,7 @@ There is an extensive (but not exhaustive) list of [included formats](#pre-defin ### Format configuration -Formats can take configuration to make them more flexible. This allows you to re-use the same format multiple times with different configuration or to allow the format to use data not defined in the tokens themselves. To configure a format add extra attributes on the file object in your configuration like so: +Formats can take configuration to make them more flexible. This allows you to re-use the same format multiple times with different configurations or to allow the format to use data not defined in the tokens themselves. To configure a format, add extra attributes on the file object in your configuration like the following: ```json { @@ -69,7 +69,7 @@ A special file configuration is `filter`, which will filter the tokens before th ### Creating formats -You can create custom formats using the [`registerFormat`](api.md#registerformat) function. If you want to add configuration to your custom format, `this` is bound to the file object so you can access attributes on the file object with `this.myCustomAttribute` if the file object looks like: +You can create custom formats using the [`registerFormat`](api.md#registerformat) function. If you want to add configuration to your custom format, `this` is bound to the file object. Using this, you can access attributes on the file object with `this.myCustomAttribute` if the file object looks like: ```json { @@ -82,7 +82,7 @@ You can create custom formats using the [`registerFormat`](api.md#registerformat ### Using a template / templating engine to create a format -A formatter is just a simple function and created easily with most templating engines. Templates are useful if there is a lot of boilerplate code to insert (e.g. ObjectiveC files). If the output consists of just the values (e.g. a flat SCSS variables file), writing a formatter function directly may be easier. +Formatters are functions and created easily with most templating engines. Formats can be built using templates if there is a lot of boilerplate code to insert (e.g. ObjectiveC files). If the output consists of only the values (e.g. a flat SCSS variables file), writing a formatter function directly may be easier. Any templating language can work as there is a node module for it. All you need to do is register a format that calls your template and returns a string. diff --git a/scripts/handlebars/templates/transforms.hbs b/scripts/handlebars/templates/transforms.hbs index 39f413c3b..623c097d3 100644 --- a/scripts/handlebars/templates/transforms.hbs +++ b/scripts/handlebars/templates/transforms.hbs @@ -1,6 +1,6 @@ # Transforms -Transforms are functions that transform a property so that each platform can consume the property in different ways. A simple example is changing pixel values to point values for iOS and dp or sp for Android. Transforms are applied in a non-destructive way so each platform can transform the properties. Transforms are performed sequentially, so the order you use transforms matters. Transforms are used in your [configuration](config.md), and can be either [pre-defined transforms](transforms.md?id=defining-custom-transforms) supplied by Style Dictionary or [custom transforms](transforms.md?id=defining-custom-transforms). +Transforms are functions that transform a property - this enables each platform to consume the property in different ways. A simple example is changing pixel values to point values for iOS and dp or sp for Android. Transforms are applied in a non-destructive way thus each platform can transform the properties. Transforms are performed sequentially, therfore the order you use transforms matters. Transforms are used in your [configuration](config.md), and can be either [pre-defined transforms](transforms.md?id=defining-custom-transforms) supplied by Style Dictionary or [custom transforms](transforms.md?id=defining-custom-transforms). ## Using Transforms You use transforms in your config file under platforms > [platform] > transforms @@ -25,7 +25,7 @@ There are 3 types of transforms: attribute, name, and value. **Name:** A name transform transform the name of a property. You should really only be apply one name transformer because they will override each other if you use more than one. -**Value:** The value transform is the most important as this is the one that changes the representation of the value. Colors can be turned into hex values, rgb, hsl, hsv, etc. Value transforms have a matcher function so that they only get run on certain properties. This allows us to only run a color transform on just the colors and not every property. +**Value:** The value transform is the most important as this is the one that changes the representation of the value. Colors can be turned into hex values, rgb, hsl, hsv, etc. Value transforms have a matcher function that filter which properties that transform runs on. This allows us to only run a color transform on only the colors and not every property. ## Defining Custom Transforms You can define custom transforms with the [`registerTransform`](api.md#registertransform). diff --git a/scripts/version.js b/scripts/version.js index 17203de3b..a7d5b7e8c 100644 --- a/scripts/version.js +++ b/scripts/version.js @@ -9,6 +9,6 @@ packageJSONs.forEach(function(filePath) { let pkg = fs.readJsonSync(filePath); pkg.devDependencies[PACKAGE.name] = PACKAGE.version; fs.writeFileSync(filePath, JSON.stringify(pkg, null, 2)); - // Add the package.json file to staging so it'll get commited + // Add the package.json file to staging and it'll get commited execSync(`git add ${filePath}`); });