Style-dictionary: Improve the "examples" section

[didoo]

I would like to improve the examples section of the project, for different reasons:

• the first time I started to look into Style Dictionary, I looked at the folder, but it was not clear to me how to use it, and what I was looking at (e.g. the npm folder, what does it mean "npm" in that context?)
• the "complex" example is quite large, but not really exhaustive
• probably some of the examples could be updated, to use the latest changes we introduced and show how they work
  Also, when I was developing new features/adding fixes or updating the tests suite, I would have loved to have a "standard" set of _token files_ that I could use as a playground to test the changes (I had to create this one), to see that I was not breaking anything, and also as input for the snapshot testing (introduced in #133) that could cover all the possible cases and variants.

@dbanksdesign @chazzmoney what do you think? and what do you prefer? that we discuss the possible improvements here, or that I start with opening a PR to show you what I have in mind and we continue the discussion there?

[chazzmoney]

I think we could improve here too and I like all of your concerns / suggestions. If you have something in mind, feel free to open a PR on it - I think starting with the code ends up producing faster results in the project.

[didoo]

@chazzmoney @dbanksdesign I have pushed the first part of the PR for the update of the "examples" section, so we can start the conversation and I can collect some feedback from you and other contributors (and possibly users).

Below some details of:

• what I have done
• why I have done it
• what still needs to be done
• where I want to go with this refactoring.

Folder structure

I think there should be some sort of guide for the users on what to expect when they look into the "examples" folder. There are three main folders: basic, complete and advanced.
The _basic_ is the basic entry-level example, where you can see how SD works in just a bunch of lines of code; the _complete_ is the example where you can find all the possible combinations, variants, different use cases around SD; the _advanced_ folder contains specific examples for specific needs.
Besides these folders, I have also created a test folder, that I would use to store the config files, assets and properties used in the testing suite (look at the Jest branch).

Open questions:

• the prefix "01/02/03/04" used in the folder names sorts them in the correct logical order, but becomes hard to read and in the CLI a space is a pain. remove the numbers? use an underscore? no strong opinions here
• should we rename "example" in "examples" ?

Properties / Config

I think we should try to keep the properties the same across the examples (whenever possible/makes sense). In this way it's easy to move from one example to another and see the actual differences, and the characteristics of the examples.

Questions still to be solved/discussed:

• for the basic example, should we remove the "ios" and "android" platforms?

Example > Basic

Is done, I think works well as is now.

Example > Complete

I still have to work on this example, will be quite a long process to add all the possible cases (admitted is even possible). At a first sight, looking at what we have in the "Complete" folder, I don't understand what "Complete" means: I see iOS and Android, but not Web; also the properties are a very generic list of properties, and the config is just a standard multi-platform config, nothing that shows all the possibilities of SD. My suggestion is that we get rid of this example (or we move it under "Advanced", but then I need more context of what it is: a native demo app in iOS and Android?) and create a proper "complete" example about the declaration, compilation and generation of design tokens/properties, nothing related to their "consumption" from another codebase/application. What do you think?

Example > Advanced > Npm Module

Is done, I think works well as is now.

Example > Advanced > S3

I have updated the example, "linking" the assets inside the design tokens, not only copying them in the assets folder. I would like to show also how the assets can be embedded (base64) in the token files but I don't understand how.

Example > Advanced > React

I have split the example in two, one for React and one for React Native (do you think makes sense?). The problem I have is that I can't have the React application running, I think is broken, looks like an example ported from another codebase but actually not completed. Does it make sense to fix it? maybe is too complex, maybe we should make a simpler application (or use Create React App and add the SD to it?). For the React Native example, I have no idea how to run it, how to check if it actually works, etc.

Other examples

I was thinking to add more examples:

• Sass maps (when will be implemented)
• Embedding assets in tokens (base64)
• Other ideas?

Important things to do

Let's remember to:

• update the "install" CLI command path for the examples!
• update the documentation for the Examples section (see https://amzn.github.io/style-dictionary/#/examples?id=examples)

Please, have a quick look at the code and tell me if it's the right direction, and what do you think of what I've written above.

[davixyz]

I agree on your comments about the Advanced > Complete example, For me when I first saw Style Dictionary I understood that the example was a complete cross platform example which means iOS, Android and Web; But since you want to introduce basic/advanced, maybe we should just have those two categories and be the cross platform example a mix of iOS/Android/Web. I think it's more straightforward to think about basic and advance and I would argue that setting up the project to create a cross platform token solution is advanced

[chazzmoney]

This is sooooooo good. Everything you are doing feels like the right thing to do. Clarity is a real problem. Our naming is bad currently and we jam a lot of stuff into each example.

Things you are doing that I like:

• Have each example do one thing well
• Keep the properties the same across the examples
• Come up with a better naming scheme
• Ensure that we have easy to find examples for the common things people do

I think the only thing that hasn't crystalized yet is the naming... maybe we should consider naming things the way that we reference them in the documentation / create an organizational structure for it. So that in the distant future, when the example set is super complete it would look something like:

• examples/cti/basic
• examples/cti/advanced
• examples/cti/themes
• examples/formats/ios/ObjectiveC
• examples/formats/ios/swift
• examples/formats/web/css
• examples/formats/design/sketch
• examples/assets/fonts
• examples/assets/audio
• examples/assets/base64
• examples/buildhooks/npm
• examples/buildhooks/imagemagik
• examples/buildhooks/s3

That obviously isn't quite right, but I think it communicates the idea thats brewing in my head.

[didoo]

@dbanksdesign I know it's a lot to read, but can you please give me your feedback on above? especially on the "Example > Advanced > S3" and "Example > Advanced > React"? thanks

[didoo]

Reporting here from #164 where @davixyz suggests to have a look at:
https://github.com/zeit/next.js/tree/canary/examples
for inspiration about the examples organisation

[dbanksdesign]

Sorry for being absent on this until now, I've been pretty swamped. I love this and the direction in #164 . To give some context around the "complete" example, what I was shooting for was to have an example style dictionary that is "complete" in the sense that it is ready to plug into an Android, iOS, or web code base, and has a "complete" set of tokens. I wanted something that was as out-of-the-box ready as can be. In reality, the example at its current state is not that.

One thing that I've struggled with while thinking about example code for Style Dictionary is that for a lot of it, there are 2 parts. The actual example Style Dictionary code (formats, transforms, properties), and then there is how to consume and use what it generates. Take the react or react-native examples, we are both showing the Style Dictionary code and the code to consume it, which in reality would most likely be 2 packages. Maybe it's fine, but something I've been thinking about.

I also just left some comments on #164

[didoo]

One thing that I've struggled with while thinking about example code for Style Dictionary is that for a lot of it, there are 2 parts. The actual example Style Dictionary code (formats, transforms, properties), and then there is how to consume and use what it generates.

I think that people adopting a solution like design tokens (be it in SD, Theo or something else) in their project, probably they will know how to consume a Scss or a JSON or a PLIST or an XML file.
In my head, there are two kind of audience for the examples: those who have just started to look into SD (and so they need simple and clear examples) and those who are adopting/have adopted SD and are looking on how to customise it to their specific needs or extend it to do something that is not available out-of-the-box.

I'll look at the comments you left and reply there.

[didoo]

@dbanksdesign @chazzmoney @davixyz I am moving the conversation directly in the PR, because otherwise... it gets lost in conversation :)

[blackfalcon]

@didoo awesome work picking this up! I too have just recently started digging into a Design Token solution and really gravitated to Style Dictionary. And I too was pretty confused by the multiple examples and had to really weed through things to build my own conclusions.

[dbanksdesign]

I think we can close this, @didoo @davixyz @chazzmoney @blackfalcon thoughts?

[chazzmoney]

Closing as we have done a lot of improvement and work here in our last two releases (2.6 and 2.7). Future requests for changes to examples should be their own issues moving forward.

Thanks for your hard work everyone!