Better examples

[didoo]

Issue #136:

Description of changes:

• updated logo in the main Readme file
• changed the folder structure in basic, complete, advanced and test (to be discussed)
• updated the Basic example and its Readme
• renamed "npm" to "npm module", updated its properties and config to match the "basic" example
• updated the s3 example making it more similar to other examples and adding some more assets to be uploaded and linked/embedded in tokens
• tried to re-organise the “react” folder in two separate folders, then decided to remove them completely
• updated/added the following "advanced" examples (with proper Readmes):
  -- assets-base64-embed
  -- auto-rebuild-watcher
  -- custom-templates
  -- custom-transforms
  -- multi-brand-multi-platform
  -- npm-module
  -- referencing_aliasing
  -- s3

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[davixyz]

Really minor thing but, should we remove the spaces on folder names so when we see them in the web we don't get things like 01%20-%20basic/; I think this will also be weird on the terminal when you are trying to cd into the directories with spaces.

Something like this would be great
https://github.com/zeit/next.js/tree/canary/examples

[didoo]

@davixyz thanks for the link! and re. the spaces in the folders filenames, I agree with you, was just an attempt to see if that makes sense. If you have time, please see also the other comments here:
#136 (comment)
and any feedback you may have on the questions/doubts I have raised is much appreciated :)

[chazzmoney]

Didoo, the most recently added example is very impressive. It will be a super useful starting point for lots of folks I think. @elliotdickison I know you did something similar to this in your actual implementation - can you take a look and see if you have any suggestions?

[dbanksdesign]

I love the direction of this. I just left a few comments. I think overall what this project is making me realize we should think about and codify a template(s) and structure of what good examples are (what you have here) and what examples we should show, and document it. This would help us when writing the examples as well as others who might want to contribute. We might not necessarily need it for this PR, but just some food for thought.

[dbanksdesign]

For this section, should we have instructions how to pull this code down locally to run it?

[didoo]

I see what you mean. Mmm, on one side it would be good to have it at the "examples" root level, on the other if someone doesn't read the main Readme they could miss it. I'll think about a solution.

[dbanksdesign]

Maybe for this example, we remove the Android and iOS stuff and focus on web outputs. We should probably add a javascript platform/output here at least.

[didoo]

I have updated the file, check if it's ok now.

[dbanksdesign]

I am really excited to get this out and I want to merge this in this week!

I've been pondering the react and react-native examples for a while now... What are people's thoughts on removing the react and react-native examples? My thinking is that these examples are a bit confusing and don't really fit the mold of the other examples. The react and react-naive examples are codebases of how to consume a style dictionary, but there is nothing really special or different about the style dictionary part itself. It is using standard transforms and formats. What is weird too is, in the real world you would probably want to have your style dictionary package separate from implementation, like react, iOS, Android, etc. and these examples have the react codebase in the same place as the style dictionary.

What if in the npm-module example, we include examples of how to consume the npm module in a react/react-native/other-js-framework codebase? Then we aren't writing a whole functioning react app, but just showing the user how to write a style dictionary as an npm module and consume it in their UI package.

Thoughts?

[didoo]

OK, since we all agree, I have removed the examples for React + React Native (we can revert them later, if we want to).

Re. your question, @dbanksdesign, I would not add the example to the npm-module example (maybe, just add an explanation on the Readme would be better).
If I imagine someone who doesn't know how to consume an npm module, I imagine someone that probably would use something like Create React App to bootstrap a project. In that case, I would like to see how to use SD with a CRA app. I don't know if that would mean "react codebase in the same place as the style dictionary" again, but from a certain point of view maybe it would be a sensible compromise to offer something React-related in the examples.

At this point, what remains to complete is the S3 example: as I mentioned in the issue:

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.

Essentially, I don't know if the asset/base64 transform works. I've tried, but it didn't work for me. Maybe I am doing something wrong? do you think there is a meaningful way to show how it works in the S3 example?

[dbanksdesign]

LGTM!

[dbanksdesign]

I got too excited and didn't see your comment. For react, totally agree, I was actually thinking of an example in the README, not like are real example.

For the s3 example, I just ran it locally and it works for me. Maybe we need an example how to use the base64 sass variables you are creating. You can use them in sass like:

.grid {
  width: 20px;
  height: 20px;
  background-image: url('data:image/svg+xml;base64, #{$grid}');
}

