chore: tooling improvements for token authoring and Storybook by lukasoppermann · Pull Request #1368 · primer/primitives

lukasoppermann · 2026-04-30T11:57:24Z

Changes

This PR adds tooling utilities for token validation and extraction, supporting safer token deprecation workflows:

New additions

Husky pre-commit hook — validates tokens before commit
Removed token detection script — identifies and reports deprecated tokens in use
Token name extraction utilities — parses and indexes token identifiers from design files
Integration with lint rule — surfaces token removal issues in CI

Why this matters

These tools help prevent accidental deprecation of active design tokens by catching removals early in the development process.

Files changed

.husky/pre-commit — new pre-commit validation
scripts/checkRemovedTokens.ts — removed token linter
scripts/utilities/extractTokenNames.ts — token parsing utilities
scripts/utilities/extractTokenNames.test.ts — tests for token extraction
scripts/buildFigma.ts — refactored for new tooling support

changeset-bot · 2026-04-30T11:57:31Z

⚠️ No Changeset found

Latest commit: d0a944e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Copilot

Pull request overview

This PR focuses on developer tooling and Storybook/VRT workflow adjustments for token authoring, along with some transformer and documentation updates.

Changes:

Adjusts token/build tooling (removed-token validation, script renames, Husky pre-commit).
Updates Style Dictionary transformers/platform config (transition CSS output, Figma attributes, CSS reference output).
Refactors/updates many Storybook stories and CI workflows for Storybook/VRT.

Show a summary per file

File	Description
src/transformers/transitionToCss.ts	Simplifies transition CSS transform logic.
src/transformers/transitionToCss.test.ts	Removes a unit test case for string timing functions.
src/transformers/figmaAttributes.ts	Removes collection override handling for Figma exports.
src/transformers/figmaAttributes.test.ts	Deletes existing test coverage (file now empty).
src/platforms/css.ts	Changes CSS `outputReferences` behavior.
scripts/utilities/extractTokenNames.ts	Adds a utility to extract token names from parsed token objects.
scripts/utilities/extractTokenNames.test.ts	Adds unit tests for token-name extraction.
scripts/checkRemovedTokens.ts	Adds a git-based validation script to ensure removed tokens are documented.
src/tokens/removed/removed.json	Adds consolidated removed-token mapping file.
src/tokens/removed/color.json	Clears file contents (now empty).
scripts/buildFigma.ts	Removes `collectionOverride` usage when building Figma scales.
package.json	Renames scripts, adds Husky, adds removed-token lint step, changes format script behavior, and changes version.
package-lock.json	Updates lockfile to match package.json script/dependency changes and version rollback.
.husky/pre-commit	Runs removed-token check pre-commit.
playwright.config.ts	Removes local `webServer` auto-start.
e2e/storybook.test.ts	Switches story discovery to `storybook-static/stories.json` and updates snapshot selection logic.
docs/storybook/stories/utilities/getTokensByName.ts	Changes Style Dictionary import style.
docs/storybook/stories/StorybookComponents/ColorPreview/ColorPreview.css	Updates selectors for special casing inset borders across themes.
docs/storybook/stories/Typography/Functional.stories.tsx	Large refactor/duplication of story implementations and table columns.
docs/storybook/stories/Typography/Base.stories.tsx	Refactors table columns inline.
docs/storybook/stories/Size/*.stories.tsx	Refactors multiple tables inline; adjusts labeling and columns.
docs/storybook/.storybook/*	Adjusts Storybook config/features and adds external CSS link.
docs/storybook/package.json	Changes Storybook/Babel dependencies and scripts.
.github/workflows/*.yml	Updates CI/deploy/VRT workflows to match new scripts and install steps.
DESIGN_TOKENS_GUIDE.md	Updates motion guidance and examples.
CHANGELOG.md	Removes the 11.7.1 section (reverts changelog content).
.changeset/proud-flowers-know.md	Removes a changeset describing functional motion tokens.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (1)

docs/storybook/stories/utilities/getTokensByName.ts:6

This should remain a type-only import. Switching from import type to a runtime import will pull style-dictionary into the Storybook bundle; Style Dictionary depends on Node APIs and typically cannot be bundled for the browser, causing Storybook build/runtime failures. Use import type StyleDictionary from 'style-dictionary' (or import the token type from style-dictionary/types) so nothing is emitted at runtime.

Files reviewed: 51/53 changed files
Comments generated: 12

      <h1 className="sr-only" id="sizing">
        Viewport ranges
      </h1>
      <DataTable
-        aria-labelledby="sizing"
+        aria-labelledby="viewports"
        data={data}


+                <div>
+                  <p>
+                    font-weight: <code>{row.original.$value.fontSize}</code>
+                  </p>
+                  <p>
+                    font-size: <code>{row.original.$value.fontSize}</code>
+                  </p>


+                    fontSize: 'var(--text-body-size-medium)',
+                    lineHeight: 'var(--text-body-lineHeight-medium)',
+                    fontWeight: 'var(--base-text-weight-normal',
+                    marginBottom: '0',


 {
  "name": "@primer/primitives",
-  "version": "11.7.1",
+  "version": "11.7.0",


+  const files = fs.readdirSync(REMOVED_DIR).filter(f => f.endsWith('.json') || f.endsWith('.json5'))
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(REMOVED_DIR, file), 'utf-8')
+      const parsed = JSON.parse(content)
+      for (const key of Object.keys(parsed)) {
+        removals.add(key)
+      }
+    } catch (e) {
+      console.warn(`⚠️  Could not parse removed file ${file}: ${e}`)
+    }


+  const blockSizeValueString = getTokensByName(sizeTokens, 'control-medium-size')[0].name
+  const condensedValueString = getTokensByName(sizeTokens, 'control-medium-paddingInline-condensed')[0].name
+  const normalValueString = getTokensByName(sizeTokens, 'control-medium-paddingInline-normal')[0].name
+  const spaciousValueString = getTokensByName(sizeTokens, 'control-xsmall-paddingInline-spacious')[0].name


+          },
+          {
+            header: 'Source value',
+            field: 'original.$value',


+    "build": "npm run clean && npm run build:tokens && npm run build:fallbacks && npm run build:figma && npm run build:config && npm run build:llm",
+    "build:tokens": "tsx ./scripts/buildTokens.ts",
+    "build:fallbacks": "tsx ./scripts/buildFallbacks.ts",
    "build:figma": "tsx scripts/buildFigma.ts",
-    "build:types": "tsc -p build.tsconfig.jsonc && tsx scripts/copyDir.ts src/types dist/build/types",
-    "build:llm": "tsx scripts/buildLlm.ts",
-    "check": "npm run lint && npm run format:check && npm run test && npm run build",
-    "check:contrast": "tsx scripts/colorContrast.ts",
+    "build:config": "tsc -p build.tsconfig.jsonc && tsx ./scripts/copyDir.ts src/types dist/build/types",
+    "build:llm": "tsx ./scripts/buildLlm.ts",
    "clean": "rm -rf dist",
-    "format": "prettier --write '**/*.{js,jsx,ts,tsx,md,mdx,css}'",
-    "format:check": "prettier --check '**/*.{js,jsx,ts,tsx,md,mdx,css}'",
-    "lint": "eslint '**/*.{js,ts,tsx,md,mdx}' --max-warnings=0 --config eslint.config.mjs && npm run lint:tokens",
+    "validate:contrast": "tsx scripts/colorContrast.ts",


