Keyboard-Only Walkthrough

---
name: Keyboard-Only Walkthrough
description: Structured protocol for testing a flow keyboard-only, with checkpoints for focus order, focus visible, skip links, escape, traps, and custom component operability.
when_to_use: A designer, dev, or QA person is about to test a product keyboard-only and wants a protocol, not vibes.
---

# Keyboard-Only Walkthrough

## What this skill does
Walks the user through a structured keyboard-only test of a flow, with scripted checkpoints and a notes template they fill in as they go. Produces a findings document at the end. Written for people who have never done this before.

## When to load this skill
Load when the user says: "test my app keyboard-only", "walk me through keyboard testing", "keyboard accessibility check", "can my users tab through this", or describes a flow and asks how to test it without a mouse.

## The procedure

### Step 1 — Set up the test environment
Before starting, give the user the setup: put the mouse away (literally — push it to the side of the desk), open the flow in a desktop browser (not mobile Safari, which has unusual tab behavior), and make sure the browser's "Tab navigates between form fields only" option is OFF on macOS Safari (System Settings → Keyboard → Keyboard navigation, or press Tab and Option-Tab to verify). Explain the six things we're testing: focus order, focus visible, skip links, Escape handlers, modal traps, and custom component keyboard operability. Ask the user to have a notes doc ready.

### Step 2 — Walk the primary flow start to end
Walk the user through their primary flow one Tab stop at a time. At each stop, they record three things: (1) what element has focus, (2) is there a visible focus indicator, (3) does the order make sense given the visual layout. Explain the keys: `Tab` forward, `Shift+Tab` backward, `Enter` or `Space` to activate, arrow keys for radio groups and custom components, `Escape` to dismiss. If the user loses track of focus, that's a finding — record it and move on by clicking (which resets) and continuing.

### Step 3 — Check focus visibility explicitly
After the primary flow, run a second pass dedicated only to focus visibility. Focus indicators fail in two common ways: (a) a global `outline: none` removed the default ring with nothing to replace it, (b) a custom ring exists but has insufficient contrast against the element's background or the page background. The check: for every interactive element, can you tell, at a glance, where focus is? Grade each stop pass/fail. Any element where you have to squint is a fail. Record it.

### Step 4 — Test skip links and landmarks
Press Tab once from a fresh page load. Is the first thing a skip link? It should read something like "Skip to main content" and take focus to the main landmark when activated. If there's no skip link and the page has more than a couple nav items, that's a finding — keyboard users have to tab through the entire header on every page. Also check: does the page have proper landmarks (`<header>`, `<nav>`, `<main>`, `<footer>`)? Screen-reader users rely on these to jump, but the skip link is the keyboard-only equivalent.

### Step 5 — Test modals, menus, and custom components
Open every modal, dropdown, combobox, date picker, and menu in the flow. For each, check:
- **Does focus move into the component when it opens?** If not, keyboard users don't know it appeared.
- **Does focus trap inside?** Tab inside a modal should not escape to the page behind it.
- **Does Escape close it?** Every dismissible component should close on Escape.
- **Does focus return to the trigger?** When closed, focus should go back to the button that opened it.
- **Can you operate it with arrow keys where expected?** Menus, listboxes, radio groups, combos — Tab moves between components, arrow keys move within.

Each failure is a finding, recorded with the component name and which check failed.

