ActsControl room

Send a tester a link — it opens on their phone like an app. Everything they do shows up here and grows the content.

Build doc · DESIGN.md

Design + build spec

Brand, tokens, type scale, button system — the design contract.

ACTS — Design + Build spec

The one source of truth. Build to THIS, not from scratch. Ground everything in Bryan's Phase 1 v2 deck (docs/…Phase 1- V2 Bryan.pdf) and Steve's notes.

0. FIGMA IS THE SOURCE OF TRUTH (Bryan, 2026-08-12)

The Figma files are mostly right — when a screen differs from Figma, match Figma (token-mapped per skin, never raw hex). Rules of engagement:

  • Files: "acts playground" (design frames) + the Make files ("Prayer Request Designs" v64+, "Pray Screen Variations", "Prayer Help Screen"). Newest iteration wins; the Make file's live version is newest of all.
  • Known-good frames (node ids in acts playground): Ask wizard = "Prayer Request Designs" 18:1280 (+ Make v64 Classic variant). Pull via the Figma desktop MCP (get_design_context on design frames; Make files render live only — screenshot the desktop app).
  • How Bryan flags the right frame: EITHER right-click the frame → Copy link (the node-id pins it exactly), OR prefix the frame name with "✅", OR keep current-truth frames on one page named "CURRENT". Any of these beats describing the design in words.
  • CTA spec (v64): massive 40px emoji flush left w/ soft drop shadow, no inner circles, title + reward stacked LEFT-justified after the icon, full-width, asymmetric padding. .btn-big implements this — never fork it.
  • Old-style screens are bugs, not variants. When touching a screen, check it against its Figma frame and bring it forward.

1. Design rules (non-negotiable)

Brand. Cormorant Garamond (display, italic for feeling) + Instrument Sans (UI/body). Signature #ec612b vermillion. Four ring/layer colors: Me #ec612b · Another #e08a52 · Parish #4e8f5f · World #6d95c4. Warm gradient canvas (cream→terracotta), floating white cards with soft shadow, vermillion gradient Pray button. Photography of hands/people ("every image shows the helpers").

8pt grid (Apple). Spacing = multiples of 8, 4pt sub-step only. Tailwind p-2/p-4/p-6/p-8, gap-2/gap-4, mt-2/mt-4/mt-6. Never mt-1.5, p-5, or arbitrary -[..px] spacing. Touch targets ≥ 44pt.

Type scale (named, never arbitrary). largeTitle 34 · title 28 · headline 20 · body 17 · subhead 15 · caption 13. Classes: .t-hero .t-title .t-headline .t-body .t-sub .t-caption .eyebrow. Body line-height ~1.5.

One token source. app/globals.css @theme + [data-skin]. No hardcoded hex in components.

Pills, not dropdowns. For small option sets, use pill selectors (components/PillSelect / the .pill class), not <select>. Applies across the app forms (ask, offer, upload).

Selection + CTA consolidation (Bryan, 2026-08-11).

  • Selected pill = black (ink) everywhere — no per-section accent on selection.
  • CTA buttons = the selected skin's brand color (--color-brand / --pray-gradient), one CTA color per design system. Section accents survive only in small identity cues (marks, eyebrows, counts).
  • View switcher = the deck's icon segmented control (grid · play · map pill, active = filled ink circle) on Home, Immersive, and Map.
  • Pills are multi-select where several can be true (e.g. relationships — a mother AND a father). First code fills the FK column; the full list is kept in the activity log.

2. Screens — "the meat" (from the deck, 13 screens)

