Style-dictionary: Create an example showing how to use a watcher to auto-rebuild

[chazzmoney]

Specifically in reference to #106

[didoo]

I can take this if it's ok, I'll add to the list of "advanced" examples (you can suggest then if/how to improve it)

[didoo]

@chazzmoney look at this commit and tell me if it's OK: https://github.com/amzn/style-dictionary/pull/164/commits/54033fec3d45cecd4650f8ae34d25affae7c8396

[chazzmoney]

Love it. Philosophical question for you - do you like the rest of the example or does it complicate things? I'm ok with it and I want to make sure it goes with the rest of your theme in making the examples better.

[didoo]

the rest of the example

what do you mean? the part of this example? you mean to simplify the config.js file an maybe other parts?

[chazzmoney]

Yeah, the non-watcher specific portion. Producing multiple platforms, etc. A simpler config might help reduce confusion perhaps?

[didoo]

@chazzmoney I agree with you. while refactoring the "examples" in #164, I am continuously finding myself in this doubt: keep it simple, with only one platform for example (apart from the most complex ones), or keep all the examples as similar as possible (so, since the "basic" has multiple platforms, always show multiple platforms, keeping the properties the same)?

The reason why I haven't decided yet is that I don't know which platform (web? why? what makes it more special than iOS or Android? if a user needs to implement design tokens for iOS, and all the examples are for web, what would he think?). I have tried to have a simplified example for iOS, but "ios/plist" doesn't work (at least for me, maybe I am doing something wrong) so I've used "ios/macros"; but for Android? there's no way to have all the tokens in output in a single, simple file (something like "android/xml") so this would mean to introduce a custom template, and at that point, the simplicity of the example has gone down the drain :(

What I have started to do, is to add in the Readme a section "What to look at" in which I explain where to look in the code of the example (see https://github.com/amzn/style-dictionary/pull/164/commits/82bf17b5277af3c88296a65080fb2e7149f09e5f)

Maybe I should rethink my approach in the examples, and favor simplicity and clarity over consistency and completeness?

@chazzmoney @dbanksdesign ideas? suggestions? opinions?

[chazzmoney]

I'm a bit focused on trying to resolve #152 and #158 so I haven't given this the attention it deserves. Will try to be more on top of this issue to support your work.

Thanks for explaining your rationale - super clear now on the structure.

It really is hard to pick a specific platform. I'm leaning towards the recently added json/nested. I could imagine that folks familiar with one platform could be anti-platform towards a different one. I'm guessing most people have come across JSON no matter what platform they work from, so it might be more freeing... I could be wrong though.

Once I get out from under those two 15X PRs, I can add examples for each platform/format we have by default. I think this could go a long ways towards helping people find the pieces they need.

What do you think?

[didoo]

The only thing is that, if we use json/nested as a "standard" example, maybe is confusing: you input JSON, and as output you receive a (very similar) JSON? maybe it doesn't convey the power of SD.
But again, is open for discussion :)

[dbanksdesign]

Both good points. I think people would get it either way, especially if we have the "how does it work" and "what to look at" sections of the README. So I would be fine with whatever we have as the platform/file output.

[didoo]

I think this can be closed now, the example is in master: https://github.com/amzn/style-dictionary/tree/master/examples/advanced/auto-rebuild-watcher