Faith Groups · App redesign — Developer handoff

1. Design tokens

All tokens are CSS custom properties in the :root block of index.html. Use them by name; never hard-code values.

Brand colors

Same palette as the new faithgroups.app landing page. Navy = text/headers, teal = primary action and brand accent.

Semantic colors

ok = success/reported, warn = pending/attention (never alone: always paired with text or icon), danger = errors.

Typography

Inter 400/500/600/700/800. Body 15.5px/1.45, large titles 30px/800 with −0.025em tracking, display numbers 44px/800.

Spacing (4px base)

Use the scale only; screen side padding is --pad (20px).

Radii

Cards 20px, inputs/rows 14px, buttons and chips fully round, bottom sheet 28px top corners.

Shadows

Soft, navy-tinted. Teal glow only on the primary button.

Sizing

Minimum tap target 48px. Primary button 52px. Tab bar 64px + safe area.

Motion

Durations and easings used by every animation (see Animation specs).

Desktop admin layout (>=1024px; --d-side-w and --d-pad grow at >=1280px)

Sidebar 232px (256px from 1280), top bar 64px, content padding 24px (32px from 1280) capped at 1320px, report drawer 480px, modal 540px. Colors, type, radii and shadows are the same tokens as mobile.

Safe areas

Typography scale

2. Components

3. Animation specs

Durations: press 120ms · fast 180ms · base 280ms · screen 380ms · slow 560ms. Easings: --ease-ios (.32,.72,0,1), --ease-out (.22,1,.36,1), --ease-spring (.34,1.56,.64,1). All motion respects prefers-reduced-motion.

4. Screens

5. Desktop admin (≥ 1024px)

At ≥ 1024px the Administración role renders as a desktop dashboard instead of the phone frame. Leader role and any width below 1024px keep the phone experience. A “Vista móvil” button (top bar) shows the phone version of the admin; “Vista de escritorio” (side panel) returns. “Cambiar vista” opens the role switcher; picking a leader switches to the phone UI. Everything stays labeled DEMO · datos ficticios.

Layout, regions and measurements

Breakpoints

Mode switching (phone ↔ desktop)

Desktop screens

Desktop screenshots

6. Screenshots

Mobile 390×844 captured from the automated walkthrough. Desktop admin captures are in section 5 (screenshots/dd-*.png); screenshots/d-*.png show the phone frame on desktop. Report-flow video (mp4).

7. ES / EN copy (key strings)

All copy lives inline as T('español','English'). Dates: fmtDate / weekLabel.

8. Accessibility notes

• Touch targets: every control is ≥ 42px; primary controls, tabs, steppers and keypad keys are 48–64px.
• Contrast: navy #05223a on #fafcfd ≈ 15:1; teal #008d9b is used for large/bold text and fills with white text (≈ 4:1 — keep ≥ 15.5px/600 on teal fills); muted #546675 on white ≈ 6:1. Verify final brand colors with your tool before release.
• State is never color-only: report status uses text + icon badges (Reportó / Pendiente); errors have text under the field; chips show a check icon when on.
• Semantics: chips use aria-pressed; switches use role=switch + aria-checked; wizard progress is role=progressbar with aria-valuenow; sheets are role=dialog aria-modal; toasts are a role=status live region; tab bar buttons set aria-current=page; icon-only buttons have aria-label.
• Keyboard: all controls are native buttons/inputs; map pins are focusable and respond to Enter/Space; Esc closes sheets; visible 3px teal focus ring.
• Desktop admin: landmarks are aside (nav with aria-label and aria-current=page), header (top bar) and main; tables use th scope=col and a visually hidden “Acciones/Actions” header; clickable report rows are focusable (role=button, Enter/Space opens the drawer); the drawer and the modal are role=dialog aria-modal, move focus in on open, trap Tab, close with Esc and return focus to the trigger; search/filter results announce counts via aria-live; the week selector is a labeled group with disabled ends.
• Reduced motion: prefers-reduced-motion: reduce removes transitions/animations (CSS) and JS transitions/counters jump to their end state; the app stays fully usable.
• Language: <html lang> follows the toggle (es/en); inputs use inputmode (numeric PIN/code, decimal offering).
• Safe areas: env(safe-area-inset-*) is applied to the demo bar, tab bar and footers for notched phones. Use viewport-fit=cover.
• To do in production: trap focus inside sheets and return focus to the trigger on close; move focus to the screen heading after each route change and announce it; add screen-reader text for the chart (table alternative); add real error-recovery/offline states.