-        : cubicBezierArrayToCss(value.timingFunction, token.path)
-
-    return `${value.duration} ${timing} ${value.delay ? value.delay : ''}`.trim()
+    return `${value.duration} ${cubicBezierArrayToCss(value.timingFunction, token.path)} ${value.delay ? value.delay : ''}`.trim()


+[data-dark-theme='dark_high_contrast'],
+.ColorPreview:has([style='background-color: var(--bgColor-inset); border: solid 1px var(--undefined);']) > div {
  border: solid 1px var(--borderColor-default) !important;
 }

-[data-light-theme='light_high_contrast']
-  .ColorPreview:has([style='background-color: var(--bgColor-inset); border: solid 1px var(--undefined);'])
-  > div {
+[data-light-theme='light_high_contrast'],
+.ColorPreview:has([style='background-color: var(--bgColor-inset); border: solid 1px var(--undefined);']) > div {
  border: solid 1px var(--borderColor-default) !important;


- Add husky pre-commit hook for token validation - Add removed token detection script and lint rule - Add token name extraction utilities with tests - Refactor buildFigma to support new token tooling These utilities enable linting and validation of token removal patterns, preventing accidental deprecation of active design tokens. skip-changeset: true Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Agent-Logs-Url: https://github.com/primer/primitives/sessions/62862b8b-5de5-4ab4-87d7-5079352e5c5b Co-authored-by: lukasoppermann <813754+lukasoppermann@users.noreply.github.com>

Copilot

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 6/6 changed files
Comments generated: 4

Copilot · 2026-05-04T08:20:17Z

+function getArg(name: string): string | null {
+  const flag = name.startsWith('--') ? name : `--${name}`
+  const idx = process.argv.findIndex(a => a === flag || a.startsWith(`${flag}=`))
+  if (idx === -1) return null
+  if (process.argv[idx].includes('=')) return process.argv[idx].split('=')[1]
+  // next arg is the value (if it doesn't look like another flag)
+  const next = process.argv[idx + 1]
+  if (next && !next.startsWith('--')) return next
+  return flag
+}


Fixed in 7e94bcd — return flag changed to return null so getArg returns null when a valued flag is provided without a value, instead of treating the flag name itself as the value.

@@ -0,0 +1,2 @@
+BASE_REF="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || printf '%s\n' origin/main)"
+npx tsx scripts/checkRemovedTokens.ts --base "$BASE_REF"


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Agent-Logs-Url: https://github.com/primer/primitives/sessions/641948a0-fd71-40b7-be44-2454938872dd Co-authored-by: lukasoppermann <813754+lukasoppermann@users.noreply.github.com>

* Initial plan * feat: add CI integration for removed token check Agent-Logs-Url: https://github.com/primer/primitives/sessions/c230b8f8-e545-4387-a486-326f7103e1a8 Co-authored-by: lukasoppermann <813754+lukasoppermann@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: lukasoppermann <813754+lukasoppermann@users.noreply.github.com>

Agent-Logs-Url: https://github.com/primer/primitives/sessions/7bc74156-cbd8-4525-a3be-c99027f33c40 Co-authored-by: lukasoppermann <813754+lukasoppermann@users.noreply.github.com>

Copilot AI review requested due to automatic review settings April 30, 2026 11:57

lukasoppermann requested a review from a team as a code owner April 30, 2026 11:57

lukasoppermann requested a review from liuliu-dev April 30, 2026 11:57

Copilot started reviewing on behalf of lukasoppermann April 30, 2026 11:58 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

lukasoppermann added the skip changeset Apply to PRs that should not result in a version bump. label Apr 30, 2026

lukasoppermann force-pushed the feat/token-tooling-improvements branch from 623725d to 15c0e9d Compare April 30, 2026 12:21

lukasoppermann temporarily deployed to github-pages April 30, 2026 12:23 — with GitHub Actions Inactive

github-actions Bot temporarily deployed to Preview (Storybook) April 30, 2026 12:23 Inactive

lukasoppermann force-pushed the feat/token-tooling-improvements branch from 15c0e9d to 564aae3 Compare April 30, 2026 12:25

lukasoppermann temporarily deployed to github-pages April 30, 2026 12:27 — with GitHub Actions Inactive

github-actions Bot temporarily deployed to Preview (Storybook) April 30, 2026 12:27 Inactive

liuliu-dev approved these changes May 1, 2026

View reviewed changes

Copilot started work on behalf of lukasoppermann May 4, 2026 07:59 View session

fix: apply Prettier formatting to color-scales.md

aa876fc

Agent-Logs-Url: https://github.com/primer/primitives/sessions/62862b8b-5de5-4ab4-87d7-5079352e5c5b Co-authored-by: lukasoppermann <813754+lukasoppermann@users.noreply.github.com>

Copilot finished work on behalf of lukasoppermann May 4, 2026 08:01

Copilot AI temporarily deployed to github-pages May 4, 2026 08:05 Inactive

github-actions Bot temporarily deployed to Preview (Storybook) May 4, 2026 08:05 Inactive

lukasoppermann requested a review from Copilot May 4, 2026 08:07

Copilot started reviewing on behalf of lukasoppermann May 4, 2026 08:08 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

Potential fix for pull request finding

4f7ff23

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of lukasoppermann May 4, 2026 08:17 View session

Copilot AI mentioned this pull request May 4, 2026

[WIP] Fix code based on review comment and add CI integration #1372

Merged

3 tasks

Copilot started work on behalf of lukasoppermann May 4, 2026 08:18 View session

lukasoppermann and others added 2 commits May 4, 2026 10:18

Potential fix for pull request finding

6c8df54

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

fix: return null when --base flag has no value in getArg

7e94bcd

Agent-Logs-Url: https://github.com/primer/primitives/sessions/641948a0-fd71-40b7-be44-2454938872dd Co-authored-by: lukasoppermann <813754+lukasoppermann@users.noreply.github.com>

Copilot finished work on behalf of lukasoppermann May 4, 2026 08:21

lukasoppermann temporarily deployed to github-pages May 4, 2026 08:25 — with GitHub Actions Inactive

github-actions Bot temporarily deployed to Preview (Storybook) May 4, 2026 08:25 Inactive

Copilot started work on behalf of lukasoppermann May 4, 2026 08:31 View session

fix: add fetch-depth: 0 to CI checkout step to fix merge-base failure

d0a944e

Agent-Logs-Url: https://github.com/primer/primitives/sessions/7bc74156-cbd8-4525-a3be-c99027f33c40 Co-authored-by: lukasoppermann <813754+lukasoppermann@users.noreply.github.com>

Copilot finished work on behalf of lukasoppermann May 4, 2026 08:35

Copilot AI deployed to github-pages May 4, 2026 08:38 View deployment

github-actions Bot temporarily deployed to Preview (Storybook) May 4, 2026 08:38 Inactive

lukasoppermann merged commit e90ce7a into main May 4, 2026
27 checks passed

lukasoppermann deleted the feat/token-tooling-improvements branch May 4, 2026 08:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: tooling improvements for token authoring and Storybook#1368

chore: tooling improvements for token authoring and Storybook#1368
lukasoppermann merged 7 commits into
mainfrom
feat/token-tooling-improvements

lukasoppermann commented Apr 30, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI May 4, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		@@ -0,0 +1,2 @@
		BASE_REF="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null \|\| printf '%s\n' origin/main)"
		npx tsx scripts/checkRemovedTokens.ts --base "$BASE_REF"

Conversation

lukasoppermann commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

New additions

Why this matters

Files changed

Uh oh!

changeset-bot Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Copilot AI May 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lukasoppermann commented Apr 30, 2026 •

edited

Loading

changeset-bot Bot commented Apr 30, 2026 •

edited

Loading