Requirements and design: user stories, acceptance criteria and accessibility

Once the client has agreed to the proposal, the team turns scope into requirements that can be built and checked. In a capstone this happens in weeks 4 and 5, alongside the architecture work of lesson 5, and it continues throughout the term as the backlog is refined. CMPUT-301 covered requirements engineering, use cases and UML; CMPUT-401 covered user stories and backlogs; CMPUT-421 covered personas, scenarios, prototyping and accessibility. This lesson shows how a capstone team uses those tools together without drowning in documentation, and why accessibility belongs in requirements from the first day rather than in a final audit.

The goal of requirements work in an agile capstone is not a complete specification. It is shared understanding: the team, the client and the supervisor should agree on what each feature does, for whom, and how everyone will know it works. A few well-written stories with clear acceptance criteria, a set of wireframes the client has seen and a short list of non-functional requirements give far more value than a fifty-page document that nobody reads. Requirements will change as the client sees working software, and the process should make change cheap.

Users and their goals

Start from the people found in discovery. Team Relay wrote three short personas based on real interviews, not imagination: a coordinator modeled on Grace's work; a regular driver, retired, who drives three mornings a week and is comfortable with a phone but not with apps that change often; and an occasional driver, a student who picks up weekend shifts and wants to sign up and swap in seconds. They also wrote one anti-persona, someone the product is not designed for: a large logistics company with paid drivers and dispatch software. The anti-persona was useful for rejecting requests that would pull the product away from a volunteer organization.

For each persona, sketch the main task flows end to end. The driver's core flow is: see open shifts, claim one, get a reminder, confirm or cancel, do the pickup and mark it complete. The coordinator's is: create recurring shifts with donors and agencies, see which are unfilled or unconfirmed, contact drivers, and see what was rescued. Walking through flows before designing screens finds gaps. Team Relay realized while walking the driver flow that a driver who cancels needs somewhere for the shift to go: back to the open list, and with an alert to the coordinator if it is within 24 hours. That became a requirement nobody had stated.

User stories and acceptance criteria

A user story describes a small piece of value from a user's point of view: 'As a driver, I want to claim an open pickup shift so that I can help when I am free.' The three parts name who wants it, what they want and why. The 'why' is the most useful part: it lets the team propose a better way to meet the need, and it lets the client judge priority. Good stories follow the INVEST guidelines from CMPUT-401: independent, negotiable, valuable, estimable, small and testable. In practice the two that matter most for a capstone are small (finishable in a few days) and testable (everyone can agree whether it is done).

Acceptance criteria make a story testable. Write them in the Given, When, Then form: given a situation, when the user does something, then something observable happens. 'Given an open shift, when I tap Claim, then the shift shows my name and is no longer open.' Criteria like this translate almost directly into automated tests (lesson 8) and into a script for the client to check at a demo. Vague words such as 'easy', 'fast' or 'user-friendly' cannot be checked and should be replaced by something measurable, like 'the dashboard loads in under two seconds on the co-op's office laptop'.

# A small linter for user stories and acceptance criteria.
# Flags stories that miss the "As a / I want / so that" form, criteria that are not
# Given/When/Then, vague words that cannot be tested, and stories that are too big.
import re
stories = [
    {"id": "RR-12", "points": 3,
     "text": "As a driver, I want to claim an open pickup shift so that I can help when I am free.",
     "criteria": ["Given an open shift, when I tap Claim, then the shift shows my name and is no longer open",
                  "Given a shift I claimed, when another driver views it, then it shows as taken"]},
    {"id": "RR-13", "points": 2,
     "text": "As a driver, I want a reminder before my shift so that I do not forget it.",
     "criteria": ["Given a claimed shift, when it is 18 hours away, then I receive a reminder by text or email",
                  "Given a reminder, when I reply CANCEL, then the shift reopens and the coordinator is alerted"]},
    {"id": "RR-14", "points": 13,
     "text": "As a coordinator, I want the system to be easy and fast.",
     "criteria": ["The dashboard should be user-friendly"]},
    {"id": "RR-15", "points": 5,
     "text": "As the director, I want a monthly report of food rescued so that I can report to funders.",
     "criteria": ["Given pickups completed in a month, when I open Reports, then I see total kg by donor and by agency",
                  "Given the report, when I choose Download, then I get a CSV file"]},
]
VAGUE = r"\b(easy|fast|user-friendly|intuitive|simple|nice|quickly|robust)\b"
FORM = r"^As (an?|the) .+, I want .+ so that .+\.$"
GWT = r"^Given .+, when .+, then .+$"
for s in stories:
    issues = []
    if not re.match(FORM, s["text"]): issues.append("not in 'As a ..., I want ..., so that ...' form")
    if re.search(VAGUE, s["text"] + " ".join(s["criteria"]), re.I): issues.append("vague, untestable words")
    bad = [c for c in s["criteria"] if not re.match(GWT, c)]
    if bad: issues.append(f"{len(bad)} criterion not Given/When/Then")
    if s["points"] > 8: issues.append(f"{s['points']} points: split it")
    print(f"{s['id']}: {'OK' if not issues else '; '.join(issues)}")

RR-12: OK
RR-13: OK
RR-14: not in 'As a ..., I want ..., so that ...' form; vague, untestable words; 1 criterion not Given/When/Then; 13 points: split it
RR-15: OK

Story RR-14 failed every check, which is typical of the first draft of a story about something the client cares about deeply but has not yet thought through. Priya took it back to Grace and asked what 'easy and fast' meant in her day. The answer split into three stories: see all unfilled shifts for the next seven days on one screen, filter by donor, and send a message to all drivers who have worked a given shift before. Each of these was small, testable and valuable, and together they captured what Grace had meant far better than the original sentence.

