AB#1612078 — Data-attribute theme scoping for type CSS custom properties

[jason-capsule42]

AB#1612078

Executive Summary

WebCoreStyleSheets (WCSS) previously shipped each visual theme's typography settings as a
separate stylesheet with no way to switch typography themes within a single page. This work
adds a standard "data attribute" hook so a consumer can activate any theme's typography on
part of a page — and bundles every theme's typography into each themed stylesheet so switching
between them no longer requires loading multiple files. The change is additive for typography:
existing pages render exactly as before unless they opt in to the new hook. It mirrors the same
scoping convention already shipped by AuroDesignTokens, keeping the two systems aligned.

A follow-up hardening pass closed a release-blocking gap that would have broken every downstream
Sass consumer on the next publish, and removed leftover files so the shipped package reflects the
new architecture cleanly.

Two follow-on decisions were made during the work at the team's direction: the Auro 2 theme
was fully removed from the build, and the Auro 1 theme's attribute code was set to atm.

Ticket: AB#1612078

The Problem

WCSS builds one bundled stylesheet per theme (Alaska, Alaska Classic, Auro 1, Auro 2, Hawaiian).
Each file exposed its typography settings under a single global scope, so there was no way to say
"use Alaska typography here, Hawaiian typography there" on the same page, and no way to switch a
theme's typography without swapping out the whole stylesheet. AuroDesignSystem's tokens already
solved this with a per-theme attribute selector; WCSS had no equivalent, leaving the two systems
inconsistent for anyone using both.

Root Cause

