Skip to content

Conversation

didoo
Copy link
Contributor

@didoo didoo commented Sep 5, 2025

📌 Summary

This PR builds on top of #3139 to change the format used for our design tokens to follow as much as possible the DTCG format.

We will leverage this new format to introduce the “experimental” $modes object for multi-theme (colocated theme) tokens.

🛠️ Detailed description

In this PR I have:

  • converted src tokens to DTCG format
    • initially I added new files in separate folders, for development, and when everything was working I replaced the old files with the new ones
  • updated main build script so that it would support the new format
    • in the process I have made some changes to the code, at times to bypass some limitations or strange handling of the DTCG format (still in the early stages), in others to simplify/modernize how we process the tokens, and in some cases fixed some logic that didn't work (the throw assertions) but we didn't notice
  • updated the scripts used to generate the CSS helpers to support the new format
  • run pnpm build to make sure the output in dist remained exactly the same
    • except for a couple of JSON files, that were updated because of the new tokens format (see commit comment)
  • updated the website logic for the "foundations/tokens" page, to use the new format of the JSON files

Outcome: apart from the JSON files, all the CSS files have remained exactly the same, which was the goal from the beginning: this gives us confidence that we're not introducing

Website preview: https://hds-website-git-project-solar-phase-1hds-5200s-f936f2-hashicorp.vercel.app/foundations/tokens

🔗 External links

Jira ticket: https://hashicorp.atlassian.net/browse/HDS-5462


👀 Component checklist

  • Percy was checked for any visual regression

💬 Please consider using conventional comments when reviewing this PR.

📋 PCI review checklist
  • If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.
  • If applicable, I've worked with GRC to document the impact of any changes to security controls.
    Examples of changes to controls include access controls, encryption, logging, etc.
  • If applicable, I've worked with GRC to ensure compliance due to a significant change to the in-scope PCI environment.
    Examples include changes to operating systems, ports, protocols, services, cryptography-related components, PII processing code, etc.

Copy link

vercel bot commented Sep 5, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Updated (UTC)
hds-showcase Ready Ready Preview Sep 5, 2025 7:30pm
hds-website Ready Ready Preview Sep 5, 2025 7:30pm

@didoo didoo force-pushed the project-solar/phase-1/HDS-5200_SD-DTCG/dtcg-format-conversion branch from 4fbb473 to 409c144 Compare September 5, 2025 19:26
@hashibot-hds hashibot-hds added the docs-website Content updates to the documentation website label Sep 5, 2025
@didoo didoo marked this pull request as ready for review September 5, 2025 19:29
@didoo didoo requested review from a team as code owners September 5, 2025 19:29
"type": "size",
"$type": "dimension",
"$value": "3px",
"unit": "px",
Copy link
Contributor

@KristinLBradley KristinLBradley Sep 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the value supposed to include the unit as well?

    "$value": "3px",
    "unit": "px",

It shouldn't be formatted as in this example?
https://www.designtokens.org/tr/drafts/format/#example-2
https://www.designtokens.org/tr/drafts/format/#dimension

    "$value": {
      "value": 3,
      "unit": "px"
    },

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs-website Content updates to the documentation website packages/tokens
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants