# Vanta overhaul — every surface the user sees

Zandy's brief (2026-09-23): replace everything the user sees. No 3-button bar,
no iOS pill, no stock Android look anywhere. This file is the map: one row per
surface, what replaces it, and how it gets into the build. A surface is not
done until it has a row marked **built** and a gate that fails if it regresses.

Design language: **Vanta Void** — true-black OLED base, a single cyan light
source (`#35E0FF`), glass that glows at its edge rather than frosting, motion
that springs rather than slides. `design/tokens.json` stays the single source
of truth; `tools/gen_tokens.py` emits the Kotlin `VantaTokens` object, the RRO
values and the SystemUI patch resources from it.

## How a surface gets replaced

Three lanes, cheapest first:

1. **Our own app** (`vendor/vanta/packages/*`, Soong, Kotlin + Compose,
   platform-signed, privileged). Used where Android already lets a system app
   own the role: home, assistant, setup wizard, wallpaper, settings entries.
2. **RRO** (`vendor/vanta/overlay/*`). Colours, radii, sizes, bools, strings.
3. **Patch series** (`patches/<repo>/*.patch`, applied by `tools/apply.sh`,
   checked by `verify_tree.py`). Only for surfaces that live inside SystemUI,
   Launcher3 or the framework and have no role or resource hook. Patches add
   new files wherever possible and keep edits to existing files small and
   anchored, so a Lineage sync is a rebase, not a rewrite.

## The map

