How to include comments in build files

[davidrpoliti]

I'm using storybook to ingest the tokens built by style-dictionary. I need to include a commented-out header that gets added to the built scss.

Is there a way to add the header in my config, or base.json, so that the output build file looks like this?

[dbanksdesign]

Yes, but you will need to create a custom format. Here is something I threw together quickly, let me know if it makes sense:

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

StyleDictionary.registerFormat({
  name: 'scss/variables',
  formatter: function(dictionary, config) {
    const header = `/**\n` +
      this.header.split('\n').map((line) => ` * ${line}`).join('\n') +
      `\n */\n`;
      
    return header +
      dictionary.allProperties.map((prop) => `$${prop.name}: ${prop.value};`).join('\n');
  }
});

module.exports = {
  "source": ["properties/**/*.json"],
  "platforms": {
    "scss": {
      "transformGroup": "scss",
      "buildPath": "build/scss/",
      "files": [{
        "header": `@tokens Colors
@presenter Color`,
        "destination": "_variables.scss",
        "format": "scss/variables"
      }]
    },
  }
}

[dbanksdesign]

this inside a custom format is bound to the file object performing the format. You can add any arbitrary data in the file object and access it in the format.

[dbanksdesign]

@davidrpoliti do you still need help with this?

[davidrpoliti]

@dbanksdesign I do! I'm going to try to get this working tomorrow with one of my peers.
(I've been on paternity leave)

Would I just add the commented out portion after @presenter Color?

[dbanksdesign]

Congrats! 🎉 I am about to do that myself.

The custom format I created in that example will take what is in the header attribute in the file object in the config and put it in a multiline comment. So you will edit the value of header with whatever you want the comment to be. Hopefully that makes sense, if not you can send me your codebase and I'll take a look.

[davidrpoliti]

@dbanksdesign this makes sense! and congrats to you as well!

I'm pretty new at this, and I can't figure out where that snippet should live. Does it go in my storybook config? Happy to send you a coffee/venmo for helping me out.

[dbanksdesign]

@davidrpoliti thanks!

That snippet would live in your style dictionary configuration. If you have a repository you are working on I could take a look at I could tell you exactly where it goes.

[anupsingh244]

Hey @dbanksdesign, What if i want multiple headers in single file like for colors, border-radius, line-height, This just create one header at top level.

[avkvirtru]

To build on the comments above, I'd love to build a mixed :root and multiple-header stylesheet like this: https://github.com/avkvirtru/virtuoso-design-system/blob/d69be98/lib/styles/tokens.css

This plays very nicely with the Storybook Design Token add-on.

[dbanksdesign]

@avkvirtru having a storybook design token format would be awesome!

[nhoizey]

I think this might answer the need:
feat(formats): adding custom file headers

[chazzmoney]

This is now part of 3.0 via #572

[jbvolvo]

This shouldnt be closed, as the actual question is to work with the design-token-addon.

Personally I think the addon lacks extendibility for custom tokens. Now you need to adhere to the available presenters provided by the addon. But if your CSS file has different token names, then the addon will break and throw an error instead.

One thing I got to work is to create a custom Formatter in style dictionary:

CC: @harrymansworth for helping me out on the final solution:

// these are the tokens we have in our stylesheet
const DESIGN_TOKEN_TYPES = [
  'color',
  'form',
  'animation',
  'font',
  'text',
  'breakpoint',
];

// just get the token name from it, like: color
const extractTokenNameFromDictionaryName = (variable) => {
  if (variable) {
    const [, name] = variable.match(/([^-]+)/);
    return name;
  }
};

// Capitalize first letter to respect the addon parser for finding the right Presenter
const sanitizeString = (string) => {
  return string.charAt(0).toUpperCase() + string.slice(1);
};

// Register your own format
StyleDictionaryPackage.registerFormat({
  name: `customFormat`,
  formatter: function ({ dictionary, file }) {
    return (
      StyleDictionaryPackage.formatHelpers.fileHeader({ file }) +
      ':root {\n' +
      DESIGN_TOKEN_TYPES.map(
        (item) =>
          `\n/**
* @tokens ${sanitizeString(item)}s
* @presenter ${sanitizeString(item)}
*/\n` +
          dictionary.allTokens
            .filter(
              (token) => item === extractTokenNameFromDictionaryName(token.name)
            )
            .map((token) => `--${token.name}: ${token.value};`)
            .join('\n')
      ).join('\n') +
      '}\n'
    );
  },
});

And then use this customFormat formatter in your config:

function getStyleDictionaryConfig(brand, platform) {
  return {
    source: [
    ...
    ],
    platforms: {
      web: {
        ...
        files: [
         ...
          {
            destination: 'new-tokens-storybook.css',
            format: 'customFormat',
          },
        ],
      },
    },
  };
}