Stop Tooltips from Saying Nothing: Contextual Help and Tooltips for Vibe Projects

The most common way a tooltip dies is appearing when the user does not need it, or, when they do need it, saying something useless. "Click here to submit the form" next to a submit button is useless; "After submitting, we will email you the result within one working day, and you do not need to resubmit meanwhile" in the same place is useful. The difference is not position but information: a tooltip should only explain the "why," never repeat what the label already says.

All examples in this article are fictional, including product names such as "Songguo Bookkeeping" and "Qinghe Shop," as well as people and copy examples. They were invented to explain the method and should not be cited as real product cases.

What deserves a tooltip: only the "why"

There is a simple filter for whether information belongs in a tooltip: if the user does not know this, will they fill something in wrong, choose wrong, or hesitate to click Next? If yes, it belongs; if no, leave it out. Never repeat what the label already says. If the button says "Save," the tooltip should not say "Click to save your changes." What users need is the other half the label does not say: what happens after saving, what consequences an option carries, or how a number is calculated.

Four kinds of information deserve tooltips. First, consequences: what happens when this option is chosen, especially irreversible or slow consequences, such as "Once enabled, past bills will not be recalculated; only new bills are affected." Second, definitions: how a number, status, or tier is defined, such as "Active users means accounts that logged in at least once in the past thirty days." Third, format and source: what format a field needs and where to find it, such as "The order number is in the top right of the confirmation email: ten digits." Fourth, exceptions: rules that hold most of the time but differ in a few cases, such as "Weekend withdrawals are processed on Monday."

Three kinds do not belong. First, instructions for the control itself: if a button's purpose needs a tooltip to explain, the button copy or layout is the problem; fix the button instead of patching it with a tooltip. Second, marketing copy: a tooltip is not an ad slot, and "Upgrade to unlock more" next to a free feature only makes users feel sold to. Third, full legal text: one summary sentence plus a "View full terms" link is enough; stuffing several hundred words of terms into a bubble means nobody will finish reading it, and nobody will remember it if they do.

Fictional example: next to Songguo Bookkeeping's "Auto-categorise" switch, the original tooltip read "Enable the auto-categorisation feature." Users still did not know whether to turn it on, because their real question was "Will my manually categorised bills be changed?" Changing it to "Once enabled, only new bills are affected; bills you categorised by hand will not change" made the question disappear. A good tooltip answers the question the user has not said out loud, rather than restating the switch's name.

Choosing a trigger: desktop has hover, phones do not

Trigger choice is not an aesthetic decision; it is a device reality. Desktop has mouse hover; mobile does not. Keyboard users use focus; touchscreen users use tap and long-press. Each trigger has its use and its cost, and choosing wrong means the tooltip either annoys people or never appears at all.

Hover suits lightweight desktop supplements: the user rests the mouse on a small question-mark icon, the tooltip appears, and it disappears when the mouse moves away. Its cost is discoverability: users who do not know something is hoverable will miss it. The remedy is a consistent visual marker for hoverable elements, such as a permanently visible question-mark icon, rather than making users guess which text is hoverable. Hover tooltips must never carry critical information, because touchscreen and keyboard users cannot trigger them at all; critical information must also appear elsewhere, such as persistent small text under the field.

Tap is the most universal trigger, especially on mobile: tap the question-mark icon, the tooltip appears as a bubble or bottom sheet, and tapping again or tapping elsewhere closes it. Its cost is an extra tap, so it suits places where users genuinely seek help. Do not put tap tooltips on every field; that turns the interface into a wall of question marks. Use tap tooltips only for the four categories that pass the filter, and leave the rest empty.

Focus triggers are for keyboard users: tabbing to a field or icon shows the tooltip, and moving focus away hides it. Many teams build hover and tap but forget focus, leaving keyboard users never seeing tooltips at all. In implementation, make the trigger element focusable, and do not let the tooltip itself steal focus, or the keyboard tab order will break.

Long-press on mobile is an option, but use it cautiously. Its discoverability is low, and it easily conflicts with the system's own long-press menus and text selection. If you use long-press, always provide a tap entry as an alternative; never rely on long-press alone. There is also an easy trap: building a tooltip that appears only on hover and is entirely absent on touchscreens effectively abandons half your users. Mobile has no hover — that is ironclad — so anything that only appears on hover must have a tap or persistent-text alternative on mobile.

The three-line rule for tooltip copy: answer first, reason second

