feat(type): add data-attribute theme scoping for type custom properties AB#1612078

[jason-capsule42]

Post-Mortems

AB#1388992

Post-mortem discussion: #295

The WebCoreStyleSheets feature documentation pages linked out to the old Orion design system website for their "see the documentation" references. That site was retired when the team completed its move from Orion to Auro, so every one of those links returned a "page not found" error. This change repoints all of those references to the current, live WebCoreStyleSheets documentation site, so readers can once again follow them and land on the correct reference material.

Tracked in AB#1388992.

AB#1612078

Post-mortem discussion: #293

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

---

Alaska Airlines Pull Request

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.

Resolves: # (issue, if applicable)

Summary:

Please summarize the scope of the changes you have submitted, what the intent of the work is and anything that describes the before/after state of the project.

Type of change:

Please delete options that are not relevant.

• New capability
• Revision of an existing capability
• Infrastructure change (automation, etc.)
• Other (please elaborate)

Checklist:

• My update follows the CONTRIBUTING guidelines of this project
• I have performed a self-review of my own update

By submitting this Pull Request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Pull Requests will be evaluated by their quality of update and whether it is consistent with the goals and values of this project. Any submission is to be considered a conversation between the submitter and the maintainers of this project and may require changes to your submission.

Thank you for your submission!

-- Auro Design System Team

Summary by Sourcery

Enable data-attribute-scoped typography themes with runtime switching while modernizing Sass module usage and preserving default theme behavior.

New Features:

• Add data-attribute scoping for typography custom properties and include all supported themes in each bundled theme stylesheet, enabling runtime theme switching within a page.
• Add shared typography classes that consume the scoped custom properties across bundled themes.

Bug Fixes:

• Prevent unknown non-default themes from silently overriding the default typography configuration during generation.
• Restore reliable Sass consumer compatibility while migrating stylesheet sources and examples to the Sass module system.

Enhancements:

• Modernize Sass sources to use namespaced modules and explicit design-token dependencies across normalization, headings, grids, utilities, and theme generation.
• Update the Auro 1 typography configuration to use the Atmos theme configuration and remove the obsolete Auro 2 theme from the generated architecture.
• Improve typography fallbacks and ensure accent letter-spacing values are emitted consistently.

Documentation:

• Regenerate SassDoc examples and generated documentation for the updated Sass module usage and theme scoping behavior.

Chores:

• Refresh generated theme bundles and documentation artifacts to reflect the new typography architecture.

[sourcery-ai]

Reviewer's Guide

Adds data-attribute-based theme scoping for typography custom properties, generates multi-theme type bundles aligned with design-tokens theme codes, wires in a theme code build step, and removes the Auro 2 theme from all builds while overriding the Auro 1 theme code to atm.

File-Level Changes

