Skip to main content

UIの状態パターン

画面を設計する際は、通常の表示に加え、読込中や入力エラーなどの状態を確認する。 このページは、AIと開発者が画面ごとの状態一覧を作るための日英用語集と記入規則を定める。 英語名は、この文書で共通タグとして採用する名称である。 実装の変数名やライブラリ固有の名称を変更する必要はない。

状態用語と分類はこのページを正本とする。 製品固有の状態ケースは、対象画面のScreen Specへ統合する。 複数画面や複数機能で同じ成立条件と振る舞いを使う場合は、Pattern Specへ切り出す。

画面と対象UIと状態の関係​

状態一覧の基本構造は「画面 → 対象UI → 状態」である。 画面全体も1つの対象UIとして扱う。 確認ダイアログやトーストは、それを表示する画面の配下に置く。

情報意味例
画面利用者が作業する場所商品一覧画面、商品編集画面
対象UI独立して状態を確認する単位商品一覧、価格入力欄、保存ボタン
部品種別対象UIが持つ共通の役割Table、TextField、Button
状態タグ対象UIがある時点で満たす条件Loading、Invalid、Focused
業務状態製品が扱う対象の業務上の段階商品の下書き、注文の支払済み

対象UIは、表示や操作の違いを独立して指定する必要がある粒度で記録する。 アイコンやラベルも、それ自体の状態を確認する必要がある場合に記録する。 同種の入力欄が複数あれば、「商品名入力欄」と「価格入力欄」のように役割で区別する。 部品種別の名称はコンポーネント命名用語集を参照する。 部品種別は複数指定でき、半角カンマで区切る。 たとえば、入力欄とラベルとエラー表示をまとめて確認する対象UIには、TextField, Label, FormMessageと記入する。 各部品の状態を独立して確認する必要がある場合は、対象UIを分ける。 画面全体には、状態一覧用の部品種別としてScreenを使う。 これは実装するコンポーネント名を指定するものではない。

状態ケースは、対象UIと状態タグの組み合わせに成立条件を付けた、確認可能な一項目である。 同じタグでも、条件や期待する動作が異なれば別のケースとして記録する。 たとえば、初回読込中と再読込中は、ともにLoadingを使い、ケースを分ける。

共通の状態用語集​

分類は、状態を同時に付けられるか判断するための軸である。 一覧にない状態が必要な場合は、意味の近い既存タグとの違いを確認してから追加する。 分類名や部品名は、状態タグとして扱わない。

データ取得​

同じ対象の同じ取得処理では、次の状態のうち1つを選ぶ。

英語タグ日本語名意味と成立条件対象UIの例
Idle未開始取得をまだ開始していない検索実行前の結果領域
Loading読込中取得を開始し、応答を待っている一覧、詳細領域
Loaded取得完了取得に成功し、応答内容が確定した取得後の一覧
Error取得失敗取得に失敗し、結果を得られなかった再試行を案内する一覧

Loadedは、結果が0件でも使う。 Errorの際に直前のデータを残す場合は、次のデータ内容のタグと併用する。 失敗の原因と再試行の可否は、ケースの成立条件と期待する操作に記載する。

データ内容​

同じ対象に表示するデータの範囲を固定し、次の状態のうち1つを選ぶ。

英語タグ日本語名意味と成立条件対象UIの例
Populatedデータあり表示対象が存在し、必要な内容が揃っている商品のある一覧
Empty未登録元のデータが0件で、検索や絞り込みによる除外ではない初回利用時の一覧
NoResults該当なし検索や絞り込みの結果が0件である検索結果一覧
Partial一部欠損表示対象はあるが、必要な内容の一部が欠けている画像未登録の商品カード

初回の読込中など、データの有無を判断できない場合は、この分類のタグを付けない。 再読込中に既存データを表示する場合は、LoadingとPopulatedを併用できる。 Partialは値の欠損を表し、追加ページをまだ取得していないことは表さない。

入力検証と編集​

入力検証の分類と、保存内容からの変更の分類を分ける。 Pristineは未変更を表し、検証済みであることは意味しない。

