# Cowork UI Kit — Composition Flows

> **Scope:** How atoms, molecules, organisms compose into _real product moments_ — the bridge between "kit ships components" and "kit ships outcomes". Brand voice + microcopy live here too because flow without voice is a wireframe, not a moment.
>
> **Audience:** AI agent invoking `/kry-ui` or `/kry-cook` to scaffold a feature for a brand. This doc tells the agent _which atoms to grab, in what order, with what microcopy and what guardrails_.
>
> **Date:** 2026-05-20 · v0.5.12-pending
> **Companion docs:** 📄 [UX-PATTERNS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/UX-PATTERNS.md) (kit-layer patterns) · 📄 [INTERACTION-RULES.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/INTERACTION-RULES.md) (mechanics) · 📄 [A11Y-RULES.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/A11Y-RULES.md) (POUR)
> **Live demos:** 🌐 `https://ui.dang.pm/flows/` (after v0.5.12 ship) · local 📁 [flows/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/)

---

## Section 0 — Why flows matter for a kit

A kit that ships only atoms ships a Lego bin. A kit that ships flows ships a Lego instruction booklet. The booklet does not constrain the Lego — it teaches the builder _which combinations have already been load-tested by gravity_.

UX-PATTERNS.md establishes brand-agnostic pattern primitives at the token + component layer. **FLOWS.md is the next layer up**: composition rules that bind 3–8 components into a sequence with shared state, shared microcopy register, and shared a11y contract. The composition layer is where the kit graduates from "design system" to "product system" — Nielsen Norman calls this _task flow analysis_ (breaking a goal into stages and screens) and notes that "seemingly simple tasks actually consist of many stages and screens" the kit author tends to underestimate.

Best-in-class kits already encode this. Atlassian ships a Forms pattern with explicit multi-step recipes and a Progress Tracker component dedicated to flow state. Material 3 ships a 4-tier onboarding model (Top User Benefits / Function-Oriented / Customization / Full-Screen). Stripe Elements ships a Payment Element that is _already a sub-flow_, not a payment input. Shopify Polaris ships an EmptyState component with prescriptive image+headline+action pattern explicitly framed as "the first step of a flow, not a dead end". The pattern is consistent: **mature kits document compositions, not just components.**

For Cowork UI Kit specifically, the multi-tenant 9-brand × 6-archetype × 2-aesthetic surface means flow guidance has compounding value: 1 documented flow recipe × 9 brand presets = 9 surface-correct flows the agent can produce without rediscovering composition. That is the leverage this doc exists to capture.

---

## Section 1 — Flow taxonomy

The 8 flow archetypes that cover ~95% of SaaS + e-commerce + consumer surfaces the kit serves. Each maps to atoms + suggested archetype (page-level template) + aesthetic default.

| # | Flow | Goal | Typical steps | Atoms / molecules | Archetype × Aesthetic | Demo |
|---|------|------|---------------|-------------------|-----------------------|------|
| **F1** | **Login / Auth** | Identity + entry to authenticated surface | Welcome → Phone/Email → OTP/Password → Success | NumberInput · SegmentedControl · Button · Toast · FocusTrap | F (PWA) × warm OR A (Dashboard) × dark | 📄 [flows/login.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/login.html) |
| **F2** | **Checkout / Order** | Convert cart → paid order | Cart → Shipping → Payment → Confirmation | Tag · NumberInput VND · DatePicker · Slider · Toolbar · Toast | C (Landing) × warm | 📄 [flows/checkout.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/checkout.html) |
| **F3** | **Onboarding** | New user → activated user | Welcome → Goals → Preferences → Done | SegmentedControl · FileUploader · Slider · ProgressBar · Toast | F (PWA) × warm | 📄 [flows/onboarding.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/onboarding.html) |
| **F4** | **Settings** | Modify account state safely | Tabs (Account / Notif / Billing / Danger) | Toolbar · DatePicker · Tag · SegmentedControl · Button danger | A (Dashboard) × dark | 📄 [flows/settings.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/settings.html) |
| **F5** | **Search & Filter** | Narrow corpus → match | Query → Filters → Results → Detail | Toolbar · Tag (filter chip) · SegmentedControl · EmptyState | B (Tool) × dark OR C (Landing) × warm | _planned v0.5.13_ |
| **F6** | **Multi-step Form** | Collect structured data > 1 screen | Step 1 → Step 2 → … → Review → Submit | NumberInput · DatePicker · SegmentedControl · Slider · ErrorState | B (Tool) × warm | _planned v0.5.13_ |
| **F7** | **Empty → Filled** | Bootstrap a list/board from zero | EmptyState → Create → List populated | EmptyState · Toast · ProgressBar (saving) · Tag | A (Dashboard) × dark | _planned v0.5.13_ |
| **F8** | **Error Recovery** | Failed action → user back on track | Error → Cause → Fix CTA → Retry → Success | ErrorState · Toast · Button · Tag (status) | universal cross-cut | _planned v0.5.13_ |