9. Mapping to the existing demo

Source: faith-layer-groups-demo (index.html, pilot.js, empower-*.js, admin-management.js, cloud.js).

10. Data contract

Report record: id, leaderId, group, leader, weekId (Monday ISO date), date, total, disciples, guests, newGuests, children, offering, lesson, start, end, people[{name, cat: disciple|guest|new, teacher}], closing{vision, mission, announcements, notes}, planning{welcome, worship, farewell, childcare, snacks}, growth{absent[], calls, sunday, inviters, invitees, prayer, fastingCount, fastingNames}

11. Notes, assumptions, open questions

• Desktop admin is a second layout, not a second app: it reads the same data, helpers, i18n and sheet definitions as the phone UI. In production use one responsive admin app (CSS grid breakpoint at 1024px) and keep the phone UI for leaders. Desktop DOM ids are prefixed d- only because the prototype keeps the hidden phone DOM alive.
• Prototype-only (do not ship): DEMO bar and role sheet, fixed date (2026-11-10, week 9–15 nov), seeded data, “Llenar ejemplo”, stylized map, simulated WhatsApp/clipboard/PIN (123456)/Face ID, attendance chart data, localStorage persistence.
• Map: the existing app uses OpenStreetMap tiles. Keep a real map in production (MapLibre/Leaflet/OSM) with these pins, zoom controls and the distance list; the illustration only shows the layout and animation. Keep locations private to administrators.
• Week definition: weeks run Monday–Sunday; weekId is the Monday. Attendance total counts disciples + guests + new guests + children (same as the current app).
• WhatsApp: real sharing should use the Web Share API / https://wa.me/?text= with the same invitation/reminder text; the prototype only previews the message.
• Open questions for the product owner: offline/queued report submission; whether leaders can edit a submitted report; whether reminders should be automatic; push notifications for new notices.
• Brand: logo/mark and colors come from the new faithgroups.app landing page; the church (tenant) name is fictional here — in production it should come from tenant settings.

12. Weekly-report form editor (admin)

Where: desktop #admin/form (sidebar → Formulario del reporte, three panes: palette · canvas · properties/preview/versions). Phone: Administración → Formulario del reporte (#admin/form at <1024px): list with ↑/↓ buttons, bottom-sheet editor, Vista previa tab, sticky Guardar borrador / Publicar.

WPAC source (honest note). The two Drive docs (1eKSdLeJ7aC7r6NZml9T_IR7PoA42MbDVCiO4hufzNiU, 1UWtL8XjAs4kGG4Y6CqksTgyXSivU2M_sp4SPASIpCjs) list only the sections of the WPAC report (lugar de reunión; datos de la reunión incl. asistencia, visitas, niños y ofrenda; cierre; planeación; motivación y crecimiento; visión y misión). Individual WPAC questions were not found in those docs. The editor therefore shows the sections from WPAC's docs and the questions from the prototype's 5-step wizard, labeled as the prototype base form — not as WPAC's own wording.

• Drag & drop: HTML5 DnD (palette → canvas, row → row) with FLIP animation; keyboard/phone: ↑/↓ buttons (fe-up, fe-down). Both write the same fields[] order.
• Autosave: the draft autosaves (debounced) with the cloud pill (Guardando… / Borrador guardado en la nube / Sin conexión · Pendiente de sincronizar). Publicar is a separate, explicit action with a confirmation dialog.
• Storage in the prototype: localStorage['fg-proto-forms-v1'] (RFORM). The leader's real 5-step wizard is still hard-coded; the published form drives the preview only (see caveats). Production: the wizard must render from form_version.fields.

