Susegad UI Accessibility GitHub

How this site looks

The view settings need JavaScript. Every page reads well without them.

Mood

The same pages, in three moods.

Theme

Components

Tooltip

A trigger and its accessible description, always linked by aria-describedby so the text reaches assistive technology whether or not it is shown. Quiet is a plain small label; warm hand-letters it; playful adds a pencil leader line. Without JavaScript, CSS alone reveals it by opacity on hover and focus.

quiet warm playful

Open the live demo npx @susegad/cli add tooltip

Stands on: Core, Core: components, Tokens

The prompt

the prompt

A word said quietly, at the elbow: a small label, a hand-lettered note, a note on a pencil line.

A trigger and its accessible description, linked by aria-describedby whether or not the tooltip is ever shown. Warm hand-letters it; playful draws a leader line to the trigger.

<link rel="stylesheet" href="susegad/components/tooltip/tooltip.css">
<script type="module" src="susegad/components/tooltip/tooltip.js"></script>

<sg-tooltip>
  <button aria-describedby="cancel-note">Free cancellation</button>
  <span id="cancel-note" role="tooltip">No charge up to 48 hours before arrival.</span>
</sg-tooltip>

The prompt

Make a tooltip web component around a trigger and a role="tooltip" element that follows it. Always link them with aria-describedby, filled in on connect if the builder left it off, so a screen reader has the text at all times, never only on hover. Style the panel with CSS alone for the no-JS path: position it absolutely above the trigger, and reveal it only by animating opacity (never display or visibility, which would remove it from the accessibility tree) on the trigger's real :hover and :focus-visible. Give it three registers by CSS alone, keyed off [data-skin]: quiet is a plain small label; warm switches to the hand face at a slightly larger size; playful adds a thin leader line, a ::after pseudo-element, between the panel and the trigger, on whichever side the panel actually landed. Then enhance with JavaScript: turn the panel into a popover, "hint" where el.popover = 'hint' reads back as 'hint' (feature detection, since the browser silently normalises an unknown value away otherwise), "manual" elsewhere, so it draws in the top layer, free of any clipping ancestor; show it after a short delay on pointerenter (ignore pointerType === 'touch', so a stuck hover never happens on a phone) and instantly on focus; hide it on pointerleave/blur and on Escape; place it above the trigger by default and below when there is little room above, using a pure function of the trigger's box, the panel's size and the viewport so the flip decision is unit tested without a browser. Place the panel with CSS anchor positioning, above the trigger and flipped below when there is no room, and keep the measured placement only for a browser without it. Let it arrive and leave as a transition from its first frame.

Words to code

When you sayTechniqueWhat happens
always link them with aria-describedbyΩ honesty, never hover-onlytooltip.js merges the panel's id into the trigger's existing aria-describedby, so a screen reader always has the text, matching the rule that a tooltip's words are never the only place a meaning lives.
reveal it only by animating opacitynative first, no-JS pathtooltip.css's base rule needs no script; the panel stays in the accessibility tree the whole time, since opacity, unlike display, does not remove content from it.
feature detection, since the browser silently normalises an unknown value awayA7, doubt the instrumenthintSupported(doc) sets el.popover = 'hint' and reads it back; a browser that does not know "hint" resets it to "", so the read-back, not a guess, decides which value ships.
hover ignores pointerType === 'touch'; a touch tap toggles on pointeruphonest interactionA touch tap fires pointerenter with no matching pointerleave until a tap elsewhere, so hover never shows or hides for touch. A tap on the trigger toggles the panel on pointerup (WebKit never focuses a tapped button, so focus alone never fires), a press anywhere else hides it, and the trigger's own click is left alone.
fit the open panel to the visual viewport, in both placement paths, and read the gap from the stylesheeta phone's innerWidth liesvisibleBox(window) and fitShift(rect, box) in tooltip.core.js; #fit() sets --sg-fit-x (transform: translateX(...), and the playful leader follows it) and trims the hover bridge with --sg-bridge-l and -r. parseGap() reads --sg-tooltip-gap for the fallback. Never window.innerWidth.
a pure function of the trigger's box, the panel's size and the viewporttestabilityplacement() in tooltip.core.js takes plain numbers and returns { left, above }, unit tested for "room above", "flips below" and "clamped inside the viewport" in Node.
place the panel with CSS anchor positioning … above … flipped belownative first, with a fallbacktooltip.css under @supports (anchor-name: --a): bottom: anchor(top), justify-self: anchor-center, position-try-fallbacks: flip-block. tooltip.js names the anchor, drops its scroll and resize listeners, and reads the side the browser chose once, as it opens, for the playful leader line (data-above). placement() is the fallback.
the panel arrives and leaves as a transition, quiet 120 ms of opacity only, warm a short rise, playful the springCSS @starting-style, per registerA transition from @starting-style with transition-behavior: allow-discrete on display and overlay, so it can fade out in the top layer; --_dur, --_ease and --_rise are set per [data-skin]; reduced motion removes the transition, so the first frame is the finished one. overlay.check.mjs reads the first frame of each.
a plain trigger button is pressed: a 1 px settle in quiet, the colour shades in warm, a small give in playfulthe touch contractsg-tooltip > :where(button, a[href]):active answers with no transition and eases back in under 150 ms: quiet translate: 0 1px, warm an inset shade mixed toward --sg-text, playful scale: 0.97 released on --sg-ease-spring. Reduced motion keeps the shade and drops the movement; :root[data-sg-input=key] drops it for the keyboard.

