Heritage Docs

Appearance

0033 — Platform Foundation UI & View Inventory ​

Status: Accepted

Date: 2026-06-22

ADO work item: AB#3074 (Platform Epic); feature created under Epic AB#3074

Deciders: Kristopher Turner (platform owner)

Amends: ADR 0031 — resolves the three flagged responsive-layout ambiguities.

Cross-references: ADR 0021, ADR 0030, ADR 0031, ADR 0032

Context ​

The platform build (AB#3074) requires a complete, authoritative enumeration of every view in the platform foundation before any view is built. Without a canonical inventory:

  • Mockups drift: screens are created ad-hoc with no agreed naming convention, making the Claude Design project (7d1ebc96-b054-48c3-913e-733a17622948) hard to navigate.
  • ADO coverage is incomplete: there is no guarantee that every view has a work item with acceptance criteria.
  • Code coverage is incomplete: routes and pages may be added or omitted inconsistently.
  • Feature ADRs (0010–0020) do not record their view sets — when those features are built there is no convention for documenting and tracking their screens.

Additionally, ADR 0031 flagged three responsive-layout values as "proposals, owner sign-off required": desktop breakpoint (1024px), desktop nav pattern (left sidebar 220px), and max content width (860px). These are already implemented in apps/web/src/components/AppLayout.tsx and match the existing packages/ui/design-system/screens/web/*.html mockups. This ADR formally ratifies them.

Decision ​

The platform foundation has ≈35 canonical views. Each view must be (a) designed as a responsive HTML mockup encoding all three web viewports, (b) registered as DesignSync cards in the Claude Design project with the full naming convention defined below, (c) tracked as one ADO User Story with clear acceptance criteria under the appropriate platform feature, and (d) backed by a web route + React page component. Nothing in the platform foundation is shipped without all four artifacts present.

Native app views (iPhone, iPad, Android) reuse the same view list and acceptance criteria, but are designed and built in separate passes with their own mockups, cards, and ADO items.

The three responsive-layout values from ADR 0031 are hereby ratified: desktop breakpoint 1024px, desktop nav pattern left sidebar 220px, max content width 860px. These are locked decisions.

Responsive layout model (ratified from ADR 0031) ​

BreakpointViewportPrimary navContent constraint
Phone< 640 pxFixed bottom tab bar (5 tabs)Single column, full width, 80 px bottom padding
Tablet640–1023 pxFixed bottom tab bar (5 tabs)Single column, max 640 px centered
Desktop≥ 1024 pxFixed left sidebar (220 px)Fluid column, max 860 px centered, no bottom bar

The five primary tab/sidebar destinations remain as defined in packages/ui/design-system/components/tab-bar.html: Home · Watch & Listen · Calendar · Messages · Me — in that order. Additional destinations added by the feature registry (ADR 0030) appear after Me.

DesignSync card naming convention &ZeroWidthSpace;

Every card registered in the Claude Design project must identify the screen, role variant (if role-specific), platform, and viewport in the format:

<Screen> — <Variant/Role> · <Platform> · <Viewport>
TokenValues
ScreenHuman-readable screen name, e.g. "Members — Detail (Adult)"
Variant/RoleOmit for all-roles screens. Add "(Admin)", "(Minister)", "(Kid)", "(Self)", etc. when role or subject differs
Platform"Web", "iPhone App", "iPad App", "Android App"
Viewport"Desktop", "Tablet", "Phone" (web only; native apps omit viewport)

Examples:

  • Members — Detail (Adult) · Web · Phone
  • Members — Manage (Admin) · Web · Desktop
  • Profile — Edit · Web · Tablet
  • Members — Detail (Adult) · iPhone App
  • Admin — Approval Queue · Web · Desktop

Re-register all existing 48 cards under this scheme.

Design-system screens folder convention &ZeroWidthSpace;

Mockup HTML files live under packages/ui/design-system/screens/ in platform-specific subfolders:

SubfolderContents
screens/web/Responsive HTML mockups for the web browser client (all 3 viewports: Desktop, Tablet, Phone)
screens/mobile/Native HTML mockups for iPhone + Android app — reserved; placeholder files only until the native app phases begin
screens/tablet/Native HTML mockups for iPad app — reserved; placeholder files only until the native app phase begins
components/Shared component snippet cards (tab bar, buttons, empty state, etc.) — used across all platforms

All "Mockup file" references in this ADR and in docs/internal/design/platform-ui-view-inventory.md use the screens/web/<file>.html path for the current platform-foundation (web) phase.

Feature ADR view convention &ZeroWidthSpace;

Every feature ADR (0010–0020 and any future feature ADR) must include a "Views" section. For features not yet built the section reads:

markdown
## Views

**Status: TBA** — view set will be defined when this feature enters active development.
The view inventory ADR (0033) and feature's ADO epic/feature items will be updated at that time.

When the feature is built: fill in the view table (screen name, route, role, mockup file, ADO story).

Canonical view inventory — platform foundation (web) &ZeroWidthSpace;

Scope: platform foundation only. Feature portals (calendar, listen, groups, marketplace, homeschool, etc.) are out of scope until their delivery phase.

Auth & onboarding &ZeroWidthSpace;

IDViewRouteRolesMockup fileADO
A1Landing / public home/publicscreens/web/landing.htmlstory under AB#3090
A2Sign-in/sign-inpublicscreens/web/sign-in.html (exists)story under AB#3085
A3Request access (sign-up step 1)/sign-uppublicscreens/web/sign-up-request.htmlstory under AB#3086
A4Create account (sign-up step 2)/sign-up/accountpublicscreens/web/sign-up-account.htmlstory under AB#3086
A5Account pending approval/pendingpublicscreens/web/account-pending.htmlstory under AB#3086
A6Sign-out confirmation(modal/flow)allscreens/web/sign-out.htmlstory under AB#3090

Shell & home &ZeroWidthSpace;

IDViewRouteRolesMockup fileADO
S1App shell / navigation chrome—allcomponents/tab-bar.html (exists)story under AB#3090
S2Home (feature-icon grid, registry-gated)/app/homeallscreens/web/home.html (rework)story under AB#3692
S3Messages inbox shell/app/messagesallscreens/web/messages.htmlstory under AB#3090

Profile / Me &ZeroWidthSpace;

IDViewRouteRolesMockup fileADO
P1Profile (Me) — own profile hub/app/profileselfscreens/web/profile.html (cleanup)story under AB#3086
P2Edit own profile/app/profile/editselfscreens/web/profile-edit.htmlstory under AB#3086
P3Privacy & visibility/app/profile/privacyselfscreens/web/profile-privacy.htmlstory under AB#3086
P4Notification preferences/app/profile/notificationsselfscreens/web/profile-notifications.htmlstory under AB#3086
P5About & Help/app/aboutallscreens/web/about-help.htmlstory under AB#3086
P6Portal links (RBAC-gated; admin/minister only)profile + sidebaradmin, ministry_leaderrendered in P1 + S1 (no separate mockup)task under P1 + S1 stories

Family &ZeroWidthSpace;

IDViewRouteRolesMockup fileADO
F1Family management/app/familyfamily headscreens/web/family.html (exists)story under AB#3086
F2Add spouse/app/family/add-spousefamily headscreens/web/family-add-spouse.html (exists)story under AB#3086
F3Add child/app/family/add-childfamily headscreens/web/family-add-child.htmlstory under AB#3086

Members &ZeroWidthSpace;

IDViewRouteRolesMockup fileADO
M1Members directory (last-name sort, family-grouped, search)/app/membersallscreens/web/members.html (rework)story under members feature
M2Member detail — adult/app/members/:idallscreens/web/member-detail-adult.htmlstory = AB#3693 (re-scoped)
M3Member detail — kid (birthday only)/app/members/:id (kid account)allscreens/web/member-detail-kid.htmltask under AB#3693
M4Member manage — admin/app/members/:id/manageadminscreens/web/member-manage-admin.htmltask under AB#3693
M5Member manage — minister/app/members/:id/manageministry_leaderscreens/web/member-manage-minister.htmltask under AB#3693
M6Export members to Excel/CSV(action)adminROADMAP — no mockup nowroadmap story, Priority 4

Admin portal &ZeroWidthSpace;

IDViewRouteRolesMockup fileADO
AD1Admin portal hub/app/adminadminscreens/web/admin.html (exists)story under AB#3166
AD2Approval queue/app/admin/approvalsadminscreens/web/admin-approval-queue.html (exists)story under AB#3166
AD3Role assignment/app/admin/rolesadminscreens/web/admin-role-assignment.html (exists)story under AB#3166
AD4Content oversight/app/admin/contentadminscreens/web/admin-content-oversight.html (exists)story under AB#3166
AD5Audit log/app/admin/audit-logadminscreens/web/admin-audit-log.html (exists)story under AB#3166

Minister portal &ZeroWidthSpace;

IDViewRouteRolesMockup fileADO
MN1Minister portal hub/app/ministerministry_leaderscreens/web/minister-portal.html (exists)story under AB#3166
MN2Minister oversight (pastoral approvals/care)/app/minister/oversightministry_leaderscreens/web/minister-oversight.htmlstory under AB#3166

System / utility &ZeroWidthSpace;

IDViewRouteRolesMockup fileADO
U1Not found / disabled-route (404)*allscreens/web/system-404.htmlstory under new feature
U2Access denied (403)—allscreens/web/system-403.htmlstory under new feature
U3Empty-state pattern—allcomponents/empty-state.htmltask under AB#3237
U4Loading / skeleton pattern—allcomponents/loading.htmltask under AB#3237
U5Error boundary ("something went wrong")—allscreens/web/system-error.htmlstory under new feature

Totals (web): ~35 views. ~100 DesignSync cards (≈33 screen mockups × 3 viewports, plus a few component cards). Existing mockups on disk: 16 (several reworked; see §Consequences).

Native app views (iPhone, iPad, Android) &ZeroWidthSpace;

Native platforms reuse the same view list (A1–U5) with identical functionality requirements. They are designed and built in separate passes — not in the platform-foundation phase:

  • iPhone app: separate mockup pass after web foundation is done (ADR 0009, Epic AB#3077).
  • iPad app: companion to iPhone, same Epic.
  • Android app: separate delivery phase (ADR 0014, Epic AB#3139).

Each native-app view gets its own ADO User Story and DesignSync cards with the convention: <Screen> · iPhone App, <Screen> · iPad App, <Screen> · Android App (no viewport suffix — native apps are single-viewport by platform).

Alternatives considered &ZeroWidthSpace;

OptionProsConsWhy not chosen
Full view inventory + one story per view (chosen)Every view is accounted for, documented, and trackable; nothing shipped without four artifactsUpfront cataloging effort— chosen
Ad-hoc screen creation (status quo)Start immediatelyInevitable gaps; no consistent naming; ADO coverage unverifiableCreated inconsistencies that triggered this ADR; rejected
One story per feature area (not per view)Fewer storiesCannot track individual view completion; acceptance criteria are too coarse to verifyGranularity too low; rejected
Separate ADR per feature's viewsFull per-feature decision detailProliferates ADRs; platform-foundation views have no natural feature homeConvention "Views: TBA" in each feature ADR achieves the same without extra ADRs; rejected

Consequences &ZeroWidthSpace;

Positive &ZeroWidthSpace;

  • Every platform-foundation view has a mockup, DesignSync card, ADO story, and route — nothing is shipped without all four artifacts.
  • The naming convention makes the Claude Design project navigable for the owner across platforms and viewports.
  • Feature ADRs gain a "Views" section as a living record of that feature's screen set.
  • The three responsive ambiguities from ADR 0031 are resolved; AppLayout.tsx and all mockups can be locked to these values.

Negative / trade-offs &ZeroWidthSpace;

  • ≈35 ADO stories to create (beyond those already existing); significant one-time ADO authoring effort required before the build phase.
  • Some existing mockups require rework (member-detail screens, profile cleanup, home rework).
  • Re-registration of ~48 existing DesignSync cards under the new naming convention.

Mockup rework required by this ADR and ADR 0032 &ZeroWidthSpace;

Current fileActionReason
screens/web/member-detail-member-view.htmlRename → screens/web/member-detail-adult.html; align fields to corrected modelADR 0032 revision
screens/web/member-detail-minister-view.htmlRewrite — same detail + Manage button (not inline pastoral fields)ADR 0032 revision
screens/web/member-detail-admin-view.htmlRewrite — same detail + Manage button (not inline edit)ADR 0032 revision
screens/web/profile.htmlRemove "Bible Study" and "Homeschool Co-op" feature tagsPlatform-only scope
screens/web/home.htmlRework to feature-icon grid (registry-driven); remove hardcoded event/content listADR 0030
screens/web/members.htmlVerify last-name alpha order + family grouping are explicitM1

New files to create under screens/web/: landing.html, sign-up-request.html, sign-up-account.html, account-pending.html, sign-out.html, messages.html, profile-edit.html, profile-privacy.html, profile-notifications.html, about-help.html, family-add-child.html, member-detail-kid.html, member-manage-admin.html, member-manage-minister.html, minister-oversight.html, system-404.html, system-403.html, system-error.html. Also needed under components/: empty-state.html, loading.html.

References &ZeroWidthSpace;

Heritage Community Hub — Internal. Access restricted via Cloudflare Access + Entra ID.

Heritage Virginia · Owner: Kristopher Turner