**How to use this table (for the AI agent):** When user says "build login for KHI", agent picks row F1 → loads recipe in § 3 → applies KHI brand preset + archetype F + warm aesthetic. The taxonomy is the dispatcher.

---

## Section 2 — Composition principles (CỨNG, copy into agent system prompt)

These 7 principles are the _operating manual_ that turns the atom inventory into a flow. Violations are anti-patterns enumerated in § 4.

### CP1 — Tiến độ phải nhìn thấy (Progress must be visible)
Every flow > 2 steps shows a step indicator with **label + position + total** ("Bước 2/4: Thanh toán"), not just "2/4". UXPin / Mobbin both note that visible progress reduces abandonment measurably — "step 2 of 4" completes higher than "step 2". Material 3 + Atlassian Progress Tracker both ship explicit `aria-current="step"` on the active step for SR users.

### CP2 — Error recovery beats error prevention
Forms with hard up-front validation that block submit feel hostile. Validate critical fields **on-blur** (phone format, OTP length, payment digit count) but let the user attempt submit and route them back to the broken field with the fix _next to_ the broken field, not in a toast. Polaris error guidance: "Tell merchants what happened. If there's a solution, explain it. If possible, offer a one-click fix."

### CP3 — Confirm trước action destructive, scale theo severity
- **Small destructive** (remove cart item, dismiss toast): inline undo for 5s, no modal.
- **Medium destructive** (cancel subscription, log out everywhere): modal with summary of consequence + explicit button text ("Hủy gói Premium" not "OK").
- **Large destructive** (delete account, wipe data): modal + **typing confirmation** ("Gõ XÓA TÀI KHOẢN để xác nhận") + button disabled until match. Mirrors GitHub repo-delete pattern.

### CP4 — Empty state must be CTA-active, not passive
"No data yet" with a sad cloud icon is decorative. EmptyState must (a) name the absence specifically ("Chưa có đơn hàng nào tháng này"), (b) suggest next action ("Tạo đơn đầu tiên" button), (c) optionally hint at why ("Đơn hàng tháng 5 hiển thị ở đây sau khi khách đặt"). Polaris EmptyState component encodes exactly this: image + headline + action + secondary description.

### CP5 — Loading state must carry context
"Loading…" is uninformative. The agent must write the operation ("Đang xử lý thanh toán…", "Đang gửi mã xác minh…", "Đang upload ảnh — 2/5"). For ops > 2s, switch from spinner to ProgressBar with percent or step counter. Stripe two-step confirmation pattern: confirm screen → processing _with what's being processed_ → success.

### CP6 — Success state must persist long enough to be read
Toast auto-dismiss < 3s loses the read window for VN users (denser script, slower scan time). Default toast timeout = 5s. **Success after destructive or financial action = no auto-dismiss** — user must close, because they need to record the order number / confirmation code. The success page (or sticky banner) is the natural place; the toast is supplementary.

