Approval Card
An agent asks before it acts: a risk tier, what exactly will happen, Allow and Deny with shortcuts, a countdown that pauses while you read, arming for high risk, hold-to-allow for critical, and a resolved row.
oxyn add approval-card- To
- Customers – EU (42)
- Subject
- What's new in October
- Send
- Today, 9:00 AM
let mut req = ApprovalRequest::new("e", "Send campaign email", Risk::Medium, opened_at);
req.details = vec![("To".into(), "Customers – EU (42)".into())];
req.expires_in = Some(Duration::from_secs(60)); // pauses while hovered
let card = use_signal(|| ApprovalCard::new(req));
rsx! {
ApprovalCard {
card: card(),
now: clock.now(),
on_decide: move |d: Decision| agent.answer(d) // AllowOnce, AllowAlways, Deny…,
}
}Rendered from Rust at build time · goes live when visible
When to use
- The agent is blocked on one action and the user decides, usually in under three seconds, whether it may proceed.
- The card must show exactly what will run (argument preview), how risky it is (risk badge), why the agent wants it (quoted reason), and offer how far the yes goes (once / session / always) or a no the agent learns from (deny with reason).
- It appears in two places: AwaitingApproval; the call's detail (command, diff) is already expanded above it.
- The footer adds only the decision row. that do not belong to a visible tool row (network, MCP with redacted args, spend, credential, questions, requests from a collapsed sub-agent).
When not to use
- Several open requests in one card: use Approval pager instead.
- Paged questions the agent asks before acting: use Approval questions instead.
- An agent's question in its own card above the composer: use Decision Card instead.
Installation
Approval Card is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add approval-carduse crate::oxyn::{ApprovalCard, HITL_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{ApprovalCard, HITL_CSS};
Usage
let mut req = ApprovalRequest::new("e", "Send campaign email", Risk::Medium, opened_at);
req.details = vec![("To".into(), "Customers – EU (42)".into())];
req.expires_in = Some(Duration::from_secs(60)); // pauses while hovered
let card = use_signal(|| ApprovalCard::new(req));
rsx! {
ApprovalCard {
card: card(),
now: clock.now(),
on_decide: move |d: Decision| agent.answer(d) // AllowOnce, AllowAlways, Deny…,
}
}Examples
Inline
Medium risk with a countdown.
- To
- Customers – EU (42)
- Subject
- What's new in October
- Send
- Today, 9:00 AM
Code
let mut req = ApprovalRequest::new("e", "Send campaign email", Risk::Medium, opened_at);
req.details = vec![("To".into(), "Customers – EU (42)".into())];
req.expires_in = Some(Duration::from_secs(60)); // pauses while hovered
let card = use_signal(|| ApprovalCard::new(req));
rsx! {
ApprovalCard {
card: card(),
now: clock.now(),
on_decide: move |d: Decision| agent.answer(d) // AllowOnce, AllowAlways, Deny…,
}
}Edit custom
Edit before Deny, custom labels and icon.
- To
- Customers – EU (42)
- Subject
- What's new in October
- Send
- Today, 9:00 AM
Code
let mut req = ApprovalRequest::new("e", "Send campaign email", Risk::Medium, opened_at);
req.details = vec![("To".into(), "Customers – EU (42)".into())];
req.expires_in = Some(Duration::from_secs(60)); // pauses while hovered
let card = use_signal(|| ApprovalCard::new(req));
rsx! {
ApprovalCard {
card: card(),
now: clock.now(),
on_decide: move |d: Decision| agent.answer(d) // AllowOnce, AllowAlways, Deny…,
}
}Card actions
Buttons inside the card, Edit shown.
- To
- Customers – EU (42)
- Subject
- What's new in October
- Send
- Today, 9:00 AM
Code
let mut req = ApprovalRequest::new("e", "Send campaign email", Risk::Medium, opened_at);
req.details = vec![("To".into(), "Customers – EU (42)".into())];
req.expires_in = Some(Duration::from_secs(60)); // pauses while hovered
let card = use_signal(|| ApprovalCard::new(req));
rsx! {
ApprovalCard {
card: card(),
now: clock.now(),
actions: "card",
on_decide: move |d: Decision| agent.answer(d) // AllowOnce, AllowAlways, Deny…,
}
}High arming
High risk: Allow arms first, Deny is the default.
$ rm -rf target/ dist/
- Deletes files that git does not track
Code
let mut req = ApprovalRequest::new("e", "Send campaign email", Risk::High, opened_at);
req.details = vec![("To".into(), "Customers – EU (42)".into())];
let card = use_signal(|| ApprovalCard::new(req));
rsx! {
ApprovalCard {
card: card(),
now: clock.now(),
on_decide: move |d: Decision| agent.answer(d) // AllowOnce, AllowAlways, Deny…,
}
}Critical hold
Hold to allow.
- Payee
- Northwind Ltd
- Card
- Visa ···· 4242
- Moves real money
- Can't be undone from here
Code
let mut req = ApprovalRequest::new("e", "Send campaign email", Risk::Critical, opened_at);
req.details = vec![("To".into(), "Customers – EU (42)".into())];
let card = use_signal(|| ApprovalCard::new(req));
rsx! {
ApprovalCard {
card: card(),
now: clock.now(),
on_decide: move |d: Decision| agent.answer(d) // AllowOnce, AllowAlways, Deny…,
}
}Terminal
Terminal prompt.
Code
let mut req = ApprovalRequest::new("e", "Send campaign email", Risk::Low, opened_at);
req.details = vec![("To".into(), "Customers – EU (42)".into())];
let card = use_signal(|| ApprovalCard::new(req));
rsx! {
ApprovalCard {
card: card(),
now: clock.now(),
variant: "terminal",
on_decide: move |d: Decision| agent.answer(d) // AllowOnce, AllowAlways, Deny…,
}
}Resolved
Folded into a resolved row.
Code
let mut req = ApprovalRequest::new("e", "Send campaign email", Risk::Low, opened_at);
req.details = vec![("To".into(), "Customers – EU (42)".into())];
req.expires_in = Some(Duration::from_secs(60)); // pauses while hovered
let card = use_signal(|| ApprovalCard::new(req));
rsx! {
ApprovalCard {
card: card(),
now: clock.now(),
on_decide: move |d: Decision| agent.answer(d) // AllowOnce, AllowAlways, Deny…,
}
}API reference
ApprovalCard
| Prop | Type | Default | Description |
|---|---|---|---|
cardrequired | Card | — | The card (request + input state). |
nowrequired | ClockMs | — | Shared clock. |
variant | String | "inline" | `inline`, `footer`, `terminal` or `modal`. |
actions | String | "tray" | Buttons on the grey tray below the card (`tray`) or inside it (`card`). |
shortcuts | bool | true | Show key hints. |
always | bool | Default::default() | "Always allow" checkbox ticked. |
pager | Option<String> | Default::default() | Pager text ("1 of 3") and batch label, for `paged`. |
batch | Option<String> | Default::default() | Batch row ("Allow all 3 once"). |
on_decide | EventHandler<Decision> | — | A decision was pressed. |
on_hold | EventHandler<bool> | — | Hold started / ended (Critical). |
on_edit | Option<EventHandler<()>> | Default::default() | Shows an Edit button before Deny when set. |
on_hover | EventHandler<bool> | — | Pointer or focus entered (`true`) or left the card: pauses the countdown. |
on_page | EventHandler<i32> | — | Pager arrows: -1 previous, +1 next. |
approve_label | Option<String> | Default::default() | Primary label ("Allow once"). |
deny_label | String | "Deny" | Quiet label ("Deny"). |
edit_label | String | "Edit" | Edit label. |
always_label | String | "Always allow this action" | Checkbox label. |
icon | Option<String> | Default::default() | Icon in the 32 px header tile (an `Icon` name); risk picks one when unset. |
children | Element | Default::default() | Custom preview above the details (recipients, a diff). |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| ⌘orCtrlEnter | Allow (declared with aria-keyshortcuts; the host binds it) |
| Esc | Deny (declared with aria-keyshortcuts) |
| Tab | Through Deny, For this session and Allow |
| Terminal | y allows, p allows always, Esc says no |
Accessibility
- Deny and Allow are real buttons that declare aria-keyshortcuts (Escape, Meta+Enter); the visible key hints are kbd elements.
- The countdown text is aria-hidden; it turns amber in the last 10 seconds.
- Risk is carried by shape and label, never colour alone.
From the spec
- Footer / inline card:
role="group"witharia-labelledby(title "Approve: run cargo publish") andaria-describedby(risk line + reason). Modal variant:alertdialog, focus on Deny. - Arrival announcement (assertive, once): "Approval needed, high risk: run cargo publish. Reason: release 0.3.0. Press Control Shift A to review." Queue arrivals after the first are polite: "1 more approval waiting, 2 total".
- Buttons have full names: "Allow once, Y", "Allow for this session, S", "Always allow, opens rule editor, A", "Deny, N". Disabled ones keep focus and explain: "Always allow is not available for high-risk actions".
- Arming:
aria-disabled="true"then polite "Allow is available". Hold:aria-describedby"Press and hold for 1.2 seconds"; progress exposed asaria-valuenow0–100 on aprogressbarlinked to the button, announced at 50 % and on completion; alternativeTypePhrase(type the target name) when the app or user enables it. - Pager: "Approval 1 of 3" (
aria-live="polite"on change); ‹ › named "Previous approval", "Next approval". - Focus order inside: risk / reason (read) → primary → secondary decisions → overflow → pager. After a decision: next open page's card; when the queue empties, focus returns to the element that had focus before the jump (or the composer).
- Single-key shortcuts can be disabled (WCAG 2.1.4); then
Alt+Yetc. (proposed). Contrast: text 4.5:1, borders / glyphs 3:1, tier carried by shape + label. - Resolved row:
status, reads "Allowed once by you after 7 seconds".
Motion & interaction
- Rise. Footer slides up from the host card's bottom edge: height 0 → auto (200 ms
ease.out), content fades in 160 ms with 40 ms delay. The host row's loader morphs to the ✋ glyph and its timer freezes with ⏸ (tool-call.md). Inline cards enter withdur.row.enter(height spring + fade, y +4 → 0). - Argument preview. Mono block, syntax-tinted; dangerous tokens flagged by the app classifier get a dotted underline in the tier tone plus a superscript glyph (shape, not only colour); the first 4 lines show, "Show all N lines" expands with
dur.expand. - Diff preview link. For
Editrequests the footer shows "2 files · +12 −3 · Open diff ↗ D"; the first hunk is inline above (family F file-edit chip);Dopens the family H diff viewer, focus returns to the footer on close. - Buttons. Hover bg 80 ms; press scale 0.97 (
spring 600 / 30); key-hint caps (Y) sit inside each button at 70 % opacity and brighten on hover; on touch the hints are not drawn. - Arming (High). A fill sweeps left→right across Allow once / For this session in 600 ms; an early press shakes the button 2 × 3 px and shows "Available in a moment" for 1.2 s. The fill completes into the normal button background (no flash).
- Hold (Critical). A 2 px ring around the button's leading glyph (card) or a bar under the label (footer) fills linearly over 1200 ms; at 50 % a single haptic tick (touch); at 100 % the button pops 1 → 1.04 → 1 and turns into "Allowed" before the collapse. Releasing early drains in 200 ms. Moving the pointer off the button while holding cancels (prevents drag-through).
- Queue pager "1 of 3". Numerator rolls (
dur.count.roll); the page slides 12 px from the inline-end (forward) or inline-start (back) with a 160 ms fade; the card's height animates withspring.snaponly if the next page differs by more than 8 px, otherwise it jumps (less motion). - Always… → pattern editor. The button widens into the editor (240 ms
spring.snap); Narrower / Broader moves a highlight over the command tokens (160 ms) and the match count rolls; broadening past the first argument tints the field border with the Medium tone and adds "Matches commands you haven't seen yet". - Resolve. Footer collapses (220 ms
spring.snap) into a one-line note with the decision glyph; ✋ morphs to ✓ (stroke 240 ms) or ⊘; the host row continues: Approved flash 400 ms → Running, orDenied(tools.md). The resolved note stays for the life of the row (it is the audit's face). - Deny with reason. Field swaps in place; on Enter the typed text lifts 8 px and fades into the resolved row quote (220 ms). From the composer: the composer text flies to the card (the composer's
dur.travel220–260 ms) and the card resolves. - Stale. Desaturate 160 ms, buttons crossfade to the stale line, hold 4 s, collapse 180 ms.
- Attention link. When the card is reached by ⌘⇧A or the selector badge, its border flashes once (400 ms, the selector's "card flash on jump").
Timing
| Transition | Duration | Delay | Easing / spring | Stagger | Frame rate |
|---|---|---|---|---|---|
| Footer rise (height / content fade) | 200 ms / 160 ms | 0 / 40 ms | ease.out | — | 60 Hz |
| Inline card enter | 200 ms height + 160 ms fade | 0 | spring.snap / ease.out | 40 ms cap 6 (bursts) | 60 Hz |
| Input guard | 400 ms | from mount | — | — | — |
| Arming fill (High) | 600 ms | after guard | linear | — | 60 Hz |
| Early-press shake | 240 ms, 2 × 3 px | 0 | linear | — | 60 Hz |
| Hold fill / drain (Critical) | 1200 ms / 200 ms | 0 | linear / ease.in | — | 60 Hz |
| Hold complete pop | 200 ms | 0 | spring.snap | — | 60 Hz |
| Button hover / press | 80 ms / ~120 ms | 0 | ease.out / spring 600 / 30 | — | 60 Hz |
| Page slide + fade | 160 ms, 12 px | 0 | ease.out | — | 60 Hz |
| Pager count roll | 280 ms | 0 | ease.out | — | 30 Hz |
| Pattern editor open | 240 ms | 0 | spring.snap | — | 60 Hz |
| Pattern highlight move / count roll | 160 ms / 280 ms | 0 | ease.out | — | 60 Hz |
| Reason field swap | 200 ms | 0 | spring.snap | — | 60 Hz |
| Submitting underline | indeterminate, 1200 ms period | 300 ms | linear | — | 30 Hz |
| Resolve collapse | 220 ms | 0 | spring.snap | — | 60 Hz |
| ✋ → ✓ / ⊘ | 160 ms + 240 ms stroke | 0 | spring.snap / ease.out | — | 60 Hz |
| Card flash on jump | 400 ms | scroll end | ease.out | — | 60 Hz |
| Expiry countdown | 1 s steps | last 60 s | digit swap | — | 1 Hz |
| Stale desaturate / hold / collapse | 160 / 4000 / 180 ms | 0 | ease.out / — / ease.in | — | 30 Hz |
| Reduced motion | footer and pages appear with 80 ms opacity, heights jump; arming = static text "Available in 0.6 s" then enables; hold keeps 1200 ms with a 4-step fill at 4 Hz and the text "Hold to allow · 1.2 s"; no shake (text only), no pop, no stroke draw, no fly-in of reason text; pager digits swap; jump flash becomes a static 2 px border for 1 s | — | linear | none | 1 Hz idle |
Responsive behaviour
- inline in a transcript, footer inside a tool-call card, terminal in a TUI, modal for critical actions.
- actions card keeps the buttons inside the card for narrow side panels.
Edge cases (spec)
- Long commands / heredocs / 40-arg MCP calls: 4 lines + "Show all"; arg tables cap at 6 rows + "+12 more"; classifier-flagged tokens hidden below the fold are summarised in the risk line.
- Long reasons: quoted reason clamps at 3 lines with "More"; reasons are never truncated in the accessible name.
- Many queued (≥ 10): pager shows "1 of 14"; a "Review list" opens the paged queue as a list; batch actions only for compatible ≤ Medium groups.
- Two approvals for the same call (args changed while open): the old one becomes
Superseded. - User answers the same request on two devices: first ack wins; the other shows "Answered on your phone".
- Card scrolled off-screen: the status strip badge and the permission chip badge carry it; ⌘⇧A scrolls it into view without moving the user's reading position more than needed (card top 24 px below the viewport top).
- Run cancelled during Holding: the hold is aborted, card becomes
Stale; no approval is sent. - Rule just added matches the remaining pages: those pages auto-resolve, pager count rolls down; if all resolve, the queue closes with "3 allowed by your rule".
- RTL: layout mirrors; command, paths, diff and pattern stay LTR in isolated spans; arming / hold fill from inline-start; pager arrows flip.
- Tiny / dense (IDE 280 px panel): buttons collapse to
YSANkey caps with tooltips; risk line becomes glyph + label; reason in tooltip; footer min height 28 px. - Touch: 44 px buttons in a 2 × 2 grid under 360 px width; hold uses haptics; no single-key shortcuts.
- Slow network: Submitting underline after 300 ms, "Still sending…" at 10 s, SubmitFailed with Retry; the call stays blocked.
- Very fast agent: if the adapter resolves the request (rule, classifier) within 150 ms, no card is drawn — only the provenance glyph on the row.
- Very slow agent after approval: the resolved row stays; the host row shows Running; nothing in the card animates afterwards.
- No reason given by the agent: the reason line reads "No reason given" in muted text (not hidden), so its absence is visible.
Notes for AI
- Import
ApprovalCardfromoxyn_dioxusand includeHITL_CSSplus the token stylesheet once. - A GPUI version exists:
ApprovalCardElinoxyn_gpui. - Props to set first:
card,now. - It reads a clock (
now) for live timers; pass one clock for the whole page rather than one per component. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.