The Brief

What changes here. Everything up to now told you what to build and how. This module tells you what must be true when you are finished, and leaves the how to you.

That gap is the point. It is also what the work is actually like.

The application. A search interface over a public archive of your choosing. It must let someone search, see results, open a single result at its own address, and come back.

Pick an archive you find genuinely interesting. You are going to look at it for a long time, and the ones that get finished are the ones where the person cared what the data said.

✦ Choosing a source

It must allow requests directly from a browser and must not need a secret key. Open Library, the Metropolitan Museum collection, the Smithsonian, and various government open data portals all qualify. Check that a plain request works from your machine before you build anything on top of it.

The acceptance criteria. Every one of these is checkable by someone else, on your deployed URL, without reading your code.

1. Searching returns results, and the results are relevant to what was typed.

2. All four states are designed and reachable: loading, error, empty, results.

3. Typing does not fire a request per keystroke.

4. A single result opens at its own URL, and that URL survives a refresh.

5. An unknown URL shows a not-found page rather than a blank screen.

6. The entire application is usable from the keyboard alone.

7. Focus moves sensibly on navigation, and is always visible.

8. Result arrival and errors are announced to assistive technology.

9. It works at 320 pixels wide and at 1440.

10. The console is clean in the production build.

11. It is deployed at a public address and deep links survive a refresh.

12. The README explains what it does, what it uses, and how to run it.

How to work. Build the smallest thing that returns one real result on screen, then deploy that immediately, before it is good. Everything afterwards is an improvement to something that already exists and already works, which is a far better position than a perfect local application that has never been deployed.

When you are stuck, go back to the four states and ask which one you are in.