Write tooltip copy in up to three lines. Line one gives the answer, directly addressing the user's question, with no preamble or pleasantries. Line two gives the reason or consequence, only when the user needs it to judge. Line three gives a destination, only when the user may need more help, such as "Full rules: Help Centre, 'Withdrawal timing'." Three lines is a ceiling, not a target: if one line suffices, never write three.

Compare good and bad copy. Bad: "This feature is used to set your preferences so the system can serve you better." It says nothing, and after reading it the user still does not know whether to turn it on. Good: "Once enabled, new bills are auto-categorised by merchant; bills you categorised by hand will not change." Line one is the answer, line two is the consequence, and there is no line three because none is needed. Another bad example: "Please enter a valid phone number." That is an error message, not a tooltip. Good: "We only use this number to send you verification codes, never for sales calls." It answers what the user is actually worried about: will this number be misused?

Copy has three hard rules. First, plain language, no jargon: write "The money arrives one day later," not "The settlement cycle is T+1." Second, no hedging with "maybe" or "possibly": confirm uncertain rules with the backend or business side first, and if they cannot be confirmed, state the boundary clearly — "Deferred over weekends" is far more useful than "Usually fairly fast." Third, numbers must be concrete: write "Within one working day," not "As soon as possible"; write "Past thirty days," not "Recently." A vague tooltip is worse than no tooltip, because it gives users the false impression that they now know something.

Test tooltip copy with the product: find three people who have never seen the feature, let them read the tooltip, then ask "Do you now know what to choose?" If two of the three still have follow-up questions, the copy is not done. Copy is written for first-time users of the feature, not for product managers.

Frequency control: show it the first time, stop nagging by the tenth

How often a tooltip appears annoys users more easily than what it says. The same tooltip is help the first time a user sees it and harassment the tenth time. Frequency control splits into three cases: first appearance, repeat appearance, and persistent hints.

First appearances can be proactive, but only once. When a new feature ships or a user first reaches a complex field, the tooltip may appear automatically to help them over the first hurdle. But auto-appearing tooltips must be dismissible at a glance, with a large, obvious close button, not a tiny cross users must hunt for. Only one auto-appearing tooltip at a time; three bubbles at once will scare users away.

Repeat appearances must be restrained. A tooltip the user has seen and dismissed should not pop up again every time they return to the page. Record "seen" or "dismissed" state, and by default keep it collapsed next time, leaving only the question-mark icon for users to open deliberately. One exception: if the rule changed and the tooltip content changed, it may appear proactively once more, but mark it "Rule updated" so users know this time is worth another look.

Persistent hints are a different approach: instead of relying on bubbles, write key information as small grey text permanently under the field. This suits information users need every time they fill in a field, such as "Withdrawal amounts must be multiples of ten." Persistent text costs space, so reserve it for genuinely frequent, genuinely error-prone information. Low-frequency information gets bubbles; high-frequency, error-prone information gets persistent text. Do not mix the two, and never show the same information as both a bubble and persistent text — users will feel nagged.

Frequency control should also read the "user has learned this" signal: if a user repeatedly skips a tooltip and never makes mistakes in that field, they have learned it, and the system can downgrade that tooltip to icon-only. But downgrading is a system behaviour; never quietly remove the entry point for users actively seeking help. The question-mark icon stays, and tapping it always shows content.

Division of labour with the help centre and onboarding: three tools, three jobs

Contextual help, the help centre, and first-use onboarding are three different tools, and mixing them makes them compete with each other. The division can be stated in one sentence: tooltips solve "I don't understand this one thing right here," the help centre solves "I want to systematically understand a topic," and onboarding solves "This is my first time here and I don't know what to do first."

Tooltips handle immediate, specific, short questions — one field, one switch, one number — capped at three lines. Anything that cannot be explained within three lines should not be squeezed into a bubble; instead, give one sentence plus a link to the matching help-centre article. Link text must state the destination, such as "See full withdrawal timing rules," not just "Learn more": users should know where they are going before they click.

The help centre handles systematic knowledge: rules, processes, policies, and FAQ collections. Tooltips should not restate the first paragraph of a help-centre article; they should give only the conclusion plus a link. Conversely, help-centre articles should not be plastered with tooltip screenshots; that reverses the two tools' responsibilities. The connection point is the link: tooltip gives the conclusion, link gives the full text, with nothing broken in between.

Onboarding handles the sequence of first use: what to do first, what next, and what you get when done. It teaches the path, not the knowledge points. Tooltips should not take on onboarding's job: do not scatter a "beginner tip" bubble beside every field in an attempt to split onboarding into a dozen bubbles. When users first arrive, give them a clear guided path; once they start operating on their own, let tooltips appear at specific sticking points. The order cannot be reversed: path first, knowledge points second.