| # | Surface | Replaced by | Lane |
|---|---|---|---|
| 1 | Boot animation | Vanta boot (already the phone's own) | copy file |
| 2 | Setup wizard | **Vanta Welcome** — five screens, identity + assistant pairing + gesture teach | app (`SetupWizard` role, overrides Provision) |
| 3 | Lock screen | **Vanta Lock** — large split clock, glass notification stack, cyan charge ring | patch SystemUI (clock provider + keyguard layout) |
| 4 | Always-on display | Vanta Lock's dimmed clock, burn-in shift | patch SystemUI |
| 5 | Status bar | **Vanta Bar** — clock centred left of the cutout, battery as a ring, icon set redrawn | patch SystemUI + icon overlay |
| 6 | Navigation | **Vanta Rail** — gesture-only; the handle becomes a thin light rail that stretches with the swipe, flares on back, dims in full screen. 3-button and 2-button modes removed | RRO `VantaRailOnly` (gestural, **overrides** the 3-/2-button overlays; Settings hides modes whose overlay is absent, no patch) + patch SystemUI (`NavigationHandle`) |
| 7 | Quick settings | **Vanta Deck** — glass chip tiles, brightness as a full-width light bar, header with the day and a Zo status chip | patch SystemUI |
| 8 | Notification shade | Deck's second page; notifications as glass cards with a lit edge in the app's colour | patch SystemUI + RRO |
| 9 | Heads-up | same card, drops from the rail at the top | patch SystemUI |
| 10 | Volume | **Vanta Dial** — a vertical light column on the right edge, stream switch by swipe | patch SystemUI (`VolumeDialogImpl` layout) |
| 11 | Power menu | **Vanta Power** — four large orbs (power, restart, recovery, lock) + emergency | patch SystemUI (`GlobalActions`) |
| 12 | Home screen | **Vanta Home** — no grid: a stream of live cards (time, now playing, next alarm, Zo cards, battery), a four-slot dock | app (HOME role, overrides Launcher3) |
| 13 | App drawer | Home's search-first drawer: type to find, ranked by use, A–Z scrubber | app |
| 14 | Recents | Launcher3 Quickstep's fallback recents, re-skinned: true-black scrim, 28dp tasks, glass clear-all with accent text | RRO `VantaLauncher3Overlay` (target com.android.launcher3); patch Launcher3 only for what has no resource |
| 15 | Wallpaper | **Vanta Aurora** live wallpaper running **Vanta Liquid** (`res/raw/liquid_frag.glsl`: ray-marched black liquid glass, thin-film, cyan softbox; reacts to unlock, tilt, time of day). The same file drives `design/render`, so the browser render is the wallpaper — `check.sh` fails if they diverge | app + RRO `default_wallpaper_component` |
| 16 | Settings | Retheme via RRO + **Vanta Hub** injected at the top of the homepage | app (EXTRA_SETTINGS tile) + RRO `VantaSettingsOverlay` (Settings + its static SettingsLib) |
| 17 | Assistant | **Vanta Voice** — hold power; a light orb rises from the rail; bring-your-own AI (OpenAI-compatible or Zo) | app (`VoiceInteractionService`, assistant role) |
| 18 | Edge panel | **Vanta Edge** — swipe from the right edge: shortcuts, clipboard, tools, Zo | app (privileged overlay) |
| 19 | Charging | cyan ripple from the port, ring on the lock screen | patch SystemUI (wired charging ripple colour/shape) + RRO |
| 20 | Dialogs, toasts, sheets | framework RRO (radii; toast + popup/floating colours; dialog body is Monet `system_surface_container_dark`, not RRO-able) | RRO |
| 21 | Icons | Vanta icon mask (squircle-cut) + themed monochrome icons forced on | RRO `config_icon_mask` (done) + setting |
| 22 | Fonts | IBM Plex (done) | overlay + theme JSON |
| 23 | Sounds | **Vanta Tones** — ringtone, notification, alarm, lock/unlock, charge, all synthesised in-repo | files + props |
| 24 | Keyboard | AOSP LatinIME retheme to Vanta Void | RRO |
| 25 | Personalization | **Vanta Studio** — one page for Aura, glass intensity, wallpaper depth, icon shape, always-on style. The thing stock Lineage has no equal of | app page in VantaHub (Look) + `VantaAuras` |
| 26 | Theme engine | **Vanta Auras** — 6 accent presets (Void, Ember, Verdant, Iris, Rose, Mono). Each re-points the Monet accent (whole framework) and `LocalAura` (in-app glass rim/glow); bg stays true black | `design/tokens.json` auras → `VantaAuras.kt` + VantaSetup accent write |
| 27 | Always-on | **Vanta Ambient** — thin split clock, weather line, next event, media mini, charge; burn-in shift. Style picked in Studio | patch SystemUI (AOD) reading `AMBIENT_STYLE` |
| 28 | Live activities | **Vanta Capsule** — navigation / timer / recording / call as lit glass capsules at the top of the home stream (not a notch island) | app (VantaHome cards) |
| 29 | Boot | **Vanta boot animation** — scan-line reveal of the `vanta` wordmark (IBM Plex Light), breathing loop, line-collapse outro; 1080² @ 60 fps | `tools/bootanim` → Lineage's `prebuilt_file` hook |
| 30 | Recovery | **Vanta recovery** — lit pill header (`vanta` / RECOVERY, R◇ F△ mode switch, amber FASTBOOTD), light running the Vanta mask rim as the install animation, cyan-on-black menu palette, "Vanta 0.1 - Android 17" title | `tools/gen_recovery.py` + `recovery.sh` + recovery patch |
| 32 | Cover screen (Flip5) | **Vanta Cover** — VantaHome recomposed for the outer panel: clock faces, notifications, now playing, controls, apps, all swipeable and ordered in Hub | app (VantaHome is the only HOME; the closed fold state makes the cover display 0) |
| 31 | Brand text | Every user-readable "LineageOS" (Settings version row, LineageParts title, permissions, trust text) reads Vanta, in every locale Lineage translates; updater and Lineage setup wizard replaced | generated RROs (`gen_branding.py`) + module overrides |

## Personalization lane (Studio)

Auras are the spine: `design/tokens.json` `auras` is the source, `gen_overlays.py`
emits `VantaAuras.kt` (the runtime table) from it, `check.sh` fails if the two
drift or if the default aura stops equalling `void.colors`. Switching an aura
does two things at once — VantaSetup writes `Aura.accentHex` as the Monet system
accent so the framework/SystemUI/Settings retint, and `VantaConfig.LOOK_AURA`
drives `LocalAura` so Vanta's own glass rims and glow follow in-process. Rendered
proof: `design/render/out/{studio,auras,ambient,capsule}.png`. The Studio page
itself lands in VantaHub's Look tab; Ambient is a SystemUI/AOD patch; Capsule is
a VantaHome card type — all reading the same config keys.

## Order of work

1. Apps that need no synced source: Home, Voice, Hub, Welcome, Aurora, Edge,
   Tones, shared `VantaCore` library. Written now.
2. RROs for SystemUI/Settings/Launcher3/LatinIME, resource names verified
   against the synced tree by `verify_tree.py`.
3. SystemUI and Launcher3 patch series, written on the build box against the
   synced source.
4. First full compile of the whole thing (Zandy: "build full rom first then
   compile").
