UX¶
The behavior layer. This section describes what the user sees and does in each feature of Tomoda — the screens, the steps, the states, the things that go wrong. It is the engineering-facing rendering of the product, written for someone who has to ship the feature, debug it in support, or QA it before a release.
UX docs are deliberately narrow: they do not retell the brand pitch, they do not enumerate the React component tree, and they do not list the backend rules. Those concerns live in adjacent layers, and the UX layer links across to them.
Where UX fits¶
| Question | Layer |
|---|---|
| Why does this feature exist? What's the story? | product/bible/ — narrative per feature |
| What are the rules / states / invariants? | product/domains/ — product spec |
| How does the user use it? | ux/ — this layer |
| What does the visual language enforce? | style-guide/ — tokens, components |
| How does the user reach it in the app? | frontend/routing.md — routes + auth gate |
| How does the screen wire to data? | frontend/state-management.md, frontend/api-client.md |
| What does the backend actually enforce? | backend/services/<topic>.md |
If two layers could plausibly host a fact, ask what question does it answer? UX pages answer "how does the user use it?" — anything else gets a link, not a copy.
Page structure¶
Every UX page in this section follows the same shape:
- Purpose — one line. What feature is this, in user terms.
- Entry points — how the user reaches it (which tab, which gesture, which deep link).
- Primary flow — the happy path, step by step. What the user sees at each step.
- Sub-flows — variations (host vs guest, RSVP'd vs not, public share vs in-app, etc.).
- States — empty, loading, error, success — what they look like and when they appear.
- Edge cases & gotchas — permission denials, offline behavior, backgrounding mid-action, geofence rejections, race conditions the user might see.
- See also — cross-links to product, style-guide, frontend, and backend.
Pages stay short. If a page approaches 500 lines, the feature is overdue for a split.
Voice¶
- Forward-looking present, third-person user. "The user taps the heart; the count increments locally, then syncs."
- Tables over prose for any list with more than three items.
- No component names. Talk about what the user perceives.
frontend/components.mdis the right home for "this is<MomentDetailSheet />". - No rule restatements. "Moments expire after 24h" is a product rule; UX describes the behavior of that expiry to the user ("After expiry, the moment is gone from the feed; if a friend had already opened it, their view stays loaded until they navigate away").
- No diagrams unless they pay rent. When a flow is genuinely branching or stateful, a small inline diagram (CSS primitives — see the Drawing diagrams section of the repo
CLAUDE.md) is fine. Otherwise, prose + tables.
Pages¶
- Identity — sign-up, sign-in, security, deletion, plus the admin and partner shell gates.
- Discovery feed — the discover view: cards, filters, refresh, pagination.
- Events — create, join, leave, host controls, capacity, the embedded chat room.
- Moments — capture, publish, visibility, retention, journaled vs timed.
- Chat — DM and group chat, message types, read receipts, edit/delete.
- Friends — requests, accept/decline, block, search, suggestions.
- Presence & live location — online indicator, active-location sharing.
- Map & radar — map gestures, clusters, marker types, the radar list.
- Profile & settings — view profile, edit, theme, language, privacy, account deletion.
What's not in scope here¶
- Web-only marketing pages — those are the brand site, not the app.