# Heads Up app kit · V1

This is the presentation contract for the **new app built from the ground up**. The older native application is not the implementation baseline. The approved product spec is: no account, no calendar connection, anonymous pixel characters, and history stored on the user's Mac.

- Living reference: `/design-system` on the marketing site.
- Brand system: `/brand/`.
- App implementation brief: [V1-UI-PROMPT.md](V1-UI-PROMPT.md).
- Shared website renderer: `site/components/brand/RoomScene.tsx`.
- Native starter: [native/HeadsUpKit.swift](native/HeadsUpKit.swift).

## What's included

| Content | Format | Contract |
| --- | --- | --- |
| Fern, Sunny, Pip, Moss, Robin, Clover | SVG; PNG at 1×, 2×, 3× | 32 × 40 transparent cells, five states each |
| Character animation sheets | SVG; PNG at 1×, 2×, 3× | 128 × 200 logical pixels, four columns, five rows |
| Thirteen room objects | SVG; PNG at 1×, 2×, 3× | Independent transparent assets, dimensions in manifest |
| Four status symbols | SVG; PNG at 1×, 2×, 3× | Shape, color, and visible words always agree |
| Xcode asset catalog | `.xcassets` | Static character states, scenery, status; scale variants included |
| Native presentation components | SwiftUI | Character, picker, status, room composition, meeting invitation |
| Geometry and design tokens | JSON | Layering, anchors, dimensions, semantic colors, type, spacing, motion |

The characters are original artwork. They evoke cozy pixel games without using game sprites or licensed characters. The app's character names describe artwork, not personal identity. Multiple participants may choose the same character.

## Constructing the room

Read `manifest.json`; don't estimate positions from screenshots. The scene is 320 × 240 logical pixels with a top-left origin. Every character uses a 32 × 40 cell and foot anchor **(16, 38)**. Place a character's top-left at `(slot.x - 16, slot.y - 38)`. This prevents jumps when switching states.

The main table occupies `(104, 100, 112, 64)`. Slot positions are foot coordinates. Render in this order:

1. Room shell and wall objects.
2. Rug and chairs.
3. North-side participants.
4. Table and its objects.
5. Foreground participants.
6. Accessible status labels. The roster identifies the current user with a quiet “you” suffix.

Use integer sprite scales where practical. Preserve aspect ratio and use nearest-neighbor interpolation (`Image.interpolation(.none)` in SwiftUI; `image-rendering: pixelated` on the web). Never blur the pixel artwork. Responsive room geometry can scale uniformly; don't stretch cells independently. Keep UI text as native text outside images.

The supplied renderer illustrates five people and supports six assigned slots. It is **not** a participant-layout engine. The app must assign stable, distinct slots, preserve them through presence changes, and provide an overflow count/list for larger rooms. If multiple people are away, give them separate doorway-area positions; don't pile sprites on one coordinate. The manifest's `away` point is the single-person reference anchor. Identity and list keys must use ephemeral participant IDs, not character names. Provide a stable “you” marker and a visible roster when characters repeat. Do not draw a green frame or floating YOU tag around the sprite.

## State semantics

| State | Visible label | Shape / color | Meaning |
| --- | --- | --- | --- |
| `heads-up` | Heads Up | Square / green | An approved app is active |
| `idle` | Idle | Circle / amber | No recent keyboard or mouse input; this is not evidence of inattention |
| `away` | Away | Diamond / coral | An app outside the approved set is active |
| `offline` | Reconnecting | Ring / neutral | Room presence is unknown because connectivity was interrupted |
| `celebrate` | Meeting complete | End-of-session treatment | Local presentation state; not a live presence value |

Idle time is elapsed time since input, never keystroke contents. The app agent must define and test thresholds, debounce, and precedence with the product state machine; do not infer thresholds from illustration timings. Missing remote updates become unknown/reconnecting, not away. Do not fabricate a live room count during an outage. A room can be empty or have one person; the normal experience should still work.

Only the room-scoped transport identifier, character choice, and necessary presence/timing signals belong in live room messages. Keep foreground app identity, browser window title, approved apps, permissions, and detailed history local. Treat a proposed wire payload such as `{ participantId, characterId, presence, sequence }` as a design boundary, not a completed backend protocol. Meeting-room derivation, expiry, anonymous authentication, reconnection, abuse controls, and deletion need implementation and review in the new app/backend. Never send names, email addresses, calendar data, raw window titles, text, screenshots, or audio to satisfy a UI requirement.