分類英語タグ日本語名意味と成立条件対象UIの例
入力検証Unvalidated未検証現在の値に対する検証結果が未確定である初期表示の入力欄
入力検証Valid入力適合現在の値が検証規則を満たす検証後の商品名入力欄
入力検証Invalid入力エラー現在の値が検証規則に違反する必須項目が空の入力欄
編集Pristine未変更値が初期値または保存済みの値と一致する初期表示のフォーム
編集Dirty未保存の変更あり値が初期値または保存済みの値と異なる編集後のフォーム

操作と表示​

操作に関する状態は、細かい分類ごとに判断する。 フォーカスとホバーのように、別の分類の状態は同時に成立する場合がある。

分類英語タグ日本語名意味と成立条件対象UIの例
操作可否Enabled操作可能利用者が対象の操作を実行できる保存ボタン
操作可否Disabled操作不可対象の操作を受け付けない送信中のボタン
編集可否Editable編集可能値の変更を受け付ける編集用の入力欄
編集可否ReadOnly読み取り専用値を表示するが、変更は受け付けない参照用の入力欄
ポインターHoveredホバー中ポインターが対象の上にあるボタン
押下Pressed押下中ボタンなどを押している最中である通常のボタン
フォーカスFocusedフォーカス中キーボード入力や操作の対象である入力欄
選択Selected選択済み選択対象として選ばれているタブ、一覧の行
開閉Open開いている開閉する対象が開いている確認ダイアログ
開閉Closed閉じている開閉する対象が閉じている確認ダイアログ
通知表示Visible表示中通知が表示されているトースト
通知表示Hidden非表示通知が表示されていないトースト

ReadOnlyとDisabledは区別する。 読み取り専用の入力欄でも、値の選択やコピーを許可する場合があるためである。 フォーカスやコピーの可否は、対象UIの仕様として記録する。 Pressedは押下中の一時的な状態であり、選択を保持するSelectedとは異なる。

処理結果と認証と権限​

保存や削除などの更新処理は、データ取得と分類を分ける。 認証は利用者の識別、権限は操作の許可を表す。

分類英語タグ日本語名意味と成立条件対象UIの例
更新処理Ready実行前更新処理の実行中でも結果表示中でもない保存ボタン
更新処理Submitting送信中更新要求を送り、結果を待っている保存フォーム
更新処理Success処理成功更新が成功し、その結果を示している成功トースト
更新処理Failure処理失敗更新が失敗し、その結果を示している失敗トースト
認証Unauthenticated未認証利用者を識別できていないログインを案内する画面
認証Authenticated認証済み利用者を識別できているログイン後の画面
権限Allowed許可対象操作の実行が許可されている編集画面
権限Forbidden権限不足対象操作の実行が許可されていないアクセス拒否の画面

更新処理のタグは、ボタン、フォーム、結果通知のどこに付けても同じ意味で使う。 対象となる処理名を成立条件に記載する。 取得失敗はError、入力の不適合はInvalid、更新失敗はFailureで区別する。 認証や権限を判定中の場合は、確定済みのタグを推測で付けず、その条件を記載する。

別名と既存資料との対応​

次の対応は、この状態一覧に記入するときの規則である。 既存の部品名やStory名を一律に変更する規則ではない。

既存の表現や別名状態一覧での扱い
Hover、Focus、押下中を意味するActiveHovered、Focused、Pressedに対応する
Readonly、Read-onlyReadOnlyに統一する
Validation分類名として扱い、Unvalidated、Valid、Invalidを選ぶ
Loading,skeleton、Skeleton、Spinner状態はLoadingとし、表示方法を別に記す
Finished処理の成否を確認し、SuccessまたはFailureを選ぶ
Fetching、Pending、Error文脈を確認し、取得、更新、入力検証のどの状態か判断する
IdealStorybookで用いる理想状態のシナリオ名であり、通常はLoadedとPopulatedに対応する
StorybookのEmpty空状態の総称であり、一覧ではEmptyとNoResultsを条件で分ける
StorybookのPartial、Error一部欠損はPartial、取得失敗はErrorに対応する

命名と識別の規則​

画面と対象UIには、日本語名と英語の識別子をそれぞれ付ける。 画面IDはproduct-listのような小文字のケバブケースとし、製品内で一意にする。 対象UIのIDも同じ形式で、その画面内で一意にする。 対象UIは、product-list / resultsのように画面IDとの組で特定する。 状態名を対象UIのIDに埋め込まず、同じ対象を状態間で追跡できるようにする。