@font-face {
  font-family: 'MyFont';
  src: url('data:font/truetype;base64,#{$ttf}');
  font-weight: normal;
  font-style: normal;
}

I think one issue with the assets.scss file you are creating is there is no 'name' transform, so there are a few variables named $ttf. Should cut down on some of the fonts included as well?

Maybe we should split out base64'ing things into its own example?

[didoo]

OK, I did a quick spike to have a "create react app" example with Sass (later we can add one with CSS Modules and one with Styled Components): 6b0a719

What do you think? Makes sense?

[didoo]

OK, now the S3 example works (it always worked, I was looking in the wrong place). But now I think it would be better to have an explicit example assets-embed (I would have loved to see it the first time I looked into SD). It will not take me long, I'll do asap. Stay tuned.

[didoo]

@dbanksdesign I have added the example for the "base-64 embed" of assets (extracted from the S3 example, so they are two different example on two quite different things). I have one "problem" that maybe you can help me with: I want to show in the same example both the assets embedding and the "normal" tokens generation. This is my config file:

{
  "source": ["properties/**/*.json"],
  "platforms": {
    "scss": {
      "transformGroup": "scss",
      "buildPath": "build/scss/",
      "files": [{
        "destination": "variables.scss",
        "format": "scss/variables"
      }]
    },
    "json/asset": {
      "transformGroup": "web",
      "buildPath": "build/json/",
      "files": [{
        "destination": "variables.json",
        "format": "json/asset"
      }]
    },
    "assets/embed/scss": {
      "transforms": ["attribute/cti", "name/cti/kebab", "asset/base64"],
      "buildPath": "build/scss/",
      "files": [{
        "destination": "assets_icons.scss",
        "format": "scss/variables",
        "filter": {
          "attributes": {
            "category": "asset",
            "type": "icon"
          }
        }
      },{
        "destination": "assets_fonts.scss",
        "format": "scss/variables",
        "filter": {
          "attributes": {
            "category": "asset",
            "type": "font"
          }
        }
      }]
    },
    "assets/embed/json": {
      "transforms": ["attribute/cti", "name/cti/kebab", "asset/base64"],
      "buildPath": "build/json/",
      "files": [{
        "destination": "assets_icons.json",
        "format": "json/flat",
        "filter": {
          "attributes": {
            "category": "asset",
            "type": "icon"
          }
        }
      },{
        "destination": "assets_fonts.json",
        "format": "json/flat",
        "filter": {
          "attributes": {
            "category": "asset",
            "type": "font"
          }
        }
      }]
    }
  }
}

what happens is that in this way we are generating twice the variables for the assets. eg.:

// variables.scss
$asset-icon-github: "assets/icons/github.svg";

// assets_icons.scss
$asset-icon-github: $asset-icon-github: "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5v...

Is there a way to filter/exclude something in the config? In the documentation, it says you can pass a function to the "filter" but this is a JSON, so it's not possible. Is there a way to do something like (pseudocode): filter: return (attributes.category !== asset)?

[dbanksdesign]

filter in JSON configs work by giving it an object to filter each token by, in the same way that lodash's filter can take an object instead of a function. Unfortunately this means that this is an inclusive filter, so it will only include things that match. We don't have a way to exclude tokens in a JSON config... Do you think the asset-base64-embed is good enough for now? I think because the advanced examples are meant to show a singular concept, like base64ing assets, this example does that well.

[davixyz]

👍 I think this is a great addition!

Also 👍 to the multiple filters, I've been doing my custom filters at template level to kinda organize tokens but maybe a multiple filter system could help

[didoo]

@dbanksdesign @chazzmoney I have decided to remove from this PR the "Create React App" example, that I added a couple of weeks ago, because I was stuck with the Readme (I couldn't find time to write it properly) and also because I wanted to try to add also "styled-components" and possibly "CSS Modules" in the same example, so making it more generic around how to consume SD tokens in a React app (created via CRA). So I'll create a separate PR later for this.

So, at this point the PR is done, for me. I'll go through the committed files again, to see if I have missed something or something needs some tweaks, but I think we should merge it in one of the next releases (since is documentation, so no effects on the code itself).

[dbanksdesign]

Having an example with styled components and css modules would be awesome! I'll go through and double check this tomorrow and I think we are good to go!