## Motion

Each sheet has four columns. Rows, top to bottom: heads up, idle, away, celebrate, offline. Crop each frame at `(column × 32, row × 40, 32, 40)` at 1×; multiply all crop coordinates for higher-scale sheets. Timing is in the manifest. The first frame matches the standalone state asset.

- Heads up: a subtle blink, only when explicitly previewed or intentionally scheduled.
- Idle: quiet closed eyes. No persistent bouncing or warning effect.
- Away: four walk frames, once on a transition (480 ms reference).
- Celebrate: a small wave, once at meeting end (600 ms reference).
- Offline: static treatment; no anxious pulsing.

The SwiftUI starter intentionally uses static states. Wire animation to actual state transitions only after implementing Reduce Motion and lifecycle cancellation. When Reduce Motion is on, choose frame zero and swap states without spatial movement. Suspend all animation while the popover is closed or the app is inactive. No sound by default. The web lab's “Play once” is an inspection control, not app autoplay behavior.

## Native integration

Add `native/HeadsUpAssets.xcassets` and `native/HeadsUpKit.swift` to the new app target. No package dependency is required. The starter is presentation-only and does not read activity, request permissions, use networking, or persist data. The local Swift check is blocked by an installed compiler/SDK mismatch (duplicate SwiftBridging module); validate this starter in the new app target with a matching Xcode toolchain before shipping.

```swift
@State private var character: HUCharacter = .fern

HUCharacterPicker(selection: $character)
HUStatusLabel(.headsUp)
HURoomScene(participants: [
    .init(id: "session-local-you", character: character,
          presence: .headsUp, slot: 0, isYou: true)
])
```

Use SF Pro for native controls and body copy. Manrope belongs to marketing/display headlines; IBM Plex Mono is a sparing utility accent, not the body font. Do not recreate web CSS in the Mac app. Favor standard `Button`, `Toggle`, `Menu`, `Settings`, keyboard shortcuts, focus behavior, and system permission controls. Use semantic text/surface colors from `tokens.json` in light/dark appearances. The room remains forest green in both.

The supplied starter includes a combined VoiceOver room description. The final app must also provide an accessible roster with each participant's identity within the session, current state, and “you” marker. Do not expose wall decorations to assistive technology. Character choice and status must be usable without color. Test Full Keyboard Access, VoiceOver, Increase Contrast, Reduce Motion, long localized labels, and larger text. Reference surface sizes are starting points, not fixed-height constraints.

## Seven surfaces and missing-state requirements

The interactive gallery demonstrates onboarding, contextual permission education, a meeting invitation, menu bar commands, the room, a wrap-up, and settings. Controls change the reference locally; they don't operate the system.

Build the additional states explicitly: no detected meeting, first person in a room, joining, join failure with retry/cancel, access denied, access revoked, browser detection unsupported, reconnecting, room ended remotely, app quit/relaunch, and sleep/wake. Destructive local-history deletion needs a native confirmation. “Not now” quiets only the current meeting. A settings command may disable prompts for one app or all apps. Keep those scopes distinct.

## Rebuild and publish the assets

From the repository root, with site dependencies installed:

```sh
python3 brand/scripts/make-app-kit.py
node brand/scripts/export-app-kit.mjs
node brand/scripts/package-app-kit.mjs
node brand/scripts/sync-site-assets.mjs
node brand/scripts/make-social-image.mjs
```

The SVG generator consumes the existing six character SVGs in `brand/dist/assets`. Edit the source generator or original character geometry, then regenerate; avoid hand-patching exported PNGs. Export uses `sharp` from the site's existing dependency tree. The package script excludes its own output archive. The sync script copies the current kit and original brand guide into `site/public/brand`.

Run `npm run lint` and `npm run build` in `site`. Native starter check: `swiftc -typecheck -module-cache-path /tmp/heads-up-swift-cache design-system/native/HeadsUpKit.swift`.

## Release boundary

The marketing site is the new product's site. Its primary CTA opens the interactive room until `NEXT_PUBLIC_HEADSUP_DOWNLOAD_URL` points to the **new** signed app release. Never connect this CTA to the legacy v1.1.10 DMG. Set the environment variable in hosting and rebuild when the new release is available. The legacy privacy/terms remain at `/legacy/privacy` and `/legacy/terms` for existing users.