Tests: python3 _tests/editor.py (add, drag, reorder, bilingual edit, hide, autosave, publish → v3, past report = v2, phone ↑/↓ and sheet).

13. Church identity (logo, accent color, contrast)

Where: desktop #admin/identity (sidebar → Identidad de la iglesia); phone Administración → Identidad; also an optional step in onboarding (Omitir por ahora).

• Color extraction (client-side): the logo is drawn to a 96-px canvas; transparent/near-white pixels are dropped; k-means (k=4, 8 iterations, deterministic seeding) returns 4–6 swatches (dominant colors + tonal variants) plus the default swatch.
• Contrast rule: the accent must reach 4.5:1 against white (WCAG AA for text). Below that, the UI shows the exact ratio and Ajustar automáticamente (darkens in small steps until ≥ 4.5:1). The official default teal measures 3.97:1 and is exempt (shown as meeting the 3:1 UI-component threshold) — flagged for Victor to decide whether to darken it for text.
• Logo placements: login screen, app header (leader/admin), desktop sidebar, onboarding preview, printed/PDF reports (header), invitation screens, giving QR screen.
• WPAC demo: WPAC uses the default colors plus the WPAC logo. Logo source: Google Drive file Logo Clear.png (id 1c9fZ318GqPQKB6Ft6PAmkfG0koM42O-d), downloaded and visually verified (navy “WP” + orange “AC” wordmark on a transparent background). The church switcher toggles Iglesia Esperanza (fictional, untouched) ↔ WPAC.

14. Plans, onboarding and invitations

Routes: #plans (public plans page) · #onboarding → /verify → /plan → /giving → /identity → /preview · #join, #join/<CODE>, #join/code, #join/expired, #join/request · admin #admin/setup (Primeros pasos).

Feature bullets under each plan are illustrative placeholders for Victor to confirm. No payment is taken and there are no card fields. Every plan lists: Copias de seguridad automáticas y cifradas (automatic, encrypted backups included).

church        { id, name, city, tz, lang, logo_url, accent_hex, uses_default_theme, plan_id, giving{...} }
admin_user    { id, church_id, name, email, role: owner|admin, email_verified_at }
plan          { id: church|multicampus|network, price_month, quote: bool }
invitation    { id, church_id, code /* 6 chars, A-Z0-9 no I/O/0/1 */, single_use: true,
                expires_at /* created + 48 h */, group_id, leader_name, channel, status: pending|accepted|expired|revoked, leader_id? }
invitation_request { id, church_id, invitation_id, name, contact, group_name, created_at }   // admin notice

• Flow: registration form → verify e-mail (demo code button) → plan → offerings (optional) → identity (optional, Omitir por ahora) → preview → Entrar a mi panel; stepper on every step.
• Setup checklist: (1) review the form → opens the editor, (2) create first group, (3) invite first leader (share menu). Invitation list shows Vence en 46 h / Aceptada / Venció with Renovar.
• Join my church: admin shares a link (WhatsApp or SMS) or a 6-char code; leader sees church name + logo + assigned group before Aceptar invitación; the code is single-use. Expired: screen Esta invitación venció → Solicitar nueva invitación → request lands in the admin's Primeros pasos with Enviar nueva invitación.

Tests: python3 _tests/onboard.py (plans, no card fields, stepper, identity, Path A, Path B, expired, request).

15. Cloud save states, offline queue and idempotent submit

• Autosave: every keystroke writes a local copy (fg-proto-local-v1); a debounced (900 ms) draft.save goes to the server. A lost connection never loses typed data.
• Submit: POST /reports with header Idempotency-Key: idem-<leader>-<week>-<random>. The key is generated once per submission series and reused on every retry; the server stores key → report and returns the stored receipt (duplicate: true) on repeats → exactly one report.
• Offline at submit: state offline, banner + Reintentar, no celebration, report is not in the admin list. On online the app retries automatically with the same key.
• Mock server (prototype): NET.call(type, payload) with 350–900 ms latency, navigator.onLine + a demo toggle (En línea / Sin conexión button), fg-proto-server-v1 as the “server database”.
• Backups: automatic, encrypted, included in every plan (stated on the plans page, settings and checklist). Real implementation = managed DB with PITR + encryption at rest; not simulated beyond copy.
• Admin form editor shows the same pill (saving/saved/offline); Publicar is separate.

