docs(spindle-ui): add Tooltip component design doc by yu-3in · Pull Request #1642 · openameba/spindle

yu-3in · 2025-11-20T05:30:36Z

新規で作成する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 · 2025-11-20T05:30:40Z

⚠️ 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 · 2025-11-20T05:32:59Z

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 · 2025-11-20T05:34:05Z

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 · 2025-11-25T04:23:25Z

+  <button class="spui-IconButton" aria-label="詳細情報" aria-describedby=":r1:" aria-expanded="true">
+    <svg aria-hidden="true"><!-- Information icon --></svg>
+  </button>
+  <div id=":r1:" class="spui-Tooltip-frame spui-Tooltip-frame--information spui-Tooltip-frame--top spui-Tooltip-frame--center" role="tooltip">


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

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

yasuda-shin · 2025-11-25T04:34:51Z

+        <svg aria-hidden="true"><!-- Cross icon --></svg>
+      </button>
+    </div>
+    <div class="spui-Tooltip-arrow"></div>


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

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

yasuda-shin · 2025-11-25T04:35:12Z

+  </button>
+  <div id=":r1:" class="spui-Tooltip-frame spui-Tooltip-frame--information spui-Tooltip-frame--top spui-Tooltip-frame--center" role="tooltip">
+    <div class="spui-Tooltip-content">
+      <div class="spui-Tooltip-text">ここに補足情報が入ります。</div>


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

何文字でもOKです！

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

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

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

tokimari

WAI-ARIA難しい・・

yu-3in · 2025-11-26T05:44:29Z

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

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

tokimari

🙏

…sにも対応する

yu-3in · 2025-11-27T02:27:54Z

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

yu-3in · 2025-11-27T02:31:04Z

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

yu-3in · 2025-11-27T06:37:54Z

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

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 · 2025-12-03T02:48:04Z

+- 初期状態で表示される
+- **初期表示時のみ**閉じるボタンが表示される
+- 一度閉じた後、hover/focusまたはclick/tapで再表示できる
+- **再表示時は閉じるボタンが表示されない**（通常のTooltipと同じ挙動）


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

yu-3in · 2025-12-03T05:24:02Z

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

yu-3in · 2025-12-03T07:41:59Z

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

tokimari

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

yu-3in · 2025-12-08T08:41:23Z

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

yu-3in · 2025-12-09T08:13:48Z

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

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

tokimari

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

tokimari

yu-3in self-assigned this Nov 20, 2025

yu-3in force-pushed the docs/tooltip branch from 12fa0cd to 6ccae5c Compare November 20, 2025 09:50

docs(spindle-ui): tooltip component design doc

5353d45

yu-3in force-pushed the docs/tooltip branch from 6ccae5c to 5353d45 Compare November 21, 2025 08:12

yu-3in changed the title ~~docs(spindle-ui): tooltip component design doc~~ docs(spindle-ui): add Tooltip component design doc Nov 25, 2025

yu-3in requested review from herablog, tokimari and yasuda-shin November 25, 2025 02:36

yasuda-shin reviewed Nov 25, 2025

View reviewed changes

docs(spindle-ui): 擬似要素を使わずに矢印を表現する

8e9bdc2

yu-3in requested a review from yasuda-shin November 25, 2025 05:16

tokimari reviewed Nov 25, 2025

View reviewed changes

docs(spindle-ui): レビューでの指摘事項を修正

15b8c23

yu-3in force-pushed the docs/tooltip branch from 88117ad to 15b8c23 Compare November 26, 2025 05:43

tokimari reviewed Nov 26, 2025

View reviewed changes

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md Outdated

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md Outdated

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md Outdated

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md Outdated

docs(spindle-ui): controlled modeとuncontrolled modeの概念を追加し、hover/focu…

3e60100

…sにも対応する

tokimari reviewed Nov 27, 2025

View reviewed changes

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md Outdated

tokimari reviewed Nov 27, 2025

View reviewed changes

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md Outdated

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md Outdated

