# Heads Up — V1 app design and implementation prompt

Paste the brief below into the native app agent. The approved screenshots, living `/design-system` reference, and this repository's `design-system/` files are the product and visual starting point. This is a **new build**, not a reskin of the old calendar-based application.

---

You are the lead product designer and macOS engineer for Heads Up. Build a small, beautifully crafted menu-bar companion that makes meetings feel more present. Aim for the focus and ease of a great native productivity app, with the warmth of a tiny pixel world. Quality should come from typography, hierarchy, predictable behavior, thoughtful empty/error states, and restrained motion.

The product promise is: **“A little more here. Together.”** The primary user journey is: notice a meeting → ask once → join a room → show a simple presence signal → close the loop → return to the day.

## Non-negotiable V1 product spec

- No account, no calendar integration, no names or email addresses in the room. Anonymous pixel characters are the only presented identity.
- Personal session history stays on the Mac. Live rooms share only the minimum anonymous information required to function. The backend must not persist personal activity history as a shortcut.
- Detect supported meetings using local app/browser signals and microphone-in-use status. Never record audio, video, screen content, or what the user types. Browser window-title inspection is local and permission-dependent.
- The user explicitly joins. One invitation per meeting; “Not now” keeps that meeting quiet. Provide per-app prompt controls and quiet hours.
- An approved app counts as heads up. Idle means no recent input; away means an unapproved app is active. Neither proves whether a human is paying attention. A disconnected peer is unknown/reconnecting, never falsely away.
- Never wire the new UI to the old app's account/calendar/data model just because it already exists. Build the correct minimal model and document unresolved platform/backend decisions.

## The experience to build

**1. First launch, under a minute.** Three compact steps: a useful explanation, the privacy promise, and a six-character picker. Do not put a permission wall or configuration checklist before the user understands the benefit. Show Fern, Sunny, Pip, Moss, Robin, and Clover at crisp pixel scales. Save the selection locally and make it easy to change. The final action is “Let’s go heads up.”

**2. Permissions at the point of need.** Ask for the exact OS access needed by the selected detection mode. Explain what it enables, what is inspected, and what stays local. Keep an explicit Not now path with reduced functionality. After returning from System Settings, refresh the real permission state. Handle denial and revocation with a calm explanation and a functional recovery action. Never display a fake enabled state.

**3. A useful invitation.** A small non-activating panel near the menu bar: character, detected meeting app, “Looks like a meeting. Go Heads Up?”, primary join action, secondary Not now. Do not steal typing focus or repeatedly reappear. Respect quiet hours and per-app preferences. Only claim other people are present if a real room lookup establishes it. Join shows pending, success, timeout, retry, and cancel states.

**4. Menu bar that works like a Mac.** Idle uses the compact mark. Active shows a legible character/status treatment, with an accessible text equivalent. The menu prioritizes Open the room, Approve current app for this meeting, Copy room link, End session, local weekly history, and Settings…. Use standard menu semantics, conventional shortcuts such as ⌘, for Settings, and Escape to dismiss. Disable unavailable actions with a reason. Do not make tiny artwork the only actionable affordance.

**5. The room is the heart.** Use the exported set pieces and manifest. A forest room, shared green table, and stable character places; props stay secondary. Identify the current user with a quiet “you” suffix in the roster. Keep the scene free of green character frames and floating YOU tags. Show an honest live count plus readable roster. Idle pauses gently; away moves toward the doorway; reconnecting preserves uncertainty. Keep empty, solo, duplicate-character, many-participant, and room-ended states coherent. Six slots are a reference, not a hard participant cap: overflow remains represented in the count and list. Prevent overlapping away sprites and reorder flicker. App approval should take one clear action and explicitly state whether it lasts for this meeting or all meetings.

**6. A good ending.** Stop live participation, show the user's own heads-up time, percentage, best uninterrupted stretch, and switches away. Derive all numbers from the same monotonic session timeline, with a documented denominator for idle/offline intervals. Never infer complete minutes of focus from a stale remote state. Keep the example three-stat hierarchy, one brief warm sentence, a little cast moment, and Done. A summary should close automatically only when the user dismisses it. No guilt language, grades, public rankings, or competitive streak pressure. If team presence appears, keep it anonymous and session-scoped; don't build a leaderboard.

**7. Settings with clear scopes.** Character picker, browser meeting detection, quiet hours, per-app prompt controls, approved apps, optional anonymous usage counts off by default, and local data deletion. Distinguish permanent approval from meeting-only approval. Confirm destructive deletion and explain exactly what is removed. Include app version and update status only when backed by the release mechanism. Time controls must use the user's locale/time zone and handle overnight quiet hours.

## Visual craft