The type custom properties were emitted under a flat, unscoped :root {} block by
generate-theme-type-css-vars in src/type/mixins/_type-generator.scss, invoked once per theme
from generate-theme in src/type/mixins/_theme-generator.scss. Because the only selector was
:root, there was no attribute-based hook a consumer could target, and each themed bundle
(src/bundled/themes/theme.global.template.scss → dist/bundled/themes/*.global.css) contained
only its own theme's variables. Nothing in the pipeline knew each design-tokens theme's short
"code," so it could not construct the [data-aag-theme=…] selectors that AuroDesignTokens uses.

A second, latent cause surfaced in review: the fix depends on a generated, git-ignored Sass
partial (src/type/mixins/_theme-codes.scss). Nothing regenerated it at publish time, and the CI
release job restores a build cache that does not include src/. On a fresh npm publish the file
would be physically absent from the working tree, so — although .npmignore does not exclude it —
npm would ship a package missing the partial, and every downstream Sass consumer would hit a fatal
Can't find stylesheet to import: theme-codes.

The Fix

• Theme codes are sourced, not hardcoded. A new codegen step,
  scripts/theme-codes.build.mjs, reads THEME_DEFINITIONS from
  @aurodesignsystem/design-tokens and writes a Sass map partial
  (src/type/mixins/_theme-codes.scss, git-ignored) mapping each theme directory to its code.
  This keeps WCSS aligned with design-tokens instead of drifting from a hand-maintained list.
• Scoped selector builder. src/type/mixins/_type-generator.scss gained
  wcss-type-scope-selector($theme-name, $include-root), which emits both the base
  [data-aag-theme="aag-theme-<code>"] and the -type suffixed selector, optionally prefixed
  with :root for the file's default theme. A new generate-multi-theme-type-css-vars mixin
  emits the default theme under :root + its attributes and every other theme under its
  attributes only.
• Multi-theme bundles. New entry files src/bundled/type/themes/<theme>.scss plus the
  aggregated src/bundled/type/themes/_all-theme-configs.scss compile to
  dist/bundled/type/themes/<theme>.css (+ .min) via a loop added to
  scripts/type.classes.css.build.mjs. The global template
  (src/bundled/themes/theme.global.template.scss) was updated to import the multi-theme type
  vars (all themes) plus the theme-agnostic typography classes, so each *.global.css now
  carries every theme's typography with its namesake as the :root default.
• Publish safety (prepack). A prepack script (node scripts/theme-codes.build.mjs) was
  added to package.json, so npm regenerates the git-ignored partial into the working tree
  immediately before packing during npm publish (which semantic-release invokes). This
  guarantees the file is present in the published package regardless of what the CI build cache
  contains — closing the release-blocking gap above.
• Build wiring & de-dup. build:theme-codes runs first in the build and test flows so the
  generated map exists before any Sass compile. The duplicate invocation was removed from
  build:dist-bundle (which is only ever called from build), so the codegen no longer runs
  twice per build.
• Tests. tests/typeThemeScoping.spec.scss (sass-true) asserts the scoped selectors for
  Alaska, Hawaiian, and Auro 1, the :root-only fallback for an unknown theme with :root
  included, and the same unknown-theme fallback with :root excluded (the null-code branch
  short-circuits before $include-root is consulted).
• Package cleanup. Four orphaned per-component subdirectories under
  src/bundled/type/themes/ (alaska/, alaska-classic/, auro-1/, hawaiian/ — each with
  accent/body/display/heading files using the older @use … as v + individual-config
  pattern) were deleted; nothing in the codebase imported them, and they would have shipped in the
  package alongside the new flat bundles and misled maintainers. _all-theme-configs.scss gained a
  maintenance comment noting it is a static manifest while theme discovery elsewhere is
  dynamic, so adding a theme requires updating it by hand or the multi-theme bundles silently omit
  the new theme.
• Auro 2 removal (team direction). A shared scripts/excluded-themes.mjs filter removes
  Auro 2 from all three theme-driven build scripts; all Auro 2 source directories/partials and
  its entries in _all-theme-configs.scss and src/config/_index.scss were deleted.
• Auro 1 code override (team direction). scripts/theme-codes.build.mjs includes a
  THEME_CODE_OVERRIDES map setting Auro 1's emitted code to atm (rather than design-tokens'
  a1), so its selectors are aag-theme-atm / aag-theme-atm-type.

Why This Works

The :root output is retained for every theme, so the cascade for existing consumers is
unchanged — the attribute selectors are purely additive and only take effect when a consumer sets
data-aag-theme on an element. Deriving the selector from design-tokens' own THEME_DEFINITIONS
means the WCSS attribute value matches AuroDesignTokens for the same theme, so both systems can be
driven by one attribute. Because each theme's type-config Sass variables are uniquely named, all
themes' variables coexist in one file without collision, which is what makes the multi-theme
"switch within one stylesheet" output safe. The typography classes are theme-agnostic (they
reference the custom properties), so emitting them once per bundle keeps output correct and
non-duplicated.

The prepack step is what makes the "non-breaking for existing consumers" guarantee actually
hold at publish time: because the generated partial is regenerated from the source of truth right
before packing, it is deterministic and cannot go stale, and Sass-source consumers can import the
type mixins on a fresh install without a compile error. Centralizing both the exclusion list and
the code override in single, commented locations keeps the theme list otherwise fully derived from
design-tokens.

Outcome

• Each themed stylesheet now lets a consumer scope or switch any theme's typography within a
  single page via the data-aag-theme attribute, matching AuroDesignTokens' convention.
• Default rendering is unchanged for typography — the new selectors are opt-in.
• The published package now contains the generated theme-codes partial, so downstream Sass
  consumers compile cleanly on the next release (the release-blocking gap is closed).
• Leftover per-component theme files no longer ship, so the package reflects the flat multi-theme
  bundle architecture without misleading dead files.
• Auro 2 no longer ships in any build output.
• Auro 1's typography activates under the atm attribute code.
• The full build passes and the automated test suite is green (50/50).

Ticket Completeness

3 of 4 acceptance criteria resolved; 1 partial (color decision deferred without a TRD). Note
that scope was intentionally broadened beyond the ticket (all themes scoped, not just three;
multi-theme-per-file output; Auro 2 removed; Auro 1 code overridden), at the team's direction
during the work.

Resolved

• Attribute selectors wrap type custom properties for Alaska, Hawaiian, and Auro 1, additive to
  :root. Delivered via wcss-type-scope-selector() and the multi-theme mixin; :root output
  retained for all themes.
• Existing consumers see no change in rendered typography (non-breaking). The scoped selectors
  are additive; :root blocks are unchanged. The prepack fix ensures this holds at publish time
  for Sass-source consumers, who would otherwise have hit a fatal missing-import error.
• sass-true spec(s) assert the new type attribute selectors for Alaska, Hawaiian, and Auro 1.
  Added in tests/typeThemeScoping.spec.scss (passing), including both unknown-theme fallback
  paths.

Not Resolved / Partial

• A decision is documented (via TRD) on whether/how color scoping is achieved. Partial.
  Color was correctly treated as out of scope (WCSS bakes color to literals at compile time, so
  there is nothing to attribute-scope yet), but no TRD was produced to formally document the
  decision — it lives only in the ticket and this session. A follow-up TRD/ticket is still owed.
• Non-breaking across the whole change set. Caveat, not a ticket miss. The typography
  scoping is non-breaking, but two team-directed additions are breaking beyond the ticket: any
  consumer importing type/themes/auro-2 (now deleted) or relying on Auro 1's a1/aag-theme-a1
  selectors (now atm) is affected. These fall outside the original acceptance criteria and were
  explicit later requests.

Learnings

• Derive from the source of truth. Reading theme codes from design-tokens'
  THEME_DEFINITIONS at build time avoids a hand-maintained list drifting out of alignment — the
  same principle applied to the exclusion filter and the code override, each centralized in one
  place.
• A git-ignored generated file needs a prepack/prepublishOnly hook to actually ship. It is
  not enough that .npmignore allows the file and src/ is published — npm only packs what is
  physically in the working tree at pack time. CI restores a cache that excludes src/, so the
  generated partial was absent on a fresh release. Regenerating it in prepack (not postinstall,
  which is excluded from the package and would break consumer installs) is the reliable fix.
• Static manifests hidden inside a dynamic pipeline drift silently. _all-theme-configs.scss
  is hand-maintained while the build scripts discover themes dynamically; without a comment
  flagging that, adding a theme would produce incomplete multi-theme output with no build error. A
  visible maintenance note is the cheapest guard.
• Delete dead files with the feature, not later. The old per-component theme subdirectories
  were superseded by the flat bundles but left behind; they shipped in the package and invited
  confusion. Removing them as part of the change keeps the published surface honest.
• Confirm output shape early. The first implementation scoped only the *.global.css files
  single-theme; the intended deliverable was multi-theme output under dist/bundled/type/*.
  Pinning down "which files, what shape" before building would have avoided a rework.
• A stated alignment goal can be overridden by product choice — record the tension. The ticket
  wanted the attribute naming aligned with AuroDesignTokens (which uses a1 for Auro 1), but the
  team chose atm. That divergence is intentional but worth flagging for anyone using both
  systems, since it defeats the "one attribute drives both" benefit for that theme.
• Report ground truth over an edited expectation. When a test assertion was changed to expect
  a value the tokens didn't support, verifying against THEME_DEFINITIONS (rather than trusting
  the edit) surfaced the conflict for an explicit decision instead of silently encoding a wrong
  value.

Iterations That Didn't Work

• Single-theme scoping in the global files only. The initial attempt added the attribute
  selectors just to dist/bundled/themes/*.global.css, each carrying only its own theme. This
  was rejected: the deliverable needed the scoped selectors in dist/bundled/type/* and needed
  every theme included per file for runtime switching. Superseded by the multi-theme mixin and the
  per-theme entry files.
• Assuming the generated partial ships because src/ is published. An early reading concluded
  the theme-codes partial would ship simply because the package includes src/. Review disproved
  this — the file is git-ignored and absent from CI's restored cache at publish time — and the
  prepack regeneration replaced that assumption.
• Auro 1 code as a1, then as atm. design-tokens defines Auro 1's code as a1, and an
  early test edit expected an unrelated atm value; that assertion was first corrected back to
  a1 after validating the tokens. The team then explicitly required atm as an intentional
  override, which was implemented via THEME_CODE_OVERRIDES and the spec updated to match.