状態タグは用語集の英語名を大文字と小文字も含めてそのまま使う。 TextField.Invalidのように部品名を結合したタグは作らず、部品種別と状態を別々に持つ。 ケースIDは画面内で一意とし、list-initial-loadingのように確認内容を識別できる名前を付ける。 複数の更新処理などが同じ対象UIに含まれる場合は、対象UIを分けるか処理の範囲を明記する。

業務状態は、UI状態とは別の欄に記録する。 識別子はproduct.publication:Draftのように、対象、状態の軸、値を組み合わせる。 日本語名、定義、成立条件、同じ軸の排他的な値を製品側で定める。 たとえば「商品の公開状態」のDraftとPublishedは排他的である。 異なる業務状態を、同じDraftという語だけでまとめない。

共通タグを追加する場合は、分類、日本語名、英語名、成立条件、類似語との差、適用例を揃える。 製品固有の理由は成立条件に記載し、PaymentErrorなどを安易に共通タグへ追加しない。 部品種別、業務状態、表示方法のどれで表すべきかも先に確認する。

状態の組み合わせと網羅する範囲​

同じ対象UIの同じ条件では、次の分類内の状態は排他的である。

  • データ取得:Idle、Loading、Loaded、Error
  • データ内容:Populated、Empty、NoResults、Partial
  • 入力検証:Unvalidated、Valid、Invalid
  • 編集:Pristine、Dirty
  • 操作可否:Enabled、Disabled
  • 編集可否:Editable、ReadOnly
  • 開閉:Open、Closed
  • 通知表示:Visible、Hidden
  • 更新処理:Ready、Submitting、Success、Failure
  • 認証:Unauthenticated、Authenticated
  • 権限:Allowed、Forbidden

Hovered、Pressed、Focused、Selectedは、それぞれ独立して有無を判断する。 非該当であればタグを付けず、確認に必要なら「フォーカスなし」などを成立条件に書く。 タグがないだけでは「非該当」「未確認」「対象外」を区別できないため、判断を記録する。

異なる分類でも、成立条件に矛盾がないか確認する。 たとえば、通常の非編集型ダイアログにDirtyを付ける必要はない。 一方、InvalidとFocused、SubmittingとDisabledは併用できる。 業務状態とUI状態も、「公開済みの商品を読込中」のように併用できる。 子の入力欄がFocusedでも、親のフォームへ同じタグを自動的に付けない。

網羅するのは、適用される基本状態と、表示や操作の確認に意味がある組み合わせである。 全タグの直積を作ることは求めない。 再読込時のデータ保持、フォーカス中のエラー表示、二重送信防止などの違いを優先する。 仕様で成立しない状態や確認を省く組み合わせは、対象UIと理由を残す。 判断できない状態は対象外とせず、「要確認」として残す。

画面ごとの記入ひな型​

次のMarkdownをコピーし、画面、対象UI、ケースの順に記入する。 すべてのケースで同じ欄を使い、適用できない欄には理由を添える。 仕様の参照先は、合意済み仕様とAIの仮定を区別するために記録する。

## 画面:日本語名

- 画面ID:英語の識別子
- 目的:利用者が行う作業
- 仕様の参照先:文書の見出しやIssueなど
- 業務状態の定義:日本語名、識別子、成立条件、同じ軸の排他的な値

### 対象UI:日本語名

- 対象UIのID:画面内で一意の識別子
- 部品種別:TextField, Label, FormMessageなど(複数の場合は半角カンマ区切り、画面全体ならScreen)

#### ケース:日本語名

- ケースID:画面内で一意の識別子
- UI状態タグ:分類ごとの英語名
- 業務状態:識別子(適用しない場合は理由)
- 成立条件:データ、操作、認証、権限などの前提
- 期待する表示:表示内容、通知、既存データの保持など
- 可能な操作:利用者が実行できる操作
- 不可能な操作:受け付けない操作と理由
- 確認手順:前提の準備、操作、確認箇所を順に記載
- 未確定事項:要確認の内容(なければ「なし」)
- AIの仮定:仮に補った内容(なければ「なし」)

### 対象外の状態と組み合わせ