### CP7 — Back button is non-negotiable in multi-step
Every step 2+ in a multi-step flow has a visible back button (or browser back must work). Atlassian's Form pattern explicitly: "'Back' standard button sits at the very left". Exception: post-payment confirmation is _not_ a step the user goes back from — block back navigation with a confirm modal if attempted, because re-submission charges card twice.

---

## Section 3 — 4 flow case studies (the actual recipes)

Each case study is a copy-pasteable template. The HTML demo in `flows/` is the canonical reference; this section explains _why each decision was made_ so the agent can adapt it to a different brand without breaking the rules.

---

### Case study 1 — F1 Login (KHI Wellness, PWA, warm)
**Demo:** 📄 [flows/login.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/login.html)

#### Goal + motivation
Returning member: open phone app, see "Đăng nhập KHI", expect to be inside in under 15 seconds. New visitor: same screen, but tap "Đăng ký" segmented control switches the same flow into signup mode (no separate page). Phone-OTP, no password — chosen because KHI member base is wellness consumers, not engineers; passwords are friction they don't carry around.

#### Step-by-step screens

| Step | Screen | What's on screen | aria-live? |
|------|--------|------------------|------------|
| 1 | Welcome | Brand wordmark · 1-line value prop · SegmentedControl [Đăng nhập / Đăng ký] · Phone NumberInput · Primary button "Tiếp tục" | no |
| 2 | OTP | "Mã xác minh đã gửi tới 09xx" · 6-digit OTP NumberInput · Countdown "Gửi lại sau 0:45" · Tertiary "Đổi số" link | yes (timer, errors) |
| 3 | Loading | Spinner + "Đang xác minh mã…" | yes (polite) |
| 4 | Success | Lotus glyph · "Chào mừng anh/chị về với KHI" · Class-of-the-day teaser · CTA "Xem lịch tập" | no |

#### Atoms / molecules / organisms used
- 📄 [NumberInput](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/number-input.html) — phone variant (10-digit) + OTP variant (6-digit, larger letter-spacing)
- 📄 [SegmentedControl](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/segmented-control.html) — login/signup toggle, `role="radiogroup"`
- 📄 [Toast](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/toast.html) — for "Mã không đúng" + "Gửi lại mã thành công"
- 📄 [focus-trap.js](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_assets/focus-trap.js) — applied to OTP modal-ish step

#### UX rationale per step
- **Step 1 button "Tiếp tục" not "Gửi"**: verb-object semantics. "Tiếp tục" implies a journey, "Gửi" implies form-submit (and "Gửi" alone violates anti-pattern AP2 below).
- **Step 1 SegmentedControl above phone input**: lets user re-mode without backing out. Apple HIG segmented-control pattern: state determines what the next field means (login = existing phone vs signup = new phone). Same field, different downstream.
- **Step 2 countdown "Gửi lại sau 0:45"**: shows _the system is doing something_, prevents impatient double-tap that creates 2 OTP requests. Re-send button enabled at 0:00.
- **Step 2 "Đổi số" tertiary link**: low-emphasis escape hatch — user typo'd phone, doesn't need a full back nav, just rewinds the phone field.
- **Step 4 "Chào mừng anh/chị"**: VN voice register matches KHI's wellness positioning (formal-warm). For tech brand (AI Tools) this would be "Đã đăng nhập" (functional). Brand voice is the variable.

#### Brand-aware variants
- **An Nhien** (e-commerce, warm earthy): swap step-4 lotus glyph for stylized agarwood mark, "Chào mừng quý khách trở lại". Auto signup → cart restoration.
- **AI Tools** (dashboard, dark): same flow but archetype A; OTP step gains a "Use authenticator app instead" option for power-users.
- **A-Kryphan** (blog, warm editorial): drop OTP — magic link via email. Step 2 becomes "Kiểm tra hộp thư".

---

### Case study 2 — F2 Checkout (An Nhien, Landing, warm)
**Demo:** 📄 [flows/checkout.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/checkout.html)

