Skip to content

WEBDEV-9043: Bring the style guide's design tokens into elements - #195

Open
pezvi wants to merge 1 commit into
mainfrom
WEBDEV-9043-design-tokens
Open

pezvi wants to merge 1 commit into
mainfrom
WEBDEV-9043-design-tokens

Conversation

@pezvi

@pezvi pezvi commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

First of the phased PRs that move the style guide into elements. This one brings in the tokens and puts the components on them. The demo restyle and docs pages, and per-component adoption, follow separately.

Tokens. tokens/tokens.json comes from the style guide unchanged apart from its description. scripts/build-tokens.mts generates src/themes/tokens.ts (gitignored, built like src/icons/, before dev, build, test and typecheck). Each token becomes a private alias on :host:

--ia-color-text-primary--: var(--ia-color-text-primary, var(--ia-color-palette-gray-850--));
  • A page overrides a token by setting --ia-color-text-primary on :root or any ancestor. Overriding a palette value carries through every role that points at it.
  • .ia-inverse, inside a shadow root or on the element, re-points text, border, focus, surface, hover and selected for dark surfaces.

themeStyles includes the tokens and takes its defaults from them. Every --ia-theme-* hook still wins. The five old palette names components read directly (--true-white, --mid-gray, --lighter-gray, --lightest-gray, --navy-blue) keep their values; the ten nothing reads are gone.

Visible color changes, per the style guide's decisions:

Role Before After
Secondary button #333 fill, white text, #999 border white fill, #2c2c2c text, #666 border
Link #4b64ff #3a4fd6
Danger button fill / border #d9534f / #d43f3a #e51c23 / #b8161c
Warning button #ee8950 fill, white text #ffb000 fill, #2c2c2c text, #cc7a00 border
--color-success #31a481 #20705a
--color-danger #e51c23 #b8161c
--default-font-family Helvetica Neue, Helvetica, Arial, sans-serif the same, with Noto Sans before the generic sans-serif (D-02)

10px root. Breaking for any consumer on a 16px root, so this ships as a major. Elements now assumes archive.org's html { font-size: 62.5% }, as petabox and offshoot already have.

  • 13 components migrated from 10px-root pages already sized for it. Five (ia-button, ia-icon, ia-otp-form, ia-otp-input, ia-status-indicator) took 16px-basis rem defaults from theme-styles.ts. They now render at the intended size on archive.org: ia-button is 36px tall, not 22.5px.
  • Offshoot's existing overrides in 10px terms (--ia-theme-button-height: 3rem and so on) render as written.
  • The demo and browser tests set the 10px root. Demo and story rem values are scaled by 1.6, so the demo looks as it did. Story controls that mirror 10px-basis component defaults are untouched.

Tests

  • src/themes/tokens.node.test.ts ports the style guide's contrast check: 99 recommended pairings against their WCAG minimum.
  • src/themes/theme-styles.test.ts covers the defaults, page overrides, palette changes carrying through, --ia-theme-* priority, .ia-inverse, and the 36px button.
  • Two size tests were recalibrated to the 10px root.

Before release: install the prerelease in offshoot and collection-browser. Bookreader's root font size is unverified.

🤖 Generated with Claude Code

Move tokens/tokens.json from the style guide and generate
src/themes/tokens.ts from it (`pnpm run tokens`, run before dev, build,
test and typecheck). Each token becomes a private alias on :host, e.g.
var(--ia-color-text-primary--), that a page can override by setting the
public --ia-* name. .ia-inverse re-points the aliases for dark surfaces.

themeStyles now includes the tokens and takes its defaults from them.
Every --ia-theme-* hook still overrides. Colors follow the style guide's
roles, so the link, secondary, danger, warning, success and danger
colors change.

Elements now assumes archive.org's 10px root (html { font-size: 62.5% }).
The theme defaults, ia-button and ia-otp-input move to that basis; the
components migrated from 10px-root pages already used it. The demo and
browser tests set the root, and demo and story rem values are scaled by
1.6 so the demo renders as before.

Port the style guide's contrast check as a node test over tokens.json.

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

Copy link
Copy Markdown
PR Preview Action v1.8.1

🚀 View preview at
https://internetarchive.github.io/elements/pr/pr-195/

Built to branch ghpages at 2026-10-21 21:12 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.31%. Comparing base (7bab08d) to head (cf7c592).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #195      +/-   ##
==========================================
+ Coverage   91.30%   91.31%   +0.01%     
==========================================
  Files         235      235              
  Lines        7465     7465              
  Branches     1639     1639              
==========================================
+ Hits         6816     6817       +1     
- Misses        307      309       +2     
+ Partials      342      339       -3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

This branch has not been deployed

No deployments
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