Stepper | Prisma Design System

Live Preview

Account

Profile

Review

Stepper / Wizard Component

Skill này hướng dẫn tạo component Stepper — hiển thị progress cho multi-step flows: onboarding, checkout, form wizard.

1. Mục tiêu (Objective)

Tạo Stepper cho multi-step flows: onboarding, checkout, form wizard. Hiển thị progress qua các bước, hỗ trợ linear và non-linear navigation.

2. AI Context & Intent (Ngữ cảnh cho AI)

Khi nào dùng Stepper?

Multi-step forms: Registration, checkout, application
Onboarding flows: Welcome wizard, setup guide
Process tracking: Order status, delivery progress
Configuration wizards: Settings setup, integration setup

⚠️ Phân biệt Stepper vs Tabs vs Progress Bar (QUAN TRỌNG)

Tiêu chí	Stepper	Tabs	Progress Bar
Bản chất	Sequential steps	Parallel sections	Single progress value
Navigation	Linear (ordered)	Random access	No navigation
State	Completed/Active/Upcoming	Active/Inactive	0-100%
Ví dụ	Checkout flow	Settings sections	File upload

Decision Tree cho AI

text

Cần multi-step UI?
├─ Steps phải theo thứ tự → Stepper (linear)
│   ├─ Desktop → Stepper (horizontal)
│   ├─ Mobile → Stepper (vertical)
│   └─ 8+ steps → Break into sub-flows
│
├─ Steps có thể jump bất kỳ → Stepper (non-linear) hoặc Tabs
│   ├─ Steps liên quan nhau → Stepper (non-linear)
│   └─ Steps độc lập → Tabs
│
├─ Chỉ cần show progress % → Progress Bar
└─ Process status tracking → Stepper (read-only, no navigation)

3. Anatomy

text

Horizontal:
┌────────────────────────────────────────────────────┐
│  (✓)──────────(2)──────────(○)──────────(○)       │
│  Step 1       Step 2       Step 3       Step 4    │
│  Account      Profile      Review       Done      │
│  Completed    Active       Upcoming     Upcoming  │
└────────────────────────────────────────────────────┘

Vertical:
┌───────────────────┐
│  (✓) Step 1       │ ← Completed: --success bg, check icon
│  │   Account      │
│  │                │ ← Connector line: --border
│  (2) Step 2       │ ← Active: --primary bg, number
│  │   Profile      │
│  │                │
│  (○) Step 3       │ ← Upcoming: --muted bg, number
│  │   Review       │
│  │                │
│  (○) Step 4       │
│      Done         │
└───────────────────┘

4. Platform Mapping

Platform	Component	Key Difference
Web	Stepper (custom)	Horizontal/vertical, clickable steps
iOS	📎 Custom (no native)	Often uses segmented or custom
Android (M3)	ProgressIndicator pattern	Stepper guidance in M3 docs
Fluent	❌ (custom pattern)	No dedicated component
Carbon	ProgressIndicator	Horizontal steps with labels

Cross-platform: Pattern hơn là component. Token file covers step indicator styling.

5. Variants

Variant	Mô tả
`horizontal`	Steps in a row (desktop)
`vertical`	Steps in a column (mobile/sidebar)

Step States

State	Visual
`completed`	`check` icon (check.svg), primary bg
`active`	Number, primary bg, bold label
`upcoming`	Number, muted bg
`error`	`x` icon (x.svg), destructive bg

5.4. Slot Map (Figma ↔ Code)

📎 Source: slot-manifest.json → stepper · Layer: card

Figma Slot	`data-slot`	CSS Class	Required	Accepts
Root	`stepper`	`.stepper`	✅	—
Item	`stepper-item`	`.stepper-item`	✅ (n×)	step (number/icon + label)
Indicator	`stepper-indicator`	—	✅	number, icon
Title	`stepper-title`	—	✅	text
Description	`stepper-description`	—	❌	text
Connector	`stepper-connector`	—	✅	line
Content	`stepper-content`	`.slot-body`	✅	*

6. Token Mapping

📦 Atomic Mapping: Xem ATOMIC-MAPPING.md → mục stepper — Density Tier: comp.

Active indicator dùng --primary / --primary-foreground, done dùng --success, pending dùng --muted, connector dùng --border. Component token JSON files đã deprecated.

7. Props & API

typescript

interface StepperProps {
  activeStep: number;
  orientation?: 'horizontal' | 'vertical';
  linear?: boolean;    // Must complete in order
  onChange?: (step: number) => void;
  children: ReactNode; // Step components
}

interface StepProps {
  label: string;
  description?: string;
  icon?: ReactNode;
  error?: boolean;
  optional?: boolean;
  completed?: boolean;
}

8. Accessibility (a11y)

Container: role="list" or aria-label="Progress".
Steps: role="listitem", completed steps aria-label="Step 1: Name - Completed".
Active step: aria-current="step".
Clickable (non-linear): Steps are buttons, aria-disabled for future steps.

9. Best Practices & Rules

Linear by default: Users complete steps in order.
Show 3–7 steps max: More → break into sub-flows.
Mobile: Switch to vertical orientation.
Error recovery: Allow going back to fix errors.
Icon: Step completed icon (check), error icon (x) CHỈ dùng Lucide icon từ assets/icons/. CẤM dùng text emoji. Xem icon.md mục 10.

10. Example Usage

jsx

{/* Checkout flow - linear horizontal */}
<Stepper activeStep={1} orientation="horizontal" linear>
  <Step label="Giỏ hàng" completed />
  <Step label="Thông tin giao hàng" />
  <Step label="Thanh toán" />
  <Step label="Xác nhận" />
</Stepper>

{/* Onboarding - vertical, non-linear */}
<Stepper activeStep={2} orientation="vertical">
  <Step label="Tạo tài khoản" completed description="Đã hoàn thành" />
  <Step label="Cập nhật hồ sơ" completed description="Tên, ảnh đại diện" />
  <Step label="Kết nối ngân hàng" description="Thêm thẻ VISA / Mastercard" />
  <Step label="Xác minh danh tính" optional description="CCCD hoặc hộ chiếu" />
</Stepper>

{/* Error state */}
<Stepper activeStep={2}>
  <Step label="Upload" completed />
  <Step label="Processing" completed />
  <Step label="Validation" error />
  <Step label="Complete" />
</Stepper>