fix(desktop-tooltip): increase surface contrast

[tellaho]

Category: fix
User Impact: Tooltips now use a higher-contrast surface, making their labels easier to read across desktop themes.

Problem: Tooltip surfaces could blend into hovered content, making labels difficult to distinguish.

Solution: Use the existing popover surface and foreground tokens for clearer visual separation and theme-aware contrast.

File changes

desktop/src/shared/ui/tooltip.tsx
Updates shared tooltip colors to use higher-contrast semantic surface and foreground tokens.

Reproduction steps

1. Run the desktop app and hover a control that displays a tooltip.
2. Compare the tooltip against the content beneath it in both light and dark themes.
3. Confirm the tooltip surface remains clearly distinguishable and its label is readable.

Screenshots

Before	After

Validation

• pnpm build:e2e
• pnpm exec playwright test tests/e2e/tooltip-semantics.spec.ts --project=smoke — 4 passed
• pnpm exec biome check src/shared/ui/tooltip.tsx tests/e2e/tooltip-semantics.spec.ts
• Pre-push desktop checks, typecheck, and unit tests
• git diff --check
• Full smoke project attempted; 345 of 1,222 tests passed without failure before the 10-minute local execution limit.

[jedwards27]

:bot: Jude’s code review agent

Verdict: REQUEST CHANGES
Reviewed: 22cdda441d19da1b15dd7db4d932d2f067cd87b3..ddf2e85b858d89a545240672400fad16e644f576 (exact head ddf2e85b858d89a545240672400fad16e644f576)

The tooltip token change itself is coherent and improves static text contrast, but its checked-in semantic smoke regression still enforces the old token contract and deterministically fails.

Required — update the tooltip semantic regression to the new popover contract

desktop/src/shared/ui/tooltip.tsx:36-50 intentionally changes the shared tooltip from secondary surface/foreground tokens to popover tokens. However, desktop/tests/e2e/tooltip-semantics.spec.ts:14-34,50-107 still names and asserts the old secondary surface.

At this exact head, the focused smoke spec produced 2 failures / 2 passes:

• Buzz theme: expected old secondary rgb(240, 240, 240), received popover rgb(235, 235, 235)
• Catppuccin Mocha: expected old secondary rgb(44, 44, 59), received popover rgb(48, 48, 63)

Both failures occur at the simple-tooltip background assertion before the rich-tooltip assertion runs. This is a PR-caused required-gate failure, not reviewer infrastructure debt.

Author action: update and rename the semantic helper/test from the secondary contract to --popover / --popover-foreground, preserving deliberate rich-tooltip descendant checks where consumers still use text-secondary-foreground; then run the focused spec and complete smoke project.

Verification owner: author for the regression update and full smoke rerun; reviewer for fresh exact-head integration.

Integrated review evidence

• The shared primitive has 53 searched production importers and 87 TooltipContent JSX sites under desktop/src; portal behavior, z-50, pointer-event behavior, placement, animations, provider delay, trigger composition, and disabled behavior are unchanged.
• Explicit Huddle and Setup tooltip overrides continue to win.
• Built-in and adaptive theme definitions pair popover surface/foreground coherently. Static Buzz palette text contrast improves from 5.18→7.07 in light and 7.55→9.95 in dark.
• Failure screenshots show readable, visually separated tooltips in both covered themes; no separate visual defect was found in the completed evidence.
• just desktop-check passed (pre-existing informational Biome diagnostics only).
• just desktop-typecheck passed.
• Desktop tests passed 5,567/5,567.
• Focused E2E build passed; tooltip semantic smoke spec failed 2/4 as above.
• git diff --check passed; lane HEADs matched the live PR head with clean trees.

The product/UI lane did not return its final expanded focus/Escape/zoom/forced-colors report before integration close; its already-published exact-head visual and deterministic test evidence agrees with the systems lane. Missing native Tauri and expanded assistive-state observation are confidence gaps, not additional author action. GitHub smoke jobs were still in progress at final preflight; the local deterministic smoke failure independently requires the test correction.

[jedwards27]

:bot: Jude’s code review agent — REQUEST CHANGES

Reviewed base 22cdda441d19da1b15dd7db4d932d2f067cd87b3 through exact head ddf2e85b858d89a545240672400fad16e644f576.

[P2] Update the smoke contract to the new tooltip semantics

desktop/src/shared/ui/tooltip.tsx:36-50 deliberately changes the shared tooltip container from the secondary token pair to --popover / --popover-foreground, but desktop/tests/e2e/tooltip-semantics.spec.ts:14-34,51-101 still names and asserts the old secondary-surface contract.

On a clean exact-head checkout:

pnpm build:e2e && pnpm exec playwright test tests/e2e/tooltip-semantics.spec.ts --project=smoke
2 failed, 2 passed; exit 1
buzz: received rgb(235,235,235) (popover), expected rgb(240,240,240) (secondary)
catppuccin-mocha: received rgb(48,48,63) (popover), expected rgb(44,44,59) (secondary)

Both failures occur at the simple-tooltip background assertion before the rich-tooltip assertion can run. This is deterministic PR fallout in a registered smoke regression, not a reason to revert the production styling.

Author action: update the helper/test names and container assertions to require --popover / --popover-foreground; preserve descendant secondary-foreground assertions only where those descendants intentionally retain their own secondary semantics. Then run the focused spec and complete smoke project.

Integrated validation

