ComputerConnection/design

Product Design: $ARGUMENTS

Deep product thinking before code. Turn ideas into specs.

---

Philosophy

• User-first - Every feature serves someone. Know who.
• Problem-first - Don't design solutions to non-problems
• Scope ruthlessly - What's the smallest thing that delivers value?
• Think in flows - Users don't see features, they experience journeys
• Design for failure - What happens when things go wrong?

---

Phase 1: Problem Definition

The User

┌─────────────────────────────────────────────────────────────┐
│  WHO IS THIS FOR?                                           │
├─────────────────────────────────────────────────────────────┤
│  Primary User: [role/persona]                               │
│  Context: [when/where they encounter this]                  │
│  Current Pain: [what sucks right now]                       │
│  Desired Outcome: [what does success look like for them]    │
└─────────────────────────────────────────────────────────────┘

The Problem

• What problem are we solving? [specific problem]
• How do users solve this today? [current workaround]
• Why does that suck? [pain points]
• How will we know we solved it? [success indicator]

The Trigger

What causes a user to need this feature?

• Event: [what happens]
• Frequency: [how often]
• Urgency: [how time-sensitive]

---

Phase 2: User Journey Mapping

Current State Journey (Before)

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Trigger │───►│  Step 1  │───►│  Step 2  │───►│  Outcome │
│          │    │          │    │  (Pain)  │    │  (Meh)   │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     │                              │
     │                              ▼
     │                        ┌──────────┐
     │                        │ Friction │
     │                        │ Points   │
     │                        └──────────┘

Pain Points:

1. [friction point 1]
2. [friction point 2]
3. [friction point 3]

Future State Journey (After)

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Trigger │───►│  Step 1  │───►│  Step 2  │───►│  Outcome │
│          │    │  (Easy)  │    │  (Easy)  │    │  (Great) │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

Improvements:

1. [how pain point 1 is solved]
2. [how pain point 2 is solved]

---

Phase 3: Feature Specification

Core Capability

One sentence: what does this feature DO?

User Stories

As a [user type], I want to [action] so that [outcome].

| Priority | Story | Acceptance Criteria | |----------|-------|---------------------| | P0 (Must) | As a... | - [ ] Criteria 1 | | P0 (Must) | As a... | - [ ] Criteria 2 | | P1 (Should) | As a... | - [ ] Criteria 3 | | P2 (Nice) | As a... | - [ ] Criteria 4 |

Functional Requirements

## FR-1: [Requirement Name]
The system SHALL [specific behavior]
When [condition]
So that [reason]

## FR-2: [Requirement Name]
...

Non-Functional Requirements

• Performance: [latency, throughput expectations]
• Scale: [how many users/items/requests]
• Availability: [uptime requirements]
• Security: [auth, data sensitivity]
• Accessibility: [a11y requirements]

---

Phase 4: UX Design

Information Architecture

## Screen/View: [Name]

### Purpose
[Why this screen exists]

### Entry Points
- From: [where users come from]
- Via: [how they get here - button, link, nav]

### Core Elements
┌─────────────────────────────────────────┐
│  [Header/Title]                         │
├─────────────────────────────────────────┤
│                                         │
│  [Primary Content Area]                 │
│  - Element 1                            │
│  - Element 2                            │
│  - Element 3                            │
│                                         │
├─────────────────────────────────────────┤
│  [Primary Action]    [Secondary Action] │
└─────────────────────────────────────────┘

### User Actions
- [Action 1] → [Result]
- [Action 2] → [Result]

### Exit Points
- To: [where users go next]
- Via: [how]

Interaction Flow

[State A] ──action──► [State B] ──action──► [State C]
              │                      │
              ▼                      ▼
         [Error State]          [Success State]

Key Interactions

| Trigger | Action | Feedback | Result | |---------|--------|----------|--------| | Click "Submit" | Validate form | Loading spinner | Navigate to confirmation | | Enter invalid data | Show error | Red border + message | Focus on field |

---

Phase 5: Edge Cases & Error States

What Could Go Wrong?

| Scenario | Impact | Handling | |----------|--------|----------| | Network fails | User loses work | Auto-save, retry | | Invalid input | Frustration | Inline validation | | Empty state | Confusion | Helpful empty state | | Timeout | Uncertainty | Clear timeout message | | Permission denied | Blocked | Clear explanation + path forward |

Error Messages

## Error: [Type]
**Tone**: [helpful / apologetic / instructive]
**Message**: [user-facing text]
**Action**: [what they can do]
**Technical**: [what to log/track]

Empty States

• First use: [what to show when no data yet]
• No results: [what to show when search/filter returns nothing]
• Deleted all: [what to show after user deletes everything]

---

Phase 6: MVP Scoping

The Smallest Valuable Thing

What's the absolute minimum that delivers value?

