`init` script for design-tokens

mimarz commented 4 months ago

As an alternative to our design-tokens template repository we should also provide a init or create script for our users to create the same design-tokens files and generic package.json.

This is a planned feature from us and we have also already had feature request from our users after we unveiled our CLI.

Notes:

Init script with prompts for things such as:
- Package name, theme name, npm package for css yes/no
Defining theme name would mean we would need to interop with Token Studios internal/private $theme.json file. This could be brittle as we have no way of knowing when these are changes, and they also use a random id for references.

unekinn commented 4 months ago

As a first step, the script could handle setting up the token sets correctly, and just output some instructions on what to do in Tokens Studio to create a theme (which token sets should be set as source, which should be enabled, etc). This would prevent having to deal with the $theme.json file in the script.

unekinn commented 4 months ago

As a suggestion for what the init script could be:

a package @digdir/create-tokens which can be run with npm init @digdir/tokens
the package's package.json defines a bin field pointing to a node script which handles package creation using a template

An example is Vite's create-vite package.

More info about npm init in the docs

unekinn commented 4 months ago

Defining theme name would mean we would need to interop with Token Studios internal/private $theme.json file. This could be brittle as we have no way of knowing when these are changes, and they also use a random id for references.

From initial testing, it seems that all the autogenerated properties present in the template repo will be generated, if missing, when you click "Styles and variables" > "Create variables" and then push to GitHub. See this branch in my test repo.

So I would think the init script could contain a template without the other properties, e.g.

  {
    "id": "0daa3ca0b427b9349da7e7dc00101b5668972926",
    "name": "Light",
    "selectedTokenSets": {
      "primitives/colors/light/global": "enabled",
      "primitives/colors/light/theme": "enabled"
    },
    "group": "Mode"
  },

etc

Then the tool can instruct the user to open the Tokens Studio and "Create variables" there. This would also work if there is a command to add a new brand to an existing tokens repo.

and they also use a random id for references.

A note on the id field specifically: This seem to be a randomly generated 40-character string. But I have also tested using simple serial ids like "1", "2", and this works fine. Tokens Studio handles this without problems. So my hypothesis is that the tool could simply use serial ids when adding ThemeObjects for $theme.json

mimarz commented 4 months ago

Wicked! Thanks for taking the time to test this @unekinn <3

Not sure when we'll have the time to take this further. We have some other stuff we need to lands first, but this could deffo be something we could do for the V1 release 🤔

Now we would only be vulnerable if they decided to change the format, but that can be easily tested :)

unekinn commented 4 months ago

Here's a working prototype init script. I should add some more instructions about the next steps in Tokens Studio, and add package.json initialization (will be quick to to)

If you're interested, I could try to create a PR in this repo.

mimarz commented 4 months ago

Here's a working prototype init script. I should add some more instructions about the next steps in Tokens Studio, and add package.json initialization (will be quick to to)

If you're interested, I could try to create a PR in this repo.

michael-scott

Wow, really nice work! Just how I imagined! I was also planning on implementing prompts for our migrations and the cli in general, which i saw you used 👏

We are still busy with V1 and a lot of underlying stuff we are still working on, so I won't have much time to look to deep into this atm, but you are free to make a PR ofc <3

We have done a lot of changes to the cli in the RC V1 branch (such as using commanderjs ) so if you want to make a PR for this it needs to be based of branch ~~feat/tokens-v2~~ next, either way this can be a good starting point! 🏃

mimarz commented 3 months ago

Everything related to this should be done based of the next branch.

unekinn commented 3 months ago

Finalized the package.json and "Next steps" instructions (feel free to comment). Will look into creating a PR next week, probably!

unekinn commented 3 months ago

Some further ideas that could be explored:

Under "Customizing the themes", step 4, it would be nice if theme.designsystemet.no could generate the correct theme identifier. Maybe an input field on the page to name the theme, which would also be "saved" in the query params for easy sharing with the share button in the "Kopier tema" popup
Additionally, it would be nice to allow users to input the theme colors as a part of the wizard

mimarz commented 3 months ago

Some further ideas that could be explored:

Under "Customizing the themes", step 4, it would be nice if theme.designsystemet.no could generate the correct theme identifier. Maybe an input field on the page to name the theme, which would also be "saved" in the query params for easy sharing with the share button in the "Kopier tema" popup

Agreed! We had a brief look at this before RC but it means you also need to update the $theme with the new name or have to do it manually afterwards in Token Studio, so we just left it as is for now and planned to purse the init script way of initialising new design-tokens after RC release.

Additionally, it would be nice to allow users to input the theme colors as a part of the wizard

We have big plans for this already :D #1886 #2085 The idea is for @digdir/designsystemet to server as a core for all of Designsystemets logic, and be used across multiple products & implementations!

unekinn commented 3 months ago

After a small break, I have updated to the latest CLI version and I'm now happy with the output. I have tested that the generated instructions work in Figma and code. Here's an example of the generated README.md with next steps.

I'll now start working on a PR based on the next branch!

mimarz commented 3 months ago

After a small break, I have updated to the latest CLI version and I'm now happy with the output. I have tested that the generated instructions work in Figma and code. Here's an example of the generated README.md with next steps.

I'll now start working on a PR based on the next branch!

Sweet!

We have did some changes on the css output and design-tokens yesterday. Haven't updated the template yet, but have a look at it in the next branch for latest format.

Most notably typography has been updated to follow the same token linking structure as colors, so people can assign their own typography and font family per theme.

unekinn commented 3 months ago

We have did some changes on the css output and design-tokens yesterday. Haven't updated the template yet, but have a look at it in the next branch for latest format.

Most notably typography has been updated to follow the same token linking structure as colors, so people can assign their own typography and font family per theme.

Since the script outputs a package.json with reference to the currently published CLI tool, I haven't changed the design tokens structure in my PR, as it would be difficult to test. If you let me know when a new version is published, I'll change the structure to match.

digdir / designsystemet

`init` script for design-tokens #2084