[PUSHPAK-JAISWAL]

What & why

Closes #128

Adds two new documentation pages to docs-site/docs/why/ matching the voice, philosophy, and structure of the existing pages:

1. Why accessibility-first locators? (why-accessibility-first-locators.md):

   • Explains the fragility of DOM-hierarchy and CSS-class selectors against layout refactors and utility CSS migrations.
   • Shows how getByRole, getByLabel, and getByText target the accessibility tree (roles and accessible names) to survive markup changes.
   • Includes before/after code examples and a multi-sprint refactoring walkthrough (button -> anchor role="button" -> input submit) where accessibility locators keep passing while CSS/XPath fail.
   • Reinforces that Selenium is never hidden, detailing escape hatches to standard By (toBy()) and native WebDriver.

2. Why WaitEngine? (why-wait-engine.md):

   • Breaks down the synchronization traps: scattered WebDriverWait instances with arbitrary hardcoded timeouts and flaky Thread.sleep hacks.
   • Explains centralized auto-waiting configured once via selenium-boot.yml (timeouts.explicit).
   • Details out-of-the-box conditions (waitForVisible, waitForInvisible, waitForClickable, waitForText, waitForUrlMatches, waitForPageLoad, waitForNetworkIdle).
   • Demonstrates standard ExpectedCondition<T> escape hatches via WaitEngine.wait(...).

Additional changes:

• Registered both pages in docs-site/sidebars.js under the Why Selenium Boot category.
• Updated cross-links in why-selenium-boot.md, why-not-plain-selenium.md, and why-not-playwright.md.

Type of change

• Bug fix
• New feature (opt-in, aligned with the framework philosophy)
• Documentation
• Internal refactor / test coverage

Checklist

• All existing tests pass (mvn clean verify)
• New behaviour is covered by unit tests
• No new external dependencies introduced without prior discussion
• Code follows existing conventions (no new frameworks, minimal abstraction)
• No breaking changes to @SeleniumBootApi public APIs (or a major version bump is justified below)
• Docs updated if user-facing behaviour changed (docs-site/)

Notes for reviewers

• Verified locally with Docusaurus production build (npm run build completed with zero broken links or markdown syntax errors).

[shossain786]

Thanks Pushpak, nice pages. I checked the API names against the code and they exist. Two fixes:

• The description lists WhyDocSnippetsCompileTest.java, but it isn't in the PR. Please add it or update the description.
• A few claims are absolute: "Survives CSS refactoring: Yes", "Network-Aware: Yes". Please soften them, and confirm the sprint-3 <input type="submit"> example actually matches Role.BUTTON in the role-matching code.

[PUSHPAK-JAISWAL]

@shossain786 on it

[PUSHPAK-JAISWAL]

@shossain786 the requested changes are done as requested. Please review those and if there are any more changes please reply.

[shossain786]

Thanks Pushpak — claims softened and the submit-button matching checks out against Role.java. I removed the stale WhyDocSnippetsCompileTest line from the description (that file isn't in the PR). Merging.