Platform UI view inventory &ZeroWidthSpace;

Status: Current (2026-06-22)

ADR: 0033 — Platform Foundation UI & View Inventory

ADO: Epic AB#3074 (Platform build)

This document is the per-view specification matrix for every platform-foundation view. For the governing decision (view inventory rules, card naming convention, feature ADR convention) see ADR 0033. For the member-detail field model see member-directory-rbac.md.

Mockup file path convention (ADR 0033) &ZeroWidthSpace;

Screen mockup HTML files live under packages/ui/design-system/screens/ in platform-specific subfolders. All paths in the "Mockup" rows below use the screens/web/ prefix — the web browser client is the current platform-foundation target.

Subfolder	Purpose
`screens/web/`	Responsive HTML mockups for the web browser client (Desktop, Tablet, Phone viewports)
`screens/mobile/`	Native HTML mockups for iPhone + Android app — reserved; placeholder files only at this time
`screens/tablet/`	Native HTML mockups for iPad app — reserved; placeholder files only at this time
`components/`	Shared component snippet cards (tab bar, buttons, empty state, etc.)

Responsive layout (ratified) &ZeroWidthSpace;

Breakpoint	Viewport width	Primary nav	Content
Phone	< 640 px	Fixed bottom tab bar (5 tabs, 60px + safe-area)	Single column, full width, 80px bottom padding
Tablet	640 – 1023 px	Fixed bottom tab bar	Single column, max 640px centered
Desktop	≥ 1024 px	Fixed left sidebar (220px)	Fluid column, max 860px centered, 32px padding

Five primary destinations (locked): Home · Watch & Listen · Calendar · Messages · Me

DesignSync card naming &ZeroWidthSpace;

<Screen> — <Variant/Role> · <Platform> · <Viewport>

Platform values: Web, iPhone App, iPad App, Android App. Viewport values (web only): Desktop, Tablet, Phone. Native apps omit the viewport suffix.

View specifications &ZeroWidthSpace;

A1 — Landing / public home &ZeroWidthSpace;

Attribute	Value
Route	`/`
Access	Public (unauthenticated)
Mockup	`packages/ui/design-system/screens/web/landing.html`
Card names	`Landing · Web · Desktop`, `Landing · Web · Tablet`, `Landing · Web · Phone`
ADO	Story under Feature AB#3090

Purpose: First page a visitor sees. Heritage Virginia branding, brief community description, sign-in CTA, and "Request Community Access" link. No feature content. Redirect to /app/home if the user is already authenticated.

Key states: Unauthenticated only. No tab bar, no sidebar. Centered card layout (similar to sign-in chrome).

Attribute	Value
Route	`/sign-in`
Access	Public
Mockup	`packages/ui/design-system/screens/web/sign-in.html` (exists)
Card names	`Sign-in · Web · Desktop`, `Sign-in · Web · Tablet`, `Sign-in · Web · Phone`
ADO	Story under Feature AB#3085

Purpose: Clerk-backed sign-in with Apple and Google social sign-in, plus email/password. Links to "Request Community Access" (A3) for new members.

Key states: Default, error (invalid credentials), loading. No app chrome (no tab bar/sidebar).

Attribute	Value
Route	`/sign-up`
Access	Public
Mockup	`packages/ui/design-system/screens/web/sign-up-request.html`
Card names	`Sign-up — Request Access · Web · Desktop`, `Sign-up — Request Access · Web · Tablet`, `Sign-up — Request Access · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: Closed-community intake form. Collects name, email, and optional note to the minister. Submits a member-join approval request (ADR 0007). User is informed the request is pending.

Key states: Form, submitting, submitted (→ A5 pending screen).

Attribute	Value
Route	`/sign-up/account`
Access	Public (post-approval link)
Mockup	`packages/ui/design-system/screens/web/sign-up-account.html`
Card names	`Sign-up — Create Account · Web · Desktop`, `Sign-up — Create Account · Web · Tablet`, `Sign-up — Create Account · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: After the minister approves the join request, the new member follows an emailed link to create their Clerk account (set display name, choose Apple/Google or email/password). One-time flow; not accessible after account creation.