Change	Details	Files
Introduce data-attribute theme scoping and multi-theme generation for typography custom properties.	Add wcss-type-scope-selector() function to build :root and [data-aag-theme="aag-theme-"] selectors for type custom properties. Refactor type CSS-var generation into generate-type-css-vars() and generate-multi-theme-type-css-vars() to emit all themes' vars in a single stylesheet with a configurable default theme. Update generate-theme-type-css-vars() and theme generator mixin to accept a theme name and use the new scoping function.	src/type/mixins/_type-generator.scss src/type/mixins/_theme-generator.scss
Generate Sass map of theme codes from design-tokens and centralize excluded themes and overrides.	Add theme-codes.build.mjs script that reads THEME_DEFINITIONS, applies EXCLUDED_THEMES and THEME_CODE_OVERRIDES (auro-1 → atm), and writes _theme-codes.scss with $wcss-theme-codes. Introduce excluded-themes.mjs with EXCLUDED_THEMES (auro-2) and a withoutExcludedThemes() helper shared by build scripts. Integrate withoutExcludedThemes() into the global theme CSS config so excluded themes are not built.	scripts/theme-codes.build.mjs scripts/excluded-themes.mjs scripts/theme.global.css.config.mjs
Add per-theme multi-theme type bundles and wire them into the CSS build.	Create _all-theme-configs.scss aggregating all themes' type configs into $wcss-all-theme-configs. Add per-theme bundled type entry files (alaska, alaska-classic, auro-1, hawaiian) that invoke generate-multi-theme-type-css-vars() with their theme as the default. Extend type.classes.css.build.mjs to build per-theme type bundles from THEME_DEFINITIONS (filtered by withoutExcludedThemes) into dist/bundled/type/themes/*.css. Update theme.global.template.scss to import the new per-theme type bundle and type-classes generator so each global bundle carries all themes' typography plus classes.	src/bundled/type/themes/_all-theme-configs.scss src/bundled/type/themes/alaska.scss src/bundled/type/themes/alaska-classic.scss src/bundled/type/themes/auro-1.scss src/bundled/type/themes/hawaiian.scss scripts/type.classes.css.build.mjs src/bundled/themes/theme.global.template.scss
Update build/test pipeline to generate theme codes before Sass compilation and modernize dependencies.	Add build:theme-codes npm script and invoke it from build, build:dist-bundle, build:dev, and test workflows so _theme-codes.scss exists before Sass runs. Bump @aurodesignsystem/design-tokens and several devDependencies (sass, semantic-release, etc.) to newer versions. Ensure dist/bundled/type/themes output directory exists before writing bundles. Regenerate SassDoc docs index to reflect new version 11.1.3.	package.json scripts/type.classes.css.build.mjs docs/index.html
Remove Auro 2 theme from configuration and source and document post-mortem for AB#1612078.	Delete all Auro 2-specific config, base, type, theme, and font files, and remove its import from src/config/_index.scss so it no longer builds. Add docs/post-mortem/1612078.md documenting the problem, root cause, fix, scope decisions, and learnings. Adjust theme filtering via excluded-themes.mjs so auro-2 is systematically excluded from theme builds.	src/config/_index.scss src/bundled/type/themes/auro-2/* (removed) src/config/auro-2/**/* (removed) src/essentials/themes/_auro-2.scss src/fonts/themes/_auro-2.scss src/type/themes/auro-2/index.scss docs/post-mortem/1612078.md scripts/excluded-themes.mjs
Add tests to lock in type theme scoping behavior.	Introduce sass-true test spec that asserts wcss-type-scope-selector() outputs for default, non-default, Auro 1 (atm), and unknown themes. Import the new type generator mixins into the test harness to validate the generated selectors against $wcss-theme-codes.	tests/typeThemeScoping.spec.scss

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[github-actions]

🚀 PR Release Published! v0.0.0-pr294.17

To install:

npm install @aurodesignsystem-dev/webcorestylesheets@0.0.0-pr294.17

Install via alias:

npm install @aurodesignsystem@npm:@aurodesignsystem-dev/webcorestylesheets@0.0.0-pr294.17

View on npmjs.com

[sourcery-ai]

Sorry @jason-capsule42, your pull request is larger than the review limit of 150000 diff characters

[jason-capsule42]

Code Review — PR #294 (as of 23baec6)

Verdict: ✅ clear to merge. No code-correctness defects, no open blockers. Two independent reviewers (Opus + Sonnet, xhigh effort) plus orchestrator checks converged; all actionable findings are resolved.

✅ Resolved in 23baec6

• Hawaiian bundle cross-reference comment — src/type/themes/hawaiian/index.scss:15 now documents why $accent-uses-letter-spacing: false must stay false and points to the accent config's letter-spacing: normal rationale (prevents a future maintainer removing it as "redundant").
• Machine-verifiable multi-theme scoping test — tests/typeThemeScoping.spec.scss adds a sass-true output/expect assertion proving the default theme emits under :root (+ attribute selectors) while non-default themes are attribute-scoped only. The previously @error-only invariant is now continuously verified in CI.
• Module-correct SassDoc example — src/utilityMixins/_layoutPropertiesGenerator.scss override example now loads the tokens module as tokens and configures via @use … with (…) instead of the pre-module "set $var then @use" pattern, so it compiles verbatim.

🟡 Advisory (no fix required)

• The Auro-2 removal / auro-1 dist-path deletion lands in a non-! commit, but the PR's separate feat!: commit already forces the major bump and MIGRATION.md §7 documents every removed/renamed path. Surface-only — release outcome is correct.

Verified clean (no findings)

