How MySous was made: a Case Study
View the code on GitHub (opens in a new tab)In 60 seconds
The problem. A home cook at 6pm stands at the open fridge with half a bunch of cilantro, some chicken thighs and a lime. They can follow a recipe, but they don't trust themselves to improvise. Recipe sites match keywords; chat assistants answer with confident text no one can check. Neither explains what goes with what, and why.
The hero interaction. The Cook puts up to six Ingredients in a basket. MySous suggests the dishes they fit, those the basket covers at least half of, fills each part it can, and says in one line why each part holds what it does, or why it's still open. Any part can be changed, and every change can be undone.
The product and design decisions.
- A hand-curated graph of Ingredient Pairings, each with a plain-language reason and a cited source, and no LLM: every claim can be checked.
- One way in and one concept to learn, the basket. I built a Pantry, used it, and cut it.
- Regional Cuisines, never "authentic", with a voice guide the build enforces.
- Accessible by construction: WCAG 2.2 AA in both themes, checked on every change.
The engineering decisions.
- A static site with no server, no database and no accounts. The basket lives in the address, so any basket can be linked to, including from this page.
- One deep module, the Kitchen, answers every question the screens ask, and refuses content that breaks a rule.
- Tests written first, at seams agreed before the code, and run against the exact site that ships.
- Built with Claude Code through a fixed loop of skills: I make the calls, Claude writes the code, and nothing ships until I say so.
MySous launches with 62 Ingredients, 309 Pairings, 10 dishes, each with a Recipe, and 8 regional Cuisines.
The code is public on GitHub, at magicianmike/my-sous (opens in a new tab), with every decision record, the decision journal (opens in a new tab) and every ticket.
One basket
The spec began with two doors: "Start from an ingredient" and "Start from what you have", where what you have was a Pantry kept on the device. I built the Pantry in full, with its tests, and used the preview. Then I cut it.


One concept, help before chores. The basket and the Pantry were both "ingredients I care about", told apart only by intent. Every screen had to explain both, and "Ready" meant two things depending on whether the Pantry was empty. The Pantry also asked for work before it paid anything back: entering what you own, then keeping it current. A stale Pantry makes "Ready" wrong, which is worse than not claiming to know. Without it there's one thing to learn. The Cook at the open fridge puts what's in front of them in the basket.

Live from MySous Ready now means one thing: the basket fills every part the dish needs. Open this basket in MySous.
Any state is a link. Back and Forward step through basket changes, a shared link reopens the same basket, and this page can open the app in exactly the state it describes. How that works is in The module.

Also needs an acid (lemon pairs best). Chicken thigh and ginger pair well, but basil doesn't pair with the rest.
Sear something, then turn the browned bits left in the pan into a quick, glossy sauce.
Live from MySous A basket where not everything pairs: basil has no Pairing with chicken thigh or ginger, and the card says so. Open this basket in MySous.
Opening this basket in MySous shows the dishes it fits, each saying what pairs and what doesn't.
The basket stays at hand. At every width it's a bar at the foot of the screen that opens as a sheet, so the page keeps its full width. On a phone the bar has a row of its own, so it never covers the control you're on. Ingredients go in from where the Cook is: an Ingredient's page, any Pairing, the Ingredients list, or what pairs with the basket.
If a "you can cook this tonight" answer is missed later, the lightest step back is an "I have this" mark on basket Ingredients that lasts the visit, not a stored inventory (ADR 0004 (opens in a new tab)).
Defaults that explain themselves
A dish arrives filled in, and says why. A dish is never a blank form. MySous fills each part from the basket first, then with the Ingredient that pairs best with the rest, then from the dish's Recipe, then from Pairings again, since the Recipe's Ingredients can give other parts a Pairing. Every fill carries one line saying why it's there. A part no Pairing can justify stays open and says so, rather than being filled with something that merely fits. The Cook changes what they'd rather change, sees the method follow, and can undo it.

