From d60e3b1b189d98c15d39f2069f0fad59db4d502c Mon Sep 17 00:00:00 2001 From: Charles Dorner Date: Tue, 20 Nov 2018 16:39:26 -0800 Subject: [PATCH] first draft of an example CLI command --- README.md | 389 +++++++++++-------------------------- bin/style-dictionary | 23 +++ config.json | 69 +++++++ properties/color/base.json | 11 ++ properties/color/font.json | 9 + properties/size/font.json | 22 +++ 6 files changed, 252 insertions(+), 271 deletions(-) create mode 100644 config.json create mode 100644 properties/color/base.json create mode 100644 properties/color/font.json create mode 100644 properties/size/font.json diff --git a/README.md b/README.md index 13a5379e..dbdabab7 100644 --- a/README.md +++ b/README.md @@ -1,292 +1,139 @@ -Style Dictionary logo and mascot +# Basic Style Dictionary -[![npm version](https://img.shields.io/npm/v/style-dictionary.svg?style=flat-square)](https://badge.fury.io/js/style-dictionary) -![license](https://img.shields.io/npm/l/style-dictionary.svg?style=flat-square) -[![Build Status](https://img.shields.io/travis/amzn/style-dictionary.svg?style=flat-square)](https://travis-ci.org/amzn/style-dictionary) -[![code climate](https://img.shields.io/codeclimate/github/amzn/style-dictionary.svg?style=flat-square)](https://codeclimate.com/github/amzn/style-dictionary) - -# Style Dictionary -> *Style once, use everywhere.* - -A Style Dictionary is a system that allows you to define styles once, in a way for any platform or language to consume. A single place to create and edit your styles, and a single command exports these rules to all the places you need them - iOS, Android, CSS, JS, HTML, sketch files, style documentation, etc. It is available as a CLI through npm, but can also be used like any normal node module if you want to extend its functionality. - -When you are managing user experiences, it can be quite challenging to keep styles consistent and synchronized across multiple development platforms and devices. At the same time, designers, developers, PMs and others must be able to have consistent and up-to-date style documentation to enable effective work and communication. Even then, mistakes inevitably happen and the design may not be implemented accurately. StyleDictionary solves this by automatically generating style definitions across all platforms from a single source - removing roadblocks, errors, and inefficiencies across your workflow. - -For detailed usage head to https://amzn.github.io/style-dictionary - -## Watch the Demo on Youtube -[![Watch the video](/docs/assets/fake_player.png)](http://youtu.be/1HREvonfqhY) - -## Contents -* [Installation](#installation) -* [Usage](#usage) -* [Example](#example) -* [Quick Start](#quick-start) -* [Style Properties](#style-properties) -* [Extending](#extending) -* [Contributing](#contributing) -* [License](#license) - - -## Installation -*Note that you must have node (and npm) installed.* - -If you want to use the CLI, you can install it globally via npm: +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: ```bash -$ npm install -g style-dictionary +style-dictionary build ``` -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: -```bash -$ npm install -D style-dictionary +You should see something like this output: ``` +Reading config file from ./config.json +Building all platforms -If you want to install it with yarn: -```bash -$ yarn add style-dictionary --dev -``` - -## Usage -### CLI -```bash -$ style-dictionary build -``` -Call this in the root directory of your project. The only thing needed is a `config.json` file. There are also arguments: +scss +✔︎ build/scss/_variables.scss -| Flag | Short Flag | Description | -| --- | --- | --- | -| --config \[path\] | -h | Set the config file to use. Must be a .json file | -| --platform \[platform\] | -p | Only build a specific platform defined in the config file. | -| --help | -h | Display help content | -| --version | -v | Display the version | +android +✔︎ build/android/font_dimens.xml -### Node -You can also use the style dictionary build system in node if you want to [extend](#extend) the functionality or use it in another build system like Grunt or Gulp. -```javascript -const StyleDictionary = require('style-dictionary').extend('config.json'); - -StyleDictionary.buildAllPlatforms(); +ios +✔︎ build/ios/StyleDictionaryColor.h +✔︎ build/ios/StyleDictionaryColor.m ``` -The `.extend()` method is an overloaded method that can also take an object with the configuration in the same format as a config.json file. -```javascript -const StyleDictionary = require('style-dictionary').extend({ - source: ['properties/**/*.json'], - platforms: { - scss: { - transformGroup: 'scss', - buildPath: 'build/', - files: [{ - destination: 'variables.scss', - format: 'scss/variables' - }] - } - // ... - } -}); - -StyleDictionary.buildAllPlatforms(); +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: ``` - -## Example -[Take a look at some of our examples](example/) - -A style dictionary is a collection of style properties, key/value pairs that describe stylistic attributes like colors, sizes, icons, motion, etc. A style dictionary defines these style properties in JSON files, and can also include static assets like images and fonts. Here is a basic example of what the package structure can look like: +├── android/ +│ ├── font_dimens.xml +│ ├── colors.xml +├── scss/ +│ ├── _variables.scss +├── ios/ +│ ├── StyleDictionaryColor.h +│ ├── StyleDictionaryColor.m ``` -├── config.json -├── properties/ -│ ├── size/ -│ ├── font.json -│ ├── color/ -│ ├── font.json -│ ... -├── assets/ -│ ├── fonts/ -│ ├── images/ -``` - -### 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. -```json -{ - "source": ["properties/**/*.json"], - "platforms": { - "scss": { - "transformGroup": "scss", - "buildPath": "build/", - "files": [{ - "destination": "scss/_variables.scss", - "format": "scss/variables" - }] - }, - "android": { - "transformGroup": "android", - "buildPath": "build/android/", - "files": [{ - "destination": "font_dimens.xml", - "format": "android/fontDimens" - }] - } - } -} -``` -| Attribute | Type | Description | -| :--- | :--- | :--- | -| source | Array | Paths to the property json files. Can have globs. | -| platforms | Object | Sets of platform files to be built. | -| platforms | Array | Paths to the property json files. Can have globs. | -| platform.transformGroup | String (optional) | Apply a group of transforms to the properties, must either define this or `transforms`. | -| platform.transforms | Array (optional) | Transforms to apply sequentially to all properties. Can be a built-in one or you can create your own. | -| platform.buildPath | String (optional) | Base path to build the files, must end with a trailing slash. | -| platform.files | Array (optional) | Files to be generated for this platform. | -| platform.file.destination | String (optional) | Location to build the file, will be appended to the buildPath. | -| platform.file.format | String (optional) | Format used to generate the file. Can be a built-in one or you can create your own. [More on formats](https://amzn.github.io/style-dictionary/#/formats) | -| platform.file.options | Object (optional) | A set of extra options associated with the file. | -| platform.file.options.showFileHeader | Boolean | If the generated file should have a "Do not edit + Timestamp" header (where the format supports it). By default is "true". | - -### Properties -```json -{ - "size": { - "font": { - "small" : { "value": "10px" }, - "medium": { "value": "16px" }, - "large" : { "value": "24px" }, - "base" : { "value": "{size.font.medium.value}" } - } - } -} -``` - -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". - -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: -```scss -$size-font-small: 10px; -$size-font-medium: 16px; -$size-font-large: 24px; -$size-font-base: 16px; -``` +If you open `config.json` you will see there are 3 platforms defined: scss, android, ios. Each platform has a transformGroup, buildPath, and files. The buildPath and files of the platform should match up to the files what were built. The files built should look like these: +**Android** ```xml -10sp -16sp -24sp -16sp -``` - + + + 12.00sp + 16.00sp + 32.00sp + 16.00sp + + + + + #CCCCCC + #999999 + #111111 + #111111 + #999999 + #CCCCCC + +``` + +**SCSS** +```scss +// variables.scss +$color-base-gray-light: #CCCCCC; +$color-base-gray-medium: #999999; +$color-base-gray-dark: #111111; +$color-font-base: #111111; +$color-font-secondary: #999999; +$color-font-tertiary: #CCCCCC; +$size-font-small: 0.75rem; +$size-font-medium: 1rem; +$size-font-large: 2rem; +$size-font-base: 1rem; +``` + +**iOS** ```objc -float const SizeFontSmall = 10.00f; -float const SizeFontMedium = 16.00f; -float const SizeFontLarge = 24.00f; -float const SizeFontBase = 16.00f; -``` - - -## Quick Start -The style dictionary framework comes with some example code to get you stared. Install the node module globally, create a directory and `cd` into it. -``` -$ npm i -g style-dictionary -$ mkdir MyStyleDictionary -$ cd MyStyleDictionary -``` -Now run: -``` -$ style-dictionary init basic -``` -This command will copy over the example files found in [example](example/) in this repo. Now you have an example project set up. You can make changes to the style dictionary and rebuild the project by running: - -``` -$ style-dictionary build -``` - -Take a look at the documentation for the example code. - - -## Style Properties - -A style property is an attribute to describe something visually. It is atomic (it cannot be broken down further). Style properties have a name, a value, and optional attributes or metadata. The name of a property can be anything, but we have a proposed naming structure that works really well in the next section. +@implementation StyleDictionaryColor -### Category/Type/Item Structure - -While not exactly necessary, we feel this classification structure of style properties makes the most sense semantically. Style properties can be organized into a hierarchical tree structure with the top level, category, defining the primitive nature of the property. For example, we have the color category and every property underneath is always a color. As you proceed down the tree to type, item, sub-item, and state, you get more specific about what that color is. Is it a background color, a text color, or a border color? What kind of text color is it? You get the point. Now you can structure your property json files like simple objects: - -``` -{ - "size": { - "font": { - "base": { "value": "16" }, - "large": { "value": "20" } - } - } ++ (UIColor *)color:(StyleDictionaryColorName)colorEnum{ + return [[self values] objectAtIndex:colorEnum]; } -``` - - The CTI is implicit in the structure, the category and type is 'size' and 'font', and there are 2 properties 'base' and 'large'. - - Structuring style properties in this manner gives us consistent naming and accessing of these properties. You don't need to remember if it is button_color_error or error_button_color, it is color_background_button_error! - - 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. - - 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'. - -You can also add a _comment_ to a style property: -``` -{ - "size": { - "font": { - "base": { - "value": "16", - "comment": "the base size of the font" - }, - "large": { - "value": "20", - "comment": "the large size of the font" - } - } - } ++ (NSArray *)values { + static NSArray* colorArray; + static dispatch_once_t onceToken; + + dispatch_once(&onceToken, ^{ + colorArray = @[ +[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.0f], +[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.0f], +[UIColor colorWithRed:0.07f green:0.07f blue:0.07f alpha:1.0f], +[UIColor colorWithRed:0.07f green:0.07f blue:0.07f alpha:1.0f], +[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.0f], +[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.0f] + ]; + }); + + return colorArray; } -``` - -The comment will appear in the output files, where relevant or the output format supports comments. - - -## 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. - -```javascript -const StyleDictionary = require('style-dictionary').extend('config.json'); - -StyleDictionary.registerTransform({ - name: 'time/seconds', - type: 'value', - matcher: function(prop) { - return prop.attributes.category === 'time'; - }, - transformer: function(prop) { - return (parseInt(prop.original.value) / 1000).toString() + 's'; - } -}); - -StyleDictionary.buildAllPlatforms(); -``` - -For more information on creating your own transforms and formats, take a look at our [docs](https://amzn.github.io/style-dictionary/). - -## Mascot - -The mascot for Style Dictionary is ["Pascal"](https://github.com/amzn/style-dictionary/issues/97) the chameleon (seen below). You can also find them blending in as the logo throughout the documentation. - -Style Dictionary logo and mascot - -## Contributing - -Please help make this framework better. For more information take a look at [CONTRIBUTING.md](CONTRIBUTING.md) - - -## License -[Apache 2.0](LICENSE) +@end +``` + +Pretty nifty! This shows a few things happening: +1. The build system does a deep merge of all the property JSON files defined in the `source` attribute of `config.json`. This allows you to split up the property JSON files however you want. There are 2 JSON files with `color` as the top level key, but they get merged properly. +1. The build system resolves references to other style properties. `{size.font.medium.value}` gets resolved properly +1. The build system handles references to property values in other files as well as you can see in `properties/color/font.json` + + +Different representations of style information: + + + + + + + + + + + + + + + + + + + + + + + +
 AndroidSCSSObjective-C