┌─────────────────────────────────────────────────────────────┐
│  MVP SCOPE                                                  │
├─────────────────────────────────────────────────────────────┤
│  IN (Must ship):                                            │
│  - [feature 1]                                              │
│  - [feature 2]                                              │
│  - [feature 3]                                              │
├─────────────────────────────────────────────────────────────┤
│  OUT (Future):                                              │
│  - [feature 4] → v2                                         │
│  - [feature 5] → if users ask                               │
│  - [feature 6] → nice to have                               │
├─────────────────────────────────────────────────────────────┤
│  CUT (Not doing):                                           │
│  - [feature 7] → out of scope                               │
│  - [feature 8] → different product                          │
└─────────────────────────────────────────────────────────────┘

Scoping Questions

• [ ] Can we ship without [feature]? If yes, cut it.
• [ ] Will users complain if [feature] is missing? If no, cut it.
• [ ] Does [feature] add complexity? If yes, defer it.
• [ ] Is [feature] solving a real problem or imagined one?

---

Phase 7: Success Metrics

How Do We Know This Worked?

| Metric | Current | Target | How to Measure | |--------|---------|--------|----------------| | [Metric 1] | [baseline] | [goal] | [method] | | [Metric 2] | [baseline] | [goal] | [method] |

Leading Indicators (early signals)

• [indicator 1]
• [indicator 2]

Lagging Indicators (outcome proof)

• [indicator 1]
• [indicator 2]

Anti-Metrics (what we DON'T want)

• [thing that would indicate failure]

---

Phase 8: Competitive Context

How Do Others Solve This?

| Competitor | Approach | Strengths | Weaknesses | |------------|----------|-----------|------------| | [Name] | [how they do it] | + ... | - ... | | [Name] | [how they do it] | + ... | - ... |

Our Differentiation

• [what makes our approach better/different]

---

Phase 9: Open Questions

Before building, resolve these:

| Question | Options | Recommendation | Needs Input From | |----------|---------|----------------|------------------| | [Q1] | A, B, C | B because... | Zach | | [Q2] | X, Y | Need more info | User research |

---

Phase 10: Design Spec Output

Summary

┌─────────────────────────────────────────────────────────────┐
│  DESIGN SPEC: [Feature Name]                                │
├─────────────────────────────────────────────────────────────┤
│  User: [who]                                                │
│  Problem: [what]                                            │
│  Solution: [how]                                            │
│  MVP Scope: [key items]                                     │
│  Success: [metric]                                          │
├─────────────────────────────────────────────────────────────┤
│  Status: Ready for implementation / Needs decisions         │
└─────────────────────────────────────────────────────────────┘

Handoff to Engineering

1. User stories with acceptance criteria
2. Screen/flow specifications
3. Edge cases and error handling
4. MVP scope boundaries
5. Success metrics for validation

---

Quick Mode

For simple, well-understood features, skip the full process:

┌─────────────────────────────────────────────────────────────┐
│  QUICK DESIGN: [Feature Name]                               │
├─────────────────────────────────────────────────────────────┤
│  User: [who]                                                │
│  Problem: [one sentence]                                    │
│  Solution: [one sentence]                                   │
├─────────────────────────────────────────────────────────────┤
│  Happy Path:                                                │
│  1. User does [action]                                      │
│  2. System does [response]                                  │
│  3. User sees [result]                                      │
├─────────────────────────────────────────────────────────────┤
│  Error Case: [main failure] → [handling]                    │
│  Edge Case: [main edge] → [handling]                        │
├─────────────────────────────────────────────────────────────┤
│  MVP: [what to build]                                       │
│  NOT MVP: [what to skip]                                    │
├─────────────────────────────────────────────────────────────┤
│  Done when: [success criteria]                              │
└─────────────────────────────────────────────────────────────┘

Use Quick Mode when:

• Feature is similar to existing patterns
• User need is well-understood
• Scope is small (< 1 day of work)
• No architectural decisions needed

Use Full Mode when:

• New user flows or interactions
• Multiple approaches possible
• Significant UI/UX decisions
• Cross-cutting concerns (auth, data model changes)

---

Integrating with Existing Codebase

Before designing, understand what exists:

# Find similar features
grep -r "similar-keyword" --include="*.tsx" --include="*.ts" src/

# Check existing patterns
ls -la src/components/
ls -la src/features/

# Review recent similar work
git log --oneline --all --grep="similar feature"

Questions to Answer

• [ ] Is there a similar feature we can extend?
• [ ] What patterns does this codebase use for [forms/modals/lists/etc]?
• [ ] Where should this live in the directory structure?
• [ ] What shared components can we reuse?
• [ ] Does this need new API endpoints or can we use existing ones?

---

Anti-Patterns

• "Let's add this while we're at it" (scope creep)
• "Users might want..." without evidence (assumption-driven)
• "It's just a small feature" (complexity blindness)
• Designing for power users first (forgetting new users)
• Skipping error states (happy path only)
• No success criteria (unmeasurable)
• Designing in a vacuum (not checking existing patterns)

---

Output

1. User and problem definition
2. Journey maps (before/after)
3. Feature spec with user stories
4. UX flow and key screens
5. Edge cases and error handling
6. MVP scope decision
7. Success metrics
8. Open questions for Zach