# Design & UX

How the problem in [`problem-and-research.md`](./problem-and-research.md) becomes an interface, following the IBM UX Design process: define → ideate → structure → wireframe → visual design.

## 1. Design principles

- **Progressive disclosure** — never ask for everything at once; reveal fields as they become relevant.
- **Optional identity sharing** — every sensitive question ships with a "prefer not to say" path. No field is mandatory except the ones that are functionally required to show a result.
- **Warm, not clinical** — soft colour, human language, no corporate tone. This is a mirror, not a form.
- **Low cognitive load** — one primary action per screen.
- **Inclusive by default** — high contrast, large tap targets, screen-reader-friendly labelling.

## 2. User stories

Written role → action → benefit, the format IBM's UX course uses to keep stories user-centred and testable.

1. As **Anika**, I want to find a woman who grew up in a background like mine and made it in STEM, so I believe it's possible for me too.
2. As **Jessie**, I want to see the exact steps a First Nations woman took to get into environmental science, so I can follow a similar path from my region.
3. As a user with no polished resume, I want to build a program application from a short guided conversation instead of a blank form, so applying doesn't stall before it starts.
4. As **Ms. Patel**, I want to share one link with my class and see where representation gaps are, so I know which stories to go find next.
5. As any user, I want to see *why* I matched with someone in plain language, not a percentage, so it feels like a reason, not a score.
6. As a user whose exact background has no story yet, I want that to be logged as missing rather than shown as nothing, so I know the gap is being worked on.

## 3. User journey

Mapped against the standard awareness → advocacy stages, anchored to how a user actually arrives (a Robogals workshop QR code):

| Stage | Touchpoint | User feeling | Opportunity |
|---|---|---|---|
| **Awareness** | QR code at the end of a workshop | Curious, low commitment | Land directly on the "pick your path" choice — no forced quiz |
| **Consideration** | Splash → Swipe or Match | Testing the water | Let her browse before asking for anything personal |
| **Decision** | 5-question identity quiz | Slightly vulnerable | Every question optional; explain *why* it's asked before asking |
| **Service** | Matches → story detail → take-action hub | Emotionally engaged | Surface a scholarship/program tied to the story she just read |
| **Loyalty** | Saved library, reminders | Invested | Private notes on why a story mattered keep it personal, not just bookmarked |
| **Advocacy** | Story submission, share | Empowered | Let a woman who matched become a future match for someone else |

## 4. Information architecture

The prototype implements this flow as 22 screens:

```
Splash
 └─ Pick Your Path
     ├─ Swipe (browse mode) ──────┐
     └─ Match quiz (5 steps)      │
         └─ Matching / loading    │
             └─ Your Matches ◄────┘
                 └─ Story Detail
                     ├─ Missing Story alert (if no match)
                     └─ Take Action Hub
                         └─ Program Detail
                             └─ Smart Apply
                                 ├─ Import (LinkedIn / resume)
                                 └─ Build It Together (guided, no-resume path)
My Elevra (saved stories, programs, applications)
Profile
Coordinator Dashboard (org-facing, shown separately from the user flow)
```

Two entry doors (Swipe and Match) exist because forcing a quiz before any value is shown contradicts progressive disclosure — a user who isn't ready to disclose anything can still get value from browsing.

## 5. Visual design system

Tokens as implemented in [`/prototype/index.html`](../prototype/index.html):

| Token | Value | Use |
|---|---|---|
| `--primary` | `#C95F4A` warm terracotta | Primary actions, brand |
| `--secondary` | `#6B9080` sage green | Secondary actions, growth/calm cues |
| `--accent` | `#E8B14C` | Highlights, badges |
| `--bg-primary` / `--bg-secondary` | `#FFFFFF` / `#FAF8F5` | Surface layering |
| `--text-primary` / `--text-secondary` | `#1C1C1E` / `#6B6B70` | Type hierarchy |
| Radius scale | `8 / 12 / 16 / 20px` | Consistent rounding from chip to card |
| Type | System font stack (SF Pro / Segoe UI / Roboto) | Native feel across platforms, zero load cost |

**Rationale:** terracotta and sage read as human and approachable rather than "techy," deliberately avoiding the blue/purple SaaS default — this is a product about seeing yourself in someone else, not a dashboard.

## 6. Accessibility considerations

- Colour pairs checked for contrast on body text against both background tokens.
- Every identity question offers a non-visual, keyboard-reachable "skip" affordance, not just a visual X.
- Copy avoids jargon (e.g. "Payment failed. Please try again." over a raw error string) per plain-language UX writing guidance.
- Tap targets sized for one-handed mobile use, since the primary entry point is a phone scan at a workshop.