Skip to content

feat(kv-tokens)!: migrate to Style Dictionary v4 pipeline#807

Open
mcstover wants to merge 20 commits intomainfrom
feat.reformat-with-style-dictionary
Open

feat(kv-tokens)!: migrate to Style Dictionary v4 pipeline#807
mcstover wants to merge 20 commits intomainfrom
feat.reformat-with-style-dictionary

Conversation

@mcstover
Copy link
Copy Markdown
Collaborator

@mcstover mcstover commented Apr 15, 2026

Summary

This update installs StyleDictionary laying the groundwork for future import of Figma based design tokens AND providing us a versatile tool to create various exports from our design tokens/variables such as automated creation of incoming skill reference files.

  • Replaces the hand-authored primitives.js with W3C DTCG JSON under tokens/core/ (primitives) and tokens/semantic/themes/ (themes).
  • Style Dictionary v4 generates dist/js/tokens.js, dist/css/tokens.css, and dist/scss/tokens.scss from those JSON sources via custom formats/transforms in build/.
  • Adds an exports map so consumers can reach tokens at @kiva/kv-tokens, @kiva/kv-tokens/tokens, @kiva/kv-tokens/tailwind, @kiva/kv-tokens/css, and @kiva/kv-tokens/scss.
  • kivaColors.js, kivaTypography.js, tailwind.config.js, build.js, kivaHeadingUnderline.js, and index.js now consume the generated tokens module. Default export shape is byte-identical to the old primitives.js (parity-verified before deletion).

Breaking changes

  • Legacy dist/kvui/tw-exported-vars.scss is no longer generated. Consume SCSS via @kiva/kv-tokens/scss instead.
  • SCSS variable names follow Style Dictionary's kebab-case convention (e.g. $color-brand-default instead of $colors-brand-default).
  • primitives.js has been removed. The default export of @kiva/kv-tokens still resolves to the same nested shape, so existing JS/Vue imports continue to work unchanged.

The feat!: + BREAKING CHANGE: footer on commit eec0d687 will trigger Lerna to bump @kiva/kv-tokens to v4.0.0 on release.

Test plan

  • npm run build succeeds across the monorepo
  • npm run lint clean
  • npm run test — 810 tests passing, 0 failures
  • kv-components build emits CSS using our custom properties (rgb(var(--text-primary)))
  • End-to-end marker test: edited tokens/semantic/themes/default.json text.primary → magenta, rebuilt, verified color flashed in Storybook, reverted
  • All three subpath exports resolve: @kiva/kv-tokens, @kiva/kv-tokens/tokens, @kiva/kv-tokens/tailwind

Next Steps

IMPORTANT!!! Merging this will create a major version bump of kv-tokens which will require a "migration" update for kv-components, cms-page-server and ui when the new version is installed.

  • These updates are minor in most cases and deal with updating the import location and the accessor for whatever primitives property is in use.
  • I've already tested locally the build of kv-components and it's storybook using these updates to ensure parity with existing styles
  • Chromatic + Storybook visual review across each app

mcstover added 17 commits April 15, 2026 11:29
BREAKING CHANGE: The legacy tw-exported-vars.scss artifact is no longer
generated. Consume SCSS tokens via the new `@kiva/kv-tokens/scss` subpath
(served from dist/scss/tokens.scss). SCSS variable names now follow
Style Dictionary's kebab-case convention (e.g. $color-brand-default
instead of $colors-brand-default). Design tokens are now generated by
Style Dictionary from tokens/core/*.json + tokens/semantic/themes/*.json;
the hand-authored primitives.js has been removed.
@mcstover mcstover requested review from a team, dyersituations, eddieferrer and emuvente April 16, 2026 00:17
Copy link
Copy Markdown
Collaborator

@dyersituations dyersituations left a comment

Choose a reason for hiding this comment

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

Lots of changes, but nothing seems obviously wrong. Will the apps need to change imports when the packages are updated?

@mcstover
Copy link
Copy Markdown
Collaborator Author

Lots of changes, but nothing seems obviously wrong. Will the apps need to change imports when the packages are updated?

Yes we will need to make updates to the app. Noted in the Next Steps section of the Description.

@dyersituations
Copy link
Copy Markdown
Collaborator

Lots of changes, but nothing seems obviously wrong. Will the apps need to change imports when the packages are updated?

Yes we will need to make updates to the app. Noted in the Next Steps section of the Description.

Nice! I didn't see that originally in the description. Sounds good.

Copy link
Copy Markdown
Collaborator

@emuvente emuvente left a comment

Choose a reason for hiding this comment

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

Awesome!

@mcstover
Copy link
Copy Markdown
Collaborator Author

A note on status here. I've fixed a couple of DX issues and added an addition tokens export. I've been testing this in the next branch and verified locally in CPS with UI pending.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants