Learning Objectives
By the end of this lesson you will be able to:
- Explain why a purely declarative scenario needs zero changes after a UI redesign
- Connect declarative design to the idea of Gherkin as living documentation
- Evaluate whether a scenario is genuinely redesign-resistant
The Payoff
Every lesson in this module has been building toward one moment: the redesign lands, and your scenarios don't even notice.
Scenario: User logs in
Given a guest is on the login page
When they submit valid credentials
Then they are redirected to their dashboard
Now imagine the design team ships a complete visual overhaul: the button changes from blue to green, the login form moves from a centered card to a split-screen layout, the field labels are reworded, and six months later the whole page is rebuilt in a different frontend framework entirely. Every one of those changes is real work for developers and designers — and none of it touches this scenario. Not one word needs to change, because the scenario never mentioned the button's color, the form's layout, the labels, or the framework in the first place. It only ever talked about a guest, valid credentials, and a dashboard — concepts that outlive any particular implementation.
Compare that to the click-script version from Lesson 1, which would need editing after every single one of those changes, despite the business rule being identical.
This Is What "Living Documentation" Means
If you've taken the Gherkin Foundations course, you met the idea of living documentation there: the claim that Gherkin scenarios, unlike a Word document or a wiki page, stay accurate because they're executed against the real system on every build — if the scenario is wrong, the build fails, so nobody can quietly let the documentation drift out of date.
Declarative design is what makes that promise durable over time. A scenario can be perfectly synchronized with the code today and still be terrible documentation tomorrow if it's full of UI details that change every redesign cycle — the scenario keeps "passing" in a technical sense while quietly becoming irrelevant noise nobody trusts. A declarative scenario doesn't just pass today; it remains a readable, accurate description of the business rule for as long as that rule exists, regardless of how many redesigns the product goes through in between. That's the difference between documentation that's accurate right now and documentation that stays accurate for the life of the product.
Checking Your Own Work
Before you consider a scenario finished, ask the redesign question from Lesson 2 one more time, but broaden it: not just "would this survive a button color change," but "would this survive a total redesign, a rebrand, or even a migration to a different UI framework?" If the answer is yes for every step, you've written something that will still be teaching the next engineer — or the next BA — what the business rule is, long after today's interface is a screenshot in an old design doc.
Pro Tip: A genuinely declarative scenario should be just as readable if you imagine it describing a phone call to a human agent instead of a web page — because it was never really about the web page.
Key Takeaways
- A purely declarative scenario requires zero edits after a visual redesign, rebrand, or framework migration, because it never referenced the UI to begin with
- This is what gives Gherkin's "living documentation" promise its staying power — accurate not just today, but across the product's redesign history
- The redesign question — extended to a total overhaul, not just a cosmetic tweak — is the final check for whether a scenario is genuinely declarative