#### Goal + motivation
Convert agarwood product cart → paid order. An Nhien customers skew 30-55, premium-conscious, distrust hidden fees. Checkout must surface total + shipping + delivery date _on screen 1_, not behind a tap. Baymard finds 26% of users abandon checkout solely because flow was too long or too complex; the antidote is _condensing decisions, not skipping screens_.

#### Step-by-step screens

| Step | Screen | What's on screen |
|------|--------|------------------|
| 1 | Giỏ hàng | 3 product cards w/ Tag (Tinh dầu / Vòng / Hộp quà) · NumberInput quantity · running total `1.250.000đ` · "Mã giảm giá" inline |
| 2 | Giao hàng | Recipient form · DatePicker delivery (dd/mm/yyyy VN locale) · Slider "Khung giờ giao" · Shipping fee revealed |
| 3 | Thanh toán | SegmentedControl [Chuyển khoản / COD / Ví] · Payment detail · Toolbar with Back + "Xác nhận thanh toán" |
| 4 | Hoàn tất | Check ✓ animation · Order code "AN24-001" copyable · "Theo dõi đơn" CTA · Toast "Đã gửi xác nhận tới email" |

#### Atoms / molecules / organisms used
- 📄 [Tag](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/tag.html) — product category chips
- 📄 [NumberInput](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/number-input.html) — VND currency variant, quantity stepper variant
- 📄 [DatePicker](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/date-picker.html) — VN locale, future dates only
- 📄 [Slider](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/slider.html) — delivery time window (8-12h / 13-17h / 18-21h)
- 📄 [Toolbar](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/toolbar.html) — sticky bottom on mobile, contains back + primary
- 📄 [Toast](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/toast.html) — confirmation messages

#### UX rationale per step
- **Step 1 inline quantity NumberInput, not pop-out modal**: each tap to mutate cart should NOT context-switch. Stay on cart, see total recompute live.
- **Step 1 running total bold + tabular-nums**: VND numbers are long ("1.250.000đ"), tabular alignment lets eye scan totals without thrash. Foundation token: `font-variant-numeric: tabular-nums`.
- **Step 2 Slider for delivery time, not dropdown**: 3 options, spatial choice beats expanded list. Slider gives haptic-feel even on desktop. (For 5+ options, switch to SegmentedControl or Select.)
- **Step 2 Shipping fee revealed AFTER address chosen**: don't surprise user with fee on payment screen (Baymard top abandonment cause #2: "extra costs too high — shipping, tax, fees"). Reveal early.
- **Step 3 SegmentedControl payment method, not radio list**: 3 options, visual parity, no scroll. Selected method expands inline detail (account number, COD note, e-wallet QR).
- **Step 3 button text "Xác nhận thanh toán" not "Đặt hàng"**: at the payment confirm moment, the action is _payment commitment_ specifically. "Đặt hàng" was on step-1 cart button.
- **Step 4 order code "AN24-001" must be copyable**: long-press / tap copies to clipboard + toast "Đã sao chép mã đơn AN24-001". User screen-shots receipts to share via Zalo.
- **Step 4 back-button blocked** (browser-back triggers modal "Đơn đã đặt thành công. Quay lại sẽ không hủy đơn — bạn vẫn muốn rời?"): prevents accidental return + re-submit anxiety.

#### Brand-aware variants
- **KHI Wellness**: checkout for class booking, not physical goods. Step 2 = pick class slot (DatePicker week-strip), step 3 = pick package (SegmentedControl 1-buổi / 4-buổi / Tháng), step 4 = calendar add + reminder.
- **BetterBuy**: same 4 steps but step 3 includes installment SegmentedControl (Trả 1 lần / 3 tháng / 6 tháng), warning Tag if installment fee > X%.

---

### Case study 3 — F3 Onboarding (A-Kryphan, PWA, warm)
**Demo:** 📄 [flows/onboarding.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/onboarding.html)

