--- name: steps-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit Steps for multi-step workflows using the Zag.js steps machine, compound list/items, panels, progress, navigation triggers, linear flow, controlled step, and variants. metadata: component_version: "2.0.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux zag-compound-components app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "https://zagjs.com/components/react/steps" contributor_sources: "libs/ui/src/molecules/steps.tsx libs/ui/src/tokens/components/molecules/_steps.css libs/ui/stories/molecules/steps.stories.tsx libs/ui/src/molecules/steps.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Steps Usage On narrow surfaces, horizontal triggers put their number above the label and wrap longer copy. Vertical workflows stack the step list above panels and navigation; their supplementary progress track becomes horizontal. From the small breakpoint upward, vertical workflows use the side-by-side layout. Use Steps for wizard/progress workflows. Use Tabs for peer panels, and Pagination for page navigation. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Steps`. **Use it when** - Ordered multi-step tasks: checkout, onboarding, import wizards (3–7 steps). **Use something else when** | Need | Use instead | | --- | --- | | Peer views | Tabs | | Pages of results | Pagination | | Explaining existing UI | Tour | **Do** - Name each step with a short noun for its stage (`Shipping`, `Payment`, `Review`). - Actions at the bottom: `Back` at the start, `Continue` at the end; the last step's button is the real action (`Place order`). - Validate each step before continuing; let users go back without losing data. - Allow jumping back to completed steps. **Don't** - Use more than ~7 steps; split the flow. - Hide the global navigation choice to leave (focused layouts still offer a way out). **Copy and states** - Step titles are short nouns (see Do); progress text `Step 2 of 4` for assistive tech. **Behaviour (from the UX spec)** - Visited is not complete: a stage becomes complete only after its conditions passed; gate list jumps too (`isStepValid` or a gated controlled `onStepChange`). - Going back keeps data but re-validates later stages the change may invalidate. - Opening the summary is not submitting; the final step has its own named action and confirmation. - Tasks that can be done in any order are a task list, not a linear Steps. **Figma → code** | Figma | Code | | --- | --- | | `appearance=subtle\|solid`, `size=sm…lg` | `appearance` (same values), `size` | | current / complete / default | `step` / `defaultStep`; complete = steps before the current one | | — | `linear`, `orientation` (not in Figma) | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Steps → UX guidelines*. ## Setup ```tsx const stages = [ { title: "Cart", content: "Check products and quantities." }, { title: "Delivery", content: "Confirm the delivery address." }, { title: "Review", content: "Review the order before confirming." }, ] {stages.map((stage, index) => ( {stage.title} ))} {stages.map((stage, index) => (

{stage.title}

{stage.content}
))}

Order confirmed

Your order is ready for processing.
BackConfirm and continue
``` Supported props: ```text count, step/defaultStep, linear, orientation horizontal | vertical appearance: subtle | solid size: sm | md | lg onStepChange, onStepComplete RootProvider/useSteps for external store ``` ## Core Patterns ### Use for ordered workflows Checkout, onboarding, setup, and import flows fit Steps. ### Keep item indexes aligned `Steps.Item index` and `Steps.Content index` must match the intended step. ### Use navigation triggers Use `PrevTrigger` and `NextTrigger` so disabled/completed state comes from the machine. ## Common Mistakes ### HIGH Custom wizard state Wrong: ```tsx {step === 1 && } ``` Correct: Use the complete Setup example: count, headers, panels and completion are derived together. Source: libs/ui/src/molecules/steps.tsx ### HIGH Missing count Wrong: ```tsx ``` Correct: ```tsx {/* Partial root-prop illustration; include the complete anatomy from Setup. */} {/* Setup list, panels and navigation */} ``` Source: https://zagjs.com/components/react/steps ### HIGH Inline progress styling Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/tokens/components/molecules/_steps.css ## Validation Commands ```sh rg -P -n "setStep|]*count=)|]*className=.*(bg-|h-|rounded-)" apps rg -P -n "]*index=)|]*index=)" apps rg -n "