Test: python3 _tests/cloud.py [--shots] — WPAC leader Daniel Torres; context.set_offline(True) exactly at Submit → offline/pending with data preserved → set_offline(False) → submit → Reporte enviado; asserts exactly one report and a deduplicated second report.submit with the same key.

16. Native iPhone app + web panel (Path A / Path B)

Web panel: select a group → Compartir invitación / Share invitation → Copiar enlace, Copiar código, Correo, Mensaje de texto, WhatsApp (one option), Más apps (Web Share API when available). iPhone app (iOS-native look, Inter, navy/teal, iOS status bar): showcase at #ios/<scene> (full-bleed 390×844; framed on desktop) and the synced journey at #journey (web panel left, iPhone right, 17 steps; autoplay).

• Universal links / associated domains: host https://<app-domain>/.well-known/apple-app-site-association (no redirect, application/json): {"applinks":{"details":[{"appIDs":["<TEAMID>.com.faithlayer.faithgroups"],"components":[{"/":"/join/"},{"/":"/give/","exclude":true}]}]}}. Add the entitlement com.apple.developer.associated-domains = applinks:<app-domain>. Handle in application(_:continue:) / SwiftUI .onOpenURL → route /join/<CODE>.
• Deferred deep link: iOS cannot hand the link through an App Store install. Do not rely on the clipboard or fingerprinting; the web fallback shows the 6-char code and the app asks for it on first launch (Unirme con un código). A first-party deferred-link service (Branch/AppsFlyer) is optional later.
• Invitation API: POST /churches/:id/invitations {group_id, leader_name, channel} → {code, link, expires_at}; GET /invitations/:code (public: church name, logo, group, status — no personal data); POST /invitations/:code/accept {name, device_id} (single use, 410 when expired, 409 when used); POST /invitations/:code/request-new {name, contact} → notifies admins.
• Push (later): APNs for aviso and reporte pendiente reminders; token registered on accept.
• Prototype caveat: the iPhone scenes are web-rendered; the App Store page is a labeled mockup; the SMS/e-mail/WhatsApp buttons show a simulated preview (nothing is sent).

Tests: onboard.py covers Path A/B/expired in the real UI; cloud.py covers the offline report; the #ios and #journey scenes are exercised by shots_ext.py (no console errors).

17. Ofrendas y diezmos / Offerings & tithes (optional)