#### Goal + motivation
First-open of A-Kryphan blog/reading app. Goal = personalize feed so the user's _next_ session is non-empty. Smashing Magazine's onboarding guidance: "delay sign-in as long as possible by allowing users to experience the app first". So: onboarding here _is_ the first read — pick topics, pick depth, see the feed populated _with what you chose_.

#### Step-by-step screens

| Step | Screen | What's on screen |
|------|--------|------------------|
| 1 | Chào | Editorial cover · "Bài đọc dành riêng cho bạn" · Tertiary "Bỏ qua, vào thẳng" link · Primary "Bắt đầu 30 giây" |
| 2 | Sở thích | "Bạn thường đọc về gì?" · SegmentedControl multi-select 8 chips (Sản phẩm / Đầu tư / Sống chậm / Công nghệ / Sức khỏe / Đọc sách / Tài chính / Khác) · ProgressBar 33% |
| 3 | Nhịp đọc | "Bài dài hay ngắn?" · Slider 3-5min / 5-10min / 10-20min · "Buổi nào bạn rảnh đọc?" SegmentedControl Sáng/Trưa/Tối · ProgressBar 66% |
| 4 | Avatar (optional) | FileUploader avatar · "Gọi mình là gì?" text input · Tertiary "Để sau" · Primary "Xong, cho mình xem feed" |
| 5 | Done | Animated fade-in of feed · Toast "Đã chuẩn bị 12 bài hợp với bạn" |

#### Atoms / molecules / organisms used
- 📄 [SegmentedControl](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/segmented-control.html) — multi-select chip mode (step 2), single-select (step 3)
- 📄 [Slider](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/slider.html) — discrete 3-stop, reading length
- 📄 [FileUploader](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/file-uploader.html) — avatar variant, square crop preview
- ProgressBar inline (use `loading-progress.html` pattern as the atom)
- 📄 [Toast](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/toast.html)

#### UX rationale per step
- **Step 1 "Bắt đầu 30 giây" not "Bắt đầu"**: time commitment is the friction. Naming it ("30 giây") shrinks the perceived cost. Smashing Magazine: register friction lowers when user knows up-front the cost.
- **Step 1 "Bỏ qua, vào thẳng" tertiary link**: respect the user who wants to skip. Default feed will be generic-popular. Onboarding completion is NOT a hard requirement to use the app.
- **Step 2 ProgressBar starting at 33%, not 0%**: psychological motivation — Material's onboarding doc + UXPin both note that "starting with a partially completed progress bar helps a user feel like they've already accomplished something". The "Bắt đầu" tap counts as progress.
- **Step 3 Slider with 3 discrete stops, not continuous**: discrete = clear choice, continuous = analysis paralysis on a preference. Snap to 3-5/5-10/10-20 minute buckets.
- **Step 4 marked (optional) explicitly**: avatar + name are nice-to-have, not blocking. "Để sau" link makes the optionality explicit instead of hiding it. Brand voice (A-Kryphan reflective) makes "Gọi mình là gì?" softer than "Tên hiển thị".
- **Step 5 "Đã chuẩn bị 12 bài hợp với bạn" specific count**: confirms _the choices mattered_. Vague "Personalizing your feed…" feels generic.

#### Brand-aware variants
- **KHI Wellness onboarding**: same 4 steps but step 2 = "Mục tiêu tập" (Giảm cân / Phục hồi / Tăng dẻo dai / Khác), step 3 = "Thời gian rảnh trong tuần" Slider, step 4 = optional medical-history note.
- **An Nhien**: step 2 = "Mùi hương bạn thích" (Nhẹ / Vừa / Đậm + chip mood: Yên / Tỉnh táo / Thiền), step 3 = "Dịp dùng" (Hàng ngày / Tặng / Thờ cúng).

---

### Case study 4 — F4 Settings (AI Tools, Dashboard, dark)
**Demo:** 📄 [flows/settings.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/settings.html)

