@schilling.mark.a/software-methodology 1.0.0

package/ui-design-workflow/references/screen-flows.md

@@ -0,0 +1,116 @@
+# Screen Flows
+
+## What is a Screen Flow?
+
+A screen flow documents every screen a feature touches, how they connect, what each screen contains, and how it behaves. It is the design specification that acceptance tests verify against.
+
+## Design Principles
+
+**Follow the user, not the feature.** Order screens by the path the user walks, not by technical grouping. A user creating an invoice starts at the list, moves to the form, ends at the detail. Design in that order.
+
+**One screen flow per feature.** A feature file maps to one screen flow document. If a feature touches screens that already exist, document what changes on those screens — don't redesign from scratch.
+
+**Design for the walking skeleton first.** The minimum viable version of each screen. Depth (sorting, filtering, pagination) comes in later releases.
+
+**Annotate with scenario references.** Every design decision should trace back to a specific scenario. This makes acceptance tests straightforward to write.
+
+## Screen Document Structure
+
+Each screen within the flow follows this structure:
+
+```markdown
+### [Screen Name]
+
+**Entry from:** [Previous screen] via [action — e.g., "Create button"]
+**Scenario refs:** [TASK-ID], Scenario: [scenario name]
+
+#### Layout
+[Describe the spatial arrangement — what's at the top, middle, bottom.
+Use a simple ASCII wireframe or prose description.]
+
+#### Data Displayed
+| Element | Source | Format |
+|---------|--------|--------|
+| [Label] | [where data comes from] | [how it's formatted] |
+
+#### Actions
+| Action | Control Type | Outcome |
+|--------|-------------|---------|
+| [What user does] | [button/input/select/link] | [what happens next] |
+
+#### States
+- **Default:** [what the screen looks like when first loaded]
+- **Loading:** [what the user sees while data is fetching]
+- **Empty:** [what the user sees when there's no data]
+- **Error:** [what the user sees when something fails]
+- **Success:** [what the user sees after a successful action]
+
+#### Accessibility
+- [Key keyboard navigation path]
+- [Screen reader label for primary action]
+- [Any ARIA roles or states needed]
+```
+
+## File Format
+
+Create: `/docs/ui-design/screen-flows/[feature-name].md`
+
+```markdown
+# Screen Flow: [Feature Name]
+
+**Feature file:** `/features/[domain]/[feature].feature`
+**Story map task:** [TASK-ID]
+**Release:** [Release name]
+
+## Flow Summary
+
+[Simple prose description of the user's path through the feature.
+2-3 sentences maximum.]
+
+## Flow Diagram
+
+```
+[Screen A] --[action]--> [Screen B] --[action]--> [Screen C]
+                              |
+                         [error] --> [Screen B with error state]
+```
+
+## Screens
+
+[Screen documents in user-flow order, using the structure above]
+```
+
+## Notation for Flow Diagrams
+
+Keep diagrams simple. ASCII is fine — the point is connectivity, not visual polish.
+
+```
+[List Page] --[Create button]--> [Create Form]
+[Create Form] --[Save]--> [Detail Page]
+[Create Form] --[Cancel]--> [List Page]
+[Create Form] --[validation error]--> [Create Form, error state]
+[Detail Page] --[Edit button]--> [Edit Form]
+[Detail Page] --[Back]--> [List Page]
+```
+
+## Designing for Existing Screens
+
+When a new feature adds to a screen that already exists, document only the delta:
+
+```markdown
+### Invoice List (modified)
+
+**Changes for this feature:**
+- New column: "Status" — displays invoice state (Draft/Sent/Paid/Cancelled)
+- New filter: "Status" dropdown in filter bar
+- New action: "Export" button in toolbar
+
+**Unchanged:** Sorting, pagination, search, row selection
+```
+
+## Common Mistakes
+
+- Designing screens that no scenario requires — stick to what the scenarios describe
+- Skipping the empty and error states — these are scenarios too
+- Making screens too dense — if a screen has more than 7 primary actions, it's doing too much. Split into sub-screens or progressive disclosure
+- Ignoring mobile — if the product will be used on mobile, note responsive breakpoints

