docs(spindle-ui): add Tooltip component design doc

[yu-3in]

新規で作成するTooltipコンポーネントのDesign Docと実装を追加しました。

意思決定ポイント

コンポーネントの命名

現状ではホバーした際に表示するいわゆる一般的なツールチップは提供せず、クリックした際に表示する形式（トグルチップ形式）のみを提供しますが、将来的にツールチップも提供する可能性があるため、ToggletipではなくTooltipとしてコンポーネントを設計しています。

コンポーネント設計

最終的にパターン3を採用しました。

パターン1: 利用者が手動で管理

<>
  <IconButton ref={triggerRef} aria-describedby="tooltip-1">
    <Information aria-hidden="true" />
  </IconButton>
  <Tooltip.Frame id="tooltip-1" triggerRef={triggerRef} open={open}>
    <Tooltip.Content>テキスト</Tooltip.Content>
  </Tooltip.Frame>
</>

Pros:

• シンプルで明示的
• 完全な制御が可能

Cons:

• id、triggerRef、aria-describedby、aria-expandedを手動管理
• アクセシビリティ対応の負荷が高く実装漏れのリスク
• ボイラープレートコードが多い

パターン2: text propで完全自動化

<Tooltip text="テキスト">
  <IconButton>
    <Information aria-hidden="true" />
  </IconButton>
</Tooltip>

Pros:

• ボイラープレートなし
• id、aria-*属性などを自動付与

Cons:

• 他コンポーネントと異なる設計（Frame/Trigger/Content構造ではない）

パターン3: Frame/Trigger/Content

<Tooltip.Frame open={open} onClose={handleClose}>
  <Tooltip.Trigger>
    <IconButton aria-label="詳細情報" onClick={handleClick}>
      <Information aria-hidden="true" />
    </IconButton>
  </Tooltip.Trigger>
  <Tooltip.Content>
    補足情報
  </Tooltip.Content>
</Tooltip.Frame>

Pros:

• リッチなコンテンツ対応
• id、aria-*属性などを自動付与
• 他コンポーネントと同じ設計
• 拡張性・柔軟性が高い

Cons:

• パターン2より若干冗長

[changeset-bot]

⚠️ No Changeset found

Latest commit: fc2c4a1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Visit the preview URL for this PR (updated for commit fc2c4a1):

https://ameba-spindle--pr1642-docs-tooltip-ypys8osb.web.app

_{(expires Fri, 16 Jan 2026 10:02:14 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: e7521619a2dd5c653490c8246e81ec2a5c8f1435}

[reg-suit]

reg-suit detected visual differences.

Check this report, and review them.

🔴 Changed	🔵 Passing
5	251

How can I change the check status?

If reviewers approve this PR, the reg context status will be green automatically.

[yasuda-shin]

idの名前ってもうちょっとわかりやすくって思ったんですが、
そもそも自動で付与されるということは利用者側はid考慮しなくてもいい感じなんですかね？

[yu-3in]

Reactの useId() で生成する想定です。
利用者側はidを認知する必要はないです。

[tokimari]

:naruhodo:

[yasuda-shin]

たぶんツールチーっぷのとんがり部分を表現するためのdivだと思うんですけどできれば空divよりかはCSSの擬似要素あたりでできるとよきかもです。
空タグあまり使わない方がいいかと思いまして。

[yu-3in]

たしかにです！擬似要素使わずともいけそうだったのでこちらで修正しました：8e9bdc2

[yasuda-shin]

いちお質問なんですが文字数って何文字でもいれれる認識であってます？

[yu-3in]

何文字でもOKです！

[yu-3in]

あまりに長いのは想定していません。

Tooltip内に多くの情報やインタラクションを含めないでください

DO NOTにも一応、長すぎるのは良くない旨入れてます。

[tokimari]

WAI-ARIA難しい・・

[yu-3in]

@tokimari
docs(spindle-ui): レビューでの指摘事項を修正
こちらで指摘いただいた点諸々修正しました。

#1642 (comment) の件だけデザイナ確認中です。

[tokimari]

🙏

[yu-3in]

Controlled mode（open propあり）とUncontrolled mode（open propなし）の概念を追加し、それぞれに対応するようにしました。（差分大きめです）
3e60100

[yu-3in]

Uncontrolled modeでは role="tooltip" は復活してます

[yu-3in]

ここまでの議論の自分なりのまとめ

Tooltipで clickとhover/focusを一緒にやろうとしているので、role="tooltip" として一律扱えずにややこしい。
role="tooltip" を使わずに aria-expanededを使えば解決するが、 hover/focusパターンにおいてそれはベストではない（できればrole="tooltip"を使いたい）

Tooltipは一般にはhover/focusでトリガーされるものTooltipにclickの機能は本来なら持ち込まれるべきではない。
もしclickでトリガーしたければPopoverにすべき。

一般に広く使われるTooltipには閉じるボタンがない。というのも、例えばキーボード操作でfocusでトリガーした時にTooltip内の閉じるボタンにアクセスする術がない。
一方で、Spindleではチュートリアルで使われる用途を想定していそうなので、閉じるボタンはつけたい。のではないか。（推論）

結論：Spindleがやろうとしているのは、TooltipではなくPopoverなのではないか。

[tokimari]

（施策の方のPRを見る前に前提理解のために覗きました！ 🙏 ）

概ね良さそうに思いました！！ 🎉
細かい点いくつか確認お願いします〜！

[tokimari]

comment. 実装上複雑になるならこの要件なくても良いかもなとは思いました（実装時に確認）

[yu-3in]

defaultOpen={true} の時はrole="tooltip"を使わないと一律に書いていたのですが、正しくは defaultOpen={true}で初期表示時のみだったので全体的に修正中です

[yu-3in]

一旦全て修正完了してます！

[tokimari]

良さそうな気がします・・！
デザイナーに仕様の再確認はおねがいしたいです 🙌

[yu-3in]

実装詳細の話になりますが、元々の設計だと cloneElement を使う想定で設計されており、 cloneElement はReactでは推奨されていない（ソース）ため設計を変更しました。
具体的には Tooltip.Trigger のchildrenをrender propsパターンに変更しました。
ced72b7

[yu-3in]

諸々デザイナーとコンセンサス取れました。
また、 #1695 にてすでに実装を進めており、その過程で以下の点について変更すべきだと判断したため反映してます：eef7097

• タッチデバイスにクリックはないのでclick/tap->tapのみに
• triggerのrender propで渡すものに onMouseEnter, onFocus, onBlur, onPointerDown を追加
• サンプルのトリガーはIconButtonのsize="exSmall", variant="neutral"に変更（より実際に使われやすいものに変更する意図）
• 閉じるボタンにはIconButtonは使わない（svg含むボタンのサイズのデザイン要件が異なるため。最小サイズが24pxだがそれだとSPで要件を満たさない）
• 初期表示のみ表示するパターンではトリガー要素は表示し続けるように変更

[tokimari]

あとは良さそうに思いました 🙌

[tokimari]