AB#1388992 — Replace 404ing Orion documentation links on WebCoreStyleSheets feature pages

[jason-capsule42]

AB#1388992

Executive Summary

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.

The Problem

The public feature documentation at auro.alaskaair.com/webcorestylesheets/features is generated from the repository's FEATURES.md. Under most feature headings, that page offered a convenience link — "see the API", "see the spec", "prefixing and scoping API" — meant to take the reader to the detailed reference for that feature.

Those links still pointed at the previous-generation Orion site (alaskaairlines.github.io/OrionWebCoreStyleSheets/...). Because that site has been decommissioned, following any of them produced a dead end. Broken links on the documentation site erode trust and block developers from finding the guidance they need to use the framework correctly.

Root Cause

The links were hard-coded in FEATURES.md and were never updated when the documentation site moved from Orion to the current WebCoreStyleSheets SassDoc site (alaskaairlines.github.io/WebCoreStyleSheets/, built by scripts/sassdoc.build.mjs). Five references still carried the retired OrionWebCoreStyleSheets host:

• Line 7 — prefixing and scoping API → #scope-prefix
• Line 86 — !important spec → #utility-variable-important
• Line 97 — layoutPropertiesGenerator API → #utility-layout-mixin-auro_layoutPropertiesGenerator
• Line 107 — insetUtility API → #utility-layout-mixin-auro_inset
• Line 119 — spacingUtility API → #utility-layout-mixin-auro_spacing

A compounding factor for one link: the inset utility was demoted from a SassDoc mixin to a statically generated set of classes (src/utilityClasses/_inset.scss, now flagged via deprecated.deprecated(...)). As a result its SassDoc anchor changed from #utility-layout-mixin-auro_inset to the group anchor #utility-inset, so a naive host-only swap would still have 404'd on the fragment.

The Fix

All five links in FEATURES.md were repointed to the current documentation site, and upgraded from http:// to https://:

• The four still-valid anchors (#scope-prefix, #utility-variable-important, #utility-layout-mixin-auro_layoutPropertiesGenerator, #utility-layout-mixin-auro_spacing) kept their fragments and only had the host changed from alaskaairlines.github.io/OrionWebCoreStyleSheets/ to alaskaairlines.github.io/WebCoreStyleSheets/.
• The inset link was remapped to the correct current anchor: https://alaskaairlines.github.io/WebCoreStyleSheets/#utility-inset.

No other documentation files needed changes: README.md and MIGRATION.md already point at the live site root, and FAQ.md's deep link (#utility-layout-mixin-auro_layoutPropertiesGenerator) was already on the current host and remains valid.

Why This Works

The current documentation site is generated by SassDoc from ./src into ./docs and published at alaskaairlines.github.io/WebCoreStyleSheets/. SassDoc uses a deterministic anchor scheme (<group>-<type>-<name>) that the Orion site also used, so four of the five fragments carry over unchanged — only the host was ever wrong for those.

Each destination anchor was verified to exist in the built docs/index.html before shipping:

• #scope-prefix ✓
• #utility-variable-important ✓
• #utility-layout-mixin-auro_layoutPropertiesGenerator ✓
• #utility-inset ✓ (the old #utility-layout-mixin-auro_inset no longer exists, confirming the remap was necessary)
• #utility-layout-mixin-auro_spacing ✓

Because docs/index.html is the exact artifact that is published, an anchor present there is present on the live site — the links resolve to real, current reference material rather than a retired host.

Outcome

Every feature-heading documentation link on the WebCoreStyleSheets features page now points to live, working reference material instead of a decommissioned site. Readers following "see the API / spec / prefixing and scoping API" from the features page reach the intended content, restoring the documentation's reliability and reflecting the completed migration off Orion.

Ticket Completeness

Both requirements expressed in the ticket are resolved. (The ticket had no formal Description or Acceptance Criteria fields; requirements were taken from its repro-steps "Current/Desired behavior".)

Resolved

• Replace the retired-Orion "see the documentation" links on the WebCoreStyleSheets feature pages — all five Orion-host links in FEATURES.md (the source of the features page) were replaced; a repo-wide check confirms no OrionWebCoreStyleSheets references remain in the docs.
• Each link should point to the current, working documentation for that feature — all five now target alaskaairlines.github.io/WebCoreStyleSheets/, and every destination anchor was verified present in the built docs/index.html, including the remapped #utility-inset.

Learnings

• Documentation links to a design-system predecessor (Orion) are a recurring debt when migrating to Auro; a host rename alone is insufficient when the underlying doc generator has reorganized anchors.
• SassDoc anchors are tied to the symbol's kind (mixin vs. class group). Deprecating a mixin into generated classes silently changes its anchor (#utility-layout-mixin-auro_inset → #utility-inset), which can break deep links even after the host is corrected.
• Always validate fragment anchors against the actual built docs/index.html, not just the host — a link that returns 200 at the host can still land nowhere if the fragment is stale.
• Worth a follow-up: a CI link-check over *.md for retired hosts (OrionWebCoreStyleSheets) and for anchors that don't exist in the built docs would catch this class of regression automatically.