Vibe Coding: build real apps with AI · Episode 33. Every agent run below is real: Claude Code 2.1.322 (model claude-opus-5-5) in print mode (claude -p --permission-mode acceptEdits), on 12 November 2026, in /home/asha/projects/canteen. The agent could not open a browser (that needed approval), so every browser check was run by us: axe-core 4.14.0 inside Playwright's Chromium at 360 × 740, pressing Tab and Enter, and printing Chromium's accessibility tree.
What was written by hand: the canteen app (episodes 31-32) was written for these videos. Farhan, Mr Iyer, Neha and Asha are fictional. The dish pictures are simple placeholders we drew.
Sources: WCAG 2.2, a W3C Recommendation since 5 October 2023 (What's New in WCAG 2.2, w3.org/WAI); contrast levels from WebAIM's Contrast and Color Accessibility article. Contrast ratios below were computed with the WCAG relative-luminance formula.
The problem: the school ramp
The school has steps and a ramp. The ramp was built for a student in a wheelchair, but aunty's trolley, a boy with a leg in plaster and a parent with a pram all use it. And ramps have measurable rules (slope, width, rails).
| The school entrance | A web page |
|---|---|
| A ramp next to the steps, built for a wheelchair | Accessibility: everyone can use it |
| Aunty's trolley, a leg in plaster | Situations: sunlight, one hand, a broken screen |
| Ramp rules: slope, width, rails | WCAG: measurable rules for the web |
Accessibility (often written a11y: a, 11 letters, y) means people can use what you build whatever their eyes, ears, hands or device. UX (user experience) is how easy and pleasant it is to use.
The AI builds the order page (real)
$ claude -p "Build the students' order page in public/index.html: show the menu with prices, let a student type their name and class, choose how many of each item, and place the order. Plain HTML, CSS and JavaScript in that one file, no packages. Make it look nice on a phone."
Write public/index.html (309 lines)
Bash node smoke.mjs (a phone-sized Chrome) -> requires approval
Bash npm test # tests 11 pass 11
Reply: "I haven't seen it running in a browser yet."
"Phone layout: the page is one column, the buttons are big
enough to tap, and the text boxes don't make iPhones zoom in."
It looked lovely on a phone. The obvious check, "looks good on my phone", is a test with one pair of eyes, one finger and one phone.
Who uses it
- Farhan, 9A, is blind and uses a screen reader: a program that reads the screen aloud and lets you move with gestures or keys (TalkBack on Android, VoiceOver on iPhone, NVDA on Windows).
- Mr Iyer has weak eyes and reads in bright sunlight.
- Neha has her wrist in plaster: she orders from the library computer with the keyboard only.
A disability can be permanent (Farhan), temporary (Neha's wrist) or situational (sunlight on your screen). WCAG (Web Content Accessibility Guidelines) 2.2 turns this into testable rules at levels A, AA and AAA; AA is the usual goal.
Test 1: an automated checker (real)
axe-core is a free, open-source library that checks a page against many WCAG rules.
$ node check.js http://localhost:4000 # axe-core 4.14, 360x740
AXE violations: 2
- color-contrast (serious): Elements must meet minimum color
contrast ratio thresholds · 2 element(s)
.out > .info > .name | insufficient color contrast of 2.52
(foreground color: #a8a29e, background color: #ffffff)
.out > .info > .price | insufficient color contrast of 2.52
- region (moderate): All page content should be contained by
landmarks · .totals
Contrast ratio in plain words
How different the text colour is from its background, from 1:1 (white on white) to 21:1 (black on white).
| Text | WCAG AA minimum |
|---|---|
| Normal text | 4.5 : 1 |
| Large text (about 24 px, or about 18.7 px bold) | 3 : 1 |
| Buttons' borders, icons (non-text) | 3 : 1 against neighbours |
The sold-out item's name and price were 2.52 : 1. The AI wanted "sold out" to look faded, but it faded words people still need to read.
Test 2: keyboard only (real)
Keyboard navigation: Tab moves to the next control, Shift+Tab goes back, Enter or Space presses a button. The control receiving key presses has the focus; the ring drawn around it is the focus indicator.
1. INPUT "student" 298x44
2. INPUT "klass" 298x44
3. BUTTON "One more Samosa" 40x40
4. BUTTON "One more Vada pav" 40x40
5. BUTTON "One more Masala chai" 40x40
6. BUTTON "One more Idli (2)" 40x40 <-- under the bottom bar
7. BUTTON "One more Banana" 40x40
{"el":[692,732],"bar":[665,740],"fullyHidden":true}
After six Tabs the focused button sits completely behind the fixed bottom bar; the screen looks as if nothing happened. WCAG 2.2 added 2.4.11 Focus Not Obscured (Minimum) (level AA): "When a user interface component receives keyboard focus, the component is not entirely hidden due to author-created content."
Test 3: what a screen reader hears (real)
A screen reader reads the accessibility tree: the browser's list of every heading, button, box and text, with its role (button, textbox) and name ("One more Samosa").
# focus on "One more Samosa", press Enter 5 times
Enter 1: focus = One more Samosa · live text = "1 | 0 | 0 | 0 | 0 | 0"
Enter 4: focus = One more Samosa · live text = "4 | 0 | 0 | 0 | 0 | 0"
Enter 5: focus = (body: focus lost)
- listitem:
- text: Samosa ₹15.00
- button "One less Samosa" [disabled]: −
- text: "0"
- button "One more Samosa": +
- The quantity is read as a bare "0"; a live region (
aria-live, a part a screen reader reads aloud whenever it changes) said just "1". - At the 5-item limit the + button became
disabled, and a disabled button can't keep focus: focus fell back to the page, throwing Neha and Farhan back to the top.
Why did it fail?
It was built and checked one way (eyes, finger, mouse), and the AI never opened it. Fix: test the ways other people use it, and give the AI the evidence.
The fix prompt (real)
claude -p "I tested public/index.html the way other students will use it,
on a 360px-wide phone:
1. axe-core 4.14 says the sold-out item name and price fail colour
contrast: 2.52:1 (#a8a29e on white).
2. Keyboard only: after Tab reaches 'One more Idli (2)', the focused
button is completely hidden under the fixed bottom bar.
3. With a screen reader, the quantity is read as just '0', and when
you press + it only says '1'. One what?
Fix these so blind students, students using a keyboard and students
with weak eyesight can all order. Also add the dish pictures from
public/img/<id>.jpg next to each item."
Its answer (extracts): "Sold-out contrast ... the same muted brown as other secondary text. That's 6.4:1 on white", "keeps that much space clear at the bottom", "a disabled button drops keyboard focus ... Now the buttons only look unavailable and stay focusable", "The images have empty alt text on purpose, because the dish name is right next to them", and "I couldn't test it in a browser ... Please repeat your three tests."
The key changes:
html { scroll-padding-bottom: calc(var(--bar-h, 96px) + 16px); }
.item.out .name, .item.out .price { color: var(--muted); } /* #6b5f57 */
<div id="announce" class="sr-only" role="status" aria-live="polite"></div>
<div class="stepper" role="group" aria-label="Samosa quantity">
<button aria-label="One less Samosa" aria-disabled="true">−</button>
<span class="qty"><span class="sr-only">Samosa: </span>0
<span class="sr-only"> in your order</span></span>
<img class="pic" src="img/1.jpg" alt="" width="48" height="48">
scroll-padding-bottom: when the browser scrolls something into view, keep this much space free at the bottom (the bar's height), so focus stops above the bar.- ARIA (Accessible Rich Internet Applications): HTML attributes that give screen readers extra information.
aria-live="polite"= read changes when the user is idle. .sr-only("screen reader only"): text hidden visually but still read aloud.aria-disabled="true": looks and is announced as unavailable, but stays focusable (unlikedisabled).
Re-test (real)
AXE violations: 1
- region (moderate): ... .totals
Tab 1-14: every + and − button; "fullyHidden": false for all of them
Enter 1: live text = "Samosa: 1 in your order. 1 item, ₹15.00."
Enter 5: live text = "Samosa: 5 in your order. 5 items, ₹75.00.
That's the max of 5." focus = One more Samosa
AI mistake 1: a made-up number. It said the new colour is 6.4:1. We measured #6b5f57 on white: 6.18 : 1. It passes, but the number was invented. When an AI quotes a number, measure it.
Trade-off to know: because the − buttons now stay focusable, crossing the menu takes 14 Tab presses instead of 5.
AI mistake 2: the error nobody could see (real)
A test no checker runs: make a mistake on purpose. Choose a samosa, leave the name empty, press Place order. The name box got focus, but "Please type your name." was printed under the menu, off the screen. axe-core reported nothing: automated checkers catch only some problems.
claude -p "One more problem on public/index.html, found on a 360x740 phone
screen: I chose a samosa, left the name empty and pressed Place order.
The name box gets focus, but the message 'Please type your name.'
appears under the menu, off the screen ... Show each form error next
to its own box, and make screen readers read it with the box."
Our check after the fix:
message under the box · focus: student · aria-invalid: true
aria-describedby: student-err
- textbox "Your name" [invalid]
- paragraph: Please type your name.
aria-invalid="true"marks a box as wrong.aria-describedby="student-err"links the box to its error text, so a screen reader reads them together ("Your name, edit, invalid entry, Please type your name").- The message also has a red border and text: never colour alone.
- The AI also scrolled server errors into view, which we hadn't asked for.
Labels, real buttons, alt text (our small example, real tree)
<input placeholder="Your name"> -> textbox "Your name"
<label for="n">Your name</label>
<input id="n" placeholder="e.g. Riya Sharma"> -> textbox "Your name"
<div onclick="go()">Place order</div> -> text: Place order
<button>Place order</button> -> button "Place order"
<img src="1.jpg"> -> img
<img src="1.jpg" alt="Samosa"> -> img "Samosa"
<img src="1.jpg" alt=""> -> (skipped: decorative)
- Form label: the visible name of a box, joined with
forandid. A placeholder is the grey hint inside; Chromium uses it as a name if there's no label, but it vanishes when you type and is faint. Always use a real label; keep placeholders for examples. - A
divwith a click handler is just text: no button role, Tab skips it. A real<button>works with Enter and Space for free. - Alt text replaces a picture for screen readers. Informative picture → describe it. Decorative picture (the name is right next to it) →
alt=""so it's skipped. Noaltat all → many screen readers read the file name.
Error messages people understand
| Bad | Better |
|---|---|
| "Error 400" | "Please type your name." |
| "Send student and items." (the API's message, for programmers) | "Choose at least one item." |
| "Invalid input" in red only | Red border + text under the box |
| "Something went wrong." | "Couldn't reach the canteen. Check your connection and try again." |
| "409" | "Poha is sold out." + the new menu |
Good = what happened + what to do, in plain words, next to the problem.
Mobile-first checks
Mobile-first: design for the small phone screen first, then let it grow.
<meta name="viewport" content="width=device-width, initial-scale=1">
body { font: 16px/1.4 system-ui, sans-serif; }
.stepper button { width: 40px; height: 40px; }
- The viewport tag makes phones use their real width; don't block pinch-zoom.
- 16 px body text is a good minimum; iPhones also auto-zoom into form boxes with smaller text.
- Touch target: the area you can tap. WCAG 2.2 2.5.8 Target Size (Minimum) (AA): "at least 24 by 24 CSS pixels" (with exceptions). Ours: 40 × 40.
- CSS pixel: the unit web pages use; a phone may use several real screen dots for each.
- Our 200% zoom test (a 360 px phone at 200% = 180 CSS px wide): no sideways scrolling, but the sticky bar took 110 of 370 px (about 30%) of the screen: worth redesigning.
180 {"scrollW":180,"clientW":180,"barH":110,"vh":370}
Checklist before you ship
- [ ] Run an automated checker (axe-core, or Lighthouse in Chrome DevTools).
- [ ] Text contrast 4.5:1 (large text 3:1).
- [ ] Do everything with Tab, Enter and Space; focus always visible.
- [ ] Read the accessibility tree (DevTools) or switch on TalkBack / VoiceOver and try it.
- [ ] Real labels, real buttons, alt text (or
alt=""for decoration). - [ ] Make mistakes on purpose: is every error visible, next to its box, and clear?
- [ ] 360 px phone, 200% zoom, 16 px text, targets at least 24 × 24.
Common mistakes (real)
| Mistake | What we saw | Why | Fix |
|---|---|---|---|
| Faded sold-out text | contrast of 2.52 (#a8a29e on #ffffff) |
Needs 4.5:1 | Darker text + a "Sold out" tag |
| Sticky bottom bar | "fullyHidden": true |
Focus not obscured | scroll-padding-bottom |
| Bare numbers read out | live text = "1 \| 0 \| 0 \| 0 \| 0 \| 0" |
No context | "Samosa: 1 in your order" |
disabled at the limit |
focus = (body: focus lost) |
Disabled drops focus | aria-disabled |
| Error off screen (the AI's) | message under the menu | Not next to the box | Text under the box + aria-describedby |
Mini project: fix the landmark note
axe still reports region (moderate): the bottom bar isn't inside a landmark. Landmarks (<header>, <nav>, <main>, <footer>) are labelled regions screen-reader users can jump between.
- Wrap the bottom bar in
<footer>(a top-level footer is the "contentinfo" landmark). - Re-run axe: 0 violations?
- Re-run the Tab test: is anything hidden?
- Commit.
Practice questions
- Grey
#999999text on white: does it pass for normal text?
Answer
No. Its contrast ratio is about 2.85:1; normal text needs 4.5:1. (Check with a contrast checker or the formula.)
- Why is
disableda problem on a button that has keyboard focus?
Answer
A disabled button can't keep focus, so focus falls back to the page and keyboard and screen-reader users lose their place. aria-disabled="true" keeps it focusable while announcing it as unavailable.
- A banner photo shows "Diwali sale: 20% off". What alt text?
Answer
The information in it: alt="Diwali sale: 20% off". It's informative, not decorative.
- axe-core says 0 violations. Is the page accessible?
Answer
Not necessarily. Checkers miss many problems (our off-screen error). Also test with the keyboard, a screen reader, zoom, and deliberate mistakes.
- Why is a placeholder not a good replacement for a label?
Answer
It disappears as soon as you type, so you can't check what the box was for, and it's usually faint grey text.
Quiz
A dish photo sits right next to its name. What alt text?
A) alt="image" · B) alt="" (empty) · C) alt="1.jpg" · D) No alt attribute at all
Answer
B: the name is already next to it, so the picture is decorative and should be skipped. With no alt at all, many screen readers read the file name.
Interview questions
- What is WCAG and which level do most teams aim for? The W3C's Web Content Accessibility Guidelines; level AA.
- How do you test accessibility? Automated checker, keyboard-only use, a screen reader, zoom/reflow, contrast checks, and real users.
- What's the difference between
aria-label,aria-describedbyand a<label>?<label>gives a visible name;aria-labelgives a name only screen readers hear;aria-describedbyadds extra description (like an error) read after the name. - What is a live region? An element with
aria-livewhose changes screen readers announce. - What's the first rule of ARIA? Use a native HTML element (like
<button>) when one exists, instead of adding ARIA to adiv.
Glossary
| Term | Meaning (with an example from this episode) |
|---|---|
| Accessibility (a11y) | Everyone can use what you build, whatever their body or device. |
| UX (user experience) | How easy and pleasant something is to use. |
| Disability (permanent / temporary / situational) | Blindness / a wrist in plaster / sunlight on the screen. |
| WCAG | Web Content Accessibility Guidelines, the W3C's testable rules (2.2, Oct 2023). |
| Level AA | The usual WCAG target (A is minimum, AAA strictest). |
| Contrast ratio | How different text and background colours are: 1:1 to 21:1 (we had 2.52). |
| Large text | About 24 px, or about 18.7 px bold; needs 3:1. |
| Automated checker / axe-core | A tool that scans a page for rule breaks (color-contrast). |
| Keyboard navigation | Using a page with Tab, Shift+Tab, Enter and Space only. |
| Focus / focus indicator | The control receiving key presses / the ring showing it. |
| Focus not obscured | WCAG 2.4.11: the focused control must not be entirely hidden. |
| Screen reader | Software that reads the screen aloud (TalkBack, VoiceOver, NVDA). |
| Accessibility tree | The browser's list of roles and names that screen readers read. |
| Role / accessible name | What a thing is (button) / what it's called ("One more Samosa"). |
| ARIA | HTML attributes that give screen readers extra information. |
Live region (aria-live) |
An area read aloud when it changes. |
aria-disabled |
Announced as unavailable but stays focusable. |
aria-invalid / aria-describedby |
Marks a box as wrong / links it to its error text. |
.sr-only |
Text hidden on screen but read by screen readers. |
| Alt text | Words that replace a picture for screen readers. |
| Decorative image | Adds nothing the text doesn't say: alt="". |
| Form label / placeholder | The box's visible name / a grey hint inside it. |
| Landmark | A labelled page region (main, nav, footer) users can jump to. |
| Mobile-first | Design for the small screen first. |
| Viewport | The visible area of the page; set by the viewport meta tag. |
| CSS pixel | The unit web pages use for sizes. |
| Touch target | The area you can tap; at least 24 × 24 CSS px (WCAG 2.5.8). |
| Reflow / zoom | Content fits without sideways scrolling when zoomed. |
scroll-padding-bottom |
Space the browser keeps free when scrolling something into view. |
Summary
- "Looks good on my phone" is not a test. Three real tests failed a lovely page: contrast 2.52:1, focus hidden under a sticky bar, a screen reader hearing bare numbers (and losing focus at the limit).
- With the evidence, the AI fixed all three; our re-test confirmed it, except a made-up contrast figure (6.4 said, 6.18 measured).
- A deliberate mistake showed an error message off screen that no checker found; fixed with text under each box and
aria-describedby. - Use real labels, real buttons and the right alt text; write errors that say what happened and what to do.
- Mobile-first: 360 px, 200% zoom, 16 px text, 24 px+ targets.
Next episode: Data privacy basics for your app.