Screen Spec Template — Ghasi Melmastoon

How to use: Copy this template into a per-screen spec file (or as a sub-block within a per-platform spec or a journey spec). Fill every section. Sections marked (required) must not be skipped.

---

Screen name: <ScreenName>

• Surface: Consumer Meta Web / Tenant Booking Web / Guest Portal Web / Consumer Mobile / Staff Mobile / Operator Desktop / Kiosk / Tablet
• Route / nav: /path (web) or Stack.Screen name (mobile) or View id (desktop/kiosk)
• Status: draft / review / approved
• Owner: ___________
• Last reviewed: YYYY-MM-DD
• Implements journey(s): J-NN, J-NN
• Components used: [list, links to each component spec]

---

1. Purpose (required)

One paragraph: who uses this screen, when, what they accomplish. State the user outcome, not the implementation.

2. Entry / exit (required)

• Entered from: [list of routes / actions / deep links / push notifications]
• Exits to: [list of routes / actions / outcomes]
• Cancellable? yes / no / partially (specify what survives cancel)

3. Layout (text wire, required)

┌──────────────────────────────────────────┐
│  Header (logo, locale switcher, ...)     │
├──────────────────────────────────────────┤
│                                          │
│   Region A (primary content)             │
│                                          │
├──────────────────────────────────────────┤
│   Region B (supporting content)          │
├──────────────────────────────────────────┤
│  Footer / action bar                     │
└──────────────────────────────────────────┘

Describe each region: what lives there, density, scrollability, sticky behaviour, responsive collapses.

4. Components (required)

Component	Where	Variant	Notes
Card	Region A list rows	cozy	Tap target = entire row
Button	Footer	emphasis	Disabled when !canSubmit
LoadingSkeleton	Region A while loading	matches list-row layout

5. Data requirements (required)

Server state (React Query)

Query	Key	BFF endpoint	staleTime	gcTime
getBootstrap	['tenant.v1', tenantSlug, 'bootstrap']	GET /bootstrap	5 min	30 min
getAvailability	['tenant.v1', tenantSlug, 'availability', params]	GET /availability	30 s	5 min

Mutations

Mutation	BFF endpoint	Idempotency-Key strategy	Optimistic?
createHold	POST /hold	ULID per hold attempt	no

Client / URL state

• Booking-draft slice fields read: ___
• URL params: ___

Local persistence

• IndexedDB keys / MMKV keys / SQLite tables read: ___
• Offline read availability: ___

6. State machine (required for non-trivial screens)

7. Interactions (required)

For each user action, what happens:

Action	Trigger	Outcome
Tap "Hold"	Footer CTA	createHold mutation; on success navigate to ConfirmationScreen; on validation error show inline; on 5xx show error toast
Pull-to-refresh	Mobile gesture	Re-fetch getAvailability; preserve scroll
Locale switch	Header dropdown	Reload with ?locale=...; preserve route

8. Loading / empty / error / offline states (required)

• Loading: Skeleton matching final layout; CTAs disabled
• Empty: Named pattern; explanatory text; one primary action ("Adjust dates" / "Browse other properties")
• Error: Named pattern from C2 error-to-UI matrix (when present); retry CTA; trace id shown if internal_error
• Offline: Banner; CTAs that require connectivity disabled with tooltip explanation; cached read still rendered

9. AI behaviour (if any)

• AI surfaces present: ___
• HITL pattern: ___
• Provenance UI: ___
• Fallback when AI unavailable: ___
• Feature flag: ___

10. Telemetry (required)

Event	When	Properties
view.page / view.screen	Mount	path, tenantId?, propertyId?
funnel.step	Multi-step flows: enter, success, abandon, error	step, result
<screen>.<action>	Specific user actions	(per-action props)
error.surfaced	Visible error	errorCode, httpStatus, path, traceId

11. Accessibility (required)

• Page heading focus on route change (web)
• Focus order through regions: ___
• Keyboard shortcuts (if any): ___
• Screen reader announcement on state change: ___
• Touch targets verified >= 44x44 pt (mobile/desktop touch) / 32x32 px (web)
• Modal trap behaviour (if applicable): ___
• Reduced motion behaviour: ___

12. Internationalisation (required)

• Strings: all via next-intl / @ghasi/i18n
• RTL behaviour: which regions mirror, which do not
• Numerals: financial values Latin; body counts per locale pack
• Truncation behaviour for long localised strings: ___

13. Performance (required)

• Mount-to-interactive budget: < N ms on Moto G4 / Pixel 4a / target hardware
• LCP element identified: ___
• Initial network call count: <= N
• Lazy-loaded sub-trees: ___

14. Security

• Auth required: yes / no; scope: ___
• Tenant boundary: how X-Tenant-Id is set
• Sensitive data on screen: ___ (passport, payment, lock-key, ...)
• Audit log entries: ___

15. Test gates

• E2E gate: G-WEB-N / G-MOB-N / G-DSK-N (when this screen is part of a critical journey)
• Component tests: ___
• Visual regression (Chromatic / Loki): LTR + RTL stories

16. Open questions

• Q1: ___
• Q2: ___

---

References

• Journey: ../frontend/journeys/.../J-NN-...md
• Platform spec: ../frontend/<surface>/<NN>-...md
• Design system: ../frontend/common/03-design-system.md
• NFRs: ../frontend/common/09-non-functional-requirements.md
• Testing strategy: ../frontend/common/10-frontend-testing-strategy.md