Color`#CCCCCC``$color-base-gray-light: #CCCCCC;``[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.0f]`
Font size`12.00sp``$size-font-small: 0.75rem;``const float SizeFontSmall = 12.0f;`
+ +Now lets make a change and see how that affects things. Open up `properties/color/base.json` and change `"#111111"` to `"#000000"`. After you make that change, save the file and re-run the build command `style-dictionary build`. Open up the build files and take a look. + +**Huzzah!** + +Now go forth and create! Take a look at all the built-in [transforms](https://amzn.github.io/style-dictionary/#/transforms?id=pre-defined-transforms) and [formats](https://amzn.github.io/style-dictionary/#/formats?id=pre-defined-formats). diff --git a/bin/style-dictionary b/bin/style-dictionary index 128e27ea..82a15fef 100755 --- a/bin/style-dictionary +++ b/bin/style-dictionary @@ -14,6 +14,12 @@ function collect(val, arr) { return arr; } +function getDirectories(path) { + return fs.readdirSync(path).filter(function (file) { + return fs.statSync(path+'/'+file).isDirectory(); + }); +} + program .version(pkg.version) .description(pkg.description) @@ -51,6 +57,23 @@ program styleDictionaryBuild(); }); +program + .command('example') + .description('Generates an example style dictionary') + .action(function(type){ + var types = getDirectories(path.join(__dirname, '..', 'example')); + + if (typeof type !== 'string' || types.indexOf(type) < 0) { + console.error('Please supply an example name from the following list:\n ' + types.join('\n ')); + process.exit(1); + } + + console.log(chalk.bold(`Copying ${type} files into './${type}' ...`)); + fs.copySync(path.join(__dirname, '..', 'example', type), process.cwd()); + console.log('Running `style-dictionary build` for the first time to generate build artifacts.'); + styleDictionaryBuild(); + }); + // error on unknown commands program.on('command:*', function () { console.error('Invalid command: %s\nSee --help for a list of available commands.', args.join(' ')); diff --git a/config.json b/config.json new file mode 100644 index 00000000..942e328a --- /dev/null +++ b/config.json @@ -0,0 +1,69 @@ +{ + "source": ["properties/**/*.json"], + "platforms": { + "scss": { + "transformGroup": "scss", + "buildPath": "build/scss/", + "files": [{ + "destination": "_variables.scss", + "format": "scss/variables" + }] + }, + "android": { + "transformGroup": "android", + "buildPath": "build/android/", + "files": [{ + "destination": "font_dimens.xml", + "format": "android/fontDimens" + },{ + "destination": "colors.xml", + "format": "android/colors" + }] + }, + "ios": { + "transformGroup": "ios", + "buildPath": "build/ios/", + "files": [{ + "destination": "StyleDictionaryColor.h", + "format": "ios/colors.h", + "className": "StyleDictionaryColor", + "type": "StyleDictionaryColorName", + "filter": { + "attributes": { + "category": "color" + } + } + },{ + "destination": "StyleDictionaryColor.m", + "format": "ios/colors.m", + "className": "StyleDictionaryColor", + "type": "StyleDictionaryColorName", + "filter": { + "attributes": { + "category": "color" + } + } + },{ + "destination": "StyleDictionarySize.h", + "format": "ios/static.h", + "className": "StyleDictionarySize", + "type": "float", + "filter": { + "attributes": { + "category": "size" + } + } + },{ + "destination": "StyleDictionarySize.m", + "format": "ios/static.m", + "className": "StyleDictionarySize", + "type": "float", + "filter": { + "attributes": { + "category": "size" + } + } + }] + } + } +} diff --git a/properties/color/base.json b/properties/color/base.json new file mode 100644 index 00000000..3822ab51 --- /dev/null +++ b/properties/color/base.json @@ -0,0 +1,11 @@ +{ + "color": { + "base": { + "gray": { + "light" : { "value": "#CCCCCC" }, + "medium": { "value": "#999999" }, + "dark" : { "value": "#111111" } + } + } + } +} diff --git a/properties/color/font.json b/properties/color/font.json new file mode 100644 index 00000000..2beb5aa3 --- /dev/null +++ b/properties/color/font.json @@ -0,0 +1,9 @@ +{ + "color": { + "font": { + "base" : { "value": "{color.base.gray.dark.value}" }, + "secondary": { "value": "{color.base.gray.medium.value}" }, + "tertiary" : { "value": "{color.base.gray.light.value}" } + } + } +} diff --git a/properties/size/font.json b/properties/size/font.json new file mode 100644 index 00000000..24e7b803 --- /dev/null +++ b/properties/size/font.json @@ -0,0 +1,22 @@ +{ + "size": { + "font": { + "small" : { + "value": "0.75", + "comment": "the small size of the font" + }, + "medium": { + "value": "1", + "comment": "the medium size of the font" + }, + "large" : { + "value": "2", + "comment": "the large size of the font" + }, + "base" : { + "value": "{size.font.medium.value}", + "comment": "the base size of the font" + } + } + } +}