Style-dictionary: JSDoc/SassDoc support

[blackfalcon]

In order to clearly document variables being generated by Style Dictionary, it would be nice if Style Dictionary supported tools like JSDoc and SassDoc.

For example, in regards to SassDoc, it would be a nice feature to automate the generation of the @type setting to use the category from the CTI convention.

Then another setting in SassDoc that would be helpful to support is @deprecated

With these features being supported in Style Dictionary in a special output mode, then the JSON would be something like ...

{
  "animation": {
    "default": {
      "property": {
        "value": "all",
        "comment": "Default property for CSS animations",
        "deprecated": "new animations coming, look at other variables"
      }
    }
  }
}

This would output the following Sass

/// Default property for CSS animations
/// @type Animation
/// @deprecated new animations coming, look at other variables
$animation-default-property: all; 

[didoo]

Since Style Dictionary is (generally) used to generate design tokens for multiple platforms, I always tend to ask myself: as a user, what would I expect this "feature" to do/generate in output for the different platforms? In this case, it would be strange as a user/consumer of SD if I add a series of comments/attributes to a node, and see that nothing happens when I generate a Swift/Plist file for iOS or an XML file for Android, or even a JS file for Web. I totally get your point, and why this may be useful, but for me, this kind of "extras" belong to custom formats. The more I work with SD, the more I think that how it works now is almost perfect, and instead of adding features we should add more examples (like how to add a custom format to generate JSDoc/SassDoc :) ) and where necessary improve the documentation.

[dbanksdesign]

To add on to @didoo's comment, one idea I've been playing around in my head is pushing a more plugin based approach. Someone could release a 'style-dictionary-docs' plugin as an npm package which would add functionality in the form of transforms/transformGroups/formats/actions. Someone could use it like:

const StyleDictionary = require('style-dictionary');
const StyleDictionaryDocs = require('style-dictionary-docs');

StyleDictionary.extend( StyleDictionaryDocs )
  .extend({
    // config
  })
  .buildAllPlatforms();

👆 would actually work in the current version of Style Dictionary if StyleDictionaryDocs has this form:

module.exports = {
  transform: {
    myCustomTransform: {}
  },
  transformGroup: {
    myCustomTransformGroup: {}
  },
  format: {
    myCustomFormat: {}
  },
  action: {
    myCustomAction: {}
  }
}

🤯 Thoughts?

[blackfalcon]

I am picking up what you are putting down. Reading @didoo comment, I agree. There is no need to fill SD with all the individual use cases. That starts to go against the intent of the project.

I really like the idea on more information in regards to how to build extensions and I really like the idea of supporting plug-ins as not to pollute SD itself.

[chazzmoney]

We definitely see that this could have value and use for people. With everyone on board not including it in the core project but rather as an extension or custom format, I'm going to close this for now. Please add any thoughts that apply to plugin architecture to #311.

Feel free to reopen if needed.