| 対象UIのID | 状態や組み合わせ | 対象外とする理由 |
| ---------- | ---------------- | ------------------------------------ |
| 対象のID | タグや成立条件 | 仕様上成立しない理由、確認を省く根拠 |

一覧画面と編集フォームの記入例​

以下は記入方法を示す架空の商品管理の仕様である。 このサイトに商品管理機能が存在することや、その仕様を決定することは意味しない。 例では、一覧の再取得中も商品を残し、公開済みの商品も編集できるものとする。 商品名は必須で、保存中は再送信を受け付けない。 削除には確認ダイアログを使い、保存結果はトーストで伝える。

画面と対象UIの一覧​

画面名画面ID対象UI名対象UIのID部品種別
商品一覧画面product-list商品一覧resultsTable
商品一覧画面product-list削除確認ダイアログdelete-confirmationAlertDialog
商品編集画面product-edit商品名入力欄product-nameTextField, Label, FormMessage
商品編集画面product-edit画面全体screenScreen
商品編集画面product-edit保存ボタンsaveButton
商品編集画面product-edit保存結果トーストsave-noticeToast

業務状態は「商品の公開状態」とし、product.publication:Draft(下書き)とproduct.publication:Published(公開済み)を定義する。 保存済みの公開設定が無効なら下書き、有効なら公開済みとし、同時には成立しない。 一覧は複数の商品を扱うため、一覧全体へ単一の公開状態を付けない。

階層で並べるケースの一覧​

次の一覧は、各ケースの表示と操作の差を先に確認するための要約である。 実際の状態一覧では、各行をひな型のケース欄へ展開して条件と確認手順を記載する。

商品一覧画面(product-list)​

対象UIのIDケースIDUI状態タグ表示と操作の確認点
resultslist-initial-loadingLoading初回読込の表示を確認する
resultslist-populatedLoaded, Populated商品を表示し、編集と削除ができる
resultslist-emptyLoaded, Empty未登録の案内から新規登録へ進める
resultslist-no-resultsLoaded, NoResults検索条件を変更できる
resultslist-partialLoaded, Partial画像未登録でも商品名から特定できる
resultslist-errorError初回取得の失敗後に再試行できる
resultslist-refreshingLoading, Populated表示中の商品を残して再取得する
delete-confirmationdelete-openOpen削除対象を示し、確認と取消ができる
delete-confirmationdelete-closedClosedダイアログを表示せず、一覧を操作できる

商品編集画面(product-edit)​

対象UIのIDケースIDUI状態タグ表示と操作の確認点
screenedit-initial-loadingLoading編集する商品の取得中を示す
product-namename-pristineUnvalidated, Pristine, Editable保存済みの値を表示する
product-namename-validValid, Dirty, Editable変更後の値を保持する
product-namename-invalid-focusedInvalid, Dirty, Editable, Focusedエラーとフォーカスを同時に示す
savesave-readyReady, Enabled適合した変更を保存できる
savesave-submittingSubmitting, Disabled処理中を示し、二重送信を防ぐ
save-noticenotice-successSuccess, Visible保存完了を通知する
save-noticenotice-failureFailure, Visible保存失敗を通知する
save-noticenotice-hiddenHidden通知を表示しない

一覧ケースの詳細​

  • 画面名と画面ID:商品一覧画面、product-list
  • 仕様の参照先:このページの「一覧画面と編集フォームの記入例」
  • 対象UI名とID:商品一覧、results
  • 部品種別:Table
  • ケースID:list-refreshing
  • UI状態タグ:データ取得=Loading、データ内容=Populated
  • 業務状態:適用しない(異なる公開状態の商品を含む一覧であるため)
  • 成立条件:商品が1件以上表示され、再取得の応答を待っている
  • 期待する表示:既存の商品を残し、読込中の表示を追加する
  • 可能な操作:再取得の完了を待つ
  • 不可能な操作:要確認(再取得中の編集と削除を許可するか未定義である)
  • 確認手順:商品を表示し、再取得の応答を保留して、商品と読込中の表示を確認する
  • 未確定事項:再取得中の編集と削除の可否
  • AIの仮定:なし