package/ux-design/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ux-design
+description: UX design skill for information architecture, interaction design patterns, usability evaluation, and onboarding strategy. Use after BDD scenarios are written and before UI design workflow runs. Triggered when the user says "design the experience", "plan the IA", "how should this interact", "is this usable", or "design onboarding". Reads personas, mental models, and feature files. Produces IA documents, interaction specs, and usability evaluations. Ensures the product is findable, learnable, and recoverable before any screens are designed.
+---
+
+# UX Design
+
+## Overview
+
+Bridges research and visual design. Takes what ux-research learned about users and what bdd-specification defined as scenarios, then answers the structural questions: How is the product organized? How do controls behave? Will users actually be able to use this? How do first-time users learn it? These questions must be answered before screen flows are designed.
+
+## When to Run This Skill
+
+- **New feature with UI:** After scenarios are written, before ui-design-workflow runs
+- **Restructuring existing features:** When navigation is confusing or task completion rates are low
+- **New user segment:** When the product must now serve users with different mental models or skill levels
+
+## Workflow
+
+### Step 1: Define Information Architecture
+
+IA is how the product is organized — what lives where, how users find things, how the mental hierarchy maps to navigation. A wrong IA means users can't find what they need. A right IA feels obvious.
+
+See `references/information-architecture.md` for structure, navigation patterns, and how to derive IA from mental models.
+
+Create: `/docs/ux-design/information-architecture.md`
+
+### Step 2: Define Interaction Patterns
+
+Interaction patterns are the rules that govern how controls behave. Consistency across the product means users learn once and apply everywhere. Inconsistency means every screen feels like a new product.
+
+See `references/interaction-patterns.md` for the pattern catalog — feedback loops, form behavior, progressive disclosure, error recovery, and state transitions.
+
+Create or update: `/docs/ux-design/interaction-patterns.md`
+
+### Step 3: Evaluate Usability
+
+Before any screen is designed, evaluate the planned experience against established usability heuristics. Catch problems at the cheapest possible point — on paper, not after implementation.
+
+See `references/usability-evaluation.md` for the evaluation framework, heuristics, and how to produce an evaluation report.
+
+Create: `/docs/ux-design/usability-evaluation/[feature-name].md`
+
+### Step 4: Design Onboarding Strategy
+
+First-time users have no context. They don't know what the product does, where things are, or what to do first. Onboarding bridges that gap — but only if it's designed intentionally.
+
+See `references/onboarding.md` for onboarding patterns, when to use each, and how to design for the empty state.
+
+Create: `/docs/ux-design/onboarding.md`
+
+## File Structure
+
+```
+docs/ux-design/
+├── information-architecture.md      ← Product organization and navigation
+├── interaction-patterns.md          ← How controls behave across the product
+├── onboarding.md                    ← First-time user experience strategy
+└── usability-evaluation/
+    └── [feature-name].md            ← Evaluation report per feature
+```
+
+## Integration
+
+```
+ux-research        →  personas, mental models, journeys
+    ↓
+bdd-specification  →  scenarios (Given/When/Then)
+    ↓
+ux-design (this skill)  →  IA, interaction patterns, usability check, onboarding
+    ↓
+ui-design-workflow →  screen flows and component specs
+```
+
+IA determines the navigation structure that screen flows follow. Interaction patterns determine how components behave in every screen. Usability evaluation catches problems before screens are designed. Onboarding strategy determines what the empty state and first-use experience look like.

package/ux-design/references/information-architecture.md

