はじめに
こんにちは。この記事は株式会社カオナビ Advent Calendar 2025の7日目の記事です。
2年前、無謀にもAdvent Calendar1人完走チャレンジに挑みました。
今年はカオナビのメンバーとして参加することができました。
当時みんなでワイワイするのにちょっと憧れていたので、お祭り感覚で楽しんでいます！
改めまして、カオナビでフロントエンドエンジニアとして働いているおでこ。です。
日本発のOSS UIライブラリ「Yamada UI」のメンテナーをしております😎
この記事では、私がYamada UIで担当しているIssueから得た学びを共有します。
先にこの記事で伝えたいことを書きます。
- UIライブラリーを提供する上で、ライブラリを利用する開発者の気持ちを想像することが大切
- ドキュメントには開発者が使いやすくなるように、必要な情報を記載する
取り組んでいるIssue
私が取り組んでいるのは、Yamada UI v2.0のドキュメントサイトの各コンポーネントページに、アクセシビリティのドキュメントを追加するIssueです。
先日v2.0がリリースされましたが、現在のドキュメントサイトにはv1.0にあったコンポーネントのアクセシビリティに関する記載がありません。
このIssueではv2.0の実装を確認しながら、v1.0の内容を参考にドキュメントを更新します。
コンポーネントごとにOSSのコントリビュート初心者向けに用意されているgood first issueとして公開していて、比較的取っ付きやすいです。
Yamada UIのアクセシビリティ
前提として、Yamada UIはWAI-ARIAのオーサリング・プラクティス・ガイドラインに準拠しており、さまざまな最新ブラウザや一般的に使用されている支援技術でテストされています。
アクセシビリティに関連する多くの難しい実装の詳細、例えばariaやrole属性、フォーカス管理、キーボードナビゲーションなどをライブラリ側で処理しています。
詳細はこちらをご覧ください。
Tagドキュメントの更新で抱いた疑問
Tagのドキュメントを更新するIssueに取り組んでいるときでした。
v1.0のドキュメントには、以下のようにデフォルトのaria-labelを上書きする方法が記載されています。
Tagは、onCloseが設定されると閉じるボタンを表示します。この閉じるボタンのaria-labelは、デフォルトで"Close tag"を設定しています。もし、aria-labelを任意の値に変更したい場合は、closeButtonPropsにaria-labelを設定します。<Tag onClose={() => {}} closeButtonProps={{ "aria-label": "Close custom tag" >}}> Tag </Tag>
Yamada UIでは、この閉じるボタンのようにライブラリ側であらかじめ設定しているaria-labelがいくつかあります。
例えばColorPickerのEyeDropperを開くボタンにはaria-label="色を選択する"が設定されています。
eyeDropperPropsにaria-labelを設定することで任意の値に変更することができます。
<ColorPicker eyeDropperProps={{ "aria-label": "好きな色を選ぶ" }}/>
このように、Yamada UIではライブラリ側でaria-labelを設定しているところは、すべて開発者側で上書きできるように実装されています。
しかし、v1.0のドキュメントでaria-labelの上書き方法について記載されているのはTagのみでした。
ここでなぜTagだけ記載しているのか分かりませんでした。全部上書きできるんだから全てのページに書く、もしくは全部書かない方が良いのではないかと思いました。
v2.0ではどのように記載するか迷ったので、Yamada UIの作者である山田さん本人に質問しました。
ライブラリを使う開発者の気持ちを想像する
山田さんに質問した
私: 「v1.0のドキュメントでは、Tagだけaria-labelを上書きする方法が書いてあるのですが、v2.0ではどうしたらいいですか？」
山田さん: 「他はなくてもいいけど、Tagにはaria-labelを上書きする方法が書いてあった方がいいと思う。なんでだと思う？」
私:（こういう時は、「やったほうがいい理由とやらない方がいい理由」を天秤にかけろと山田さんに以前教わったな...）
私: 「やった方がいい理由は、開発者がaria-labelを上書きしたいと思った時、ライブラリの内部実装を調べなくてもドキュメントを見れば方法がわかるから親切」
私: 「やらない方がいい理由はドキュメントの記載が多くなって煩わしさを感じる」
山田さん:「浅いよ〜、もっとユーザーの気持ちを想像しなくちゃ」
私:（確かに私の考えではTagだけ記載する理由が説明できない...）
山田さん:「Tagがどんな時に使われるか考えてみてよ」
私: （TagはECサイトだったら商品の分類とか、Qiitaのようなブログサイトだったら記事に書かれている内容を分類するために使われる。そのタグを閉じるボタンだから...）
Tagの使われ方を想像する
さて、みなさんはこの理由が分かりましたか？
理由は、Tagは開発者がaria-labelを上書きすべきケースが圧倒的に多いコンポーネントだからです。
Tagはアイテムを説明するキーワードを使用して分類または整理するコンポーネントです。
そのため、開発者が「どの画面で」「何のために」配置するかによって、ユーザーが受け取るべき意味が変わります。
例えばTagは以下のような場面で使用されます。
-
検索フィルターとして使う: 閉じるボタンの意味は「条件を解除する」
-
適用中のクーポンを表示する: 閉じるボタンの意味は「クーポンの適用を取り消す」
-
タスク管理のカテゴリを表示する: 閉じるボタンの意味は「タスクとカテゴリの紐付けを外す」
つまり、見た目は同じコンポーネントでも、「そこで何を表現しているか」によって、閉じるボタンを押した時の振る舞いが全く異なるのです。
従って、Tagを使うときには開発者が状況に合わせてaria-labelを設定するべきです。
とはいえ、ライブラリとしてaria-labelを必須にするのは思想が強すぎる、かえって使いづらさを生んでしまうため、開発者が設定しなくても問題ないようにデフォルト値を設定しています。
よって、デフォルト値を設定してあるけど開発者側でaria-labelを設定して欲しいし、開発者目線でも上書きしたいケースが多いはずだから、Tagはドキュメントにその方法を書くべきだということです。
一方、ColorPickerのEyeDropperを開くボタンは開発者側で上書きしたいケースがほぼないでしょう。どんなところで使われたとしても、ライブラリ側で設定しているaria-label="色を選択する"で問題ないはずです。
上書き可能なように実装はしてありますが、ほぼあり得ないならドキュメントに書くのはむしろノイズです。デフォルト値が設定されていることだけ記載しておけば十分でしょう。
これが、Tag以外のコンポーネントには記載しない理由です。
まとめ
UIライブラリを提供するときは、ライブラリを利用する開発者の気持ちを想像することが大切だと学びました。
特にドキュメントサイトはYamada UIを使ってくれる人に向けたものなので、この考えに基づいて必要な情報を記載することが求められます。
ちょうどYamada UIに新規コンポーネントを追加しようとしているので、このコンポーネントを使う人は、いつ・どこで・どのように使うかを想像して、使いやすいものを作り上げたいと思いました。
終わりに
今回紹介したのはgood first issueですが、内部実装を見てariaやroleで何が設定されているかなどを確認する必要があるので、単なるコピペでは達成できない難しさがあります。
それでも、挑戦するとライブラリの考え方・実装、アクセシビリティも同時に学ぶことができるので、吸収できるものが多いと思います！
もし興味を持ってくださる方がいたら、ぜひコントリビュートをお待ちしております😎