Accessibility

  • The trigger's aria-describedby names the tooltip's text at all times; hover and focus only decide whether it is also shown.
  • Escape hides the panel without moving focus away from the trigger.
  • Touch users get the tooltip through focus, the same path as keyboard users.
  • Panel text holds WCAG contrast in every palette and theme (tested). Forced colours give the panel a real border instead of relying on its filled background.

Credit

The leader line is a common annotation convention, not tied to a specific tradition. No credit is owed beyond the drawing itself.

<sg-tooltip> wraps a trigger and its accessible description. The trigger's aria-describedby always points to the tooltip text, whether or not it is ever shown on screen, so a screen reader has it regardless of hover.

The tooltip's words must never be the only place a meaning lives. Put anything a person must know to act (a price, a deadline, a policy) in real text nearby too; use the tooltip for a helpful extra, not the only copy of something that matters.

Use

<link rel="stylesheet" href="susegad/components/tooltip/tooltip.css">
<script type="module" src="susegad/components/tooltip/tooltip.js"></script>

<sg-tooltip>
  <button aria-describedby="cancel-note">Free cancellation</button>
  <span id="cancel-note" role="tooltip">No charge up to 48 hours before arrival.</span>
</sg-tooltip>

Leave aria-describedby and the id off and the element wires them itself, as long as the trigger and the role="tooltip" element are both direct children, trigger first.

Attributes and properties

ValuesDefault
registerquiet, warm, playfulinherited
open (property, read only)booleanfalse

Registers

Look
quiet (and no JS)a plain small label
warmhand-lettered, in the hand face, a little larger
playfulthe same, with a pencil leader line pointing from the panel to the trigger

How it shows

Without JavaScript, CSS alone reveals the panel on :hover and :focus-visible, by opacity only (never display or visibility), so the accessible description is never hidden by the visual state either way. With JavaScript, the panel becomes a popover (hint where the platform understands it, else manual), drawn in the top layer so it is never clipped by an ancestor, shown after a short delay on hover (to avoid flicker while the pointer passes over the page) and instantly on focus, and dismissed by Escape or by leaving. It opens above the trigger by default and below it when there is little room above.

The panel is a popover in the top layer. Where CSS anchor positioning is supported it sits above its trigger, centred on it, and the browser flips it below when there is no room above (position-try-fallbacks: flip-block); elsewhere the element measures and places it (tooltip.core.js's placement(), with the gap read from --sg-tooltip-gap in tooltip.css by parseGap(), so the number lives in one place). Either way, the last step is fitting it to what a person can see: tooltip.js measures the open tooltip against window.visualViewport (its visibleBox() in the core; without one, the document's clientWidth) and, if it sits outside, slides it back to 8 px inside with a --sg-fit-x custom property that the stylesheet turns into a translateX. Not window.innerWidth: mobile Chromium widens it to fit overflowing content, and an anchored panel's containing block follows, so on a phone a panel opened near the right edge used to spill past the screen. fitShift() is pure and tested; the phone cells of the check press it at 390 px on a clean page and on a widened one, with and without anchor positioning. The panel is capped to the visible width less 16 px (--sg-fit-max), so a 22em hand-lettered warm panel no longer spills past a 320 px phone. The playful leader line is clipped with overflow: clip and a 10 px clip margin (the UA sheet's overflow: auto hid it), and --sg-lead-x puts it under the middle of the trigger however the panel was placed or slid. The fallback places from the trigger's top edge, never from innerHeight, which a phone widens, and the bridge is trimmed before data-open draws it. Anchored, position-try-fallbacks: flip-block did not move a warm panel (56 px tall) that the top edge of the screen cut by 4 px, a trigger 60 px down; #fit now puts it below by hand when it is cut there and there is room below, with top: anchor(bottom) and a margin of the gap (not a pixel top, which would stay behind when the page scrolls). and the invisible hover bridge stops at the visible edge, because a band past it was itself 24 px of sideways scroll on a phone. It arrives and leaves as a CSS transition from @starting-style: quiet is 120 ms of opacity, warm adds a short rise, playful a rise on the spring; reduced motion shows it at once. A plain trigger button that is a direct child is pressed like every Susegad control: 1 px in quiet, a shade in warm, a small give in playful.