Also needs an acid (lemon pairs best). Chicken thigh and garlic pair well. Both are common in Punjabi, Japanese, Levantine and Oaxacan cooking.
Sear something, then turn the browned bits left in the pan into a quick, glossy sauce.
Live from MySous Two Ingredients in the basket; MySous suggests lemon for the acid, and says why. Open this basket in MySous.
- Words before colour. A Suggestion leads with "Ready" or "Needs 1 more", and a line says what it needs and what would fill it: "Also needs an acid (lemon pairs best)." The badge's colour echoes the words but never stands in for them.
- A reason, never a score. Each Suggestion says why it ranked where it did in a sentence, naming each Pairing once: "Ginger pairs with chicken thigh, garlic and soy sauce, and garlic with chicken thigh and basil." A number explains nothing about why.
- On screen, the Cook's words. The glossary's Combination, Formula and Slot read "basket", "dish" and "part" on screen. I chose "basket" from fifteen candidates. Code and content keep the domain terms.
- Change anything, undo the last change. Each part has Options: a checklist of what could go there, ranked against the rest of the dish. Only the latest change offers Undo, so it sits beside what changed, and focus moves to it.
- Never a dead end. MySous suggests only the dishes a basket fits. When none fits yet, it names the closest and what to add to each, and the basket offers what pairs with it, one tap to add. Search says when an Ingredient isn't in MySous yet, and how to find another.
Honest about culture
Regional, hedged and sourced. A Cuisine is named at the level people cook in: Sichuan, Oaxacan, Levantine, Punjabi, never "Asian" or "Mediterranean". Copy says "common in", never "authentic", hedges what varies by household ("many cooks", "usually"), and states food safety plainly. Where agencies differ, the stricter figure comes first: pork is 160°F / 71°C, with the FDA's 145°F / 63°C and a rest given too.

Also needs an aromatic (garlic pairs best). Everything here pairs with lamb. All are common in Levantine cooking.
Sear something, then turn the browned bits left in the pan into a quick, glossy sauce.
Live from MySous The rank reason names the Cuisines a Pairing is common in, at regional level. Open this basket in MySous.
The same rule shaped the Cuisines page. I first wanted a flag for each Cuisine. But Levantine spans four countries, one of them contested, and Punjab two, while Sichuan and Cantonese would both show China's flag. Each Cuisine shows the drawings of the Ingredients it leans on instead.
Sourced, by rule. Every Pairing cites at least one source with a link, gathered by reading cooks and writers from each tradition, culinary institutions and official bodies: Japan's agriculture ministry, the Larousse dictionary of Mexican gastronomy, Regione Campania. Nothing comes from pairing books, which ADR 0001 (opens in a new tab) rules out on copyright grounds, or from flavour-compound data, whose central claim held for Western cuisines and reversed in East Asian ones. Each Launch Cuisine has to offer three Ingredients for every part a dish can ask for, or record, with a source, that it seldom uses that kind of Ingredient. Six such exceptions remain, such as soft herbs in Sichuan cooking.
Writing to that standard changed the content. Claims no source supported were cut, two Pairing Reasons that said more than any source were rewritten, and gremolata lost its only Pairing until I could source new ones. The module covers how the build holds the content to these rules.
Look and feel
I settled the look by rendering the real Ingredient page in three prototype rounds, in light and dark at phone and desktop widths, and choosing from what I saw rather than from descriptions. Every variant also ran an in-page WCAG contrast audit, so none could win on looks alone.