Key states: Form, submitting, complete (→ A2 sign-in or → S2 home).

A5 — Account pending approval &ZeroWidthSpace;

Attribute	Value
Route	`/pending`
Access	Public / authenticated-but-pending
Mockup	`packages/ui/design-system/screens/web/account-pending.html`
Card names	`Account Pending · Web · Desktop`, `Account Pending · Web · Tablet`, `Account Pending · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: Shown after A3 (request submitted) or if a member signs in while their account is still pending_approval. Explains that leadership will review and approve. No app chrome.

Key states: Pending (default). If approved and user returns, redirect to /app/home.

A6 — Sign-out confirmation &ZeroWidthSpace;

Attribute	Value
Route	Modal / flow (not a standalone route)
Access	All authenticated roles
Mockup	`packages/ui/design-system/screens/web/sign-out.html`
Card names	`Sign-out · Web · Desktop`, `Sign-out · Web · Tablet`, `Sign-out · Web · Phone`
ADO	Story under Feature AB#3090

Purpose: Confirmation dialog before signing the user out. "Sign out" CTA clears the Clerk session and redirects to A2.

Key states: Confirmation modal overlay (shown over whichever page the user was on).

Attribute	Value
Route	Shell — present on all `/app/*` routes
Access	All authenticated roles
Mockup	`packages/ui/design-system/components/tab-bar.html` (exists, authoritative for tabs)
Card names	`Shell — Tab Bar · Web · Phone`, `Shell — Tab Bar · Web · Tablet`, `Shell — Sidebar · Web · Desktop`
ADO	Story under Feature AB#3090

Purpose: The persistent app chrome: bottom tab bar on phone/tablet (5 tabs); left sidebar on desktop (same 5 destinations). Includes the Heritage Virginia wordmark (desktop) and avatar/sign-out affordance. Admin and minister see RBAC-gated portal links in the sidebar (desktop) or in their Profile hub (P1, phone).

Tab order (locked): Home · Watch & Listen · Calendar · Messages · Me

RBAC nav: Portal links are appended after "Me" (sidebar, desktop) or surfaced in P1 (phone) for admin and ministry_leader only. Links are driven by canManage/role from the session; not rendered for member or visitor. Feature-registry entries are appended by the feature registry (ADR 0030) when each feature is onboarded.

S2 — Home (feature-icon grid) &ZeroWidthSpace;

Attribute	Value
Route	`/app/home`
Access	All authenticated roles
Mockup	`packages/ui/design-system/screens/web/home.html` (rework: registry-driven icon grid)
Card names	`Home · Web · Desktop`, `Home · Web · Tablet`, `Home · Web · Phone`
ADO	Story under Feature AB#3692

Purpose: The first screen after sign-in. Shows a greeting with the user's name, then a grid of feature icons — one icon per onboarded feature. Icons are driven by the feature registry (GET /config/features, ADR 0030); un-onboarded features show nothing. Platform foundation = 0 or 1 icons (Messages if onboarded). "Watch & Listen", "Calendar", etc. icons appear here automatically when those features are onboarded.

Key states: Empty (foundation, no features yet — show a "more coming soon" placeholder if nothing is registered); populated (one icon per feature); RBAC-filtered (some features have minRole filtering).

S3 — Messages inbox shell &ZeroWidthSpace;

Attribute	Value
Route	`/app/messages`
Access	All authenticated roles
Mockup	`packages/ui/design-system/screens/web/messages.html`
Card names	`Messages · Web · Desktop`, `Messages · Web · Tablet`, `Messages · Web · Phone`
ADO	Story under Feature AB#3090

Purpose: Simple platform-foundation inbox shell. In the platform phase (no Messaging feature yet) this shows a single-column list of messages from Heritage Virginia leadership (one-way broadcasts). Reuses components/message-row.html pattern. Full messaging feature (Pony Express, ADR 0018) is out of platform scope.

Key states: Empty (no messages), populated, unread badges.

P1 — Profile (Me hub) &ZeroWidthSpace;

Attribute	Value
Route	`/app/profile`
Access	Self (all authenticated roles viewing their own profile)
Mockup	`packages/ui/design-system/screens/web/profile.html` (cleanup: remove feature tags)
Card names	`Profile — Me · Web · Desktop`, `Profile — Me · Web · Tablet`, `Profile — Me · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: The user's own profile hub. Shows avatar, display name, role, family group. Sub-nav rows: Edit profile (P2), Privacy & visibility (P3), Notification preferences (P4), About & Help (P5), Sign out (A6). Admin and minister also see portal links here (phone viewport) or in the sidebar (S1, desktop viewport).

Platform-only tags: No feature tags (no "Bible Study", no "Homeschool Co-op" — those are feature content, not platform). Role badge only.

P2 — Edit own profile &ZeroWidthSpace;

Attribute	Value
Route	`/app/profile/edit`
Access	Self
Mockup	`packages/ui/design-system/screens/web/profile-edit.html`
Card names	`Profile — Edit · Web · Desktop`, `Profile — Edit · Web · Tablet`, `Profile — Edit · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: Edit display name, avatar, phone, address, birthday, anniversary, bio. Member edits their own fields only. PATCH /me/profile. Role and family composition are not editable here.

P3 — Privacy & visibility &ZeroWidthSpace;

Attribute	Value
Route	`/app/profile/privacy`
Access	Self
Mockup	`packages/ui/design-system/screens/web/profile-privacy.html`
Card names	`Profile — Privacy · Web · Desktop`, `Profile — Privacy · Web · Tablet`, `Profile — Privacy · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: Control phonePublic (whether phone number appears to peer members) and any other member-controlled visibility toggles. PATCH /me/profile.

P4 — Notification preferences &ZeroWidthSpace;

Attribute	Value
Route	`/app/profile/notifications`
Access	Self
Mockup	`packages/ui/design-system/screens/web/profile-notifications.html`
Card names	`Profile — Notifications · Web · Desktop`, `Profile — Notifications · Web · Tablet`, `Profile — Notifications · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: Toggle push, email, and SMS notification categories. Calls PATCH /me/notifications. Platform foundation: show the settings surface with stubs; full delivery via ADR 0013 (Twilio).

P5 — About & Help &ZeroWidthSpace;

Attribute	Value
Route	`/app/about`
Access	All authenticated roles
Mockup	`packages/ui/design-system/screens/web/about-help.html`
Card names	`About & Help · Web · Desktop`, `About & Help · Web · Tablet`, `About & Help · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: Static page — Heritage Virginia contact info, app version, copyright, privacy policy link, terms of use link. No dynamic data. Accessed from P1.

F1 — Family management &ZeroWidthSpace;

Attribute	Value
Route	`/app/family`
Access	Family head (primary account)
Mockup	`packages/ui/design-system/screens/web/family.html` (exists)
Card names	`Family · Web · Desktop`, `Family · Web · Tablet`, `Family · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: Shows the family group: member list with relationship + status badges. Add spouse (→ F2) and Add child (→ F3) CTAs. Family composition changes route through the approval queue (ADR 0007). If no family group yet, shows a "not linked" placeholder.

F2 — Add spouse &ZeroWidthSpace;

Attribute	Value
Route	`/app/family/add-spouse`
Access	Family head
Mockup	`packages/ui/design-system/screens/web/family-add-spouse.html` (exists)
Card names	`Family — Add Spouse · Web · Desktop`, `Family — Add Spouse · Web · Tablet`, `Family — Add Spouse · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: Approval-gated spouse-invite form. Posts spouse-add to the approval workflow (ADR 0007). Shows pending state after submission.

F3 — Add child &ZeroWidthSpace;

Attribute	Value
Route	`/app/family/add-child`
Access	Family head
Mockup	`packages/ui/design-system/screens/web/family-add-child.html`
Card names	`Family — Add Child · Web · Desktop`, `Family — Add Child · Web · Tablet`, `Family — Add Child · Web · Phone`
ADO	Story under Feature AB#3086

Purpose: Create a child sub-account (username + PIN — ADR 0007). Split from the inline Add Child form in family.html into its own screen. Posts to /family-groups/:id/children.

M1 — Members directory &ZeroWidthSpace;

Attribute	Value
Route	`/app/members`
Access	All authenticated roles
Mockup	`packages/ui/design-system/screens/web/members.html` (rework: verify last-name sort + grouping)
Card names	`Members — Directory · Web · Desktop`, `Members — Directory · Web · Tablet`, `Members — Directory · Web · Phone`
ADO	Story under Members feature

Purpose: Full member directory. Sorted alphabetically by last name. Members of the same family grouped together under their family name. Search bar (?q=). Clicking a member navigates to M2 or M3 (replaces the inline toggleSelected panel). Children visible to admin/ministry_leader only.

M2 — Member detail (adult) &ZeroWidthSpace;

Attribute	Value
Route	`/app/members/:id`
Access	All authenticated roles (403 for peer member viewing a child)
Mockup	`packages/ui/design-system/screens/web/member-detail-adult.html`
Card names	`Members — Detail (Adult) · Web · Desktop`, `Members — Detail (Adult) · Web · Tablet`, `Members — Detail (Adult) · Web · Phone`
ADO	Story AB#3693 (re-scoped)

Purpose: Full-page member detail for an adult. Shows birthday, anniversary (if married), address, phone, email. Same fields for all viewers. Admin and minister see a "Manage" button (→ M4 or M5). See ADR 0032 for the field model.

M3 — Member detail (kid) &ZeroWidthSpace;

Attribute	Value
Route	`/app/members/:id` (child account)
Access	Admin, ministry_leader, family head; 403 for peer members
Mockup	`packages/ui/design-system/screens/web/member-detail-kid.html`
Card names	`Members — Detail (Kid) · Web · Desktop`, `Members — Detail (Kid) · Web · Tablet`, `Members — Detail (Kid) · Web · Phone`
ADO	Task under AB#3693

Purpose: Member detail for a child sub-account. Shows birthday only. No contact information. Same "Manage" button affordance for admin/minister navigates to M4/M5.

M4 — Member manage (admin) &ZeroWidthSpace;

Attribute	Value
Route	`/app/members/:id/manage` (admin role)
Access	`admin` only
Mockup	`packages/ui/design-system/screens/web/member-manage-admin.html`
Card names	`Members — Manage (Admin) · Web · Desktop`, `Members — Manage (Admin) · Web · Tablet`, `Members — Manage (Admin) · Web · Phone`
ADO	Task under AB#3693

Purpose: Admin management screen for a specific member. Edit profile fields (any member); change account status (suspend/reactivate); change role (links to AD3 Role Assignment page); view audit log for this member. Server returns 403 for callers outside admin.

M5 — Member manage (minister) &ZeroWidthSpace;

Attribute	Value
Route	`/app/members/:id/manage` (ministry_leader role)
Access	`ministry_leader` only
Mockup	`packages/ui/design-system/screens/web/member-manage-minister.html`
Card names	`Members — Manage (Minister) · Web · Desktop`, `Members — Manage (Minister) · Web · Tablet`, `Members — Manage (Minister) · Web · Phone`
ADO	Task under AB#3693

Purpose: Minister pastoral management screen for a specific member. Pastoral overview: family context, account type; initiate approval-queue actions. No write access to profile fields, status, or role. Server returns 403 for callers outside ministry_leader.

AD1 — Admin portal hub &ZeroWidthSpace;

Attribute	Value
Route	`/app/admin`
Access	`admin` only
Mockup	`packages/ui/design-system/screens/web/admin.html` (exists)
Card names	`Admin — Hub · Web · Desktop`, `Admin — Hub · Web · Tablet`, `Admin — Hub · Web · Phone`
ADO	Story under Feature AB#3166

Purpose: Admin portal landing. Summary sections linking to AD2–AD5. Quick stats.

AD2 — Approval queue &ZeroWidthSpace;

Attribute	Value
Route	`/app/admin/approvals`
Access	`admin`, `ministry_leader`
Mockup	`packages/ui/design-system/screens/web/admin-approval-queue.html` (exists)
Card names	`Admin — Approval Queue · Web · Desktop`, `Admin — Approval Queue · Web · Tablet`, `Admin — Approval Queue · Web · Phone`
ADO	Story under Feature AB#3166

Purpose: Queue of all pending approval items (member-join, spouse-add, child-add, content-publish). Filter pills by type. Approve/deny actions (ADR 0007).

AD3 — Role assignment &ZeroWidthSpace;

Attribute	Value
Route	`/app/admin/roles`
Access	`admin` only
Mockup	`packages/ui/design-system/screens/web/admin-role-assignment.html` (exists)
Card names	`Admin — Role Assignment · Web · Desktop`, `Admin — Role Assignment · Web · Tablet`, `Admin — Role Assignment · Web · Phone`
ADO	Story under Feature AB#3166

Purpose: Search members, select a role, save. PUT /members/:id with role field. Admin-only.

AD4 — Content oversight &ZeroWidthSpace;

Attribute	Value
Route	`/app/admin/content`
Access	`admin`, `ministry_leader`
Mockup	`packages/ui/design-system/screens/web/admin-content-oversight.html` (exists)
Card names	`Admin — Content Oversight · Web · Desktop`, `Admin — Content Oversight · Web · Tablet`, `Admin — Content Oversight · Web · Phone`
ADO	Story under Feature AB#3166

Purpose: Published announcements and pending content items. Withdraw or demote published content. Filter by type.

AD5 — Audit log &ZeroWidthSpace;

Attribute	Value
Route	`/app/admin/audit-log`
Access	`admin` only
Mockup	`packages/ui/design-system/screens/web/admin-audit-log.html` (exists)
Card names	`Admin — Audit Log · Web · Desktop`, `Admin — Audit Log · Web · Tablet`, `Admin — Audit Log · Web · Phone`
ADO	Story under Feature AB#3166

Purpose: Cursor-paginated audit log (GET /admin/audit-log). Login/logout, approval actions, content events. Can be filtered to a specific member via ?memberId= (linked from M4).

MN1 — Minister portal hub &ZeroWidthSpace;

Attribute	Value
Route	`/app/minister`
Access	`ministry_leader`
Mockup	`packages/ui/design-system/screens/web/minister-portal.html` (exists)
Card names	`Minister — Hub · Web · Desktop`, `Minister — Hub · Web · Tablet`, `Minister — Hub · Web · Phone`
ADO	Story under Feature AB#3166

Purpose: Minister portal landing. Pending approvals summary, published announcements. Links to AD2 (Approval Queue, shared with admin) and MN2 (Oversight).

MN2 — Minister oversight &ZeroWidthSpace;

Attribute	Value
Route	`/app/minister/oversight`
Access	`ministry_leader`
Mockup	`packages/ui/design-system/screens/web/minister-oversight.html`
Card names	`Minister — Oversight · Web · Desktop`, `Minister — Oversight · Web · Tablet`, `Minister — Oversight · Web · Phone`
ADO	Story under Feature AB#3166

Purpose: Pastoral overview — family group list, pending pastoral items, member count by status. Read-only. Minister can navigate from here to individual member detail (→ M2/M3) and then to the minister management screen (→ M5) for specific members.

U1 — Not found / 404 &ZeroWidthSpace;

Attribute	Value
Route	`*` (catch-all)
Access	All
Mockup	`packages/ui/design-system/screens/web/system-404.html`
Card names	`System — 404 · Web · Desktop`, `System — 404 · Web · Tablet`, `System — 404 · Web · Phone`
ADO	Story under new system/utility feature

Purpose: Shown for unmatched routes and disabled feature routes that return nothing. Heritage Virginia branding, "Go home" CTA, no app chrome.

U2 — Access denied / 403 &ZeroWidthSpace;

Attribute	Value
Route	(rendered programmatically on 403 API response)
Access	All
Mockup	`packages/ui/design-system/screens/web/system-403.html`
Card names	`System — 403 · Web · Desktop`, `System — 403 · Web · Tablet`, `System — 403 · Web · Phone`
ADO	Story under new system/utility feature

Purpose: Shown when a user navigates to a role-restricted URL or the API returns 403. Explains access is restricted. "Go home" CTA.

U3 — Empty state (component) &ZeroWidthSpace;

Attribute	Value
Route	(component, not a route)
Access	All
Mockup	`packages/ui/design-system/components/empty-state.html`
Card names	`Components — Empty State · Web · Desktop`
ADO	Task under AB#3237

Purpose: Reusable empty-state component with icon, heading, body text, optional CTA button. Used on MembersPage (no results), Messages (no messages), etc.

U4 — Loading / skeleton (component) &ZeroWidthSpace;

Attribute	Value
Route	(component, not a route)
Access	All
Mockup	`packages/ui/design-system/components/loading.html`
Card names	`Components — Loading · Web · Desktop`
ADO	Task under AB#3237

Purpose: Skeleton loading state pattern for list and card surfaces. Used while API data is loading.

U5 — Error boundary &ZeroWidthSpace;

Attribute	Value
Route	(rendered by React error boundary)
Access	All
Mockup	`packages/ui/design-system/screens/web/system-error.html`
Card names	`System — Error · Web · Desktop`, `System — Error · Web · Tablet`, `System — Error · Web · Phone`
ADO	Story under new system/utility feature

Purpose: React error boundary catch-all. "Something went wrong" message with a "Reload" or "Go home" CTA. Heritage Virginia branding.

M6 — Export members to Excel/CSV (ROADMAP) &ZeroWidthSpace;

Status: ROADMAP — not built in platform phase.

Description: Allow admin to export the full member directory to Excel/CSV. Requires server-side generation and download link. Needs code and API work. Created as a Priority 4 ADO story (roadmap item) under the Members feature.

ADO: Roadmap story, Priority 4, tag roadmap, parent = Members feature.

Native app view catalog (designed in later phases) &ZeroWidthSpace;

All views A1–U5 apply to native app platforms. Designed in separate passes per platform:

iPhone / iPad: delivery phase per ADR 0009, Epic AB#3077.
Android: delivery phase per ADR 0014, Epic AB#3139.

Card naming for native: <Screen> · iPhone App, <Screen> · iPad App, <Screen> · Android App.

Code-readiness gaps &ZeroWidthSpace;

Gap	Work	ADO
No feature registry code	Build `FeatureRegistryEntry` in `packages/shared-config`; `GET /config/features`; Home grid	AB#3692
No `/app/members/:id` or `/manage` routes	Add routes + `MemberDetailPage` + `MemberManagePage`	AB#3693
No last-name sort / family grouping in MembersPage	Add sort + grouping; navigate on click	AB#3693
No real Home / Messages / Me hub routes	Add `/app/home`, `/app/messages`, `/app/me`; fix AppLayout tab mappings	AB#3090
RBAC nav unused (`_showAdmin` computed but not rendered)	Render portal links; add `isMinister`; reconcile role utils	AB#3087 + AB#3166
Profile sub-views missing	Add P2–P5 routes + pages	AB#3086
No Tabs/SegmentedControl in `@hch/ui`	Add component	AB#3237
Token drift: `#15803D` not in `tokens.ts`	Canonicalize success green in `tokens.ts`; update mockups	AB#3237
Profile feature tags	Remove "Bible Study" / "Homeschool Co-op" from `profile.html`	AB#3086