@@ -0,0 +1,144 @@
+# Information Architecture
+
+## What Is Information Architecture?
+
+IA is the structure of the product — how content and features are organized, categorized, and labeled so users can find what they need. It determines what appears in the navigation, how pages relate to each other, and what mental categories the product uses.
+
+Good IA feels invisible. Users find things where they expect them without thinking about it. Bad IA feels like a maze — users know what they want but can't find it.
+
+## Deriving IA from Mental Models and Story Maps
+
+IA is not invented. It is derived from two sources:
+
+### Source 1: Mental Models (from ux-research)
+
+Read `/docs/ux-research/mental-models/`. The mental model defines the categories users expect. If the user thinks of their work in terms of "invoices", "customers", and "payments", those are the top-level categories — regardless of how the database is structured.
+
+**Rule:** Navigation labels match mental model vocabulary. Never expose system terminology in navigation.
+
+### Source 2: Story Map Backbone (from story-mapping)
+
+Read `/docs/story-map/backbone.md`. Each activity on the backbone is a potential top-level navigation item. The backbone is already ordered by user flow — IA follows that order.
+
+**Rule:** If an activity has enough tasks to warrant its own section, it becomes a nav item. If it has 1–2 tasks, it may live inside a parent section.
+
+## Navigation Patterns
+
+Choose ONE pattern for the product. Do not mix patterns. Consistency is more important than any individual pattern being "better."
+
+### Top Navigation Bar
+**When to use:** 3–6 top-level sections. Desktop-primary products. Products where users switch between sections frequently.
+
+```
+[Logo]  [Section A] [Section B] [Section C] [Section D]     [User]
+         ^^^^^^^^^^
+         Active section highlighted
+```
+
+**Rules:**
+- Maximum 6 items. More = group into a dropdown or rethink the IA.
+- Active section is always visually distinct.
+- Sub-sections appear as a secondary nav row or dropdown on hover/click.
+
+### Sidebar Navigation
+**When to use:** 5+ top-level sections with sub-sections. App-style products where users spend long sessions inside one section. Products with hierarchical content.
+
+```
+┌─────────────┐
+│ [Logo]      │
+│             │
+│ [Section A] │  ← active
+│  [Sub 1]    │
+│  [Sub 2]    │
+│ [Section B] │
+│ [Section C] │
+└─────────────┘
+```
+
+**Rules:**
+- Expandable/collapsible sections keep the sidebar scannable.
+- Active item + active section are both highlighted.
+- On mobile, sidebar becomes a drawer opened by hamburger menu.
+
+### Bottom Navigation (Mobile Only)
+**When to use:** Mobile-first products with 3–5 primary sections. Users need one-thumb access to all major areas.
+
+```
+┌───────────────────────┐
+│                       │
+│     [Content]         │
+│                       │
+├───────────────────────┤
+│ [A]  [B]  [C]  [D]   │  ← icons + labels, active highlighted
+└───────────────────────┘
+```
+
+**Rules:**
+- Maximum 5 items (4 is ideal).
+- Icons must be universally understood or labeled.
+- Current section is highlighted. Badges show counts (unread, pending).
+
+## Labeling Rules
+
+Labels are the words that appear in navigation and headings. They must match the mental model vocabulary exactly.
+
+- Use the terms from `/docs/ubiquitous-language.md`
+- Use nouns for sections ("Invoices"), not verbs ("Create Invoice")
+- Use plural for collections ("Invoices", "Customers"), singular for individual items ("Invoice #001")
+- Never use internal system names, database table names, or technical terms in navigation
+
+## Hierarchy Rules
+
+- **Maximum depth: 3 levels.** Top section → Sub-section → Detail page. Deeper than 3 means the IA is too complex. Flatten or split.
+- **Breadcrumbs for depth.** Any page more than 2 levels deep shows breadcrumbs so users know where they are and can navigate back.
+- **Current location is always visible.** The user must always be able to answer "where am I?" by looking at the navigation.
+
+## File Format
+
+Create: `/docs/ux-design/information-architecture.md`
+
+```markdown
+# Information Architecture
+
+**Navigation pattern:** [Top nav / Sidebar / Bottom nav]
+**Source:** Derived from personas [list] and backbone activities [list]
+
+## Navigation Structure
+
+```
+[Section A: Label]
+├── [Sub-section A1: Label]
+├── [Sub-section A2: Label]
+└── Detail: [Individual item page]
+
+[Section B: Label]
+├── [Sub-section B1: Label]
+└── Detail: [Individual item page]
+```
+
+## Section Definitions
+
+### [Section A: Label]
+**Mental model source:** [Which mental model this maps to]
+**Backbone activity:** [Which story map activity]
+**Contains:** [What the user finds here]
+**Entry point:** [How users get here — nav item, link, etc.]
+
+### [Section B: Label]
+[Same structure]
+
+## Labeling Decisions
+| Label used | Why | Alternative rejected | Why rejected |
+|---|---|---|---|
+| [Label] | [Reason — matches mental model / ubiquitous language] | [Alt] | [Why not] |
+
+## Navigation Rules (product-specific)
+- [Any rules specific to this product's IA]
+```
+
+## Common IA Mistakes
+
+- **Organizing by feature instead of by user goal.** "Reports" is a feature. "My Business Health" is a user goal. Organize around what the user wants to accomplish.
+- **Too many top-level sections.** If navigation has 8+ items, users can't scan it. Group related sections. Reduce scope.
+- **Inconsistent labeling.** Calling something "Invoices" in the nav but "Bills" in the content. Pick one term. Use it everywhere.
+- **Burying critical actions.** If the primary action (create invoice) requires more than 2 clicks from any page, the IA is wrong. Primary actions should be reachable from anywhere.