Accessibility

How this component meets WCAG 2.2 level A and AA, criterion by criterion, how each was checked, and what your page still owns.

  • Meets 12
  • Meets with author's part 1
  • Not applicable 3
  • Does not meet 1
CriterionStatusHow it was checked
1.1.1 Non-text contentNot applicableThe tooltip is text, and it adds no image or icon. The trigger is the author's.
1.3.1 Info and relationshipsMeetsaria-describedby links the trigger to the panel's text at all times, so the text reaches assistive technology whether or not it is shown: packages/components/tooltip/tooltip.check.mjs, "no JS: the trigger already names the tooltip text as its description" and "no JS: the button carries the description in its accessible tree". packages/components/tooltip/tooltip.test.js: the CSS reveals the panel by opacity only, never display or visibility.
1.4.1 Use of colorNot applicableThe tooltip carries no meaning in colour.
1.4.3 Contrast (minimum)Meetspackages/components/tooltip/tooltip.test.js: "contrast: <palette> <theme>: the panel's text reads against its own background" (the panel is --sg-surface text on a --sg-text ground, tested for every palette in light and dark). axe: tools/axe.mjs --url /packages/components/tooltip/demo.html: 0 violations across 6 runs (three registers, light and dark, desktop), 2026-10-07.
1.4.4 Resize textMeetsManual test, 2026-10-07: demo with the root font size at 200 percent at 1280 px, three registers, nothing wider than the screen (throwaway Playwright script). The panel is sized in em with max-width: 22em and width: max-content: packages/components/tooltip/tooltip.css.
1.4.10 ReflowMeetsManual test, 2026-10-07: demo at 320 CSS px, three registers, page width 320, no sideways scroll (throwaway Playwright script). With JavaScript the panel is clamped inside the viewport (tooltip.test.js, "placement: centred on the trigger, clamped inside the viewport"). On a phone (a touch, isMobile context at 390 px, a trigger pinned to the right edge) tooltip.check.mjs "<register>, phone, <clean or widened page>[, JS fallback]: a tooltip opened from the right edge stays inside the visual viewport" and "opening it adds no sideways scroll to the page" measure the open tooltip against visualViewport and the page with tools/lib/overflow.mjs; before the fix the tooltip sat past the screen on a widened page and, even on a clean one, its hover bridge added 24 px of sideways scroll.
1.4.11 Non-text contrastNot applicableThe tooltip is a text panel with no control or state of its own; its focus is the trigger's, which is the author's.
1.4.12 Text spacingMeetsManual test, 2026-10-07: the WCAG text-spacing values (line height 1.5, letter 0.12em, word 0.16em, paragraph 2em) injected on the demo, three registers, page width 320 with no sideways scroll (throwaway Playwright script). The panel grows with its text (width: max-content). No check in the repository asserts it yet.
1.4.13 Content on hover or focusDoes not meetWith JavaScript it meets all three parts. Dismissible: while the panel is open, Escape closes it wherever focus is, including with the pointer alone and no focus on the trigger, without moving focus (packages/components/tooltip/tooltip.js, a keydown listener on the document while open; packages/components/tooltip/tooltip.check.mjs: "<register>: pointer on the <trigger or panel>, no focus: Escape closes it and focus does not move", which failed on the trigger in all three registers before the fix, and passes in Chromium, WebKit and Firefox). Hoverable and persistent: the shown panel takes the pointer (pointer-events: auto while open), and the 8 px gap between trigger and panel belongs to the tooltip too, through two invisible bands as tall as the gap (--sg-tooltip-gap, 8 px) on the element itself, above and below the trigger (sg-tooltip[data-open]::before and ::after in packages/components/tooltip/tooltip.css; they sit on the element, not the panel, because the panel's overflow: auto clipped a bridge drawn on it, and each band stops where the gap stops, so neither the trigger nor a button one gap away is covered: tooltip.check.mjs, "a click 1 px inside a button one gap below the trigger lands on that button", which failed with 12 px bands). Leaving the element (trigger, panel or bands) hides it after 300 ms. tooltip.check.mjs: "<register>: the point midway across the 8 px gap belongs to the tooltip (the panel or its bridge), not the page" (the element at that point was the page's section before the fix), "the pointer rests in the gap for 450 ms (longer than the 300 ms hide delay) and the tooltip is still open" (red with the bands removed), and "moving the pointer onto the panel keeps it open", in all three registers in Chromium, WebKit and Firefox. Without JavaScript it does not meet the dismissible part: CSS alone reveals the panel on :hover and :focus-within, and CSS cannot answer a key, so Escape does nothing (manual test, 2026-10-07, JavaScript off: opacity 1 on hover and still 1 after Escape, a reviewer's probe). The no-JS reveal is hover and focus on the trigger, which the reader ends by moving away.
2.1.1 KeyboardMeetsThe trigger is the author's native control, reached by Tab, and focus opens the panel at once: packages/components/tooltip/tooltip.check.mjs, "<register>: focus opens it instantly, no delay". Escape closes it (see 1.4.13). The panel itself is not a control and takes no focus. On touch a tap on the trigger reveals it (tooltip.check.mjs: "touch: a tap on the trigger shows the tooltip", "it stays open while the reader reads", "a second tap on the trigger closes it", "a tap elsewhere closes it", and "the tap still pressed the button"), in Chromium, WebKit and Firefox.
2.1.2 No keyboard trapMeetsManual test: packages/components/tooltip/tooltip.js takes no focus and binds keydown only for Escape (on the trigger, and on the document while the panel is open), which closes the panel without moving focus; Tab and Shift+Tab are untouched.
2.4.3 Focus orderMeetsThe panel is never focusable, so it adds no tab stop, and the trigger keeps its place in the page's order (packages/components/tooltip/tooltip.js). Focusing the trigger opens it at once: tooltip.check.mjs, "focus opens it instantly, no delay".
2.4.7 Focus visibleMeetstools/touch.check.mjs --only tooltip requires and proves a focus style in each register on the trigger; the rule is sg-tooltip :is(button, a, [tabindex]):focus-visible in packages/components/tooltip/tooltip.css.
2.4.11 Focus not obscured (minimum)Meets with author's partThe panel sits above the trigger, or below it when there is no room above, never over it: tooltip.check.mjs, "the panel opens below a trigger with no room above" (panelTop >= triggerBottom - 2). It does not take focus. A sticky header or banner the page adds can cover a trigger that is scrolled to.
2.5.3 Label in nameMeetsThe trigger is named by its own visible text; the tooltip adds only aria-describedby, never aria-label (packages/components/tooltip/tooltip.js).
2.5.8 Target size (minimum)MeetsManual test, 2026-10-07 (throwaway Playwright script): the trigger is the author's control, and on the demo at 390 px with touch, in each register, every trigger at least 124 by 47 px (127 by 49 in playful).
4.1.2 Name, role, valueMeetsThe panel is role="tooltip" and described by the trigger's aria-describedby; tooltip.check.mjs reads button "Free cancellation" with its description, with JavaScript off and on, and the touch probe shows it on a tap that focuses the button. axe: tools/axe.mjs --url /packages/components/tooltip/demo.html: 0 violations across 6 runs (three registers, light and dark, desktop), 2026-10-07.

The page author owns:

  • Loading the script on any page where a tooltip's text is more than a hint: without it the panel cannot be dismissed with Escape (1.4.13).
  • The trigger: a real <button> or link with its own name, and the tooltip's words, in the language of the page, and lang on a tooltip in another language (3.1.2).
  • Never putting a meaning someone must act on (a price, a deadline) only in a tooltip: say it in real text nearby too.
  • Sticky headers and banners that could cover the trigger when it takes focus (2.4.11).

How it behaves

  • aria-describedby links the trigger to the tooltip's text at all times.
  • Touch: a tap on the trigger shows the tooltip and a second tap hides it; a tap anywhere else, or Escape, hides it too. It reacts to pointerup, so it works in WebKit, which never focuses a tapped button, and the trigger's own click still fires once (tooltip.check.mjs, the "touch:" cells, with a real tap in Chromium, WebKit and Firefox).
  • Escape dismisses it without moving focus.
  • The panel's background and text hold 4.5:1 contrast in every palette and theme (tested).

All 57 tables, and how the library tests

Budget

Behaviour 4.4 KB (tooltip.js + tooltip.core.js); skins quiet, warm and playful are each a no-op mount, under 0.2 KB: the look is entirely in tooltip.css, keyed off [data-skin], [data-open] and [data-above].