# UX + Contract Pre-Coding Gate

## Purpose
Prevent UI/API drift by enforcing contract-first UX planning before feature code starts.

## Scope
- `doc/product/UX_Journeys.md`
- `doc/product/UX_Implementation_Spec.md`
- `doc/product/ux-mocks/*.md`
- `doc/governance/Product_Gap_Readiness_Gate.md`
- `doc/api/openapi.draft.yaml`
- `doc/api/asyncapi.draft.yaml`

## Mandatory Rules
1. Route-first:
- Every new user/admin route must be listed in `UX_Implementation_Spec.md` before code.

2. Contract-first:
- Every screen action must map to an OpenAPI or AsyncAPI operation.
- If no operation exists, add/update the contract first.

3. State completeness:
- Every mock must define `loading`, `empty`, `error`, `success`, `restricted`, `rate_limited`.

4. Async behavior explicit:
- Polling cadence, websocket behavior, and terminal/error states must be documented.

5. Authorization clarity:
- Each screen must state required role (`user` or `admin`) and restricted behavior (`403` UX).

6. Brand and theming consistency:
- Use `doc/product/Brand_Guidelines.md` for naming, visual tokens, and logo usage.
- Do not hotlink external brand assets in production UI code.

7. Product gap readiness:
- Every workflow must declare persona, canonical entry point, empty-state
  dependencies, in-place recovery, success signal, cleanup path, expected
  blocked states, and environment lane.
- Unknown dependency creation, cleanup, role boundary, or recovery behavior is
  a design/contract gap, not something to discover in UAT.

## Definition of Ready (UI/API Feature)
- [ ] Screen mock exists under `doc/product/ux-mocks/`.
- [ ] Product gap register row exists and is `ready_for_dev` or `accepted_gap`.
- [ ] OpenAPI/AsyncAPI operations for all actions are present.
- [ ] UX state matrix is complete for the screen.
- [ ] Empty-state dependency and in-place recovery paths are represented in the mock/spec.
- [ ] Cleanup and failure/retry states are represented in the mock/spec.
- [ ] Error codes referenced by UX exist in `Error_Code_Catalog.md`.
- [ ] Role/permission behavior is explicitly documented.

## CI/Review Enforcement
- Reviewers should block PRs that introduce UI behavior without contract/mocks updates.
- Reviewers should block PRs that move product-gap discovery into broad UAT
  instead of resolving or accepting the gap during design/dev.
- Spectral + contract checks remain mandatory for API/event changes.