chore(nimbus): `Steps` component by jaikamat · Pull Request #1005 · commercetools/nimbus

jaikamat · 2026-02-02T17:45:13Z

Summary

Adds the Steps component - a display-only progress indicator for multi-step
processes like forms, wizards, and onboarding flows.

Figma link here

Features

Compound component API: Steps.Root, Steps.List, Steps.Item,
Steps.Indicator, Steps.Separator, Steps.Content, Steps.Label,
Steps.Description
Three sizes: xs, sm, md
Two orientations: horizontal, vertical
Indicator types: Numeric (with checkmark on complete) or custom icons
State derivation: Automatically calculates complete, current,
incomplete states from step index
Accessible: ARIA roles (list, listitem), aria-current="step", screen
reader labels

Usage

<Steps.Root step={1} count={3}>
  <Steps.List>
    <Steps.Item index={0}>
      <Steps.Indicator type="numeric" />
      <Steps.Content>
        <Steps.Label>Account</Steps.Label>
        <Steps.Description>Create your account</Steps.Description>
      </Steps.Content>
    </Steps.Item>
    <Steps.Separator />
    <Steps.Item index={1}>
      <Steps.Indicator type="icon" icon={<PersonIcon />} />
      <Steps.Content>
        <Steps.Label>Profile</Steps.Label>
      </Steps.Content>
    </Steps.Item>
  </Steps.List>
</Steps.Root>

vercel · 2026-02-02T17:45:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nimbus-documentation	Ready	Preview, Comment	Feb 5, 2026 8:16pm
nimbus-storybook	Ready	Preview, Comment	Feb 5, 2026 8:16pm

changeset-bot · 2026-02-02T17:45:28Z

⚠️ No Changeset found

Latest commit: fa6e77d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

packages/nimbus/src/components/button/button.stories.tsx

packages/nimbus/src/components/steps/steps.mdx

jaikamat · 2026-02-02T19:46:07Z

packages/nimbus/src/components/steps/steps.recipe.ts

I have to say it was pretty wild to see Claude ingest the Figma spec using the Figma MCP and derive these values directly from it. Made the job much, much easier.

openspec/changes/archive/2026-02-03-add-steps-component/specs/nimbus-steps/spec.md

packages/nimbus/src/components/steps/steps.tsx

misama-ct · 2026-02-03T12:18:39Z

packages/nimbus/src/components/steps/steps.dev.mdx

+### With descriptions
+
+Add optional descriptions below labels to provide additional context for each step:
+


Any idea how to handle this case? Squeezing would look unprofessional, hiding steps is kinda meh, horizontal scrollbars ugly. Or should we just trust consumers to switch orientation if necessary?

I'm of a mind to push this onto consumers (for now), we could program the component to aggressively wrap text to preserve x-overflow, but I don't know that it's necessary to ship it as-is

container queries?

see also the 'container queries' example here: https://piccalil.li/blog/a-workaround-for-using-custom-properties-in-media-queries/#downsides

It should be possible to grab the width of the steps parent wrapper, width of the wrapper for the steps, and compare them, and if the parent wrapper is smaller then update the styling for each step

I think we could indeed leverage container queries, but through the existing conditionals-system.

We could use the large sizes tokens to create default container-queries.

Add to system:

