[Feature Request]: Contextual Hover-Help Tooltips in UI #233
Description
[Feature Request]: Contextual Hover-Help Tooltips
🧭 Epic
Title: Contextual Hover-Help Tooltips
Goal: Surface concise, always-visible explanations for every primary action in the Admin UI by adding lightweight hover (and focus) tooltips.
Why now: New administrators often ask what "Add New Tool" or the ⚙️ "Test" icon actually do. Embedding the guidance inline eliminates context-switching to docs and reduces onboarding time.
🧭 Type of Feature
- Enhancement to existing functionality
🙋♂️ User Story 1 – Creation Buttons
As a: Gateway administrator
I want: clear tooltips on every "Add New …" button
So that: I instantly understand what gets created before clicking.
✅ Acceptance Criteria
Scenario: Tooltip on "Add New Server"
Given I am on the "Virtual Servers Catalog" panel
When I hover OR keyboard-focus the "➕ Add New Server" control
Then a tooltip appears within 200 ms reading
"Creates a new Virtual Server by combining Tools, Resources & Prompts from global catalogs."
And the tooltip disappears when the control loses hover/focus
Scenario: Tooltip on other creation buttons
Given I am on each catalog panel (Tools, Resources, Prompts, Gateways, Roots)
When I hover/focus the respective "Add New …" control
Then I see the tooltip text listed in "Tooltip Copy Map" (below)🙋♂️ User Story 2 – Action Buttons
As a: Gateway administrator
I want: hover help for critical row-level actions (⚙️ Test, 🔄 Activate/Deactivate, 🗑️ Delete)
So that: I avoid unintended destructive operations.
✅ Acceptance Criteria
Scenario: Tooltip on Deactivate action
Given a tool row shows "Deactivate"
When I hover/focus the link
Then a tooltip reads "Temporarily disables this item (can be re-activated)."
Scenario: Tooltip on Delete action
Given a row shows "Delete"
When I hover/focus the link
Then a tooltip reads "Permanently deletes this item – cannot be undone."🙋♂️ User Story 3 – Accessibility & Theme Support
As a: keyboard-only or screen-reader user
I want: tooltips to appear on focus and expose ARIA aria-describedby text
So that: the guidance is available without a mouse and in both light/dark modes.
✅ Acceptance Criteria
Scenario: Keyboard focus
When I tab to any actionable element with a tooltip
Then the tooltip becomes visible
And the element has aria-describedby linking to the tooltip content
Scenario: Dark mode
Given I toggle dark mode
Then tooltip styling remains legible (contrast ratio ≥ 4.5:1)📝 Tooltip Copy Map
| Location | Control | Tooltip text |
|---|---|---|
| Virtual Servers Catalog | Add New Server | Creates a new Virtual Server by combining Tools, Resources & Prompts from global catalogs. |
| Global Tools | Add New Tool | Registers a new Tool from an existing REST or MCP endpoint. |
| Global Resources | Add New Resource | Uploads or links a reusable data asset (file, URI, or text). |
| Global Prompts | Add New Prompt | Creates a reusable message template with parameters. |
| Gateways / MCP Servers | Add New Gateway | Registers an external MCP server and imports its catalogs. |
| Roots | Add New Root | Registers a base directory that MCP servers can browse for files. |
| Row action – Test | Test | Execute this Tool with sample inputs. |
| Row action – Activate | Activate | Re-enable an inactive item. |
| Row action – Deactivate | Deactivate | Temporarily disable this item (can be re-activated). |
| Row action – Delete | Delete | Permanently delete this item – cannot be undone. |
📐 Design Sketch (optional)
sequenceDiagram
participant User
participant UI
participant Tooltip
User->>UI: hover/focus Add New Tool
UI->>Tooltip: show(text, position)
User-->>UI: mouseout/blur
UI->>Tooltip: hide()
🔗 MCP Standards Check
- Pure front-end change; no protocol impact
- No breaking changes to existing MCP integrations
🔄 Alternatives Considered
| Approach | Pros | Cons |
|---|---|---|
| Inline help text under each control | Always visible | Visual clutter, harder to scan |
| Link to docs | Zero code | Forces context-switch; slows workflow |
| Onboarding tour | Rich guidance | One-off; doesn’t help day-to-day |
Chosen: Always-available tooltips—minimal effort, maximal clarity.
📓 Additional Context
- Use a lightweight Tailwind + Alpine pattern (
relativewrapper ➜absolutetooltip) to avoid extra JS libraries. - Ensure tooltip hides on scroll to prevent orphaned bubbles.
- Follow IBM accessibility guidelines for timing (appear ≤ 200 ms, disappear ≤ 300 ms).
- Not yet in scope: strings added to i18n bundle