Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Vaults UI — Design Alignment (restore design.pen)
Why
The shipped Vaults UI drifted from the design.pen frames (the visual source of
truth). Realign every Vaults surface to its design frame, faithfully. The
frames — and their exported PNGs — are the literal spec. The root cause of the
drift was that nobody compared the implementation against the frames; this task
closes that gap and a gatekeeper will re-verify each surface against the frame
before merge.
Source of truth
design.pen lives at ../avibe-docs/design.pen relative to this repository.
Open it through the pencil MCP tools, resolving that checkout-relative path
to an absolute filePath when required. Exported reference PNGs are in
/tmp/vault-design/. For each surface, BOTH read the PNG and read the frame via
batch_get (high readDepth, resolveVariables: true) to get exact copy,
spacing, colors, radii. Map every value to a UI token/class; add a token if one
is missing — never hardcode a one-off hex.
| Surface | design frame (id) | reference PNG | implementation |
|---|---|---|---|
| Create / "Add a secret" | vyed5 (dialog KsYUN) |
vyed5.png |
ui/src/components/ui/vault-secret-form.tsx + AddSecretDialog in components/workbench/VaultsPage.tsx |
| Protected setup | kAmWj (modal gV1j9) |
kAmWj.png |
vault-protected-unlock.tsx (needs-setup branch) |
| Protected unlock | g5Q7F (modal Yv2bL) |
g5Q7F.png |
vault-protected-unlock.tsx (locked branch) |
| Approval — access | w8u5l (card SKBld) |
w8u5l.png |
vault-approval-card.tsx (access) |
| Approval — signing | eWOjt (card pRtHq) |
eWOjt.png |
vault-approval-card.tsx (sign) |
| Provision ($NAME) | F4N19 (card NqXrN) |
F4N19.png |
vault-secret-form.tsx (fixedName mode) |
| Hub page | y4rw5Q |
y4rw5Q.png |
components/workbench/VaultsPage.tsx |
| Group dropdown (open) | WgGQy (popover e3rPI) |
WgGQy.png |
Combobox group picker in vault-secret-form.tsx |
Confirmed divergences (audited — fix these for sure)
A. Protected setup (kAmWj) — vault-protected-unlock.tsx needs-setup branch
Current: a passkey card AND a full password <form> shown at once as two coequal
sections, embedded in the create <form>. Target (match kAmWj.png), ONE
recommended path:
- shield-check icon badge; title "Set up protected secrets"; subtitle.
- ONE recommended green card: primary button "Add a passkey", a RECOMMENDED badge, caption "Face ID · Touch ID · security key — the most secure option".
- a recovery tip box (add a second passkey / save a recovery code).
- a "Use a password instead" text link + a red "less secure" badge; clicking it reveals the password fields (progressive disclosure) — hidden by default.
- "Maybe later" dismiss.
- HARD: remove the
<form>element. Use buttons +onClickreading state. Password setup is a buttononClick, not a form submit. (This is the nested-<form>-inside-the-create-<form>bug that caused a full-page reload.)
B. Protected unlock (g5Q7F) — vault-protected-unlock.tsx locked branch
Target (match g5Q7F.png): scan-face icon; "Unlock to continue"; subtitle
" is protected — unlock it in your browser to sign"; primary "Unlock with
passkey" + caption "Face ID · Touch ID · security key"; "Use password
instead" reveal link (less secure) → reveals password field + unlock button; a
mint factor-safety note; Cancel. Again no <form> — onClick buttons.
C. Create dialog (vyed5) — vault-secret-form.tsx
- Kind selector: design is a 2-segment toggle (Static value | Signing key), not two big cards. Use a segmented control (reuse the existing Tabs/segmented primitive, or build one consistent with the design system).
- Field order: Kind → Name → Value → Protection → Group → Advanced.
- Name hint: "Letters, numbers, underscore · case preserved".
- Value: input + eye toggle; placeholder "Paste the secret value".
- Protection: two cards Standard / Protected, exact copy — Standard "Machine-encrypted. Headless use OK. For API keys.", Protected "Unlocked in your browser. Survives machine theft. No headless."; selected = green border + check.
- Advanced: a single collapsible box containing (a) "Allowed hosts (for proxy fetch)" input, and (b) an "Always ask before each use" toggle with help "Never granted in advance, even per-key". The impl currently lacks both the Advanced grouping and the toggle.
- Primary button label: "Create secret" (currently "Save"/"保存").
- Setup/unlock: do NOT embed as a coequal third section under the form. When Protected is chosen and the vault is not unlocked, show the setup/unlock step (per A/B) as the gating step; keep "Create secret" disabled until unlocked. Must not be a nested form and must match the frames.
- DECISION — do NOT silently drop:
description+tagsexist in the impl but are absent from thevyed5mock. Do not delete them; fold them under "Advanced" (or keep minimal) and flag this in the PR description for owner review. Also verify whether "Always ask before each use" maps to a real backend policy field; if it is not supported, flag it rather than fake a dead toggle.
D. Approval cards (w8u5l access, eWOjt signing) — vault-approval-card.tsx
Compare header / detail rows / scope options / footer to the frames and align
copy + layout. The embedded protected-unlock panel inherits the A/B fix (this
file reuses VaultProtectedUnlock).
E. Hub (y4rw5Q → VaultsPage.tsx), Provision (F4N19), Group dropdown (WgGQy)
Compare each to its frame and fix divergences (sections, spacing, control styles,
copy). Provision = the fixedName mode of the form → match SecureInputCard.
Group dropdown → match GroupPopover.
Constraints
- The
design.penframes are the literal spec — match them. Map every size/weight/spacing/radius/color/shadow to a UI token/class; add the token if missing; never hardcode a one-off hex. - Reuse
ui/src/components/uiprimitives (Button, Badge, Card, Dialog, Input, Switch, Combobox, Tabs/segmented…). Extend a primitive before forking. - i18n: all copy through
ui/src/i18n/en.json+zh.json, kept 1:1. Reuse existing keys; add new ones in both files. cd ui && npm run build(tsc + vite) MUST pass.- Do NOT change backend behavior or the crypto. CARDINAL INVARIANT: plaintext — secret values, released DEKs, private keys — lives ONLY in the browser and in avault; the daemon only ever relays opaque blobs. Restyling must not alter any crypto / submit path. Keep the keypair sign-only guard.
- Do not touch the parked sandbox (#706) or unrelated code.
Deliverables
- Every Vaults surface realigned to its frame.
- A "Results" section appended here: per surface, what diverged and what changed, referencing the frame.
npm run buildgreen.- A NON-draft PR titled
fix(vaults): realign UI to design.pen frames. Description must name the capability, list the surfaces changed, call out the description/tags + "always ask" decisions/flags, and state evidence layers (build; manual; Codex E2E pending). - Own the Codex review loop (background-watch-hook + bundled
wait_pr.py), re-request@codex reviewafter each push, fix findings at root. Do NOT merge — the gatekeeper merges after Codex passes and after fidelity is verified against the frames.
Verification (by the gatekeeper — not the implementer)
- Render each built surface and compare side-by-side to the frame PNG.
- Codex runs an end-to-end test in the local Incus regression env to confirm the design is restored.
Results
All copy/spacing/colors mapped to existing tokens/classes (mint/mint-soft,
gold, violet/violet-soft, accent/accent-soft, destructive, surface/
surface-2, border, muted/muted-foreground, foreground). No one-off hex
added. i18n: every string routed through en.json + zh.json, verified 1:1 (197
keys each, no gaps) and every referenced key resolves. cd ui && npm run build
(tsc + vite) passes. Cardinal invariant preserved: the crypto/submit path
(sealValue / sealBlindBox / getVaultPubkey / createVaultSecret /
establishing_vmk / keypair signer_kind + public_meta) is byte-for-byte
unchanged; the only payload change is restructuring policy and adding the real
policy.always_ask field (see Flags). Setup, unlock, create, provision, and the
group dropdown were rendered in a throwaway light-theme harness and visually
confirmed against the frame PNGs (harness removed before commit).
A. Protected setup (kAmWj) — vault-protected-unlock.tsx (needs-setup)
- Diverged: two coequal sections (passkey card + a full password
<form>) embedded inside the create<form>— invalid nested form that reloaded the page. - Changed: full rewrite, form-free (buttons +
onClick). Centered shield-check badge, title "Set up protected secrets" + subtitle. ONE recommended green card (1.5px mint border onmint-soft):RECOMMENDEDbadge, solid green "Add a passkey" (variant="brand"), caption. Life-buoy recovery tip. "Use a password instead" +less securebadge link that progressively reveals the password fields (hidden by default; auto-revealed only when no passkey is available here). "Maybe later" dismiss (via new optionalonDismiss). Enter submits via keydown, not form submit.
B. Protected unlock (g5Q7F) — vault-protected-unlock.tsx (locked)
- Diverged: password rendered as an inline
<form>; no progressive disclosure. - Changed: form-free. Gold scan-face badge, "Unlock to continue" + " is
protected — unlock it in your browser to sign" subtitle (new
secretNameprop). "Unlock with passkey" (variant="brand") + caption; "Use password instead" reveal link → password field + Unlock; mint factor-safety note; Cancel.
C. Create dialog (vyed5) — vault-secret-form.tsx
- Diverged: Kind as two big cards; field order had Value before Group with Description/Tags/Hosts as loose siblings; no Advanced grouping; no always-ask; primary button "Save"; protected setup/unlock embedded as a coequal section.
- Changed: Kind is now a 2-segment
SegmentedRadio(reused primitive). Field order Kind → Name → Value → Protection → Group → Advanced. Name hint added. Value placeholder "Paste the secret value". Protection cards use exact frame copy and the selected card shows a mint check. Group uses the extendedCombobox(folder icons + design create row). New Advanced collapsible holds Description, Tags, Allowed hosts, and the "Always ask before each use" toggle. Primary button "Create secret". Protected setup/unlock now renders as a gating step (not a nested form, not coequal) and "Create secret" stays disabled until unlocked.
D. Approval cards (w8u5l access, eWOjt sign) — vault-approval-card.tsx
- Diverged: access header used a cyan key icon; sign used a wallet; detail rows were a bordered sub-panel with uppercase labels; scope used a check-circle; Approve/Sign used a shield icon.
- Changed: access = gold
LockKeyhole, sign = violetPenTool. Details are a borderless list with sentence-case fixed-width labels and top/bottom dividers; command is a plain mono chip; egress usesCpu. Scope options use a radio indicator (mint ring + dot) with the selected label bold. Approve =Check, Sign =PenTool. Protected gating shows the unlock panel while locked, then the mint operation note once unlocked (no duplicate note).
E. Hub (y4rw5Q), Provision (F4N19), Group dropdown (WgGQy)
- Hub —
VaultsPage.tsx: subtitle → "Secrets your agents use — names only, values never shown". Active grants are now compact dismissible chips (icon ·type · ref· live countdown · ×) instead of full cards. Group headers gained a folder icon and a smarter count ("N secrets" / "N keys"). Secret rows gained analways-askbadge and aproxy · <host>badge. Out of scope (net-new features, not restyles): the search field, the "By skill" tab, and per-row ⋯ menus — these frames depict capabilities that don't exist yet and were intentionally not built. - Provision —
vault-secret-form.tsx(fixedName) +secret-request-card.tsx: thefixedNamemode now matchesSecureInputCard: a cyan key header ("Agent needs a secret"), a cyan name-highlight box (asterisk + "Secret name" + name + "not set yet" badge), Value + eye + "Submitted over TLS…" help, a "Store as" segmented Standard|Protected, and a "Save & wake agent" button. Same submit path. - Group dropdown — extended
Combobox: added optionalwithFolderIcon(folder icon per option + on the trigger; mint-soft selected row with check) andcreateButtonLabel(a bordered "+ " input with a green Create button). Both are opt-in, so every otherComboboxcaller is unchanged.
Flags for owner review
- Description + Tags exist in the impl but are absent from the
vyed5mock. Per the spec they were not deleted — they're folded under the new Advanced collapsible and stay fully functional. Confirm this placement is acceptable. - "Always ask before each use" maps to a real backend field:
policy.always_ask(storage/vault_service.py_secret_access_grantablereturnsFalsewhen set → the secret is never granted in advance, even per-key), which matches the mock's help text exactly. It is wired live (static secrets only; keypairs are already never value-grantable, so the toggle is disabled for them). Not a dead control.