Discussion: outputting files 1:1

[dbanksdesign]

This issue is meant to be an open discussion about a topic to see if this is something we want to support in Style Dictionary and how to do that.

Because of the way Style Dictionary works, by merging all source token files together first, there is no easy way to have a 1-to-1 mapping of source token file to build artifact. For example, having a JSON file for each component like 'button.json', 'input.json', 'heading.json', etc. and you wanted output files like 'button.scss', 'input.scss', and 'heading.scss' for the web, and maybe something similar for other platforms.

This is actually the way Theo does things, you input a single file and output files from that.

Is this use-case something Style Dictionary should support, and if so, what is the best way to do that?

Thanks to @elliotdickison for bringing this up!

[elliotdickison]

Thanks for getting this conversation started! A few details about our use-case:

We do 1-1 source-to-build token files in our project specifically when generating web variables that are resolved at runtime (e.g. JavaScript variables or CSS3 variables). Since these variables are resolved at runtime they contribute to the final size of the application bundles that import them (unlike sass variables, which boil out at build time). Keeping our token modules granular allows us to only import the tokens that we need in our apps (e.g. import button css variables and not date picker css variables) and helps us avoid shipping unnecessary bytes to the browser.

[chazzmoney]

@elliotdickison correct me if I am wrong, but this seems like it could be related to #104 as well?

If so, I don't see why we couldn't add in two processing options. The first would do exactly what you had requested in 104. The second would allow a specification of how to output files, including outputting at a specific depth level or based on some metadata property.

Using both of these together could enable the 1:1 functionality you are describing. The important question is how to incorporate this correctly into the codebase. The input setting as either a config option or a separate metadata item? The output setting maybe as a platform option?

I know this might seem like a lot of added functionality, but it seems to me to be working towards being less opinionated about how to specify tokens. @didoo I think you don't use CTI at all - would this be a step in the right direction in your opinion?

[elliotdickison]

Re: #104 - definitely related, keeping our token files granular means that we end up with a lot more files and rely more on file structure for organization. This makes the token paths pretty redundant in most cases (e.g. "/my/token/module.js" would contain something like { my: { token: { module: { a, b, c } } }).

[davixyz]

This is an interesting topic and definitely something people coming from Theo would appreciate. I myself started by doing this: I would filter base on the category I wanted and just add the tokens onto a file manually, so I would have colors.less, typography.less, etc. But then, after some talks with @dbanksdesign we came to the conclusion that honestly, it wasn't adding a lot of values, since at least these variables in less/sass preprocessor won't really matter if they're split in multiple files or 1 file; At the end, the generated CSS will resolve the dependencies and everything will work as expected.

I think this is more towards organization, I've found that in Android/iOS people will care a lot on the separation. I've convinced my Android/iOS stakeholders to live with the full tokens file but I can see that they're not happy, it's just something they would like in terms to access individual files related to the things they want to import, I just see it as overhead of more files to mantain

Being said that, I think if this feature is built, it could be passed as platform option so we can enable it for certain platforms vs not in others; And Maybe provide a generic flag for the whole dictionary to enable it for all platforms.

[kharrop]

We actually needed this use case! In our config.js file, for a given platform, we have our files structured like this:

 files: properties.map(tokenCategory => ({
          destination: `${tokenCategory}.js`,
          format: "format/js",
          filter: {
            attributes: {
              category: tokenCategory
            }
          }
        }))

This outputs files based on the category, so it still utilizes what's great about Style Dictionary and using the proper overrides and deep merge, but still keeps the output organized by category (or whatever people prefer).

Happy to add this as an example since this could be helpful for folks needing this for tree shaking or if they want to feature token categories as separate stories in their Storybook/documentation.

Something that would be nice that we would like to see is if we could output just the tokens that are specific to a brand/platform instead of having all the globals included as well.

[dbanksdesign]

This would be a great example! If you have the time we would appreciate the PR. You can use the other example folders as inspiration.

For outputting tokens specific to a brand/platform would filters work? In the file object in your config you can specify a filter out (or in) specific tokens.