• @use/@forward namespace migration across all touched files — consistent throughout.
• Intended bug fixes correct: ds-breakpoint-lg → ds-grid-breakpoint-lg (_responsive.scss); var(--$ds-text-body-default-weight) → var(--ds-text-body-default-weight, …) (_fontStyles.scss).
• Config threading (@forward re-exports, _all-theme-configs.scss aliases, src/config/_index.scss collision avoidance) — sound.
• essentials/fonts atmos self-reference + @forward 'base' hide $paragraph — correct.
• Build/CI: --tag pr<number> safe (pull_request-triggered); build:theme-codes threaded through prepare/prepack/test/build; generated _theme-codes.scss gitignored but shipped via prepack.

Informational

• Post-mortem coverage: AB#1502836 and AB#1559488 are the post-mortem reports themselves; parity in sync for AB#1388992 and AB#1612078. No TRD produced for AB#1612078 (ticket recommended one).

_{🤖 Reconciled from Opus + Sonnet reviewer passes via /auro:code-review.}

[chrisfalaska]

Pulled down locally and built.

Ran a single diff so far, just want to confirm this looks as expected before I do the others:

https://www.diffchecker.com/GpJR0wR0/

[jason-capsule42]

Pulled down locally and built.

Ran a single diff so far, just want to confirm this looks as expected before I do the others:

https://www.diffchecker.com/GpJR0wR0/

yes, and already reviewed with @forrest-for-real

[chrisfalaska]

I noticed commit cda6be03c933acc7562172e5da2ea9020ecab0f0 has the feat! cobention, but there's no explicit "BREAKING CHANGE" in the commit message.

[chrisfalaska]

Risks / things that could bite later

• Committed dist/ has no freshness guardrail (biggest issue). Nothing rebuilds it on release (@semantic-release/git commits only CHANGELOG, package.json, and docs; prepack rebuilds only theme codes). It will drift from src/ and create merge noise.

  • Recommendation: Add a CI gate: npm run build && git diff --exit-code dist/, or revert to build-on-release.

• _theme-codes.scss is git-ignored and generated. Direct Sass invocation without the prebuild step fails. This is mitigated by the npm lifecycle (build, test, prepare, and prepack run build:theme-codes first), but it's a build prerequisite worth knowing.

• _all-theme-configs.scss is a hand-maintained manifest. Adding a theme requires two manual edits; a missing bundled entry only fails at global-build time.

• Breaking renames: auro-1 → atmos, auro-2 dropped, generate-theme-type-css-vars has a new positional arg, and there are no @forward shims for old @import entry points.

  • All are justified/documented, but must ship in the intended major.

Test gaps

• Add regression specs for the two 799c24b utility-class output fixes (.util_is-lgOnly, font-weight).

• Add an assertion that the default-theme block precedes non-default blocks in source order. The cascade-correctness argument depends on it.

// Guards SOURCE ORDER specifically: the default theme's `:root` block must be
// emitted BEFORE any non-default attribute block. `:root` and `[data-aag-theme]`
// have equal specificity, so if a consumer sets a non-default theme attribute on
// the root element, the cascade resolves by source order — the non-default block
// only wins if it follows the default's `:root` block. This stub deliberately
// lists the default theme SECOND in the map; a mixin that emitted in map order
// (instead of hoisting the default first) would put the non-default block ahead
// of `:root` and fail this assertion.
@include it('emits the default theme first even when it is not first in the manifest map') {
  $stub-themes: (
    'hawaiian': map.get(all-theme-configs.$wcss-all-theme-configs, 'hawaiian'),
    'alaska': map.get(all-theme-configs.$wcss-all-theme-configs, 'alaska')
  );

  @include assert {
    @include output {
      @include generate-multi-theme-type-css-vars($stub-themes, 'alaska');
    }
    @include expect {
      @include generate-type-css-vars(
        map.get($stub-themes, 'alaska'),
        ':root, [data-aag-theme="aag-theme-as"], [data-aag-theme="aag-theme-as-type"]'
      );
      @include generate-type-css-vars(
        map.get($stub-themes, 'hawaiian'),
        '[data-aag-theme="aag-theme-ha"], [data-aag-theme="aag-theme-ha-type"]'
      );
    }
  }
}

[jason-capsule42]

All review comments address with code changes in latest commit per discussion with @chrisfalaska

[chrisfalaska]

Built and tested locally. Feedback applied. 🚀

[rmenner]

🎉 This PR is included in version 12.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