nwave-ai/nw-design-methodology

Design Methodology (Apple LeanUX++)

Design Workflow

PHASE 1              PHASE 2              PHASE 3              PHASE 4
Journey Mapping      Emotional Design     TUI Prototyping      Integration Check
      |                    |                    |                    |
      v                    v                    v                    v
"What's the flow?"   "How should it feel?"  "What does it look?"  "Does it connect?"

Phase 1: Journey Mapping (1-2 days)

• Techniques: User journey mapping | goal-completion flow | step identification
• Question: "What complete journey is the user trying to accomplish?"
• Output: Journey map with steps, commands, and touchpoints

Phase 2: Emotional Design (1 day)

• Techniques: Emotional arc design | form follows feeling | transition analysis
• Question: "How should the user FEEL at each step?"
• Output: Emotional annotations on journey map

Phase 3: TUI Prototyping (1-3 days)

• Techniques: Progressive fidelity | ASCII mockups | TUI design patterns
• Question: "What does each step look like?"
• Output: TUI mockups for each journey step

Phase 4: Integration Check (1 day)

• Techniques: Shared artifact tracking | horizontal coherence | CLI vocabulary
• Question: "Do all pieces connect properly?"
• Output: Validated journey with integration checkpoints

Journey Schema

schema_version: 1

journey:
  name: "{Goal Name}"
  goal: "{What user is trying to accomplish}"
  persona: "{User persona reference}"

  emotional_arc:
    start: "{Initial emotional state}"
    middle: "{Journey emotional state}"
    end: "{Final emotional state}"

steps:
  - id: 1
    name: "{Step Name}"
    command: "{CLI command or action}"

    tui_mockup: |
      +-- Step N: {Name} -----------------------------------------+
      | {ASCII representation of CLI output}                       |
      | ${variable} <-- tracked artifact                           |
      +------------------------------------------------------------+

    shared_artifacts:
      - name: "{artifact_name}"
        source: "{single source of truth file}"
        displayed_as: "${variable}"
        consumers: ["{list of places this appears}"]

    emotional_state:
      entry: "{How user feels entering step}"
      exit: "{How user feels after step}"

    integration_checkpoint: |
      {What must be validated before proceeding}

    failure_modes:
      - "{What can go wrong at this step — used by DISTILL for error scenario generation}"
      - "{Another failure scenario}"

    gherkin: |
      Scenario: {Step description}
        Given {precondition}
        When {action}
        Then {observable outcome}
        And shared artifact "${variable}" matches source

integration_validation:
  shared_artifact_consistency:
    - artifact: "{name}"
      must_match_across: [1, 2, 3]
      failure_message: "{Integration error description}"

changelog:
  - date: "{YYYY-MM-DD}"
    feature: "{feature-id}"
    change: "{What changed in this update}"

Emotional Arc Patterns

Confidence Building

Start: Anxious/Uncertain | Middle: Focused/Engaged | End: Confident/Satisfied Use when: Complex multi-step operations

Discovery Joy

Start: Curious | Middle: Exploring | End: Delighted Use when: Learning new features

Problem Relief

Start: Frustrated | Middle: Hopeful | End: Relieved Use when: Fixing issues or debugging

Transition Rules

• Build confidence progressively through small wins
• Provide clear feedback at each step
• Error states guide to resolution rather than adding frustration
• Positive-to-negative transitions need explicit warning or buffer step

Apple Design Principles Applied

• Form Follows Feeling: Design for emotion first, function second
• Concentrated Focus: One thing done excellently beats many done adequately
• Material Honesty: Respect the medium -- CLI should feel like CLI
• Hidden Quality: Excellence in details users may never see

CLI UX Patterns (clig.dev)

Command Structure

• Pattern: tool [noun] [verb] or tool [verb] [noun]
• Pick one pattern consistently across entire journey
• Example: crafter agent create or crafter create agent

Feedback Principles

Responsive: print something in <100ms | Progress: show for long operations | Transparent: show what is happening | Recoverable: clear errors with suggested fixes

Progressive Disclosure

• Level 1 (default): Basic output for common use
• Level 2 (--verbose): Detailed output for power users
• Level 3 (--debug): Diagnostic output for troubleshooting

Help Design

Implement --help on every command | Make help discoverable | Provide contextual suggestions

Output Formats

Three artifact types produced:

1. Visual Journey (journey-{name}-visual.md): ASCII flow diagram with emotional annotations and TUI mockups per step
2. Structured Schema (journey-{name}.yaml): Machine-readable journey definition following schema above
3. Gherkin Scenarios (journey-{name}.feature): Testable acceptance scenarios from each journey step

All artifacts go to docs/feature/{feature-id}/discuss/.