Sync Maturity Levels - Create JSON parser

[Andrew565]

Description

In order to facilitate syncing maturity levels across components, Figma, the Docs site, and Storybook, a parser needs to be created in order to take the component-library/packages/web-components/components-docs.json file and transform it into a format which can easily be read by Figma and the Docs site.

Details

Ideally, the parser should generate a single file which can be read by Figma and the Docs site. This file should match the format expected by the Variables Import Figma plugin. It is recommended to name it component-maturity-levels.json as a potential file name.

Once this file is generated, it will have to be tested in Figma, so loop in the help of one of the designers at that stage.

Making this file work with the Docs site will be taken care of in a separate ticket.

Tasks

• Create a parser which will take in the components-docs.json file and output a *.tokens.json file
• Upload the new tokens file to Figma and ensure that it imports without errors

Acceptance Criteria

• A *.tokens.json file is generated that imports into Figma

[danbrady]

Thanks, @Andrew565 . Great write-up. I think we might want to reconsider the filename. While I think it's a good idea to use the JSON format that matches the expected format, naming the file components.tokens.js might lead to confusion because:

1. These are not really design tokens. We've - or at least I have been - been using the "tokens" and "variables" terms interchangeably. But these values are purely for documentation and would never be used in component design/dev.
2. We have other design tokens and a subset of them are for components. So components.tokens.js could easily be thought of as those, instead of what they really are, maturity labels.
3. In Figma, the filename becomes the name of the "Collection" (which is a way of grouping variables together. So I'm a tad concerned that a components.tokens.js collection could be misinterpreted.
4. We don't and probably never will have these in our Airtable of other tokens, which is our current SoT for tokens.

With that said, what do you think of something like component-maturity.json or even more explicitedly component-maturity-levels.json?

Also, for your reference, this is the current JSON structure in the Figma demo:

{
  "component name": {
    "variable1 name": {
      "$type": "string",
      "$value": "some string value"
    },
    "variable2 name": {
      "$type": "string",
      "$value": "some string value"
    }
  },
  ...
},

Using that format, this is how I mocked the demo JSON (only showing 3 components):

{
  "alert": {
    "category": {
      "$type": "string",
      "$value": "USE"
    },
    "level": {
      "$type": "string",
      "$value": "DEPLOYED"
    }
  },
  "file input": {
    "category": {
      "$type": "string",
      "$value": "USE WITH CAUTION"
    },
    "level": {
      "$type": "string",
      "$value": "AVAILABLE"
    }
  },
  "notification": {
    "category": {
      "$type": "string",
      "$value": "DON'T USE"
    },
    "level": {
      "$type": "string",
      "$value": "DEPRECATED"
    }
  }
}

Lastly, while we have a little flexibility, we can't do any sort of text manipulation to the variable values. That's why you see actual string values in my demo. So for example, we can't directly change a "use_with_caution" value to be "USE WITH CAUTION" in a Figma component. However, there are a few ways we could get around that if it turns out to be difficult to construct a JSON this way. Or if there's a best practice to structure this sort of JSON, we should use that and see if we can rig Figma to use it. So, this is all to say, let's agree on the JSON structure before getting too far ahead of design/dev. :)

[Andrew565]

Looks good, thanks Dan.