入力ケースの詳細​

  • 画面名と画面ID:商品編集画面、product-edit
  • 仕様の参照先:このページの「一覧画面と編集フォームの記入例」
  • 対象UI名とID:商品名入力欄、product-name
  • 部品種別:TextField, Label, FormMessage
  • ケースID:name-invalid-focused
  • UI状態タグ:入力検証=Invalid、編集=Dirty、編集可否=Editable、フォーカス=Focused
  • 業務状態:product.publication:Published(公開済み)
  • 成立条件:公開済み商品の入力済みの商品名を空にし、検証後に入力欄へフォーカスする
  • 期待する表示:必須エラーとフォーカスの表示を同時に確認できる
  • 可能な操作:商品名の再入力
  • 不可能な操作:不適合な値での保存(商品名が必須であるため)
  • 確認手順:公開済み商品を開き、商品名を空にして検証し、入力欄へフォーカスする
  • 未確定事項:検証の契機が入力中、フォーカス離脱時、保存時のいずれか
  • AIの仮定:検証の契機は仮定せず、確認手順の具体化を保留する

対象外と要確認の記録例​

画面IDと対象UIのID状態や組み合わせ判断理由
product-list / resultsIdle対象外この例では画面を開くと取得を開始する
product-list / delete-confirmationDirty対象外確認と取消のみで、編集項目がない
product-edit / saveSubmitting, Enabled対象外保存中は再送信を受け付けない
product-edit / product-nameInvalid, Hovered, Focused確認を省略この例ではホバーによる表示の変化がないものとする
product-edit / product-nameReadOnly要確認閲覧権限だけを持つ利用者への表示が未定義である

要約にない状態も、自動的に対象外にはならない。 実際の製品では、画面全体の認証と権限、再取得失敗、保存後の変更状態なども確認する。

共通タグで画面を横断して集める例​

画面ID、対象UIのID、部品種別、状態タグ、業務状態をそれぞれ別の条件として扱う。 部品種別の条件は、カンマで区切った種別のいずれかに一致するかで判断する。 抽出するのは対象UIのケースであり、その状態が構成部品のすべてに成立することは意味しない。 状態タグの条件は、ケースにそのタグが含まれるかで判断する。 複数タグを指定した場合は、すべてを含むケースを抽出する。

抽出条件上記の記入例で該当するケース
状態タグ=Loadingproduct-list / list-initial-loading、product-list / list-refreshing、product-edit / edit-initial-loading
状態タグ=Invalidproduct-edit / name-invalid-focused
部品種別=TextField、状態タグ=Focusedproduct-edit / name-invalid-focused
状態タグ=SubmittingかつDisabledproduct-edit / save-submitting
業務状態=product.publication:Published、状態タグ=Invalidproduct-edit / name-invalid-focused

Loadingで集めると、商品一覧と商品編集の両画面の読込中を抽出できる。 TextField.Invalidという専用タグを増やす必要はない。 将来、各ケースへ画像やプレビューを関連付ければ、同じ条件でギャラリーを構成できる。 このページでは記入規則を定め、絞り込み機能、ギャラリー、JSONやYAMLの形式は実装しない。

AIが状態一覧を作る手順​

  1. Screen Specと関連するFlow Spec、Feature Spec、Pattern Specを読み、参照先を記録する。
  2. 画面と対象UIを抽出し、日本語名、識別子、部品種別を付ける。
  3. 各対象UIについて、用語集の分類ごとに適用、対象外、要確認を判断する。
  4. 適用する基本状態の成立条件と、期待する表示と操作を記載する。
  5. 製品固有の業務状態を別欄で定義し、表示や操作が変わるケースへ付ける。
  6. 表示や操作に差が出る組み合わせを追加し、分類内の排他性と条件の矛盾を確認する。
  7. ケースごとに確認手順を具体化し、対象外の理由、未確定事項、AIの仮定を残す。
  8. 英語タグの表記ゆれ、IDの重複、同じ条件のケースの重複を点検する。
  9. 状態タグを1つ選んで画面を横断して集め、名称と意味が揃っているか確認する。
  10. 要確認の内容を仕様の決定者へ提示し、回答後に状態ケースと関連するUX仕様を更新する。

仕様に根拠がない動作を、確定した期待値として補わない。 仮定を使ったケースには、仮定した内容と影響する確認手順を明記する。 未確定の条件があるケースは、確認可能になったケースと区別して引き渡す。

関連文書​