#### Goal + motivation
Modify account state from a dashboard surface. Settings is _not_ a wizard — there's no "step 1 → done". It's a hub with tabs, each tab is a mini-form, the danger-zone tab is explicitly walled off. GitHub-style Danger Zone pattern is the industry default for a reason: spatial isolation = cognitive isolation.

#### Tab-by-tab screens

| Tab | Screen | What's on screen |
|-----|--------|------------------|
| Tài khoản | profile form, email change requires re-auth | Avatar FileUploader · text inputs · Save button (sticky bottom) |
| Thông báo | granular notification toggles · SegmentedControl frequency (Realtime / Daily digest / Off) per channel | rows of toggle + freq · "Test gửi thử" link per row |
| Thanh toán | Tag (Free / Pro / Team) plan · DatePicker next billing date (readonly) · invoice history list · upgrade/downgrade Button | plan card · billing date · invoices Table |
| Vùng nguy hiểm | 3 actions: Đăng xuất tất cả thiết bị / Xuất dữ liệu / Xóa tài khoản | red-bordered cards · destructive Button per action · typing confirmation for delete |

#### Atoms / molecules / organisms used
- 📄 [Toolbar](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/toolbar.html) — top tab bar with `role="tablist"`, roving tabindex
- 📄 [DatePicker](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/date-picker.html) — readonly variant for billing date
- 📄 [Tag](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/tag.html) — plan badge
- 📄 [SegmentedControl](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/segmented-control.html) — notification frequency
- Button danger variant (composed from `--danger` semantic token)
- 📄 [Toast](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/toast.html) — for "Đã lưu" / "Lỗi: …"
- 📄 [focus-trap.js](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_assets/focus-trap.js) — applied to delete-confirm modal

