Design-first means you write the OpenAPI contract, review it, mock it, and get consumer feedback on it before anyone builds the implementation. The economics are obvious once you have lived through the alternative: changing a YAML file costs nothing, and changing a shipped API that people depend on costs a great deal.
It also changes who gets a say. A contract you can read and mock is something a product manager, a front-end developer, and a partner can all react to. Code is not. Design-first is how the consumer gets into the room before the decisions are baked.
That said, I gave up years ago on the idea that everyone will adopt it. Plenty of good teams work prototype-first or code-first, and telling them they are doing it wrong just gets you ignored. The thing worth insisting on is not the sequence — it is that a machine-readable contract exists, that it is accurate, that it is in version control, and that it is treated as authoritative rather than as a by-product.
There is one current pressure worth naming. In a world dominated by runtime gateways, there is a temptation to treat design-time as optional because the gateway is where everything “really” happens. That is backwards. No amount of runtime sophistication fixes a badly designed contract, because the contract is what consumers built against.
