Skip to content

docs(design): add UI kit and design tokens, auto-generate colour tokens - #988

Open
jacobvjk wants to merge 3 commits into
epic/v2from
docs/design-kit-v2
Open

jacobvjk wants to merge 3 commits into
epic/v2from
docs/design-kit-v2

Conversation

@jacobvjk

@jacobvjk jacobvjk commented Oct 9, 2026

Copy link
Copy Markdown
Collaborator

What

Adds a design reference to docs/design/ so our designer can find it next to the code:

File Purpose
tpr-ui-kit.html Visual reference of every color, type size and reusable component, labeled with the real Tailwind classes. Includes the v2 components from #937 (tabs, scope ribbon, data tables, section panels, notices, sector-segment badge, selectable badges).
tpr-design-tokens.json Tokens Studio file for importing colors, type, radius and shadows into Figma.
README.md How to open the kit (GitHub shows HTML as source), and what stays in sync automatically vs. what is maintained manually.

Keeping tokens in sync

  • New script scripts/build-design-tokens.ts (npm run tokens:build) regenerates the color group of the token file from the @theme block in src/index.css. Other groups (type scale, radius, shadows: Tailwind defaults not defined in our CSS) and color descriptions are hand-maintained and carried over.
  • New CI job "Check design tokens match src/index.css" in node-build-committed-files.yml, modeled on the existing timeseries index check. It fails if a color changes without regenerating the file.
  • The UI kit HTML is a hand-maintained snapshot. The README asks that component changes update it in the same PR.

Not part of the site

Nothing in docs/ is imported or copied by Vite. I ran npm run build and confirmed none of these files appear in dist/.

Testing

  • npx vitest run scripts/build-design-tokens.test.ts: 6 tests pass
  • prettier --check ., eslint on the new script, and the forbidden-patterns terms are all clean
  • Drift test: changing a color in src/index.css without regenerating makes the check fail with the exact value diff. Regenerating on this branch reproduces the committed file byte-for-byte.

For reviewers

  • Should the new CI job be a required check? I didn't change any branch rulesets.
  • When epic/v2 merges into main, remove the "not yet live" note at the top of the UI kit, as the README describes.

🤖 Generated with Claude Code

…om index.css

Add docs/design/ so the designer can find the UI reference next to the code:
- tpr-ui-kit.html: visual reference of tokens and components, incl. v2 (#937)
- tpr-design-tokens.json: Tokens Studio file for Figma
- README.md: how to open the kit, and what is automatic vs. manual

The colour group of the token file is generated from the @theme block in
src/index.css by `npm run tokens:build`; other groups and colour
descriptions are hand-maintained and carried over. A new CI job in
node-build-committed-files.yml fails when the committed file is stale.

Nothing in docs/ is bundled into the site build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown

Expected version change and release notes

🚨 WARNING: This PR is not expected to trigger a new version

To trigger a version bump, use at least one conventional commit message in this branch. See: https://www.conventionalcommits.org/en/v1.0.0/

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown

Azure Static Web Apps: Your stage site is ready! Visit it here: https://proud-glacier-0f640931e-988.westus2.2.azurestaticapps.net

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The Figma handoff contains invalid sample JSON and several token and component values that do not match the documented source styles.

4 open findings
What changed in this PR

Adds a code-adjacent design reference and automated color-token synchronization for Figma handoff.

Changes:

  • Adds a UI kit and Tokens Studio design-token file.
  • Adds token generation, tests, and an npm command.
  • Adds CI drift detection and maintenance documentation.
File Description
scripts/​build-design-tokens.ts Generates color tokens from Tailwind theme CSS.
scripts/​build-design-tokens.test.ts Tests parsing and token preservation.
package.json Adds the token build command.
docs/​design/​tpr-ui-kit.html Provides the visual component reference.
docs/​design/​tpr-design-tokens.json Defines Figma-compatible design tokens.
docs/​design/​README.md Documents usage and synchronization responsibilities.
.github/​workflows/​node-build-committed-files.yml Checks committed tokens for drift.

🧠 Review effort: Balanced


💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread docs/design/tpr-design-tokens.json
"type": "borderRadius"
}
},
"boxShadow": {
Comment thread docs/design/tpr-ui-kit.html Outdated
Comment on lines +1391 to +1395
shipping in the TPR front end, pulled directly from
<code>src/index.css</code> and <code>src/components/</code> — not
redrawn from memory. Each entry carries the real Tailwind class
names and CSS custom properties, so a Figma file built from this
stays traceable back to the code that renders it.
Comment thread docs/design/tpr-ui-kit.html
- Tokens: add the missing 5xl line-height (48px) and give shadow-sm/md/lg
  both layers of Tailwind's composite shadows.
- UI kit: rebuild the Pathway card preview from PathwayCard.tsx classes
  (padding, type sizes, label style, button layout). The 1.5°C temperature
  cell is pinishgreen-100 per getTemperatureColor, not rmired-100; same fix
  in the condensed scope ribbon. Default badge border is rmigray-200.
- UI kit: the Tokens Studio sample is now valid JSON, and the step points
  at the real file instead.
- UI kit: the intro no longer claims previews are exact; tags win.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown

Expected version change and release notes

🚨 WARNING: This PR is not expected to trigger a new version

To trigger a version bump, use at least one conventional commit message in this branch. See: https://www.conventionalcommits.org/en/v1.0.0/

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown

Azure Static Web Apps: Your stage site is ready! Visit it here: https://proud-glacier-0f640931e-988.westus2.2.azurestaticapps.net

Compared each preview with its source and corrected the drift:
- Primary button: 16px regular text (no text-* class), label "Download".
- Search box: 2px focus ring, 20px gray-400 icons, 16px text at desktop.
- Filter dropdown: gray-300 border, composite shadow-sm, "Sector..." when
  inactive, bold ": 3" when active; panel spacing, gray-200 border and
  12px uncoloured text actions as in DropdownFacetShell/MultiSelectDropdown.
- Range slider: gradient, covers, 1px handle border with ring-2 + shadow-md,
  12px ticks; it is used on the step-by-step guide pages, not the search
  page's temperature filter (that one uses number fields).
- Sentiment/neutral scales: 4px radius; the first bar was not faded and the
  label used the wrong colour; label names the selected value.
- Tooltip: 4px radius, opacity-95, arrow, real availability copy.
- Highlight: 4px radius (rounded-sm in Tailwind v4).
- Header: real nav (Contact Us, Resources), sizes and logo placement.
  Footer: logo row, links with mail icon, separate copyright row.
- Removed the Accordion section: AccordionItem has no callers on epic/v2
  since ba2dbc2.
- v2 previews: no divider above the ribbon's tabs, gray-200/300 borders on
  the column geography select, real footnote and empty-state copy, Badge's
  mr-2 mb-1 spacing, key-feature pick-lists show every option with the
  unselected style.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown

Expected version change and release notes

🚨 WARNING: This PR is not expected to trigger a new version

To trigger a version bump, use at least one conventional commit message in this branch. See: https://www.conventionalcommits.org/en/v1.0.0/

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown

Azure Static Web Apps: Your stage site is ready! Visit it here: https://proud-glacier-0f640931e-988.westus2.2.azurestaticapps.net

@jacobvjk
jacobvjk requested a review from AlexAxthelm October 9, 2026 12:28
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.

2 participants