#### UX rationale per tab
- **Tab order**: Tài khoản (most-used) → Thông báo → Thanh toán → **Vùng nguy hiểm last** (matches GitHub's Danger Zone bottom-right positioning). Reading order = severity gradient.
- **Sticky save button bottom**: user can edit anywhere on the tab, save without scroll-hunting. Disabled until form dirty.
- **"Test gửi thử" per notification row**: lets user verify the channel works _before_ relying on it for real alerts. Reduces "did the email never arrive or was the toggle off?" debugging.
- **Plan Tag color-coded**: Free = `--text-3` (muted), Pro = `--primary` (brand), Team = `--accent` (premium). Mid-glance recognition.
- **Vùng nguy hiểm: 3 actions, increasing severity**: Đăng xuất TB khác (recoverable in 1 tap) → Xuất dữ liệu (irreversible action but no destruction) → Xóa tài khoản (irreversible destruction). Each escalates the confirmation pattern (CP3).
- **Delete account modal**: focus-trapped, requires typing "XÓA TÀI KHOẢN" verbatim, button disabled until match, 5-second delay even after match enables ("Xác nhận trong 5… 4… 3…") — final speed-bump. The 5s pattern is a "designed friction" — Smashing Magazine on friction-as-feature: "for irreversible actions, the friction itself communicates gravity".
- **Toast after destructive action ≠ auto-dismiss**: "Đã đăng xuất 4 thiết bị khác. iPhone hiện tại vẫn đang đăng nhập." — close-required toast because the user wants to verify the count.

#### Brand-aware variants
- **KHI Wellness**: same 4 tabs + add "Lịch tập" tab for class subscription state. "Vùng nguy hiểm" includes "Hủy gói tháng" with grace-period explainer.
- **An Nhien**: replace "Thanh toán" tab with "Địa chỉ" + "Phương thức thanh toán" sub-sections (consumer e-com, not SaaS subscription).

---

## Section 4 — Anti-pattern checklist (8 mistakes the agent must not make)

Every line below corresponds to a concrete violation the kit has either seen in the wild or that authoritative sources flag explicitly. If the agent's generated flow trips any of these, fix before reporting done.

| # | Anti-pattern | Why bad | Source |
|---|--------------|---------|--------|
| **AP1** | Step indicator "1/4" without label | User loses _where they are conceptually_ — just "fraction" not "topic". Must include label "Bước 2/4: Thanh toán" | Atlassian Progress Tracker · UXPin progress-tracker guide |
| **AP2** | Submit button labeled "Gửi" / "OK" / "Submit" | Generic verb breaks action-object semantics. Use verb+object ("Đặt hàng", "Đăng ký", "Xác nhận thanh toán") | Stripe checkout flow guide |
| **AP3** | Error message "Sai" / "Có lỗi xảy ra" | Vague. Must state _what failed_ + _how to fix_. "Mã OTP không đúng — kiểm tra tin nhắn hoặc bấm Gửi lại mã" | Polaris error guidance |
| **AP4** | Success toast auto-dismiss < 3s | Read window too short for VN script. Default 5s; for financial / destructive confirmation, **no auto-dismiss** | NN/g 10 heuristics § Visibility of system status |
| **AP5** | Validation only on submit | User fills 5 fields, hits submit, sees 5 errors. Validate critical fields on-blur (phone format, email shape, OTP length) | Baymard checkout research |
| **AP6** | Loading state "Loading…" without context | User doesn't know what's happening. "Đang xử lý đơn hàng — không tắt trình duyệt" tells them what + warns them | Stripe two-step confirmation pattern |
| **AP7** | Destructive action with single-click confirm | Account delete / "wipe data" / "log out everywhere" needs typed confirmation + 5s delay. Severity → confirmation strength | GitHub Danger Zone pattern · designmybit destructive UX |
| **AP8** | Multi-step form without back button | User can't review/correct earlier step → abandonment. Back always visible (except post-payment-confirm) | Atlassian forms: "Back sits at very left" |
| **AP9** | Empty state without CTA | Passive "no data" with sad icon dead-ends. Must name absence + suggest action + optional why | Polaris EmptyState component |
| **AP10** | Tabbing through a flow breaks focus order | Focus skips backwards, traps in dropdown, jumps off-screen. Test full Tab cycle on every flow. Apply `focus-trap.js` to modals | WAI-ARIA APG focus management |

---

## Section 5 — Adopting a new flow into the kit

Process for the AI agent when user asks "build flow X for brand Y":

1. **Match X to taxonomy** § 1. If no row matches, the request is either compound (split into 2 flows) or novel (escalate to Dang).
2. **Load case-study recipe** § 3 if X ∈ {F1..F4}. For F5-F8 (planned), follow the principles in § 2 + assemble from atoms.
3. **Apply brand preset** — pick `brands/{Y}.brand.css`, write HTML comment header with archetype + aesthetic + brand + iter.
4. **Microcopy register** — match brand voice (KHI = wellness formal-warm, An Nhien = premium-traditional, A-Kryphan = reflective, AI Tools = functional-tech). Cite atoms in microcopy/ folder if exist.
5. **Run probe**: `pwsh _build\gradient-contrast-probe.ps1 flows/<file>.html` (local mode) — 0 fails required.
6. **Self-critique** 5+2 points (kit § "UI craft" + flow continuity + microcopy quality).
7. **Document choice** in HTML header comment + register in this file's § 1 table.

---

## Section 6 — Cited sources (research backing)

1. **Nielsen Norman Group — User Flow Analysis** — 🌐 [https://www.nngroup.com/articles/](https://www.nngroup.com/articles/) and 🌐 [Disruptive Workflow Design](https://www.nngroup.com/articles/disruptive-workflow-design/). Cited for: task flow analysis principle (CP), "seemingly simple tasks consist of many stages and screens" framing.
2. **Atlassian Design System — Forms Pattern** — 🌐 [https://atlassian.design/patterns/forms/](https://atlassian.design/patterns/forms/). Cited for: progress-tracker convention, "Back" left-align rule (CP7, AP8), multi-step button layout.
3. **Material Design — Onboarding** — 🌐 [https://m2.material.io/design/communication/onboarding.html](https://m2.material.io/design/communication/onboarding.html) and 🌐 [Material 3 Motion tokens](https://m3.material.io/styles/motion/easing-and-duration/tokens-specs). Cited for: 4-tier onboarding model, step indicator best practices (CP1), motion duration scale.
4. **Baymard Institute — E-Commerce Cart & Checkout Usability Research** — 🌐 [https://baymard.com/research/checkout-usability](https://baymard.com/research/checkout-usability) and 🌐 [Checkout Optimization 16→8 Fields](https://baymard.com/blog/checkout-optimization-from-16-fields-to-8). Cited for: 26% abandonment cause data, 35% conversion-lift potential, form-field reduction principle (F2 rationale).
5. **Stripe — Checkout flow design strategies** — 🌐 [https://stripe.com/resources/more/checkout-flow-design-strategies-that-can-help-boost-conversion-and-customer-retention](https://stripe.com/resources/more/checkout-flow-design-strategies-that-can-help-boost-conversion-and-customer-retention) and 🌐 [Payment Successful page guide](https://stripe.com/resources/more/payment-successful-pages) + 🌐 [Two-step confirmation pattern](https://docs.stripe.com/payments/build-a-two-step-confirmation). Cited for: review-before-submit pattern (F2 step 3), step-tracker reducing drop-off (CP1), success page composition (AP4, F2 step 4).
6. **Shopify Polaris — Empty state + Error messages** — 🌐 [https://polaris-react.shopify.com/components/layout-and-structure/empty-state](https://polaris-react.shopify.com/components/layout-and-structure/empty-state) and 🌐 [Polaris Error messages](https://legacy.polaris.shopify.com/patterns/error-messages). Cited for: EmptyState image+headline+action pattern (CP4, AP9), one-click-fix error principle (CP2, AP3).
7. **Smashing Magazine — User Onboarding Flow design** — 🌐 [https://www.smashingmagazine.com/2023/04/design-effective-user-onboarding-flow/](https://www.smashingmagazine.com/2023/04/design-effective-user-onboarding-flow/) and 🌐 [Designing Friction as a Feature](https://www.smashingmagazine.com/2018/01/friction-ux-design-tool/). Cited for: "delay sign-in" principle (F3 rationale), strategic friction for destructive actions (CP3, AP7 — delete account 5s delay).
8. **W3C WAI-ARIA Authoring Practices Guide (APG)** — 🌐 [https://www.w3.org/WAI/ARIA/apg/patterns/](https://www.w3.org/WAI/ARIA/apg/patterns/) (Tabs, Radio Group, Breadcrumb patterns). Cited for: `role="tablist"` + roving tabindex (F4 tabs), `role="radiogroup"` (SegmentedControl in all 4 flows), `aria-current="step"` semantics (CP1, AP10).
9. **UXPin / Mobbin — Progress Tracker Design** — 🌐 [https://www.uxpin.com/studio/blog/design-progress-trackers/](https://www.uxpin.com/studio/blog/design-progress-trackers/) and 🌐 [Mobbin Progress Indicator glossary](https://mobbin.com/glossary/progress-indicator). Cited for: 3-7 step optimum, partial-progress motivation, vertical-stepper mobile fallback (F1/F3 mobile rationale).
10. **GitHub Danger Zone pattern + designmybit destructive UX** — 🌐 [https://designmybit.com/designing-better-buttons-how-to-handle-destructive-actions/](https://designmybit.com/designing-better-buttons-how-to-handle-destructive-actions/). Cited for: typing-confirmation pattern + spatial isolation of destructive actions (F4 Danger Zone, CP3, AP7).

---

**Version log**

| Version | Date | Change |
|---------|------|--------|
| 0.5.12-pending | 2026-05-20 | Initial FLOWS.md + 4 demo HTML (Login KHI, Checkout An Nhien, Onboarding A-Kryphan, Settings AI Tools) |