Scenario: Frontend Team
Design a harness where browser QA, accessibility, visual state, and design rules are load-bearing.
Key takeaways
- Frontend harnesses must verify rendered behavior, not just compilation: browser QA, accessibility, design rules, and a QA report are the load-bearing elements.
- The recommended loop runs typecheck/lint, then browser QA, then an accessibility check, and only produces a PR once those pass.
- Make the task contract enumerate loading, empty, and error states so missing UI states are caught before review.
- Require both desktop and mobile browser QA plus keyboard navigation in done criteria, with screenshots when visual behavior changes.
- Start by templating a short UI task contract, making browser QA mandatory for user-facing changes, and moving repeated review comments into
docs/design-rules.md.
Frontend teams often fail after the code compiles. The risk is not only TypeScript or tests. It is real rendered behavior.
Problem Structure
- The component compiles but the screen is broken.
- Loading, empty, and error states are missing.
- Keyboard and screen-reader behavior regress.
- Responsive layout breaks on mobile.
- Design-system rules are remembered by humans, not enforced by the harness.
Load-Bearing Elements
| Element | Why it matters |
|---|---|
| Browser QA | Verifies rendered behavior |
| A11y gate | Catches keyboard and semantic regressions |
| Design rules | Keeps UI consistent |
| Screenshot or QA report | Preserves evidence for review |
Recommended Loop
Artifact Structure
design-rules.md
interaction-patterns.md
a11y-gates.md
ui-task-contract.yaml
browser-qa-report.md
Example Done Criteria
frontend_done:
must_pass:
- "typecheck"
- "lint"
- "desktop browser QA"
- "mobile browser QA"
- "keyboard navigation"
evidence:
- "qa-report.md"
- "screenshots when visual behavior changed"Common Failures
| Failure | Harness response |
|---|---|
| Looks fine in code, broken in browser | Browser QA required |
| Missing empty/error state | Task contract lists states |
| A11y regression | Keyboard and semantic gate |
| Design inconsistency | Design rules loaded before implementation |
First 30 Days
- Create a short UI task contract template.
- Make browser QA mandatory for user-facing UI changes.
- Move repeated design review comments into
docs/design-rules.md.