fix: restore inline focus ring in forced-colors mode - #185

Fixes #176. Thanks @stevenpelletier90 for the report, the six-palette results, and especially the warning about confirming the media query is actually matching before trusting what you see. That one shaped how I verified this.

Why nothing is painted

hds-focus-ring-inline (src/scss/_hds-mixins.scss) opens with outline: none and then draws its dashed ring with four repeating-linear-gradient layers. Forced-colors mode does not paint background images, so all four layers drop out, and the native outline is already gone. Nothing remains.

This also explains the asymmetry you observed between buttons and links. hds-focus-ring paints through a ::before with mask-image plus a background-color, and background colors are remapped to system colors rather than dropped, so that ring survives. Measured on a keyboard-focused element with forced colors on:

The fix

One @media (forced-colors: active) block inside the mixin, using the $border-high-contrast value USWDS already uses for this in usa-range, usa-date-picker and checkbox-and-radio-colors:

@media (forced-colors: active) {
  outline: $border-high-contrast;
  outline-offset: 0;
}

Fixing the mixin rather than _link.scss covers everything that takes the inline ring. Confirmed in the compiled stylesheet that all five call sites now carry it:

a:not(:has(>img,>svg)):focus-visible            (base/_content-rules.scss)
.usa-link:focus-visible                          (components/_link.scss)
.usa-button--unstyled:focus-visible:not(...)     (components/_button.scss)
.hds-blockquote__attribution a:focus-visible     (components/_blockquote.scss)
.usa-breadcrumb__link:focus-visible              (components/_breadcrumb.scss)

Verification

Playwright with forcedColors: 'active', real Tab keypress so :focus-visible applies, reading computed styles off the built dist/css/hds.min.css:

Two things worth calling out:

• Default rendering is unchanged. The off rows are identical before and after, so nothing ships to sighted users on a normal theme.
• The media query really matched. Your warning is the failure mode I was most worried about, so the gradient count going 4 → 0 under emulation acts as a positive control: that only happens when forced-colors is genuinely active. An early version of my harness loaded the page with setContent, which silently blocked the file:// stylesheet, and every element came back looking like the browser default. That is the same trap from the other direction, and it would have "proved" there was no bug.

npm run lint:scss, prettier --check and remark all pass. Changeset included as a patch.

On tests

I did not add an automated test. The suite runs Storybook stories in headless chromium and leans on Chromatic for visual verification, and forced-colors is not something either currently emulates, so a new FocusTest story would snapshot the normal ring and tell you nothing about this bug. FocusLink already covers the normal-mode ring.

Your inset: -2px note is well taken, and it is why I asserted on computed outline-style and layer counts rather than geometry or a screenshot. If you would like forced-colors coverage in CI, the smallest version is a vitest browser test with a dedicated playwright context, separate from the storybook project so it does not affect other stories. Happy to add that in this PR or a follow-up, whichever you prefer.