import { defineConfig, createSystem, defaultConfig } from "@chakra-ui/react" const config = defineConfig({ conditions: { // Custom container query condition cq3xl: "@container (min-width: 768px)", cqSm: "@container (min-width: 384px)", // ... }, }) export const system = createSystem(defaultConfig, config);

Usage:

<Stepper orientation={{ cqSm: 'vertical', cq3xl: 'horizontal', }} />

We have an example story for this now that dynamically switches. Consumers specify it at the moment. If we feel we want to internalize this, we can, but I ran out of time today.

misama-ct

Couple of things. Happy, we're still needed.

packages/nimbus/src/components/steps/components/steps.content.tsx

packages/nimbus/src/components/steps/steps.recipe.ts

misama-ct · 2026-02-04T08:15:14Z

packages/nimbus/src/components/steps/steps.slots.tsx

+  key: "nimbusSteps",
+});
+
+export const StepsRootSlot: SlotComponent<HTMLDivElement, StepsRootSlotProps> =


Not that it's a harm, but is SlotComponent as type still needed now that we generate the recipe types on the client side?

Hmm, I'm not sure actually, might need more exploration since we have 20+ components that use this pattern.

Maybe we can scope it to another unit of work

packages/nimbus/src/components/steps/steps.mdx

packages/nimbus/src/components/steps/steps.types.ts

openspec/changes/archive/2026-02-03-add-steps-component/tasks.md

packages/nimbus/src/components/steps/components/steps.root.tsx

packages/nimbus/src/components/steps/components/steps.item.tsx

ddouglasz

🦾🤖🫳🏻🎤

ByronDWall

This is a good start, but I have significant questions. The biggest one is around controls - I think we need persistent next/previous buttons.

I also really think we should only display the active content, similar to how tabs work, rather than show all steps on the page.

Also, I have some styling concerns.

ByronDWall · 2026-02-05T13:53:58Z

packages/nimbus/src/components/steps/steps.recipe.ts

+      },
+      "&[data-state='complete']": {
+        borderColor: "primary.9",
+        color: "colorPalette.contrast",


I believe contrast is meant to be a background color that will provide an acceptable contrast ratio for any of the colors in a palette that are meant to be used for text (.10+?). Also, we don't set a colorPalette for this recipe, are we sure that this will be primary.contrast or will it be the default color palette set on ::root (neutral, I think)?

Also, it results in not being able to see the indicator title in dark mode:

ByronDWall · 2026-02-05T13:56:27Z

packages/nimbus/src/components/steps/steps.recipe.ts

+      borderColor: "neutral.7",
+      color: "neutral.12",


One thing chakra does in its steps component that's interesting is it allows the user to configure color palettes for the indicators. I feel like this is in keeping with nimbus' stance on configurability, but also we don't need to implement it

ByronDWall · 2026-02-05T15:13:18Z

packages/nimbus/src/components/steps/steps.tsx

+  /**
+   * # Steps.Root
+   *
+   * Container component that manages step state and provides context to child components.
+   */
+  Root: StepsRoot,
+
+  /**
+   * # Steps.List
+   *
+   * Flex container that wraps all step items and separators.
+   */
+  List: StepsList,
+
+  /**
+   * # Steps.Item
+   *
+   * Container for a single step. Automatically derives state from its index.
+   */
+  Item: StepsItem,
+
+  /**
+   * # Steps.Indicator
+   *
+   * Visual indicator showing step number or icon.
+   */
+  Indicator: StepsIndicator,
+
+  /**
+   * # Steps.Separator
+   *
+   * Visual line connecting step indicators.
+   */
+  Separator: StepsSeparator,
+
+  /**
+   * # Steps.Content
+   *
+   * Container for step label and optional description.
+   */
+  Content: StepsContent,
+
+  /**
+   * # Steps.Label
+   *
+   * Displays the step title.
+   */
+  Label: StepsLabel,
+
+  /**
+   * # Steps.Description
+   *
+   * Displays optional hint text below the label.
+   */
+  Description: StepsDescription,


These are the descriptions users actually see in the ts autocomplete - I think they could be expanded a bit?

ByronDWall · 2026-02-05T15:39:59Z

packages/nimbus/src/components/steps/components/steps.content.tsx

+  const [styleProps, functionalProps] = extractStyleProps(restProps);
+
+  return (
+    <StepsContentSlot


It's super weird to me that the content for all the steps is always on the page - shouldn't each step act more like a tab where only the active panel is visible?

tylermorrisford · 2026-02-05T19:29:03Z

packages/nimbus/src/components/steps/steps.mdx

+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => setCurrentStep(Math.max(0, currentStep - 1))}
+          isDisabled={currentStep === 0}
+        >
+          Previous
+        </Button>
+        <Button
+          variant="solid"
+          size="sm"
+          onClick={() => setCurrentStep(Math.min(4, currentStep + 1))}
+          isDisabled={currentStep === 4}
+        >
+          Next
+        </Button>


These buttons are acting funny(same for the 'step states' example in dev docs). Claude really is hot for size="sm" to implemented I guess.

Fwiw, there was a PR in flight to enable small size buttons, I just hadn't rebased yet

jaikamat requested a review from a team February 2, 2026 17:45

jaikamat self-assigned this Feb 2, 2026

jaikamat requested review from ByronDWall, ddouglasz, misama-ct, stephsprinkle, tylermorrisford and valoriecarli and removed request for a team February 2, 2026 17:45

jaikamat added the enhancement New feature or request label Feb 2, 2026

vercel bot deployed to Preview – nimbus-documentation February 2, 2026 17:45 View deployment

jaikamat commented Feb 2, 2026

View reviewed changes

packages/nimbus/src/components/button/button.stories.tsx Show resolved Hide resolved

vercel bot deployed to Preview – nimbus-storybook February 2, 2026 17:46 View deployment

jaikamat commented Feb 2, 2026

View reviewed changes

packages/nimbus/src/components/steps/steps.mdx Show resolved Hide resolved

jaikamat commented Feb 2, 2026

View reviewed changes

openspec/changes/archive/2026-02-03-add-steps-component/specs/nimbus-steps/spec.md Show resolved Hide resolved

vercel bot deployed to Preview – nimbus-documentation February 2, 2026 19:47 View deployment

vercel bot deployed to Preview – nimbus-storybook February 2, 2026 19:48 View deployment

misama-ct reviewed Feb 3, 2026

View reviewed changes

packages/nimbus/src/components/steps/steps.tsx Show resolved Hide resolved

misama-ct reviewed Feb 3, 2026

View reviewed changes

jaikamat marked this pull request as ready for review February 3, 2026 17:39

vercel bot deployed to Preview – nimbus-documentation February 3, 2026 17:41 View deployment

vercel bot deployed to Preview – nimbus-storybook February 3, 2026 17:43 View deployment

vercel bot deployed to Preview – nimbus-documentation February 3, 2026 17:48 View deployment

vercel bot deployed to Preview – nimbus-storybook February 3, 2026 17:50 View deployment

misama-ct reviewed Feb 4, 2026

View reviewed changes

vercel bot deployed to Preview – nimbus-documentation February 4, 2026 16:18 View deployment

vercel bot deployed to Preview – nimbus-storybook February 4, 2026 16:20 View deployment

ByronDWall reviewed Feb 5, 2026

View reviewed changes

packages/nimbus/src/components/steps/components/steps.item.tsx Show resolved Hide resolved

ddouglasz approved these changes Feb 5, 2026

View reviewed changes

ByronDWall reviewed Feb 5, 2026

View reviewed changes

tylermorrisford reviewed Feb 5, 2026

View reviewed changes

vercel bot deployed to Preview – nimbus-documentation February 5, 2026 19:56 View deployment

vercel bot deployed to Preview – nimbus-documentation February 5, 2026 19:59 View deployment

vercel bot deployed to Preview – nimbus-storybook February 5, 2026 20:01 View deployment

jaikamat added 18 commits February 5, 2026 15:08

chore(nimbus): create openspec proposal for steps component

8a9f0b5

chore(steps): first pass

35af574

cchore(steps): remove useless link

766ba08

chore(nimbus): stub docs tests

bc3c24a

chore(nimbus): extract component files

7193686

chore(nimbus): archive openspec

c77179e

chore(n): support style props

4f1c407

chore(n): address recipe inconsistencies

f7d71d6

chore(n): preserve conditionalValue props for orientation

e0e4b71

chore(n): check em

f5b855a

chore(n): gracefully fallback

d135512

chore(docs): add life cycle state and figma links

7861672

chore(steps): solve next/prev bug

e427b18

chore(steps): fix vertical separator spacing issue

86716d6

chore(steps): don't expose step context for consumer use

b7bba99

chore(steps): types readability

ca63df3

chore(steps): additional tests

1bf74f3

chore(steps): allow for separator growth

e563399

jaikamat force-pushed the CRAFT-1743 branch from 330b69f to e563399 Compare February 5, 2026 20:08

vercel bot deployed to Preview – nimbus-documentation February 5, 2026 20:11 View deployment

chore(steps): archive

fa6e77d

vercel bot deployed to Preview – nimbus-documentation February 5, 2026 20:14 View deployment

vercel bot deployed to Preview – nimbus-storybook February 5, 2026 20:16 View deployment

		### With descriptions

		Add optional descriptions below labels to provide additional context for each step:

Conversation

jaikamat commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

Usage

Uh oh!

vercel bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaikamat Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

misama-ct left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ddouglasz left a comment

Choose a reason for hiding this comment

Uh oh!

ByronDWall left a comment

Choose a reason for hiding this comment

Uh oh!

ByronDWall Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tylermorrisford Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jaikamat commented Feb 2, 2026 •

edited

Loading

vercel bot commented Feb 2, 2026 •

edited

Loading

changeset-bot bot commented Feb 2, 2026 •

edited

Loading

jaikamat Feb 3, 2026 •

edited

Loading

ByronDWall Feb 5, 2026 •

edited

Loading

tylermorrisford Feb 5, 2026 •

edited

Loading