Native app (/app/*), skinnable. Home has three views; a persistent bottom nav Give · Receive · Donate.

  1. Home — Cards — one feed mixing open requests + answered-prayer stories. Card: photo · ACT TYPE eyebrow · title · "N people prayed" · I'll pray. Top switch: Cards / Immersive / Map.
  2. Home — Immersive — full-screen, one act fills the display, story overlaid, right-rail actions (pray count · Share · Next), big I'll pray, swipe up for next. This IS the 18–25 "night/immersive" skin.
  3. Home — Map — nearby acts on a map (selected pin big/bold), filters Nearby / Completed / Requests, list with distances.
  4. Act Detail — Open — hero photo · "PRAYER · ON BEHALF" · title · "Asked by Linda · for her mom" · "12 people have prayed" · I'll pray + Share + Invite.
  5. Act Detail — Geographic — hero · "CANDLE · AT A PLACE" · map+pin · "1.2 mi away" + Directions · "4 people have visited" · I'll light a candle + Share + Invite.
  6. Request — "I Need an Act" — dominant PRAY, then layer (me/another/parish/world), ask (Prayer/Candle/Visit), mode (once/group), "I have a different act ›".
  7. Completion loop — four candidates, testable side-by-side: SMS reply · two-tap · trust · timer (5:00 auto-complete). Trust is the default/lead (agree to pray, no tracking — fits the no-surveillance ethos). Completion creates the story.
  8. Story Card — "Susie prayed for Linda's mom", photo, "12 prayed · acts.app/a/linda", Share to Facebook + Copy link. Every completed act makes one.
  9. Helper Offer flow — "I'm headed to [place]; who wants [act] while I'm there?"
  10. Parish room — "12 praying right now", avatar stack, Join, "Fr. Miguel asked the parish to pray at 8:00 PM".
  11. Widget — daily "Pray at noon" moment + day-streak ring + Near You.
  12. Guest → member ladder, Witness / signup, Two sides + moderator.
  13. Donate + sponsor-donor (pledge per act / per pilgrimage day).

3. Steve's required features (his notes — must be present)

Gap list Steve flagged (Phase 1 missing vs. pitch):

  • Place-anchored acts (candle at a named church, grave visit, shrine).
  • Helper offer flow (two-sided, not just seeker requests).
  • Proof of act — photo confirmation + shareable saint/prayer cards.
  • Explicit mission catalog (Rosary, novena, candle, adoration, pilgrimage) — not one generic Pray.
  • Gamification economy — points ("Heaven/Mission Credits"), effort-scaled rewards, category badges (Pilgrim, Hospital Intercessor, …), levels.
  • Donation micro-gifts + sponsor-donor / walk-a-thon pledges.
  • Geo-targeted tags — hospitals, airports, test centers, prisons, stadiums.

4. Skins (native app only, not admin hub)

acts (default brand) · modern · night(=immersive 18–25). lib/skins.ts + [data-skin] blocks. Hub picks which skin tester links open in.

5. Build order (proposed)

  1. Lock the grid/type system (globals type scale) — foundation.
  2. Home — Cards (the center) + bottom Give·Receive·Donate nav.
  3. Act Detail — Open + Geographic.
  4. Story Card + completion (start with two-tap + trust).
  5. Home — Immersive (night skin) + Map.
  6. Request flow polish · Parish room · Offer flow · Donate · gamification surfacing.

6. Clickables — four levels (Bryan, 2026-09-05 design review)

Every tappable thing is one of these, and looks like it. Native tokens in expo/lib/theme.ts (BTN, BTN_TEXT, LINK_TEXT, TAB_UNDERLINE).

| Level | Job | Looks like | Examples | |---|---|---|---| | L1 Primary | do the act | filled button — vermillion (ask side) or green (give side); one per screen | Amen · Yes — give $5 · Post my ask · I'm here — Check in | | L2 Secondary | the alternative, the next step | outlined button · soft-tinted pill · bold act-colored text in a gray bar | No, not today · Add intention · Pray • Go there • Comment · the card's icon row | | L3 Tertiary | change / settings / elsewhere | quiet Marian-blue text + chevron; never boxed, never filled | Change location › · Change place of worship › · profile's place line | | L4 Nav state | where am I | ink text, 2-pt vermillion underline when selected, muted otherwise | Home/Ask/Offer/Profile · All / Near / Congregation |

Rules: the vermillion underline is the only vermillion line — section rules are hairlines in line. A row that opens something carries a chevron. Points ride on L1/L2 labels only ("· +10 pts"), never on L3 or L4.

7 · Brutalist pass (native, 2026-09-05 — Bryan: "love it")

The mark is two things. The v1 logo (praying hands + expression lines + heart) splits into its halves: hands with the lines = the ASK, the heart = the GIVE. The masthead carries the whole mark, ink with a vermillion heart (BRAND = "brut", components/BrandMark.tsx).

The two doors ((tabs)/index.tsx): stacked *mark · tag · body · arrow*, same height. ASK = ink block, white hands-with-lines, white text. GIVE = white block, 2-pt ink line, red heart (T.red), ink text. The arrow sits beside the body copy, never in the title row. Open ("What does this mean?"): the doors go solid act colour with large cream titles, cream copy, white prompt rows, an × close per door; it folds on leaving and on any prompt.

Icons v3 (design/icons-v3/, components/icons/v3.ts, ICON_SET = "v3"): drawn in the v1 hands' own style — rounded chunky silhouettes, one ink. All icons black; the candle is just the flame, orange; "prayed" hands (rows, count lockups, explainer prompts) are the success green T.prayed. Tab bar: house · open palm (Ask) · hands-with-heart (Offer) · person. v1/v2 are tagged (icons-v1, icons-v2) and copied under design/icons-v*.

Buttons are square-ish — T.radiusBtn = 8 everywhere (Pray/Comment, prompts, ✓ Prayed, Add intention, parish, donate). No pills.

Tooling: scripts/svg.py + /svg skill — every SVG that arrives is rendered, split, and generated from; a picture of icons is traced. Logo explorations live in app/logo-lab.tsx (dev only).