### Step 6 — Write the findings doc
At the end, help the user consolidate their notes into a findings document, grouped by severity:
- **Blockers** — anything that makes a flow impossible to complete (keyboard trap, unreachable button, no focus visible on submit, modal can't be closed).
- **Serious** — anything that makes a flow painful but possible (awkward focus order, missing skip link, inconsistent focus ring).
- **Polish** — inconsistencies, minor visual glitches, small order issues.

Hand off to [Form Accessibility Audit](/agents/skill-form-accessibility-audit) if form findings dominate, or [WCAG Quick Audit](/agents/skill-wcag-quick-audit) for a code-level review.

## A worked example

**User:** Walking through our meeting-booking app. Never done this before.

**Claude:** Setup first. Mouse to the side — actually to the side, not just "I won't use it". Browser: Chrome or Firefox on desktop. Open the app to the landing page. Notes doc open. Ready?

**User:** Ready.

**Claude:** Press Tab once. What has focus?

**User:** Nothing visible. I think it might be on the logo?

**Claude:** Finding #1, blocker — no visible focus on the first tab stop. That means a global `outline: none` somewhere in your CSS with no replacement. Press Tab again and tell me what's focused now.

**User:** Still can't tell. Maybe the "Sign in" button? I only know because I heard something click.

**Claude:** Finding #2, blocker — focus visibility is broken site-wide, not just on one element. This is top priority; no keyboard user can use the app until it's fixed. Continue the walk so we catalog the other issues, but know that fix #1 will be: add a visible focus ring to `*:focus-visible` in your global CSS.

Keep tabbing. Count out loud. Tell me when you land on something you can name.

**User:** One, two, three, four — okay, now the "Book a meeting" button has focus, I can see a dotted outline because it's a native button.

**Claude:** Good — native buttons preserve default focus, which is why that one shows. Press Enter.

**User:** A modal opened. "Pick a date."

**Claude:** Is focus inside the modal?

**User:** Yes, on the first day of the current month.

**Claude:** Good — that's proper focus movement on modal open. Now press Escape.

**User:** Nothing happened.

**Claude:** Finding #3, serious — modal does not close on Escape. Close it with the X button, keyboard-only. Tab until you reach the X.

**User:** Tabbing... I can't tell where I am. Eventually I think I hit something because the modal closed.

**Claude:** Finding #4, blocker — even when the Escape handler is missing, users need a reachable close button with visible focus. The modal currently has neither. Also, when the modal closed, where did focus return to?

**User:** I don't know. I pressed Tab and ended up at the top of the page.

**Claude:** Finding #5, serious — focus was not returned to the "Book a meeting" button that opened the modal. Keyboard users lose their place entirely.

Keep walking. Let's try the date picker. Click "Book a meeting" again, wait for the modal, then tell me — can you navigate days with arrow keys?

**User:** Arrow keys do nothing.

**Claude:** Finding #6, blocker — the date picker is custom and not keyboard-operable. That means keyboard users cannot book a meeting at all. This is the second blocker for the booking flow.

(walkthrough continues)

**Findings document (consolidated):**

**Blockers (4):**
1. No visible focus indicator site-wide. Fix: replace global `outline: none` with a `:focus-visible` rule.
2. Modal close button not reachable due to #1. Will partially resolve with #1, but verify after.
3. Date picker not keyboard-operable. Fix: implement arrow-key navigation per WAI-ARIA date picker pattern, or use a native `<input type="date">`.
4. Custom dropdowns in the duration picker also not operable (noted during walkthrough).

**Serious (3):**
5. Escape does not close modals. Add Escape handler.
6. Focus does not return to trigger when modal closes. Add focus restoration.
7. No skip link. Add "Skip to main content" as first tab stop.

**Polish (1):**
8. Tab order in the footer goes social links → legal links but visually reads legal → social. Flip the DOM order.

Want me to load the form accessibility audit for the booking form's fields once you've fixed the blockers?

**User:** Yes, after we fix the focus ring.

**Claude:** Good call. Start there.

## What this skill will NOT do
- Will NOT run the test for the user. The whole point is for the user to press keys themselves and feel the friction.
- Will NOT skip the setup step. Mouse goes away, or the test is theater.
- Will NOT guess what an element is called if the user can't tell. That's a finding, not a blocker to continue.
- Will NOT produce a pass/fail verdict on a product's accessibility. It produces findings. Sign-off needs a human auditor.
- Will NOT accept "it's probably fine" for any checkpoint. Every stop gets an explicit answer.