feat: add json output format

[dstaley]

📌 Summary

Adds a new output format that generates a JSON file that can be re-consumed by other Style Dictionary instances.

🛠️ Detailed description

As part of marketing's adoption of HDS, we want to generate a set of tokens that build upon the existing tokens of HDS. There are a handful of instances where we take a color value and perform modifications on it (such as lighten/darken) that are only possible if we have access to the underlying token value. For example:

{
  "color": {
    "vault": {
      "button": {
        // ...
        "background-color-hover": {
          "type": "color",
          "value": "{color.vault.brand}",
          "modify": [
            { "type": "mix", "args": ["black", 0.06, { "space": "srgb" }] }
          ]
        },
        // ...
        "border-color-focus": {
          "type": "color",
          "value": "{color.vault.foreground}",
          "alpha": "0.1"
        }
      }
    }
  }
}

Currently, we maintain an entire fork of the tokens package to accomplish this, but have realized that if we could pass the HDS tokens into another instance of Style Dictionary, then we could reduce our fork to just our custom tokens.

This PR adds a third output format using the built-in json format. For simplicity, it doesn't configure a custom formatter to remove unnecessary properties, but that's a weak opinion loosely held.

This JSON file can then be passed into Style Dictionary like so:

const config: Config = {
  source: ['src/marketing/**/*.json'],
  include: [
    require.resolve(
      '@hashicorp/design-system-tokens/dist/products/tokens.json',
    ),
  ],
  platforms: {
    'web/css-variables': {
      transformGroup: 'marketing/web',
      buildPath: 'dist/marketing/css/',
      prefix: 'hdsplus',
      basePxFontSize: 16,
      files: [
        {
          destination: 'tokens.css',
          format: 'css/variables',
          filter(token: DesignToken) {
            return token.isSource
          },
        },
      ],
    },
  },
}

This configuration will generate a new set of tokens that have access to the underlying token values from HDS, but won't overwrite them given it uses a different prefix.

📸 Screenshots

N/A

🔗 External links

HashiCorp Slack link: https://hashicorp.slack.com/archives/C05CBQ2J6J3/p1689625431482409

---

👀 Reviewer's checklist:

• +1 Percy if applicable
• Confirm that PR has a changelog update via Changesets if needed
• Confirm that A11y tests have been run locally for this component

💬 Please consider using conventional comments when reviewing this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
hds-showcase	✅ Ready (Inspect)	Visit Preview	Jul 21, 2023 5:18pm
hds-website	✅ Ready (Inspect)	Visit Preview	Jul 21, 2023 5:18pm

[didoo]

@dstaley I had a quick look at the changes, and I have some thoughts:

• I am not super keen in adding formats to the other "targets" when they're not used (products, devdot) when technically what we want is to add a new export type only for marketing
• I think there is an opportunity to add marketing as a "target", and explicitly set which components you want to use (import later) and potentially even include "base" tokens for marketing if makes sense (something to discuss later, probably)
• I have did a quick test, to make sure what I have in mind actually works (😀) so I am going to send you the git patch in DM so you can play with it and see if makes sense to you too, and maybe even clean up the code/logic (it's been done quickly as a test)

[dstaley]

@didoo Great points! I've refactored the implementation to incorporate your feedback and the patch you sent over (which was super helpful, so thank you!). This new approach adds a platforms configuration option to the target config which allows us to specify the output platforms for each target. products and devdot have ['web/css-variables', 'docs/json'] whereas marketing has ['web/css-variables', 'json']. This PR also enables the marketing target.

[didoo]

@dstaley I love your approach, more neat and the code flows better. Let me review the PR "officially" (I've left already a couple of comments in your last commit).

[didoo]

All good for me. Great work! 🙌

🚢

[didoo]

@dstaley when you want, you can merge the PR (you don't need more approvals, right? or are there other blockers I am not aware of?)