yu-3in added 2 commits November 27, 2025 13:56

docs(spindle-ui): do/do notにFigmaに記載の仕様を忠実に含める

3bdf1cd

docs(spindle-ui): toggletipについての言及の文言を改善

9217a9b

docs(spindle-ui): modeを廃止し、defaultOpenやcloseOnClickOutside propを新たに追加…

6f808cb

…し仕様を再整理

yu-3in force-pushed the docs/tooltip branch from 9ebeb37 to 6f808cb Compare December 2, 2025 02:48

tokimari reviewed Dec 3, 2025

View reviewed changes

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md Outdated

yu-3in added 5 commits December 3, 2025 13:26

docs(spindle-ui): closeOnClickOutsite propを削除

fe76116

docs(spindle-ui): 初期表示ありの場合と機能を持つ要素の関係性について言及

d5e03d2

docs(spindle-ui): アクセシビリティチェックリストを更新

f678a49

docs(spindle-ui): 校正

513f3dd

docs(spindle-ui): defaultOpenがtrueの場合はrole groupをつける

672dff1

docs(spindle-ui): defaultOpenがtrueでも再表示時は通常のTooltipの挙動とする

3237f84

yu-3in requested a review from tokimari December 3, 2025 07:42

tokimari reviewed Dec 4, 2025

View reviewed changes

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md

docs(spindle-ui): triggerのchildrenをrender propsパターンに変更

ced72b7

yu-3in force-pushed the docs/tooltip branch from 3de5f92 to ced72b7 Compare December 8, 2025 09:02

docs(spindle-ui): 実際に実装して一部変更

eef7097

yu-3in requested a review from tokimari December 9, 2025 08:13

tokimari reviewed Dec 11, 2025

View reviewed changes

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md Outdated

yu-3in added 2 commits December 11, 2025 12:29

docs(spindle-ui): onPointerUpを追加し、ポインタ操作のキャンセルができるように項目を追加

093cfea

docs(spindle-ui): figmaに合わせてチュートリアルをオンボーディングに文言統一

2c534f4

yu-3in requested a review from tokimari December 11, 2025 04:05

docs(spindle-ui): スクリーンショットを4種類のツールチップを比較するテーブルの画像に差し替え

6efaa4b

yu-3in force-pushed the docs/tooltip branch from a512c29 to 6efaa4b Compare December 11, 2025 04:10

yu-3in mentioned this pull request Dec 11, 2025

feat(spindle-ui): add Tooltip component #1695

Draft

5 tasks

tokimari reviewed Dec 12, 2025

View reviewed changes

Comment thread packages/spindle-ui/src/Tooltip/design-doc.md

docs(spindle-ui): タッチデバイスの判定の詳細設計を追加

fc2c4a1

yu-3in requested a review from tokimari December 19, 2025 10:05

tokimari approved these changes Dec 22, 2025

View reviewed changes

yu-3in merged commit 178000a into main Dec 22, 2025
11 checks passed

yu-3in deleted the docs/tooltip branch December 22, 2025 01:51

Conversation

yu-3in commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

意思決定ポイント

コンポーネントの命名

コンポーネント設計

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

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

パターン3: Frame/Trigger/Content

Uh oh!

changeset-bot Bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions Bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

reg-suit Bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tokimari left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yu-3in commented Nov 26, 2025

Uh oh!

tokimari left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yu-3in commented Nov 27, 2025

Uh oh!

yu-3in commented Nov 27, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yu-3in commented Nov 27, 2025

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

Uh oh!

tokimari left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yu-3in commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

yu-3in commented Nov 20, 2025 •

edited

Loading

changeset-bot Bot commented Nov 20, 2025 •

edited

Loading

github-actions Bot commented Nov 20, 2025 •

edited

Loading

reg-suit Bot commented Nov 20, 2025 •

edited

Loading

yu-3in commented Dec 3, 2025 •

edited

Loading

yu-3in commented Dec 8, 2025 •

edited

Loading

tokimari left a comment •

edited

Loading