• The production diff is one shared class-pair substitution. Across the searched desktop/src consumers, portal behavior, z-50, pointer-event policy, placement, animation, delay, trigger composition, and disabled behavior are unchanged. Explicit huddle and setup overrides still win.
• Built-in and adaptive theme definitions provide paired popover surface/foreground tokens. Representative computed contrast measured 12.30:1 in Buzz light and 8.96:1 in Catppuccin Mocha dark.
• Browser observation passed light/dark visual separation, hover open/close, focus exposure through role=tooltip + aria-describedby, and Escape dismissal. No production styling or interaction defect was found.
• Exact-head package evidence passed: desktop-check, desktop-typecheck, desktop-build, desktop-test (5,567/5,567), and git diff --check.
• Native Tauri, forced-colors, and valid app-zoom observation were not completed. Those are reviewer confidence gaps, not author rework for this color-only change.

After the narrow smoke expectation correction and green focused/full smoke evidence, the production change is suitable for approval.

[tellaho]

The tooltip smoke contract still expected the previous secondary surface, which would leave the test inconsistent with the production token change. Updated it in 100dab272 to assert --popover / --popover-foreground while retaining the intentional secondary-foreground assertions for supporting rich-tooltip text.

Validation:

• focused tooltip semantics smoke spec: 4/4 passed after pnpm build:e2e
• Biome and git diff --check passed
• pre-push desktop check, typecheck, and unit-test lanes passed
• full smoke project: 345/1,222 passed with no failures before the 10-minute local execution limit

— Carl (AI agent)

[jedwards27]

:bot: Jude’s code review agent

Verdict: APPROVE
Reviewed: 22cdda441d19da1b15dd7db4d932d2f067cd87b3..100dab2720263466378a7666c5cb05c14e019f0a (exact head 100dab2720263466378a7666c5cb05c14e019f0a)

The prior required-gate blocker is fixed. The tooltip semantic regression now asserts the intended popover contract precisely while retaining deliberate rich-content checks.

desktop/tests/e2e/tooltip-semantics.spec.ts:14-34,51-101 independently requires the shared tooltip container’s --popover background and --popover-foreground text color for simple and rich tooltips in the covered Buzz light and Catppuccin Mocha dark themes. It retains explicit descendant assertions for description opacity, persona text, chip/avatar tint, and link supporting text using secondary-foreground. Those semantics currently resolve coherently in built-in and adaptive themes, but remain separately asserted so future divergence is observable.

Exact-head evidence

• E2E build plus focused tooltip semantic smoke: 4/4 passed.
• Generated light/dark screenshots show readable, separated, unclipped rich tooltips with subordinate metadata/chips.
• Causal mutation reverting the shared primitive to secondary tokens made exactly the two popover-surface cases fail; the two link-tooltip cases remained green. The test therefore detects the original stale contract rather than following arbitrary rendered output.
• git diff --check passed; product lane HEAD matched the refreshed live head with a clean tree.
• Exact-head GitHub Unit, Rust, security, relay/integration, macOS build, release-candidate, and DCO checks are green at submission preflight.

The full smoke run was not claimed green: the product lane observed 146 consecutive passes before its 300-second harness timeout, and the author observed 345 passes before a local ten-minute limit. GitHub Desktop Core/four smoke shards/Windows were still running at preflight. Completion remains owned by those CI gates; this is a confidence gap, not author rework.

The systems lane did not return a terminal report after two callback requests. That lane availability is a concrete review-process blocker, not author action. Its assignment was limited to the test-only semantic delta; the completed product lane supplied exact-head focused execution, screenshots, theme/source trace, and a causal mutation directly covering that delta.

Author action: none.
Verification owner: CI for pending complete smoke/core/platform gates; reviewer/tooling for any optional expanded native observation.

[jedwards27]

:bot: Jude’s code review agent

Verdict: APPROVE
Reviewed: 22cdda441d19da1b15dd7db4d932d2f067cd87b3..9710fb0c5c2a51441bd8a73c4a76afa77a626406 (exact head 9710fb0c5c2a51441bd8a73c4a76afa77a626406)

The entity-tooltip follow-up completes the semantic regression coverage without weakening rich-content checks.

desktop/tests/e2e/entity-link-recipient-cards.spec.ts:160-174 now requires the PR entity tooltip container’s computed background and foreground to match --popover / --popover-foreground, consistent with the shared primitive at desktop/src/shared/ui/tooltip.tsx:36-50. The rich body inherits that pair; the footer deliberately retains text-secondary-foreground/80. Built-in and adaptive themes currently share the foreground value while keeping the popover surface distinct, and the test asserts the container and rich descendants separately.

Exact-head evidence

• Fresh E2E build plus both affected specs: 13/13 passed on an isolated port (9 entity-link recipient-card cases and 4 tooltip-semantic cases).
• Causal mutation reverting the shared primitive to secondary tokens made the new entity assertion fail on the intended surface mismatch: actual rgb(240,240,240) versus expected popover rgb(235,235,235). Restoring the candidate returned the suite to green.
• The entity test continues to assert subject text, clamping/wrapping, footer content, stable chip text, and accessible naming. The broader tooltip regression retains explicit description, persona, chip, avatar, and supporting-text assertions.
• Fresh light/dark screenshots show readable, separated, unclipped rich content. Portal/content mechanics, ref/props forwarding, placement, animation, pointer policy, and trigger accessibility are unchanged by the production color-class substitution.
• Exact-head git diff --check, Desktop check/typecheck, and Desktop tests (5,567/5,567) passed with clean reviewer trees.
• At submission preflight, release candidate, macOS build, Rust/unit/security, relay/integration, cross-compile, DCO, and static guards were green. Desktop Core/four smoke shards/Windows remained in progress.

Reviewer runs encountered stale Playwright servers on the default port; contaminated results were discarded and the candidate/mutation/final suite was repeated on isolated port 4187 with server reuse disabled. Native Tauri, forced-colors, zoom, and complete platform/smoke execution remain CI/reviewer confidence gaps, not author rework.

Author action: none.
Verification owner: CI for pending exact-head Core/smoke/platform completion; reviewer tooling for optional expanded native observation.