Where: onboarding step Ofrendas y diezmos (optional) and later Configuración → Ofrendas y diezmos (#admin/giving; phone: Administración → Ofrendas y diezmos). Leader: Mi grupo → Compartir ofrendas y diezmos. Visitor pages: #give/<church>/<group> (Stripe-style, TEST MODE) and #give-ext/<church>/<group> (example external provider).

Simulation boundaries: no real Stripe keys, no real charges. Everything Stripe-related is a clearly-labeled simulated TEST MODE (banner MODO DE PRUEBA / TEST MODE, test-card hint 4242 4242 4242 4242). QR codes are real and scannable (generated client-side with the inline MIT library qrcode-generator 2.0.4; no CDN) and are verified by decoding in the tests. Stripe demo URL: https://faithgroups-app-prototype.vercel.app/#give/wpac/<celula>.

church.giving   { mode: unset|stripe|external|later, stripe: not_connected|connecting|pending|enabled,
                  ext: { url, tested, saved, groupUrls: { <group_slug>: url } } }
payment         { id, church_id, group, group_slug, week_id, amount, category: offering|tithe,
                  status: succeeded, session_id /* idempotency */, created_at }

Real implementation (not built):

• Onboarding: Stripe Connect Standard (church owns the Stripe account; fewer compliance duties for us) or Express. POST /v1/accounts → POST /v1/account_links {type: account_onboarding} → redirect → return URL. Store stripe_account_id on the church.
• Enabled state: webhook account.updated → when charges_enabled && details_submitted set giving.stripe = enabled (pending until then).
• Per-group link: create a Payment Link or a Checkout Session (mode=payment, payment_intent_data.on_behalf_of/direct charge with Stripe-Account header) per group with metadata: { church_id, group_id, category }; the visitor chooses Ofrenda/Diezmo (two prices or a custom amount + category metadata). QR encodes the Faith Groups short URL /give/<church>/<group> that creates the Session on demand.
• Recording payments: webhooks checkout.session.completed and payment_intent.succeeded (verify signature; handle retries) → insert payment keyed by checkout_session.id/payment_intent.id (unique index = idempotency) → add to the group's weekly report for the week of created. Refunds (charge.refunded) subtract.
• Reporting: weekly report shows Efectivo (manual entry) and En línea (Stripe) (sum of succeeded payments for that group + week) separately, plus the total; the admin summary adds both.
• External link mode: only store the URL and optional per-group overrides; no webhooks. An integration (e.g., the provider's API/webhook) would be needed to reflect gifts automatically.

Test: python3 _tests/give.py (Stripe states, TEST MODE banner, payments recorded once, cash vs online report rows, external validation/test/save, QR decoded with OpenCV for one WPAC célula in both modes, leader share sheet).

18. Routes, tests, and caveats for sections 12–17

• Plan feature lists are placeholders for Victor to confirm; prices are $39 / $99 / quote as requested.
• The WPAC individual questions were not found in the Drive docs; the question set is the prototype's wizard, labeled as such.
• The leader's 5-step wizard remains hard-coded; the published form drives the preview only (production wizard must render from form_version.fields).
• Stripe, the App Store page, SMS/e-mail/WhatsApp sending, e-mail verification and the server are all simulated; the QR codes, the color extraction, contrast math, offline queue and idempotency logic are real code.
• The Faith Groups default teal (#008d9b) is 3.97:1 on white: fine for large text and UI components, below 4.5:1 for small text — decide whether to darken the default.

19. Legal: Terms of Use, Privacy Policy and acceptance record (draft)

Status: drafts pending legal review, version 2026-11-11-draft1. Pages: privacidad.html and terminos.html (bilingual ES/EN, English default, ?lang=es|en, toggle remembered in localStorage key fg-lang), served next to the app and on the landing preview. noindex while in draft.

acceptance = { termsVersion, privacyVersion, acceptedAt /* ISO-8601 */, adminEmail, churchId, source: 'registration' | 'settings' }
// prototype: ORG.consent[churchId] (latest) + ORG.consentLog[] (history) in localStorage 'fg-proto-org-v1'

Production requirement. Store acceptances server-side in an append-only table terms_acceptance { id, church_id, admin_user_id, terms_version, privacy_version, accepted_at (server time, UTC), source, ip?, user_agent? } (IP and user agent are optional, decision pending). Never trust the client timestamp. On sign-in, compare the latest accepted versions with the current ones and block the admin dashboard with an Accept new version screen until accepted. Keep every version's text (immutable, addressable by version id) so an acceptance can be reproduced. Leaders do not accept; the church does through its administrator.

Permissions the policy describes (verify on the server):

• In the prototype these limits live in the UI over localStorage data; a leader could read other data from the browser. The API must enforce them per request (list = admin all, leader own; meeting_location writes by leader limited to own group; list_meeting_locations admin only).
• All admins see everything (no per-admin scopes); Permisos por iglesia for the network plan is future.
• Report free-text fields (notes, prayer, fasting names, absent names) can hold sensitive data; children are captured as a count only.
• Fonts are loaded from Google Fonts on the landing and the app (visitor IP goes to Google): self-host Inter before launch if the policy should say no third-party requests. A production map (OpenStreetMap tiles) also discloses the viewer's IP.
• Tests: python3 _tests/legal.py [--shots] (checkbox gating, stored record, Configuración, links, ES/EN, 1440 + 390). Screenshots: screenshots/lg-*.png.