Stepper::Navigation and Stepper::List: Create components

[dchyun]

📌 Summary

This PR adds the following new components to the HDS components library.

• Hds::Stepper::Nav
  • Subcomponents: Hds::Stepper::Nav::Step and Hds::Stepper::Nav::Panel
• Hds::Stepper::List
  • Subcomponent: Hds::Stepper::List::Step

Preview pages

• Stepper Nav
• Stepper List

Requirements Doc

🛠️ Detailed description

Hds::Stepper::Nav Component

This component is a visual indicator of an on-page linear progress, where users can see where they are in a given flow.

The component can be used in two ways. Either using the contextual <S.Step> and <S.Panel> components, or using the @steps argument and passing in an array.

Using Contextual Components

// Example
<Hds::Stepper::Nav
  @currentStep={{this.currentStep}}
  @onStepClick={{this.updateCurrentStep}}
  as |S|
>
  <S.Step>
    <:title>Step 1 Title</:title>
    <:description>Description</:description>
  </S.Step>
  <S.Step>
    <:title>Step 2 Title</:title>
  </S.Step>
  <S.Panel>
    Step 1 content
  </S.Panel>
  <S.Panel>
    Step 2 content
  </S.Panel>
</Hds::Stepper::Nav>

Using @steps argument

// Example
{{#let
  (array
    (hash title='Step 1 Title' description='Description')
    (hash title='Step 2 Title')
  )
  as |steps|
}}

<Hds::Stepper::Nav
  @steps={{steps}}
  @currentStep={{this.currentStep}}
  @onStepChange={{this.updateCurrentStep}}
>
  <:body>
    {{#if (eq this.currentStep 0)}}
      Step 1 content
    {{else}}
      Step 2 content
    {{/if}}
  </:body>
</Hds::Stepper::Nav>

Stepper::Nav

• <[S.Step]>: Stepper::Nav::Step as yielded component
• <[S.Panel]>: Stepper::Nav::Panel as yielded component
• <:body>: Named block used for step content when using steps argument
• steps: Array of data for steps to be created
• currentStep: Base indexed value for step that is currently active
• isInteractive: If true, the user may use the stepper to navigation to previous steps
• titleTag: Sets the DOM tag used for step title text
• onStepChange: Event triggered when the active step is changed through a click on a step

[S].Step

• <:title>: Contextual block for title text
• <:description>: Contextual block for description text

[S].Panel

• yield: Elements passed as children are yielded as inner content of a
  HTML element

Hds::Stepper::List Component

This component is a visual indicator of a linear progress, where users can see where they are in a given flow.

// Example
<Hds::Stepper::List as |S|>
  <S.Step @status="complete">
    <:title>Title</:title>
    <:description>Description</:description>
    <:content>
      Step 1 content
    </:content>
  </S.Step>
  <S.Step @status="progress">
    <:title>Title</:title>
    <:description>Description</:description>
    <:content>
      Step 2 content
    </:content>
  </S.Step>
  <S.Step @status="incomplete">
    <:title>Title</:title>
  </S.Step>
</Hds::Stepper::List>

Stepper::List

• <[S].Step>: Stepper::List::Step as yielded component
• titleTag: Sets the DOM tag used for step title text

[S].Step

• <:title>: Contextual block for title text
• <:description>: Contextual block for description text
• <:content>: Contextual block for any additional content
• status: Status of the step based on current indicator statuses

📸 Screenshots

Hds::Stepper::Nav

Interactive

Non-interactive

Hds::Stepper::List

🔗 External links

Jira ticket: HDS-4411
Requirements Doc: Link
Figma file: Link

---

👀 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.

[vercel]

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

Name	Status	Preview	Updated (UTC)
hds-showcase	✅ Ready (Inspect)	Visit Preview	Mar 11, 2025 4:40pm
hds-website	✅ Ready (Inspect)	Visit Preview	Mar 11, 2025 4:40pm

[MelSumner]

@heatherlarsen I think my specific concern is that while this may technically meet the requirements for use of color, it doesn't meet the intention of use of color.

Specifically, the use of checkmarks vs numbers is not a way that users know that something is interactive or not. It's a tiny design detail that I suspect only trained eyes (designers) will notice.

I suppose if we don't really expect users to know (or intuit) that the stepper could be interactive, then 🤷 But if we are really going for differentiation in the UI/for improved UX, then the interactive version needs to be dramatically and distinctly different.

[shleewhite]

Yeah, +1 to what @MelSumner said. The failure is that noticing one variant has a filled in check icon but the other doesn't is not a meaningful difference to know if something is interactive or not for someone who is color blind. Yes, there are interaction states, but that requires the user interacting with the UI first to know. The goal is for users to know at a glance which variant they are looking at.

There are several differences between this and SideNav (which contains links that don't have an underline) - there is no "non-interactive side nav" variant that users have to differentiate between and it is a common pattern for the site navigation links to be in a column on the side of the page without underlines. The placement on the page as part of the navigation makes it understood that they are interactive.

We discussed this before and came to the conclusion that there should be an outline around the step icon to make it look more like a button. I am not sure when we moved away from that design, but, to me, that was a good solution to this issue.

Side note: if the intention is that completed non-interactive steps don't have the check icon, then there is a bug with the current implementation of the component.

cc @majedelass @heatherlarsen

[heatherlarsen]

@shleewhite For clarification, are you all comparing the two variants (blue vs black) or between the steps within a variant (check vs number)?

[shleewhite]

@shleewhite For clarification, are you all comparing the two variants (blue vs black) or between the steps within a variant (check vs number)?

@heatherlarsen I am comparing the 2 variants.

[KristinLBradley]

@heatherlarsen I think my specific concern is that while this may technically meet the requirements for use of color, it doesn't meet the intention of use of color.

Specifically, the use of checkmarks vs numbers is not a way that users know that something is interactive or not. It's a tiny design detail that I suspect only trained eyes (designers) will notice.

I suppose if we don't really expect users to know (or intuit) that the stepper could be interactive, then 🤷 But if we are really going for differentiation in the UI/for improved UX, then the interactive version needs to be dramatically and distinctly different.

@MelSumner In the Guidelines, we tell consumers to always pair the Stepper Nav with buttons for navigation: https://github.com/hashicorp/design-system/pull/2727/files#r1988406951

Would that be enough to satisfy accessibility requirements?

[shleewhite]

@MelSumner In the Guidelines, we tell consumers to always pair the Stepper Nav with buttons for navigation: https://github.com/hashicorp/design-system/pull/2727/files#r1988406951

Would that be enough to satisfy accessibility requirements?

@KristinLBradley I dont think so, since the non-interactive nav is also always paired with buttons. The issue is being able to distinguish the two variants without color.

[MelSumner]

FWIW, I'm going to defer to Lee on this PR, since I'm OOO this week and don't want to be a blocker here.