The result is single-line drawings on a shared 48-unit grid, each Ingredient in its own colour pair for light and dark, a neutral interface so colour always identifies an Ingredient and never a state, Fraunces at its softest for headings ("the serif lends credibility and gives it an editorial authority") and rounded Nunito for everything else. Controls stay quiet so the Ingredients carry the colour: Add is the one solid button, and the rest are outlined. Motion happens only on first paint or on the thing that changed, and none of it under reduced motion. The rejected variants are in What I rejected.
Accessible by construction. Every component is built to WCAG 2.2 AA in light and dark. Nothing is said by colour alone, every change the Cook makes is announced, and focus moves where it should after every action that moves it. Touch targets are 44px on a phone, and nothing scrolls sideways from 320px wide, or at 200% zoom. I check each screen by hand with VoiceOver on an iPhone and a Mac, this Case Study included. Testing approach covers the checks that run on every change.
The tech stack
A static site, on purpose. MySous is a Next.js 16 app exported as static files (output: "export") and served by Vercel. There's no server, database, account or analytics. The product doesn't need one: the content is curated and changes with a commit, and the Cook's only state is the basket, which lives in the address. With nothing running, there's nothing to keep up, nothing to pay for per visit, and nothing to leak. Vercel builds a preview of every pull request.
- React 19 and TypeScript, in strict mode. The domain's words are its types:
Ingredient,Pairing,Formula,Slot,Suggestion. - Content as files. Ingredients and Recipes are Markdown with front matter, each Ingredient has an SVG drawing, and Pairings, Cuisines and Formulas are YAML, all in the repo. A Pairing's reasons and sources are reviewed in a pull request like code. Zod schemas parse every Markdown and YAML file, so a malformed one fails the build with its file and what's wrong, not a blank page.
- MDX for this page, so a live dish card can sit in the middle of a paragraph (ADR 0002 (opens in a new tab)).
- Images made before the build. Each Ingredient's and dish's image is made once, while writing content, and committed. Before every build, sharp turns each into AVIF and WebP files at several widths. Nothing is generated while the app runs (ADR 0005 (opens in a new tab)).
- Design tokens in code. Colours, type, spacing and motion live in one TypeScript file that writes the CSS custom properties for both themes. Stylesheets may use only tokens, and a test fails on any raw colour, or any length in px or rem.
- Few dependencies in the browser. Floating UI places tooltips. The rest is the platform: a native dialog for the basket sheet, radio inputs for segmented controls, and the address for state.
No runtime model. A model would have made Suggestions read more fluently, and every sentence would have been a claim no one checked. The rank reasons and fill reasons are built from the curated graph, so each is as true as its source (ADR 0003 (opens in a new tab)).
Testing approach
Tests first, at seams agreed first. Before a feature's first test, I agree where the tests go: the public seams where behaviour shows, such as loadKitchen or a journey in the browser. Each test is written and seen failing before the code that passes it. When a test comes after its code, or never fails because the behaviour was already there, the journal says so.
The Kitchen, through its front door. The Kitchen is the module that holds every rule, described in The module. Every Kitchen test goes through loadKitchen with a small fixture content folder written for that rule, so the internals can change without breaking tests. The same suite loads the real content. A Pairing without a source fails the build, and a launch Cuisine short of a part fails the tests.
Components, one at a time. Every component has stories in Storybook: each of its states, with real Ingredients' names, colours and drawings, and real images, read from the content. Each story is also a test. Vitest runs it in Chromium, plays what a Cook would do, such as arrowing through the combobox's matches or removing an Ingredient from the basket, and fails it on any axe violation. These tests cover what a component does on its own; journeys across pages stay with the browser tests. The stories are published with the site, at /storybook (opens in a new tab).
The site that ships. Browser tests run against the exact static export, never the dev server, at a phone's size and a desktop's. They cover each journey by mouse and keyboard, and run axe on every screen in both themes.
Rules as tests. Some rules are cheaper to enforce than to remember:
- every text colour pairing is checked for contrast in both themes, and so is every Ingredient's drawing against its own wash;
- stylesheets use only tokens;
- no copy says "authentic", in content or in code;
- nothing scrolls sideways from 320px wide, or at 200% zoom, and every control on a phone is a full touch target.
Two examples of the checks changing the design: axe caught the basket bar's name running its words together as "Your Combination0 of 4", and, as the content grew, a tile sitting under the docked bar on a phone, which is why the bar now has a row of its own.
Every change, in CI. GitHub Actions runs the type check, the unit tests, the build, which loads the real content, the component tests and the browser tests on every pull request. I merge only when it's green. One browser test failed twice there and nowhere else. On a phone, with reduced motion, it saw none of the Pairing rows begin their entrance, which under reduced motion takes no time. It passed on my Mac, in Linux in Docker with the same browser, and with the CPU slowed twelve times. So rather than retry until green, I changed what the test watches. It now checks what it means: no row is swapped as the page goes live. Forcing the rows to be swapped made it fail with all 37 rows reported, so the check still bites.
The module
The pages never touch files, YAML or schemas. They ask one deep module, the Kitchen, questions: an Ingredient's Pairings, grouped by reason; a Cuisine's Ingredients, the ones it leans on first; the dishes a basket fits; what could be added to it; a dish's Recipe. The site is static, and the Cook can build any basket. So the Kitchen that renders pages at build time is rebuilt in the browser, from the same validated content.
The content, sent once. At first the layout handed the content to the browser's Kitchen as a prop, which wrote all of it into every page's HTML. Now the build validates it and writes it to one JSON file, bundled into the app's script, so a visitor downloads it once and the browser caches it. It's about 280 KB, 63 KB gzipped, and every page loads all of it. If it grows much larger, or some pages turn out not to need the Kitchen, the next step is to load it lazily, or send each page only what it uses.
One module answers every question. The rules (what fills a part, why, what's still needed, which dishes a basket fits, how they rank) live in the Kitchen, never in the screens. Dishes rank by how many parts they still need, then by how well the Ingredients the Cook chose pair. A shared Cuisine breaks ties, but never outweighs a real Pairing. Once, a review found a screen working out for itself what to add to a dish. That logic moved into the Kitchen, and two bugs went with it.
Content that can't half-load. loadKitchen returns a Kitchen or a list of errors, never a half-loaded Kitchen. It collects every problem before failing, so an author fixes a batch of content in one pass. It checks that:
- every reference resolves, with no duplicates and no Ingredient paired with itself;
- every part of every dish can be filled;
- each Recipe fills its dish and gives every part an amount;
- every Ingredient that could fill a safety-sensitive step carries cited guidance for it;
- images carry alt text, provenance and a review;
- every Pairing has a linked source, every Cuisine is named regionally, and no copy uses the voice guide's banned words: "easy", "easily", "simply", "just" and "authentic".
const result = await loadKitchen("content");
if (!result.ok) throw new Error(result.errors.map(({ file, message }) => `${file}: ${message}`).join("\n"));
The address is the source of truth. The basket lives in the address, as ?with=chicken-thigh,basil,ginger, and nowhere else. There's no client-side store. Every link between screens carries it, and a Cuisine filter sits beside it (&cuisine=levantine) for the same reasons. The one thing MySous keeps in the browser is the theme you choose, a display preference rather than app state. Live embeds like the cards on this page read a fixed basket instead, through a small provider, so the same component renders from a given basket or from the address.
Building with Claude
I built MySous with Claude Code. I make the product, design and content decisions; Claude writes the code and its tests, through a fixed loop of skills. The product itself has no model in it (ADR 0003 (opens in a new tab)).
The loop. Every change goes the same way:
- Spec and ticket. A change starts as a GitHub issue under the product spec, written in the glossary's words. A domain-modeling skill keeps the glossary (opens in a new tab) and the ADRs (opens in a new tab) current as terms and decisions settle.
- Decisions, as options. Where a choice is mine, Claude asks with two to four options and a recommendation, and I pick. The journal records which choices were mine and which were defaults.
- Seams, then tests. We agree where the tests go before any are written. Then each test is written, seen failing, and passed.
- Two reviews, apart. Two agents review the change in parallel: one against the repo's written standards and a list of code smells, one against the spec. They report separately, so code that's tidy but wrong, or right but messy, can't hide behind the other.
- A journal entry, with before and after screenshots, what was decided, what the reviews found and what was kept. The journal (opens in a new tab) and the tickets (opens in a new tab) are public.
- Ship on my word. Nothing is pushed, opened as a pull request or merged until I say so.
What the reviews caught. A screen working out what to add to a dish, which belonged in the Kitchen; moving it fixed a "Pairs with" that named an Ingredient the basket didn't have. A search with no match that offered no next step. A sentence that carried two ideas, against the voice guide. A word, "fits", used in two senses.
Pushing back. The loop works because Claude raises conflicts rather than resolving them quietly. When I asked for country flags on the Cuisines page, it pointed out that flags undo the regional naming, and offered the drawings that shipped. When a test failed only in CI, it re-ran it in Docker before asking whether to change the test.
Research with sources. Pairing and cultural research ran as background research agents, reading primary sources: cooks and writers from each tradition, culinary institutions, official food-safety bodies. They cited only pages they had fetched. Their notes are kept in the repo, and I check what goes into the content.
What stays mine. Choosing between options, approving the copy, running each VoiceOver pass on an iPhone and a Mac, cooking each Recipe, and reviewing each generated image before the build will accept it.
What I rejected, and what’s next
Visual directions. Each round's other variants, with why they lost:






Product and engineering.
- A compound-based pairing dataset. Large and free, but its central claim is contested and doesn't hold across cuisines (ADR 0001 (opens in a new tab)).
- An LLM in the MVP. No blank chat box, no API keys or cost, and no generated culinary claim that can be wrong (ADR 0003 (opens in a new tab)).
- A Pantry. Built and cut, as above (ADR 0004 (opens in a new tab)).
- A "Not everything pairs" box with fix buttons. Built, then cut: each Suggestion's rank reason already says what doesn't pair, and the Cook doesn't need a separate task to resolve it.
- A client-side store for the basket. It would break Back and Forward, shared links and this page's deep links.
- Prerendering every Suggestion. With dozens of Ingredients and up to six in a basket, there are millions of baskets.
- A disabled Add button at the limit. A disabled button can't take focus or explain itself; Add stays active and says why nothing was added.
- A side panel for the basket on wide screens. It took a column from every page; the bar at the foot works at every width.
What's next.
- Rescue. Guided help when something goes wrong mid-cook: a split sauce, too much salt, a missing ingredient. It's where an LLM might earn a place, because describing a problem in free text is valuable there. Following ADR 0003 (opens in a new tab), it would come with constrained outputs drawn from the same curated graph, and a deterministic fallback that works with no model at all.
- Content toward 100 Ingredients, in sourced batches, with images generated and reviewed to the style guide, and each Recipe cooked before it ships.
- Shareable dishes, by putting a dish's changes in its address as well as its basket.