Compositions

Wizard system

Every multi-step flow in the app uses the same canonical chrome — creation wizards, import flows, configuration setup. Header (back arrow + breadcrumb + step pills) → body (2-column: main form left, panel triggers right) → side panels → sticky footer. Don't invent feature-specific wizard layouts.

Overview

The wizard chrome is one composition; what changes per flow is the form fields inside the left card and the trigger summaries on the right. Always 2 columns — never 3. Ancillary settings go behind .wiz-panel-trigger chips on the right that open .wiz-side-panel drawers.

Use cases

  • Workspace / project creation. 2–3 steps — identity → members → review.
  • Import flows. Source file picker → column mapping → confirm. See Upload wizard.
  • Configuration setup. First-run wizards for connecting services, setting permissions, etc.

Anatomy

PartClassRole
Step pills.wiz-step-pillTop-of-page progress. One pill per step, active and completed states distinct.
Wizard card (left).wizard-cardPrimary form — keep to ~6 fields. More than that → move behind a panel trigger.
Panel triggers (right).wiz-panel-triggerStacked summary chips for ancillary settings. Show current values; refresh after Apply.
Side panel.wiz-side-panelSlide-in drawer with full settings for one trigger. Sticky Cancel/Apply footer.
Sticky footer.wiz-sticky-footerPage-level Cancel · Back · primary action. Always visible regardless of scroll.

Best practices

  • 2-column layout, not 3. Left = one .wizard-card with primary fields. Right = stacked .wiz-panel-trigger buttons. Don't render ancillary settings inline as a 3rd column.
  • Live trigger summaries. Each trigger shows a few key values from its panel. Summaries must re-render after every Apply.
  • One sticky footer. Position fixed, left offset matches sidebar + QA panel width. Cancel on the left, primary on the right.
  • Apply re-renders triggers. Closing a side panel with Cancel just closes — no dirty tracking. Apply closes AND updates the matching trigger's chip values.

Composition

The wizard composes from: Page header (WizardCrumbs variant), Form elements (inside the card), Buttons (sticky footer + side panel actions), Breadcrumbs (origin-aware crumb in the header).