AuroDocsSite Token/WCSS Loading Compliance

[jordanjones243]

Status	Draft for review
Area	AuroDocsSite (React + Vite documentation site)
Related	ADO #1255504 — theme-compliance tech-debt ticket (filed May 2025)
Estimated effort	~2–3 days (docsite only)
Reference implementation	auro-formkit test/dev harness

---

1. Context

Released versions of design-tokens and WCSS are hand-copied into Content Stack before Test/QA/Prod
actually consume them. As a result, the deployed environments can lag behind what Design has published on
npm/CDN — there may be token versions on @latest that are not yet live in Test/QA/Prod.

For pre-release theme testing to be meaningful, the docsite (and the component repos' localhost and test
environments) must run against the same token/WCSS version that is actually deployed — i.e., the version
installed as a dev dependency in the repo. They must never fetch tokens/WCSS from a CDN @latest
URL, because @latest can resolve to a version that is not yet in the target environment, so local
results would not match what ships.

The problem is therefore about how tokens are loaded per environment, not which token names the CSS
uses. The auro-formkit repo already follows the correct pattern and is the reference (see §4).

Acceptance Criteria

Localhost, test and docsite all render using the installed version of DesignTokens and
WebCoreStylesheets. They should not use a CDN reference in any case.

Definition of "theme compliant" for this ticket: the environment renders using the installed
dev-dependency versions of DesignTokens and WebCoreStylesheets, with zero CDN references. This is a
loading guarantee — it is not a statement about which token names the CSS uses or whether every surface
re-themes.

Two consequences for scope:

• No CDN reference in any case — this is broader than @latest. Every CDN URL for DesignTokens /
  WebCoreStylesheets must be removed, including the ones currently pinned to the installed version
  (§2.4). The only acceptable source is the installed dev dependency.
• Three targets — the AC covers component-repo localhost, component-repo test, and the
  docsite. This TRD delivers the docsite target; localhost and test live in the individual
  component repos and are tracked separately (§5), using the FormKit harness as the template.

2. Current State

The docsite is a hybrid: the main site loads tokens/WCSS from the installed dev dependency, but the
typography section fetches them from CDN @latest.

2.1 Already correct — served from the installed dev dependency

