A field guide does not explain the whole of nature. It helps you recognise what is in front of you, tells you how to tell it apart from things that look similar, and sends you back outside to look again. This publication tries to do the same for the parts of frontend engineering that only show up when real people use real software.
Most writing about building interfaces covers the expected path: the form that is filled in correctly, the name that fits in its box, the sentence in the author’s own language. The interesting failures are elsewhere. A phone number turns around inside an Arabic sentence. A character counter disagrees with the person typing. A meeting is scheduled for a time that does not exist. These problems are well documented in specifications and poorly documented almost everywhere else, so they are rediscovered one bug report at a time.
Unhappy Paths is a free, independent, static website. Each issue takes one territory and works through it in four stages:
- Reproduce. An experiment that runs in your browser, so you see the behaviour rather than read about it.
- Understand. What is happening and why, in plain language, traced to the specification that defines it.
- Fix. Code you could ship, with its trade-offs stated.
- Test. Fixtures, checklists and tests you can take back to your own work.
Principles
Correctness before cleverness
Every technical claim should be traceable to a primary source: a specification, a standard, or reference documentation such as MDN. Issues link to those sources inline and list them at the end. Where the sources are silent or inconsistent, the text says so.
Real behaviour, not simulations
Experiments use the browser’s own engines: its text segmentation, its bidirectional layout, its form controls. They do not reimplement them in JavaScript to produce a convincing picture. When an experiment explains something, for example by labelling characters with their Unicode properties, that explanation is shown next to the browser’s actual result and never replaces it.
Honest about limits
Browsers differ, specifications change, and a demonstration in one browser is not a guarantee about all of them. Issues say which browser their notes were checked against and which cases they leave out. No compatibility claims are made beyond what the cited sources support.
Explain the browser, do not blame it
Many “bugs” in this territory are specified behaviour meeting incomplete information. The guide distinguishes between what the platform does by design, what is a genuine gap (and is tracked as one), and what is a mistake in our own code.
No manufactured problems
Mixed Arabic and English text is not broken. Emoji are not a problem to be stamped out. The guide shows edge cases where they actually occur, and says so when the default behaviour is fine.
Privacy
This site has no backend, no accounts, no analytics, no advertising and no cookies. Fonts are served from the site itself, so loading a page does not contact a third party. The experiments run entirely in your browser: text you type or paste is processed locally, is not sent anywhere, is not logged and is not saved.
Corrections
If you find an error, a claim that is not supported by its source, or behaviour in your browser that contradicts what an issue says, it is a bug in the guide. Corrections are made in the open, and an issue’s date of last update reflects them.
Colophon
Built with Astro as plain static HTML, with small, separate scripts for each experiment. Text is set in Figtree, Arabic in IBM Plex Sans Arabic and code in JetBrains Mono, all served from this site. The mark is a dotted circle, the symbol Unicode charts use for a missing base character: an accent with nothing to sit on.