Use `tokens.json` and the exported artwork. Paper #F5F2E9, forest #184C35, ink #123827, green #64D86B, amber #FFD15B, coral #FF7563. Native SF Pro body and controls, consistent 4/8/12/16/24/32 spacing, restrained 6–12 pt corners. Keep headings compact and direct. Use sentence case for interface copy and utility labels; avoid all-caps labels. Let content set height; support long labels and accessibility text sizes.

The current website's Manrope headlines establish the brand; they don't require turning native menus into a webpage. Avoid excessive cards within cards, gradients, glass effects, dashboard chrome, and decorative metrics. Preserve the twelve-tile Hu mark and original character geometry. Pixel artwork uses nearest-neighbor interpolation and consistent foot anchors. Every icon needs a clear purpose.

Light and dark appearances must both feel intentional. Keep the pixel room green, adapt chrome and text to appearance, and verify contrast in real OS settings. Presence always has a shape and a word, not color alone.

## Motion, accessibility, and attention

Use 160 ms control feedback, roughly 240 ms scene transitions, one 480 ms walk, and a single 600 ms end wave as starting points. No endless bouncing, pulsing status, particles, sound, or motion while the popover is hidden. Respect Reduce Motion with static frame swaps. Cancel animation when the window closes or session ends.

All controls must work with keyboard and VoiceOver. Supply an accessible roster equivalent to the scene, meaningful selected states, logical focus order, and visible focus. Don't announce each decorative object or every elapsed second. Announce material state changes without interrupting conversation. Test Increase Contrast, Differentiate Without Color, reduced transparency, and both appearance modes.

## Engineering and acceptance bar

Build reusable native views from `native/HeadsUpKit.swift`; keep rendering independent of session/detection/network models. Use an explicit state machine for detection, invitation, joining, active, reconnecting, ending, and summary. Track explicit user intent separately from heuristic signals. Persist only necessary local preferences/history, and reset meeting-scoped permissions on exit.

Before calling V1 done, demonstrate:

1. Fresh install → onboarding → optional permission path → character choice → first meeting.
2. Join, Not now, later manual join, quiet hours, per-app disabling, and no duplicate prompts after brief mic/app transitions.
3. Approved-app switching, debounced away/idle transitions, reconnection, same character chosen twice, and more than six participants.
4. Meeting ends, manual end, remote room expiry, app quit, relaunch, sleep/wake, and permission revocation; no zombie rooms or fabricated live presence.
5. Summary arithmetic against deterministic timeline fixtures, zero-duration handling, and local deletion.
6. Keyboard-only and VoiceOver journeys, Reduce Motion, light/dark/Increase Contrast, and localized long strings.
7. Inspect outbound payloads: no personal identity, meeting title, calendar data, raw activity content, or persistent activity history. Optional telemetry truly starts off.
8. Idle performance: no animation timer or unnecessary polling while UI is closed. No focus stealing or popover that blocks another app's controls.

Deliver working native views and interactions, the state model, previews for every non-happy-path state, targeted behavioral tests, and a short map of platform/network work still required. Use the supplied artwork rather than replacing it with emoji or placeholders. Don't call a visual prototype a finished meeting detector or a working backend.

Keep V1 deliberately small. Defer accounts, calendar sync, AI notes, chat, manager dashboards, team rankings, world building, cosmetic stores, and elaborate progression. The room should make the meeting better; it should never become another meeting to manage.

---

## Design rationale and primary references

These are design principles adapted to Heads Up, not a claim that Granola implements this product or endorses it.

- Granola's documented ad-hoc call notifications use microphone activity to offer a contextual action and expose global/per-app notification controls. The Heads Up adaptation is one relevant invitation with explicit control over interruptions. [Granola notifications](https://docs.granola.ai/help-center/taking-notes/notifications).
- Granola's 2024 launch explains a familiar, simple workspace with the user retaining control and clear distinctions between user-entered and generated material. The transferable idea is a legible system that explains its evidence. For Heads Up, visibly separate known presence, inferred local state, and unknown connectivity; don't add AI or transcription. [Granola launch principles](https://www.granola.ai/blog/announcement).
- Familiar native commands and a predictable menu structure reduce the work of using a small utility. The prompt adapts Apple's menu guidance to the core Heads Up actions. [Apple: Menus](https://developer.apple.com/design/human-interface-guidelines/menus).
- Motion should communicate state and respect accessibility preferences. Here, that means brief transitions and static alternatives, not persistent entertainment. [Apple: Motion](https://developer.apple.com/design/human-interface-guidelines/motion), [SwiftUI: Accessible appearance](https://developer.apple.com/documentation/swiftui/accessible-appearance).

References reviewed November 9, 2026. The product decisions and acceptance criteria above are specific recommendations for this approved V1, not quotations from those sources.
