The Design Doc

The spec said what the toast system does. The design doc says how it gets built. Open design.md in your change folder.

Four sections:

Note: The design doc is where exploration pays off. When you explored "Postgres vs SQLite", the reasoning (embedded, offline, single file) became the constraints in Context. The tradeoffs you surfaced became Goals/Non-Goals. The questions exploration asked become the Decisions you document here.

Context — one paragraph on the constraints. Single file, no build tooling, no framework. This is the proposal's scope decision turned into a working constraint for every decision that follows.

Goals / Non-Goals — what this implementation delivers and what it deliberately doesn't. Notice what's in the Non-Goals: accessibility, pause-on-hover, mobile layout. Those aren't oversights — they're decisions. The AI will not add them, because they're written down as out of scope.

Decisions — this is the most important section. Four choices are documented here, each with the reasoning behind it:

• A ToastManager class keeps state in one place instead of scattered module-level variables
• CSS custom properties for variant colors — readable without a preprocessor
• CSS @keyframes for enter, a .toast--leaving class for exit — this is the spec's sequencing requirement made concrete. The transitionend listener fires after the animation completes, then removes the element. That's how "animation plays first, DOM removal after" actually works in code.
• A single fixed #toast-container div — toasts stack via normal flow, no JS positioning math

Risks / Trade-offs — two edge cases called out before the AI writes a line. The transitionend listener fires multiple times if multiple properties transition; the fix is once: true. Very old browsers don't support CSS custom properties; acceptable for a tutorial demo.

The decisions section is doing the same thing the spec did — taking things that would have been silent AI guesses and making them explicit. The difference is that the spec described behavior, and the design doc describes implementation. Both live in your repo. Both get read before code is written.

If anything here doesn't match how you want it built, edit it now. In lesson 06 you'll break the design into tasks and hand it to the AI.