The Vite plugin copyDepFiles (vite.config.js) serves /tokens/* from
node_modules/@aurodesignsystem/design-tokens/dist and /styles/* from
node_modules/@aurodesignsystem/webcorestylesheets/dist in dev, and copies them into dist/ on build.
These consumers use it correctly:

• index.html — links /tokens/web/alaska.min.css and /styles/bundled/themes/alaska.global.min.css.
• src/components/header/ThemeSwitcher.js — swaps /tokens/web/{theme}.min.css and
  /styles/bundled/themes/{theme}.global.min.css (installed versions).
• src/App.js — imports token CSS directly from node_modules.

2.2 Violations — CDN @latest fetches (runtime)

The typography preview path fetches from CDN @latest, so it can render against tokens/WCSS that are not
deployed:

File	Line	Fetches from CDN @latest
src/config/themes.js	6–7	CDN_URL + webcorestylesheets@latest/dist/bundled/themes (WCSS_THEME_PATH, used by getThemeCssUrl)
src/content/dynamic/typography/ThemedPreviewFrame.js	5	design-tokens@latest/.../CSSCustomProperties--bundled.css
″	6	webcorestylesheets@latest/dist/elementDemoStyles.css
″	9	auro-header@latest/dist/auro-header__bundled.js

ThemedPreviewFrame renders inside an <iframe> and injects these links/scripts into it, plus the WCSS
theme URL from config/themes.js (getThemeCssUrl). All resolve to @latest.

2.3 Displayed code samples that teach @latest (documentation quality)

src/content/dynamic/typography/overview.js (lines 93–94, 136–137) shows <link … webcorestylesheets@latest …> / design-tokens@latest inside <pre><code> blocks. These are not runtime loads, but they
document the wrong pattern to consumers and should be corrected for consistency.

2.4 Pinned-version CDN fallbacks (in scope — AC forbids any CDN reference)

renderComponentPage.js (lines 175, 231) and renderFormkitComponentPage.js (lines 168, 210) build
cdn.jsdelivr.net/...@{installedVersion} URLs for demo markdown and a custom-{name} bundle. They are
pinned to the installed version (not @latest) and largely dead — component pages set markdownContent
via a local import, and registerCustomComponent is a no-op (never assigns .src). Even so, the AC
("no CDN reference in any case") requires their removal.

2.5 Other CDN references (decision needed)

index.html (line 76) loads the @webcomponents/webcomponentsjs polyfill from unpkg.com (pinned @2).
It is not DesignTokens/WCSS, so it is outside the AC's literal subject — but "no CDN reference in any
case" may be intended literally. Flag for a decision: leave as-is, or vendor it from the installed
dependency. The auro-header@latest script in §2.2 is a component (not tokens/WCSS) but is on @latest
and must be addressed regardless.

3. Proposed Work

1. Repoint the typography preview to installed versions. In ThemedPreviewFrame.js and
   config/themes.js, replace the @latest CDN URLs with the locally-served paths already provided by the
   copyDepFiles plugin (/tokens/..., /styles/...) or direct node_modules imports. Covers the tokens
   bundle, WCSS theme CSS, and elementDemoStyles. (~1 day.)
2. Register auro-header in the iframe from the installed package rather than the auro-header@latest
   CDN script (the component is already a dev dependency and registered in the main document; the iframe
   needs it defined in its own context). (~0.5 day — iframe custom-element registration is the fiddly part.)
3. Remove the pinned-version CDN fallbacks in renderComponentPage.js / renderFormkitComponentPage.js
   (and the no-op registerCustomComponent) — required by the AC, not optional. (~0.25 day.)
4. Update the overview.js code samples to show the installed-dependency pattern instead of @latest.
   (~0.25 day.)
5. Decide on non-token CDN references — the unpkg webcomponentsjs polyfill (§2.5); confirm whether the
   AC's "no CDN in any case" applies and vendor from the installed dependency if so. (~0.25 day if in scope.)
6. Guard against regressions + verify build. Confirm vite build ships local /tokens and /styles
   in dist/, and add a CI check (grep/lint) that fails on any cdn.jsdelivr.net / unpkg.com URL
   referencing design-tokens or webcorestylesheets in src — not just @latest. (~0.5 day.)
7. Regression check. The docsite has no automated test infrastructure — the test script is a
   no-op (echo "No tests specified" && exit 0) — so theme/visual regression is necessarily manual.
   The credible automated gate is the CI grep guard from step 6 (fails the build on any CDN token/WCSS
   URL); pair it with a manual pass over the typography preview and the switcher across themes. (~0.5 day
   manual; establishing real visual-regression coverage is a larger, separate effort.)

Total: ~2–3 days for the docsite loading fix. No per-component docsite changes are required; the change
is confined to the typography path plus shared build/config. Standing up automated visual-regression testing
is explicitly not included and would be a separate effort.

4. Reference Implementation (auro-formkit)

FormKit pins tokens/WCSS to the installed dev dependency in its test/dev harness — the pattern to mirror:

• packages/config/src/web-test-runner.config.mjs (and …-global.mjs) inject:

  <link rel="stylesheet" href="/node_modules/@aurodesignsystem/design-tokens/dist/legacy/auro-classic/CSSCustomProperties.css">
  <link rel="stylesheet" href="/node_modules/@aurodesignsystem/design-tokens/dist/web/alaska.css">

• packages/config/src/demo-styles.scss imports WCSS from the installed package
  (@aurodesignsystem/webcorestylesheets/dist/...), not a CDN.

The docsite's equivalent of "serve from node_modules" is the existing copyDepFiles Vite plugin; the fix
is to route the typography path through it instead of CDN @latest.

Note: FormKit's raw components/*/demo/*.html files still contain @latest CDN links, so the pinning
lives in the dev/test harness, not the demo HTML. Confirm the exact intended mechanism with the lead
before mirroring, and treat the harness configs (above) as the source of truth.

5. Related / Out of Scope

• Component repos' localhost & test environments (auro-button, auro-alert, etc.) need the same
  installed-dev-dependency loading. That work lives in each component repo, not this one — track separately,
  using the FormKit harness as the template. This TRD covers the docsite only.
• Content team's rendering-content-sdk (strategic follow-up). Once this fix lands, the docsite could
  adopt the Content team's rendering SDK so tokens load the same way production actually resolves them,
  rather than the docsite maintaining its own local-serving mechanism. Tracked under
  ADO #1603135. A longer-term
  alignment, not required to satisfy this ticket's AC.

Future theming improvements (not this ticket)

A few adjacent items worth a follow-up:

• Granular theme application. The token themes now support applying color and type independently
  (the themed files expose --ds-basic-color / --ds-advanced-color separately from --ds-basic-type).
  The theme switcher should offer the same choice — apply an entire theme, just the colors, or just the
  type.
• Typography re-themes on switch. The header ThemeSwitcher swaps :root token files but never sets a
  data-aag-theme attribute or swaps the typography type classes (classes.{theme}.css), so type styles
  do not currently re-theme on switch. (This is a prerequisite for the type-only option above.)
• Unify the two implementations. The site has two separate theming mechanisms — the header's :root
  file-swap and the typography preview's attribute model — that could be unified to prevent drift.

6. Appendix — key files

Concern	File
Local token/WCSS serving (correct mechanism)	vite.config.js (copyDepFiles)
Correct consumers (installed versions)	index.html, src/components/header/ThemeSwitcher.js, src/App.js
CDN @latest violations (fix target)	src/config/themes.js, src/content/dynamic/typography/ThemedPreviewFrame.js
@latest in displayed code samples	src/content/dynamic/typography/overview.js
Pinned-version CDN fallbacks	src/functions/renderComponentPage.js, renderFormkitComponentPage.js, src/content/utils/registerCustomComponent.js
Non-token CDN reference (decision)	index.html (unpkg webcomponentsjs polyfill)
Reference implementation	auro-formkit/packages/config/src/web-test-runner.config.mjs, demo-styles.scss

[jason-capsule42]

This TRD looks great and covers all the aspects I can think of.