AppSideNav::List:Link - Fix background issue

[didoo]

📌 Summary

This is a follow-up of #3026.

I've noticed that the focused state of the AppSideNav::List:Link items was covered by the following item in the list:

The reason is that in #3026 I have applied an explicit background to it, the same color as the backdrop of their container.

This issue didn't happen in the previous implementation (SideNav::List:Link):

The reason for this difference is that before the focus was applied via a pseudo-element, so the z-index would take care of the stacking, while in the new implementation of the side navigation the focus is applied as box shadow.

This PR fixes the issue.

🛠️ Detailed description

In this PR I have:

• updated the showcase for the status of AppSideNav::List:Link to make the problem visible
• set a transparent background color for .hds-app-side-nav__list-item-link

👉 👉 👉 Preview: https://hds-showcase-git-sidenav-list-link-fix-backgro-cf8dad-hashicorp.vercel.app/components/app-side-nav#states

📸 Screenshots

Before:

After:

🔗 External links

Jira ticket: https://hashicorp.atlassian.net/browse/HDS-5153

---

👀 Component checklist

• Percy was checked for any visual regression
• A changelog entry was added via Changesets if needed (see templates here)

💬 Please consider using conventional comments when reviewing this PR.

📋 PCI review checklist

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.
• If applicable, I've worked with GRC to document the impact of any changes to security controls.
  Examples of changes to controls include access controls, encryption, logging, etc.
• If applicable, I've worked with GRC to ensure compliance due to a significant change to the in-scope PCI environment.
  Examples include changes to operating systems, ports, protocols, services, cryptography-related components, PII processing code, etc.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
hds-showcase	✅ Ready (Inspect)	Visit Preview	Jul 22, 2025 11:23am
hds-website	✅ Ready (Inspect)	Visit Preview	Jul 22, 2025 11:23am

[Copilot]

Pull Request Overview

This PR fixes a background/z-index stacking issue in AppSideNav::List::Link where focused states were being covered by subsequent list items. The fix changes the background from an explicit color to transparent, allowing proper stacking of focus states that are now implemented as box shadows.

Key changes:

• Changed background color from explicit surface color to transparent for link items
• Updated showcase to demonstrate the fix with multiple links in lists
• Added margin reset for better visual consistency in showcase

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
packages/components/src/styles/components/app-side-nav/content.scss	Sets transparent background for link items to fix focus state stacking
showcase/app/templates/page-components/app-side-nav/index.hbs	Updates showcase to use multiple links and proper list structure to demonstrate the fix
showcase/app/styles/showcase-pages/app-side-nav.scss	Adds margin reset for showcase list wrapper styling

[heatherlarsen]

Great improvement!

I found a couple of instances where the focus ring is still being cut off:

At the bottom of the list...not in all cases, though 🤔

When focus is visible on the list item above an active list item

[didoo]

I found a couple of instances where the focus ring is still being cut off:
At the bottom of the list...not in all cases, though

@heatherlarsen yes, this is a known issue. While we know what a possible fix may be for it, this PR is only focusing on the background issue

When focus is visible on the list item above an active list item

yeah, nice catch! there are so many combinations and permutations that it's hard to test them all! I've added more use cases to the showcase page for the AppSideNav, related to this, and I'll move the PR to draft so that @KristinLBradley can have a proper look at it and see if the fixes to this issue are correct, if there are better alternatives, and expecially if we're covering all the use possible cases (there may be more that I have forgotten).

[KristinLBradley]

From Heather:

I found a couple of instances where the focus ring is still being cut off:

At the bottom of the list...not in all cases, though 🤔

When focus is visible on the list item above an active list item

@heatherlarsen @didoo

I've been investigating the remaining focus ring issues. For the first one, when panels are used there is an overflow:hidden on the panel that causes the focus ring to be cut off. This was part of a bug fix with scrolling: Merged PR, Jira ticket

The safest way to fix this bug (I think) would be to add a bit of top and bottom padding to the panel container to give the focus ring room. This would alter the layout from the AppSideNav's not using panels though. (It would probably be possible to add some tricky CSS to change the overall visual padding dependent of the AppSideNav when it contains a panel vs. not to keep the visual spacing consistent but it would be a touch messy.)

It may also be possible to delete the overflow:hidden style on the panel but that risks re-introducing bugs with scrolling the AppSideNav content and is difficult to test for to account for all possible interactions related to navigating between links.

For the 2nd issue, with active list item backgrounds overlapping the focus ring, I wasn't able to duplicate it so it seems that this issue may already be fixed in this PR?

[didoo]

It may also be possible to delete the overflow:hidden style on the panel but that risks re-introducing bugs with scrolling the AppSideNav content and is difficult to test for to account for all possible interactions related to navigating between links.

@KristinLBradley yes, that was I was hoping you could do or have more context about: do you remember why this fix was introduced, and how to replicate the issue that made us make the fix, so we can see if it's still applicable?

For the 2nd issue, with active list item backgrounds overlapping the focus ring, I wasn't able to duplicate it so it seems that this issue may already be fixed in this PR?

Yes, I would assume this is fixed with this PR, but I need you to double check the proposed solution, because it involves a bit of refactoring of position and z-index values, so I may have not considered something.

[KristinLBradley]

It may also be possible to delete the overflow:hidden style on the panel but that risks re-introducing bugs with scrolling the AppSideNav content and is difficult to test for to account for all possible interactions related to navigating between links.

@KristinLBradley yes, that was I was hoping you could do or have more context about: do you remember why this fix was introduced, and how to replicate the issue that made us make the fix, so we can see if it's still applicable?

For the 2nd issue, with active list item backgrounds overlapping the focus ring, I wasn't able to duplicate it so it seems that this issue may already be fixed in this PR?

Yes, I would assume this is fixed with this PR, but I need you to double check the proposed solution, because it involves a bit of refactoring of position and z-index values, so I may have not considered something.

@didoo I checked out this PR branch locally and also removed the overflow: hidden style from .hds-side-nav__content-panel then linked to the local files and tried testing within both cloud-ui & atlas. I navigated around and tried focusing various links. I wasn't able to reproduce the original issue so as far as I can tell it's not needed. Terraform/atlas has a custom overflow: hidden style on an outer ".sidebar-scrollbar" container however which still cuts off the focus ring on focused links at the top & bottom of the AppSideNav. (I tried also commenting out this custom style and then navigated around & focused the AppSideNav links and wasn't able to detect issues.)

I'll continue testing your other solution for the 2nd issue to see if I encounter issues but so far I'm not seeing any.

[KristinLBradley]

So far, I haven't been able to uncover issues related to this change and the z-index above.

[didoo]

Nice!

[didoo]

@KristinLBradley I have moved the PR out of draft, please review.

Note: this PR fixes only the background issue; for the overflow issue you should open a distinct PR so we have better traceability of the changes we're introducing. As soon as it's open, I can review it.

[KristinLBradley]

@KristinLBradley I have moved the PR out of draft, please review.

Note: this PR fixes only the background issue; for the overflow issue you should open a distinct PR so we have better traceability of the changes we're introducing. As soon as it's open, I can review it.

@didoo Should I create a Jira ticket or is it ok to open a PR directly?