What's the best way to pass metadata to the next PostCSS plugin?

[GarthDB]

We transform our design tokens to CSS custom properties. I want to pass along metadata like deprecated so we can use a linter to inform teams using deprecated tokens they should use something else.

I think we could follow the SassDoc comment convention for translating the metadata to the CSS source code.

For a simplified example: tokens.json

{
  "aToken": {
    "value": "green",
    "deprecated": true
  }
}

That would get transformed to: tokens.css

:root {
  /* @deprecated */
  --aToken: green;
}

I'm making a PostCSS plugin to look for the CSS custom property definitions proceeded by the @deprecated comment, collect them into an array, and pass them along to the next plugin to use, like a Stylelint plugin. Then if a product engineer runs the Stylelint plugin against code that uses the deprecated CSS custom property it would warn them.

Here's a simple version of the plugin that analyzes the CSS custom property definitions:

const plugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-context-docs",
    Declaration(decl, postcss) {
      if (
        decl.prev() &&
        decl.prev().type === "comment" &&
        decl.prev().text.startsWith("@deprecated")
      ) {
        // How do I best pass the decl.prop to the next PostCSS plugin?
      }
    },
  };
};
plugin.postcss = true;
export default plugin;

Would result.messages be the best way to store an array of the deprecated properties for the next plugin to use or is there something better?

[ai]

Would result.messages be the best way to store an array of the deprecated properties for the next plugin to use or is there something better?

Yes, it is the best channel for communication between plugins.

Also, you may use Node.raws for something node-based, but I think it is not your case.

[GarthDB]

Thanks, I'll try it out.

What about just adding the data to the result object?

const plugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-context-docs",
    Declaration(decl, { result }) {
      if (
        decl.prev() &&
        decl.prev().type === "comment" &&
        decl.prev().text.startsWith("@deprecated")
      ) {
        decl.deprecated = true;
        if (Object.hasOwn(result, "deprecatedVars") && Array.isArray(result.deprecatedVars)) {
          result.deprecatedVars.push(decl.prop);
        } else {
          result.deprecatedVars = [decl.prop];
        }
      }
    },
  };
};
plugin.postcss = true;
export default plugin;

[ai]

It will be not compatible with TypeScript and could potentially have problem in future if we will add the same key in Result.

It will work but not very accurate in terms of code maintability.

[GarthDB]

That makes sense. So using messages, the API docs say the message should contain plugin and type properties. Is there any guidance on what type should be?

[ai]

I use plugin name as a prefix for type