package/ux-design/references/interaction-patterns.md

@@ -0,0 +1,141 @@
+# Interaction Patterns
+
+## What Are Interaction Patterns?
+
+Interaction patterns are the rules that govern how controls behave. They are product-wide conventions. A button behaves the same way on every screen. A form validates the same way everywhere. An error is presented the same way throughout.
+
+Consistency here is the difference between a product that feels like one cohesive tool and a product that feels like a collection of unrelated screens.
+
+## Pattern 1: Feedback Loops
+
+Every action the user takes must produce a visible result. Without feedback, users don't know if their action worked, repeat it (causing duplicates), or lose trust.
+
+### Feedback Timing
+
+| Action type | Feedback timing | Feedback type |
+|---|---|---|
+| Button click (instant action) | Immediate (< 200ms) | Visual state change on button |
+| Form submission | Immediate (button shows loading) | Loading state, then success or error |
+| Data save (auto-save) | Within 2 seconds | Subtle "Saved" indicator, fades after 3s |
+| Background process | Within 5 seconds | Progress indicator or status update |
+| Long-running process (> 10s) | Ongoing | Progress bar with estimated time, or "We're working on it" |
+
+### Feedback Hierarchy
+
+- **Micro-feedback:** Button press ripple, checkbox toggle animation. Confirms the control registered the interaction.
+- **Action feedback:** Toast notification, inline status change. Confirms the action completed.
+- **State feedback:** Page updates, data refreshes. Confirms the result is reflected.
+
+**Rule:** Never skip a level. If a button click triggers a save, the user needs micro-feedback (button reacts), action feedback (save confirmed), AND state feedback (the saved data appears).
+
+## Pattern 2: Form Behavior
+
+Forms are the most common interaction pattern. Consistency here has the highest impact.
+
+### Validation Timing
+
+| Validation type | When to validate | Why |
+|---|---|---|
+| Required field | On blur (when user leaves the field) | Validates too early (on focus) is annoying. Too late (on submit) wastes time. |
+| Format validation (email, phone) | On blur | Same reasoning as required fields |
+| Cross-field validation (password confirm) | On blur of the second field | Can't validate until both fields have values |
+| Business rule validation (unique name) | On blur, requires server call | Must check against existing data |
+| Form-level validation | On submit | Catches anything field-level missed |
+
+### Error Presentation
+
+- Field-level errors appear **inline, directly below the field**. Never at the top of the form alone.
+- The field border changes to error state (see ui-design-system components reference).
+- Focus moves to the first field with an error on submit.
+- Error messages are specific: "Email must contain @" not "Invalid input".
+- Error messages suggest correction: "Must be at least 8 characters (currently 5)" not just "Too short".
+
+### Success After Submit
+
+- Form disappears or transitions to a confirmation/detail view
+- A success indicator confirms what was created or saved
+- The user can immediately see the result of their action — no need to navigate elsewhere to verify
+
+## Pattern 3: Progressive Disclosure
+
+Show only what the user needs right now. Reveal more as their context develops. Overwhelming users with all options at once increases cognitive load and reduces task completion.
+
+### Levels of Disclosure
+
+**Level 1 — Default view:** The minimum controls needed for the most common action. Everything else is hidden.
+
+**Level 2 — Expanded view:** Additional options revealed when the user indicates they need them (clicks "More options", selects a specific variant, etc.)
+
+**Level 3 — Advanced view:** Power-user options behind a clearly labeled "Advanced" toggle or section. Most users never see this.
+
+### When to Disclose
+
+| Trigger | Pattern |
+|---|---|
+| User clicks "More options" | Expand additional fields/controls inline |
+| User selects a specific type | Show fields relevant to that type only |
+| User has completed the basic flow | Offer enhancements ("Want to add a discount?") |
+| User explicitly opts in | Show advanced configuration panel |
+
+### Rules
+- The default view must be sufficient to complete the primary task
+- Disclosed content appears adjacent to the trigger, not in a separate location
+- Disclosure state persists within the session — don't collapse it every time
+- Label what's hidden: "3 more options available" not just a vague "More" button
+
+## Pattern 4: Error Recovery
+
+Errors will happen. The product's job is to make recovery as painless as possible. A product that handles errors gracefully builds more trust than a product that never has errors but recovers badly when it does.
+
+### Error Categories and Recovery Patterns
+
+**Validation error (user input is wrong):**
+- Show inline error message
+- Keep all entered data intact — don't clear the form
+- Focus on the first error field
+- User corrects and resubmits — no penalty, no restart
+
+**Not found (resource doesn't exist):**
+- Show a clear message: "[Entity] not found"
+- Suggest what to do next: "Check the ID and try again" or link to the list view
+- Never show a blank page or a generic error code
+
+**Permission denied (user can't do this):**
+- Show a clear message: "You don't have permission to [action]"
+- Explain what permission is needed or who to contact
+- Don't hide the feature entirely — that makes it invisible and confusing
+
+**Server error (something went wrong on our side):**
+- Show a human-readable message: "Something went wrong. Please try again."
+- Preserve entered data wherever possible
+- Offer a retry button
+- If the error persists, suggest contacting support
+
+**Network error (connectivity lost):**
+- Show a connection status indicator
+- Queue actions locally if possible — complete them when reconnected
+- Never lose unsaved work due to a network blip
+
+### Recovery Rules
+- **Never blame the user.** Error messages describe what happened, not what the user did wrong.
+- **Always provide a path forward.** Every error state has at least one action the user can take.
+- **Preserve context.** The user should never have to start over after an error.
+
+## Pattern 5: State Transitions
+
+Many entities in the product move through states (Draft → Sent → Paid). How these transitions are presented determines whether the user understands what's happening or is confused by unexplained changes.
+
+### Visibility Rules
+- The current state is always visible on the entity's detail view
+- State is shown as a badge or status indicator (see ui-design-system components)
+- Available transitions (actions the user can take) are shown as buttons, labeled with the resulting state: "Send Invoice" not just "Next"
+- Unavailable transitions are either hidden or shown as disabled with an explanation
+
+### Transition Feedback
+- Transitioning state shows a brief loading indicator
+- After transition, the state badge updates immediately
+- A confirmation message states what changed: "Invoice sent to ACME Corp"
+- If the transition fails, show an error and return to the previous state — no ambiguous in-between
+
+### State Visibility by Persona
+Different personas may see different states. An accountant reviewing invoices sees "Pending Review" and "Approved". A business owner sending invoices sees "Draft" and "Sent". The state model is the same underneath — the UI filters what's relevant per persona.

package/ux-design/references/onboarding.md

@@ -0,0 +1,159 @@
+# Onboarding
+
+## Why Onboarding Matters
+
+First-time users have zero context. They don't know what the product does, where things are, or what to do first. The first 60 seconds determine whether a user stays or leaves. Onboarding is not a feature — it is the product's first conversation with the user.
+
+The goal of onboarding is not to teach the entire product. It is to get the user to their first success as fast as possible. Once they experience success, they are motivated to explore further.
+
+## The First Success Principle
+
+Every onboarding strategy must answer one question: **What is the single most valuable thing this user can accomplish in the first session, and how do we get them there with zero friction?**
+
+This is the "first success." Everything in onboarding is optimized to reach it. Features, settings, and advanced capabilities wait until after first success.
+
+**Example:** For an invoicing product, first success = "User creates and sends their first invoice." Onboarding does not teach reporting, settings, or integrations first. It guides the user straight to creating an invoice.
+
+## Onboarding Patterns
+
+Choose the pattern(s) appropriate for the product and primary persona. Most products use a combination.
+
+### Pattern 1: Empty State Design
+
+The most important onboarding moment is often the first screen the user sees after signing up — which is empty. An empty screen with no guidance causes immediate abandonment. An empty screen with a clear next step causes immediate engagement.
+
+**Structure of an effective empty state:**
+```
+[Icon or illustration — relates to the domain, not generic]
+
+[Headline — what the user will be able to do here]
+"Your invoices will appear here"
+
+[Body — one sentence of context]
+"Create your first invoice to get started."
+
+[Primary action button — the single most important thing to do]
+[Create Invoice]
+
+[Optional: secondary link for users who need context first]
+"Not sure where to start? See how it works →"
+```
+
+**Rules:**
+- Every list, table, or data view has a designed empty state
+- The empty state is not a blank page with a generic "No data" message
+- The primary action in the empty state is the same action that leads to first success
+- The empty state disappears completely once data exists — it is not a persistent element
+
+### Pattern 2: Guided First Action
+
+After the user clicks the empty state's primary action, guide them through the first completion without interruption.
+
+**How it works:**
+- The form or flow for the first action is pre-populated with sensible defaults wherever possible
+- Required fields are minimal for the first action — reduce friction to zero
+- Helper text or placeholder text explains what to put in each field
+- No optional fields are shown on the first pass (progressive disclosure — see interaction-patterns.md)
+- After completion, a clear success state confirms what was accomplished
+
+**Example flow:**
+```
+1. Empty state: "Create your first invoice"  →  [Create Invoice]
+2. Form appears with:
+   - Customer name (helper: "Who is this invoice for?")
+   - Amount (helper: "How much do they owe?")
+   - Due date (default: 30 days from today)
+   - [Send Invoice] button
+3. Success: "Invoice sent to [Customer]! They'll receive it by email."
+4. User lands on invoice detail — first success achieved.
+```
+
+### Pattern 3: Contextual Tooltips
+
+After first success, reveal additional capabilities at the point where they become relevant — not all at once.
+
+**Rules:**
+- Tooltips appear only when the user navigates to a new area for the first time
+- One tooltip at a time. Never show multiple tooltips simultaneously.
+- Each tooltip explains one thing: what this control does and why it matters
+- Tooltips are dismissible. They do not block interaction.
+- Tooltips do not reappear after dismissal (within the same session or across sessions, depending on product)
+- Tooltips are not shown for controls that are self-explanatory (a button labeled "Save" needs no tooltip)
+
+**Trigger rules:**
+- First visit to a new section → show tooltip for the primary action in that section
+- First time a new feature becomes available (e.g., after completing a prerequisite) → show tooltip explaining the new capability
+- Never show tooltips based on time alone ("You've been using this for 5 minutes, here's a tip") — this interrupts flow
+
+### Pattern 4: Progress Indication
+
+For products where setup requires multiple steps (profile completion, integrations, configuration), show progress so the user knows what remains.
+
+**Structure:**
+```
+Setup Progress: ██████░░░░  60% complete
+
+✅ Create account
+✅ Send first invoice
+○  Connect bank account
+○  Set up recurring invoices
+```
+
+**Rules:**
+- Progress indication is only used when there are 3+ distinct setup steps
+- Each step has a clear completion condition — no ambiguity about whether it's done
+- Steps are ordered by value: the most valuable actions first
+- Completing all steps is encouraged but never required — the product is fully usable after first success
+- Progress indication disappears once all steps are complete or after a reasonable time (it does not linger forever)
+
+## Onboarding Strategy Document
+
+Create: `/docs/ux-design/onboarding.md`
+
+```markdown
+# Onboarding Strategy
+
+**Primary persona:** [Name — from personas]
+**First success definition:** [The single most valuable accomplishment in the first session]
+**Patterns used:** [List: empty state design, guided first action, contextual tooltips, progress indication]
+
+## First Success Flow
+
+[Step-by-step description of how the primary persona reaches first success.
+Include what they see at each step, what is pre-populated, what is hidden.]
+
+1. [Step 1 — what the user sees and does]
+2. [Step 2]
+3. [Step N — first success achieved]
+
+## Empty States
+
+| Screen | Empty state message | Primary action | Secondary link |
+|---|---|---|---|
+| [Screen name] | [Headline] | [Button label] | [Link text → destination] |
+| [Screen name] | [Headline] | [Button label] | [Link text → destination] |
+
+## Contextual Tooltips
+
+| Location | Trigger | Tooltip text | Why here |
+|---|---|---|---|
+| [Control or section] | [What triggers it] | [What the tooltip says] | [Why this is the right moment] |
+
+## Progress Steps (if applicable)
+
+| Step | Completion condition | Value delivered |
+|---|---|---|
+| [Step name] | [How we know it's done] | [What the user gains] |
+
+## Secondary Persona Onboarding
+
+[How does the secondary persona's first experience differ? Do they need a different first success path? Are there empty states specific to their view?]
+```
+
+## Common Onboarding Mistakes
+
+- **Teaching the product before the user has a reason to care.** A video tour on signup teaches nothing — the user has no context to attach the information to. Guide them to first success first. Then teach.
+- **Requiring setup before first value.** If the user must complete a 10-step setup before they can do anything useful, they leave. Make first success possible with zero setup.
+- **Showing everything at once.** A dashboard full of empty widgets and "Get started" prompts everywhere is as confusing as an empty page. One clear next step at a time.
+- **Never letting go.** Tooltips and guides that persist forever become noise. They should fade as the user becomes comfortable. The product should feel clean and uncluttered after the first session.
+- **Ignoring the returning user.** A user who left mid-onboarding and returns should pick up where they left off, not restart. Preserve state.