Wireframes and prototypes

Wireframes are low-fidelity sketches of screens that show layout and content without visual design. They are the cheapest way to test whether the team and the client imagine the same product. Team Relay drew wireframes on paper first, then in a shared design tool, for the six screens that cover the core flows. They tested the paper versions with Grace and two drivers in a 30-minute session each, using the think-aloud method from CMPUT-421: the participant tries a task and talks while doing it, and the team watches without helping. Two problems appeared immediately. Drivers looked for the shift time in large type at the top, not in a list of details, and the regular driver did not recognize an icon-only 'swap' button.

Prototypes come in fidelities, and the right one depends on the question. A paper prototype answers 'is this the right content and flow?'. A clickable mock-up answers 'can people find their way?'. A thin coded prototype answers 'does this technology work for us?'. Do not polish a prototype beyond what the question needs. Team Relay built one throwaway coded prototype in week 4, a single page that sent a test text message through the messaging provider, because that integration was their riskiest technical assumption. It worked, and they threw the code away rather than building on it, because it had been written in two hours with no tests.

Accessibility from day one

Accessibility means that people with disabilities can use the product. For RescueRoute this is not hypothetical. The co-op's drivers include older adults, some with low vision or reduced dexterity, and at least one who relies on a screen reader. The coordinator may one day be someone who navigates by keyboard. The Web Content Accessibility Guidelines, WCAG 2.2, published in October 2023, are the standard reference; Level AA conformance is the usual target and the level most accessibility laws point to. CMPUT-421 and CMPUT-404 covered WCAG in detail. The capstone lesson is about timing: accessibility is cheap when built in from the first story and expensive when bolted on at the end.

Make accessibility part of the definition of done and of acceptance criteria. Team Relay added four checks to every user-interface story: it works with a keyboard alone, it has visible focus and correct labels for a screen reader, text and important graphics meet contrast ratios of 4.5 to 1 for normal text and 3 to 1 for large text and interface components, and status is never conveyed by color alone. The last check mattered for the dashboard, where the first design used red, yellow and green dots for shift status. Sofia changed it to colored badges with words, 'Unfilled', 'Unconfirmed' and 'Confirmed', which helped not only color-blind users but everyone glancing at a phone in sunlight.

WCAG 2.2 added several criteria that matter for mobile-first tools. Target size (minimum), success criterion 2.5.8, requires interactive targets of at least 24 by 24 CSS pixels unless they are spaced far enough apart. Focus not obscured requires that sticky headers or footers do not hide the element that has keyboard focus. Accessible authentication limits the use of puzzles and memory tests during sign-in, which ruled out an image-based CAPTCHA the team had considered. Dragging movements requires an alternative to drag-and-drop, which affected the coordinator's planned drag-to-reschedule feature. Checking a design against these early is simple arithmetic, as the program below shows.

# Checking a planned phone layout against WCAG 2.2 target size (2.5.8, Level AA):
# interactive targets at least 24 x 24 CSS pixels, or spaced so a 24 px circle
# drawn around each does not overlap another target. Team Relay's own goal is 44 px.
targets = [
    # (name, width, height, mid_x, mid_y) in CSS pixels on a 390 px wide screen
    ("Claim shift button", 358, 48, 195, 520),
    ("Swap link",           60, 20, 300, 580),
    ("Cancel link",         60, 20, 300, 602),
    ("Menu icon",           24, 24,  24,  30),
    ("Call coordinator",   170, 44, 100, 660),
    ("Map pin",             18, 18, 320, 300),
]
import math
def too_small(w, h): return w < 24 or h < 24
for name, w, h, cx, cy in targets:
    notes = []
    if too_small(w, h):
        # spacing exception: no other target midpoint within 24 px
        close = [n for n, w2, h2, x2, y2 in targets if n != name and math.dist((cx, cy), (x2, y2)) < 24]
        notes.append("below 24 px" + (f", too close to {close}" if close else ", but spaced (passes 2.5.8)"))
    if w < 44 or h < 44:
        notes.append("below team goal of 44 px")
    print(f"{name:20} {w:3}x{h:<3} " + ("; ".join(notes) if notes else "OK"))

Claim shift button   358x48  OK
Swap link             60x20  below 24 px, too close to ['Cancel link']; below team goal of 44 px
Cancel link           60x20  below 24 px, too close to ['Swap link']; below team goal of 44 px
Menu icon             24x24  below team goal of 44 px
Call coordinator     170x44  OK
Map pin               18x18  below 24 px, but spaced (passes 2.5.8); below team goal of 44 px

Automated checkers catch perhaps a third of accessibility problems; the rest need people. Plan at least one session in which someone uses the product with a screen reader and keyboard only, and if possible include a user with a disability in testing. Team Relay asked the driver who uses a screen reader to try the sign-up and claim flows in sprint 2, with Grace's help and his consent. He found that the 'Claim' buttons were all announced as 'Claim' with no shift information, so he could not tell which shift he was claiming. The fix, adding the shift's date and donor to each button's accessible name, took ten minutes; finding it without him would have taken much longer.

Non-functional requirements

Functional requirements say what the system does. Non-functional requirements say how well: performance, availability, security, privacy, maintainability, cost and so on. They are often forgotten in capstones and they often decide whether the client can keep using the product. Write them as measurable statements. Team Relay's included: pages load in under two seconds on a mid-range phone on a 4G connection; the system is available 99 percent of the time during the pilot; hosting costs stay under the co-op's limit; all personal data is encrypted in transit and at rest; and a volunteer with basic web experience can deploy a new version by following the README. Lesson 5 turns these into architecture decisions.

Worked examples