# Icon-only Tooltip Rule

## Essence

Rule for accessible browser-native tooltips on unlabeled interactive controls.

Every interactive control without a visible text label must expose a tooltip that describes the action.

## Hook

Use when an interactive element is represented only by an icon or visual mark.

## Internal Rules

- Applies to all interactive controls without visible text labels.
- Current MVP tooltip mechanism is the native `title` attribute.
- Tooltip text describes the action or result.
- Tooltip text must not describe only the icon shape.
- Disclosure controls use action-specific labels:
  - collapsed: `Expand submenu`;
  - expanded: `Collapse submenu`.
- Do not build custom tooltip UI until a dedicated tooltip component exists.

## Use When

- An icon-only button is interactive.
- A disclosure icon can expand or collapse content.
- A visual-only control needs a readable action label on hover.

## Do Not Use When

- The control already has a visible text label.
- The icon is decorative and not interactive.
- A component has a dedicated visible label or accessible name pattern.

## Edge Cases

- If the icon changes shape but the action stays the same, keep the tooltip action text the same.
- If the action changes with state, update tooltip text with state.
- Tooltips are not a substitute for proper accessible names.
- Browser-native tooltip timing and styling are intentionally browser-controlled for MVP.

## Accessibility Notes

- Tooltip text should match the control action.
- Icon-only controls still need accessible names.
- Keyboard users should not depend only on hover tooltip behavior.
- Future custom tooltip work needs its own component and accessibility rules.

## Related Components And Patterns

- `Disclosure Icon Button`: uses this rule for expand/collapse tooltip text.
- `Collapsible Menu Item`: indirectly depends on the rule in clickable mode.
- Prop Naming Rule: keeps tooltip-related state names consistent.

## Code Paths

- `apps/portfolio-site/src/pages/design-system/index.astro`
- `packages/design-system/src/components/DisclosureIconButton.astro`