1 · One card for every live call (CANONICAL — mirrors QA 1395973)

Every live call runs in ONE floating card (PhoneCallOverlay, phone_call_overlay.dart). That covers a call placed from the composer's Call button or any call button, and a received call.
The card sits above every page, dialog and sheet (the Transfer sheet included). It also sits above the loading, maintenance, update and confirmation overlays. Clicks outside the card reach the screen underneath.
The card is independent of the composer. The composer never holds a live call and the card never docks into it. Tapping Call does not change the composer.
Ending a call has no wrap-up step and does not switch the composer to Log. Log stays the manual backup for calls made off the system.
No motion anywhere. The card appears and disappears instantly, and its height (72↔120) and colours swap instantly. It refreshes every second (the timer).
Desktop and mobile web: an incoming call rings in the card.
Native iOS/Android: the phone's own call screen rings, and the card first appears when the call connects.
The in-call keypad (draft PR #2087) is not in QA and not part of this spec.
Retired 2026-09-29 (supersedes ds_v276 / ds_v280): the Call Pill — green fill, 2px border, waveform, Dialing and Reconnecting states, the desktop audio-device picker, tooltips, the busy-disabled Call tab and "docks into the composer".

2 · Anatomy (CANONICAL — mirrors QA 1395973)

02:41Shane Dusang

327 wide (min(frame, 327) when the frame is narrower) × 72. 120 with the v2 Hold/Transfer row (72 + 40 + 8).
Pad 16 · r7 · 1px border painted inside (no layout shift) · no shadow.
A flexible text column and a button grid sit 16 apart, top-aligned.
Text column: gap 6, pad 2 top / 4 bottom.
Line 1 (status) and line 2 (name): 600 14px, line-height 1.
Line 3 (badge): --t-tiny orange-01, only on the 120 card.
Every line is single-line with an ellipsis. Nothing is selectable.
The name is gray-00 in every state and always shows a pointer. Tapping it opens the customer's activity page when the caller is a known customer; otherwise the tap does nothing. No hover styling.
Button grid: rows 8 apart and right-aligned, buttons 8 apart. An empty bottom row is dropped; the card stays 120.
Text width is 239 / 191 / 143 when the widest row holds 1 / 2 / 3 buttons.
Pixel map (card-relative): line 1 y18–32 · line 2 y38–52 · line 3 y58–74 · top-row buttons y16–56, at x271, 223 and 175 (right to left) · bottom row y64–104, in the same x slots.
UNMAPPED (literals, no token): 327, the 6px line gap, line-height 1 on --t-paragraph-sb.

3 · Buttons (CANONICAL — mirrors QA 1395973)

End

Mute

Muted

Speaker on

Speaker off

Hold

Resume

Transfer

Done

Hold disabled

Mute · keyboard focus

Mute · focused + pressed

40×40 · r5 · 20px FA Regular glyph. The glyph is --global-gray-01 (#383838) in both themes.
Fills — theme-independent: --global-gray-06 (Mute, Speaker, Hold, Transfer) · --global-red (End) · --global-green (Accept, Done). Themed: --orange-01 (Resume; #F98430 light / #FF9B52 dark).
Mute and Speaker never change fill; only the glyph swaps.
What each does: End hangs up or declines; during Ask first it cancels the consult (TEL-1b). Accept answers. Hold / Resume toggles hold. Transfer opens the Transfer sheet. Done completes Ask first.
No hover or pressed change.
Disabled looks identical. Only the cursor becomes the arrow, taps do nothing, and the button can't take focus.
Keyboard: Tab focuses and Enter activates. Focused = a 2px blue-01 ring inside the box (gray-03 while pressed).
No tooltips on the card: it sits above the app's navigator, so there is nowhere for a tooltip to render.
The app ships FA 5.15.3 Pro Regular and the kit draws FA6 Regular. The codepoints match but the drawings differ slightly (parity UNVERIFIED).

4 · Incoming · Calling · Connected (CANONICAL — mirrors QA 1395973)

Incoming

Incoming CallMarisol Vega

Incoming · returned transfer

Returned · Karla Sellers didn't pick upMarisol Vega

Incoming · a colleague asks first

Karla Sellers asks firstMarisol Vega

Incoming · unknown caller

Incoming CallUnknown

Calling...

Calling...Shane Dusang

Calling... · engine can't report mute

Calling...Shane Dusang

Connected

02:41Shane Dusang

Connected · long call

75:03Shane Dusang

Frames — Incoming: gray-07 fill, 1px orange-01 border, orange-01 status. Calling: gray-07 fill, 1px gray-05 border, gray-02 status. Connected: blue-03 fill, 1px blue-01 border, blue-01 status.
Top row, left to right — Speaker: connected, mobile only (section 6). Mute: connected or calling, when the phone engine reports mute. End: always. Accept: incoming only, far right.
Incoming status line: "Incoming Call", or "Returned · {name} didn't pick up" (a transfer that came back), or "{name} asks first" (a colleague's Ask first).
Calling status line: "Calling...". Connected status line: the timer.
The timer is MM:SS from connect. Minutes are zero-padded and never wrap at 60 (75:03).
The caller's name falls back to "Unknown". A colleague's name falls back to "a colleague".
Connected at 72 (no Hold/Transfer row) covers: legacy calls · v2 calls while controls are being checked (up to 3 tries, 1s apart) · calls whose controls were refused (TEL-1b).
Mute while calling depends on the phone engine per platform (UNVERIFIED).

5 · Default position, drag, saved position (CANONICAL — mirrors QA 1395973)

02:41Shane Dusang

The layout decides the idiom, not the platform. A window at least 1344×720 at launch gets the desktop layout; anything smaller gets the mobile layout.
Desktop default: centred over the 424px right detail column. That is 48.5px from the window's right edge (left = window width − 375.5) and 98px from the window top: the 50px app header + 16 global padding + 16, inside the 16px layer inset (48 below the header). The card's height does not change it.
Mobile default: centred in the frame 16px inside the screen edges. At top and bottom, the safe-area insets replace the 16 when present.
The mobile default uses the height the card first appears with, normally 72. When the Hold/Transfer row arrives the card grows 48px downward; it is not re-centred.
The whole card is the drag handle: text, gaps and blank area. A drag that starts on a button moves the card and cancels the tap.
Pointer movement applies 1:1. No drag visuals: no shadow, scale, grab cursor, snap or inertia.
Drag threshold: Flutter's defaults (UNVERIFIED).
The card stays 16px inside the left and right window edges, and 16px inside the top and bottom edges unless a safe-area inset exists, in which case it stops at the inset. It is clamped while dragging and on every render.
Resizing the window re-clamps the card without changing the saved spot.
The position is saved on every drag movement to the user's preference phone_call_card_position (per user, shared by both layouts). It is used for every later call and after restarts.
Before the first drag, every call uses the default.
This page saves the demo positions in this browser only.

6 · Mobile (CANONICAL — mirrors QA 1395973)

02:41Shane Dusang

Incoming CallMarisol Vega

Speaker shows only while connected, only on native iOS/Android and mobile web, and only when the phone engine reports speaker state. Mobile web is UNVERIFIED.
Speaker is always the leftmost top button: fa-volume-high on, fa-volume-low off, fill unchanged.
Desktop and desktop web never show Speaker.
With three top buttons the text column is 143 wide.
Native iOS/Android never show the incoming card: the phone's call screen rings and the card appears on connect. Mobile web shows the incoming card.

7 · Hold and Transfer (CANONICAL — mirrors QA 1395973)

Connected · v2

02:41Shane Dusang

Muted

02:41Shane Dusang

On hold

02:41Shane Dusang

Controls refused (409)

02:41Shane Dusang

The row appears on a connected v2 call once the controls check succeeds (up to 3 tries, 1s apart). Until then the card is the 72 connected card. When the row appears the card grows to 120 instantly.
The bottom row is right-aligned (on mobile it sits under Mute + End): Hold (fa-pause), or Resume (fa-play on orange-01) · Transfer (fa-right-left).
On hold the card stays blue: no orange frame, only the button changes.
Transfer opens the Transfer sheet, and the card stays above it.
Hold and Transfer are disabled while a transfer is in progress (Transferring) and on the colleague's card during an Ask first. During Ask first itself they are hidden. Disabled looks identical: arrow cursor, taps do nothing.
There is no pending state: a hold request doesn't disable anything, and the icon flips when the server confirms. No spinner.
If the server says this call can't be controlled (409), the toast "Call controls are not available for this call" shows and the card drops to 72 for the rest of the call.
Mute, and Speaker on mobile, combine with every state below.
Not in QA and not drawn: the in-call keypad (draft PR #2087).

8 · Ask first (CANONICAL — mirrors QA 1395973)

Ringing the colleague

Calling Karla Sellers...Shane Dusang on hold 02:41

Talking to the colleague

Talking to Karla SellersShane Dusang on hold 03:05

No answer — back with the caller

03:40Shane Dusang

Calling Karla Sellers...Shane Dusang on hold 02:41

Ask first (from the Transfer sheet) puts the caller on hold and rings the colleague.
Line 1 reads "Calling {name}..." and becomes "Talking to {name}" once the colleague answers.
Line 2 reads "{caller} on hold MM:SS". MM:SS is the total call timer, not the time on hold.
During Ask first (ringing or talking) the red button cancels the Ask first and brings the caller back to the rep. It does not hang up.
Hold and Transfer are hidden for the whole Ask first. While ringing the bottom row is empty.
While talking, Done (fa-check on global-green) sits under End. Done transfers the caller: the card returns to idle, hold goes off, and the toast "Transferred to {name}" (success) shows.
No answer after 45 checks (~90s), or after 10 failed checks, means the rep is back with the caller. The card then renders exactly like the idle v2 card (timer, name, Hold/Transfer enabled, not on hold), with the toast "{name} didn't answer" (warning).
If the colleague leaves the Ask first, the toast is "{name} left the call" (warning).
No toast when an Ask first starts (the card already says "Calling {name}...") or when the rep cancels it.

9 · Transferring · Returned (CANONICAL — mirrors QA 1395973)

Transferring

Transferring to Karla Sellers...Shane Dusang

Transferring · caller on hold

Transferring to Karla Sellers...Shane Dusang

Returned — incoming

Returned · Karla Sellers didn't pick upShane Dusang

Returned — connected

00:48Shane DusangReturned · Karla Sellers didn't pick up

After Transfer or Voicemail in the sheet, line 1 reads "Transferring to {name}..." and line 2 is the caller's name (no "on hold").
End hangs up. Hold/Resume follows the hold state. Both bottom buttons are disabled.
Toast (info, 5s): "Transferring to {Full Name}" or "Sent to voicemail for {Full Name}".
If the colleague doesn't pick up, the call comes back to the rep as an incoming call reading "Returned · {name} didn't pick up".
Once that call connects, the same text stays as the badge for the whole call.
A returned call can be held, asked-first or transferred again.

10 · The colleague's side (CANONICAL — mirrors QA 1395973)

Ringing

Devon Park asks firstShane Dusang

Connected during the Ask first

00:12Shane DusangDevon Park asks first

The asked colleague's card rings with "{rep} asks first".
Once connected and past the controls check, line 3 shows "{rep} asks first" until the Ask first ends (completed, canceled, no answer or given up). Before the check it is the 72 card.
End hangs up; the colleague never runs an Ask first of their own here. Hold and Transfer stay disabled.
The hold button shows the server's hold state. It is likely Resume (orange) while the Ask first runs (UNVERIFIED).
When both badges apply, the returned badge wins over the asks-first badge.

11 · Which states combine (CANONICAL — mirrors QA 1395973)

These are exclusive, one at a time: the status (incoming, calling or connected) · the incoming variant · the Ask first phase (idle, ringing, talking, failed or transferring) · v1 (72) or v2 (120).
These combine freely with any connected state: Mute on/off (also while calling) and Speaker on/off (mobile).
Hold (Resume) combines with idle, failed and transferring (disabled there), and with the colleague's side (disabled).
During Ask first the caller is on hold but the Hold button is hidden; line 2 says "on hold".
The returned badge combines with every rep-side phase and wins over the asks-first badge.
The colleague's side never shows rep-side phases: its Transfer is disabled, so no Ask first can start there.
Badges need the v2 row, so there is never a badge on the 72 card.
The timer runs through every connected state. During Ask first it moves into line 2.
Line 1 variants: Incoming Call · Returned · X didn't pick up · X asks first · Calling... · MM:SS · Calling X... · Talking to X · Transferring to X...
Line 2 variants: the caller's name · Unknown · {name} on hold MM:SS
Line 3 variants: none · Returned · X didn't pick up · X asks first
On the card, X falls back to "a colleague".

12 · Toasts (CANONICAL — mirrors QA 1395973)

success · 2s · Done after Ask firstTransferred to Karla Sellers

info · 5s · TransferTransferring to Karla Sellers

info · 5s · VoicemailSent to voicemail for Karla Sellers

warning · 3s · no answerKarla Sellers didn't answer

warning · 3s · the colleague leftKarla Sellers left the call

info · 5s · controls refused (409)Call controls are not available for this call

error · 3s · any other control errorWe couldn't complete that requestWe apologize for the inconvenience. Our development team has been made aware of this issue.

error · 3s · offlineNo Network ConnectionPlease connect to a wifi or cellular network to access this content.

error · 3s · a second call while one is liveYou are already on a call. Please end the call before making a new one.

placement · desktop

You are already on a call. Please end the call before making a new one.

placement · mobile (wraps, stays centred)

You are already on a call. Please end the call before making a new one.

One floating toast at the bottom centre, 16px from the edges, shrink-wrapped, at most window − 32 wide.
A new toast replaces the current one. Tapping a toast dismisses it.
Durations: success 2s · info 5s · warning 3s · error 3s.
Fills: success green-01 · info blue-01 · warning orange-01 · error red-01.
Text and icon use --white, which is dark text on the colour in dark mode. Every line is centred, and a two-line toast has no gap between its lines.
In "Transferred to {name}", "{name} didn't answer" and "{name} left the call", the name falls back to "a colleague". "Transferring to" and "Sent to voicemail for" use the colleague's full name, with no fallback in the code.
Error text comes from the server. Only the default and offline strings are known.
No toast for: starting Ask first, hold / unhold, the rep's own cancel, or anything on the colleague's side.
One call at a time: starting a second call shows the error toast "You are already on a call. Please end the call before making a new one." (phone_call_service.dart:500-510). The old busy-disabled Call tab is retired.
Where they overlap, the call card sits above toasts (the card is above the app's navigator). UNVERIFIED on device.
Motion: a 250ms fade + height reveal (Material 3 floating SnackBar). UNVERIFIED, not drawn.
The toast glyph is fa-solid (the atom specimen's weight; the app's weight is UNVERIFIED).