The test for this division is to lay one help-centre article, one onboarding round, and ten tooltips side by side and check for overlap above half. If a tooltip and a help-centre article say the same paragraph, the tooltip is too long; if every onboarding step explains field meanings, onboarding has overstepped. Where overlap exceeds half, cut one of the two.

Accessibility: reachable by keyboard, readable by screen readers

Tooltip accessibility is not a bonus; it is the baseline. Keyboard users must be able to tab to the trigger, open the tooltip with Enter or Space, close it with Esc, and return focus to the trigger on close. If opening a tooltip steals focus and closing it loses focus entirely, keyboard users get lost. Test by unplugging the mouse and walking every page with tooltips using only the keyboard; if you cannot walk it, it fails.

Screen reader users need two things. First, the trigger must have readable text, such as "About auto-categorisation," not an icon-only element that reads out as just "button." Second, when the tooltip appears, the screen reader must be able to read its content: put the content in the accessibility tree associated with the trigger, or announce it politely when it appears — never aggressively, interrupting what the user is already hearing. After closing, do not leave unreadable leftover text behind.

Several easily missed points: tooltips must not rely on colour alone to convey meaning — do not use only a red bubble for warnings; add text such as "Note." Contrast must pass: light grey text on a light bubble is unreadable for low-vision users. Tooltip show and hide animations must not flash or zoom rapidly; users sensitive to motion must be able to turn animations off. Accessibility testing needs no expensive equipment: walk it with a keyboard, listen with a screen reader, and view it at large font size and high contrast. Those three passes surface most problems.

Dark mode and small screens: tooltips must not only look good on light, large screens

Tooltips fail most easily in dark mode: a pale yellow bubble that looks fine in light mode can become a glaring block in dark mode, or its text can blur into the background. The rule is: bubble background, text, border, and shadow must all have dark-mode values; do not change only the page background and leave the bubble. In dark mode, the bubble background should be slightly lighter or darker than the page to create hierarchy, but not with excessive contrast — a pure white bubble on a pure black page glares. Shadows barely work in dark mode, so rely on borders and brightness differences for hierarchy.

Small-screen rules are more concrete: bubble width must not exceed screen width minus margins on both sides; for triggers near the screen edge, the bubble must flip direction automatically rather than being cut in half by the screen; long tooltips on small screens should become bottom sheets instead of being squeezed into a thin, tall bubble. Bottom sheets on small screens have three advantages: enough width, a close button within finger reach, and no risk of being pushed off-screen by the keyboard. The pass bar is simple: at the smallest common phone width, tap every element with a tooltip; if no bubble is cut off, none covers the field being typed, and the close button is tappable, it passes.

Dark mode and small screens belong on the pre-release checklist, not in post-release user feedback. Before sign-off, make a table: light desktop, dark desktop, light mobile, dark mobile — one screenshot with a tooltip in each combination, featuring the longest tooltip. If the longest tooltip is fully readable in all four combinations, the adaptation passes.

A self-check checklist for tooltip copy

Check every tooltip against this list before shipping. Information screening: the tooltip answers the question the user has not said out loud, rather than restating the label; it falls into one of the four categories — consequence, definition, format/source, exception; it is not an instruction, marketing copy, or legal text. Trigger: when desktop has hover, mobile has a tap or persistent-text alternative; critical information is not hover-only; keyboard focus triggers it, Esc closes it, and focus returns to the trigger on close.

Copy: the first line is the answer; if one line suffices, never write three; no jargon, no hedging words like "maybe" or "as soon as possible," numbers are concrete; three people who have never seen the feature know what to choose after reading it. Frequency: first appearance is proactive only once and dismissible at a glance; dismissed tooltips stay collapsed next time, leaving only the icon; when rules change and tooltips reappear proactively, the change is marked; high-frequency, error-prone information uses persistent small text rather than repeated bubbles.

Division of labour: anything that needs more than three lines becomes one sentence plus a help-centre link, with link text stating the destination; no restating help-centre articles, no teaching the onboarding path. Accessibility and adaptation: walkable by keyboard alone; readable by screen readers, both trigger and content; information not conveyed by colour alone; dark-mode values for background, text, and border; at the smallest phone width, bubbles are not cut off, do not cover the input, and the close button is tappable.

One final reminder: the ultimate test of a tooltip is not how beautifully it is written, but whether error rates in that field fall after it appears. Ship a tooltip, run a week of data, and check whether error rates and support inquiries for that field changed. A tooltip with no change means something is wrong — the wrong information, the wrong trigger, or copy that misses the point. The data will tell you which one.