ヒントボックス：使用するタイミングと方法

ヒントボックスは、近くのアクションをより簡単、迅速、明確、または信頼性の高いものにする1つのオプションのテクニックを強調表示します。装飾的な要約ではありません。読者はこれをスキップしてもタスクを正しく完了できます。

この実際の例には1つのアイデアが含まれており、それが改善するプラクティスの横に表示され、その利点を説明しています。色付きの境界線ではなく、これら3つの特性がヒントをヒントたらしめています。

この要素が重要な理由

読者はすべての文に等しい注意を払うわけではありません。指示や判断が多いページでは、まず必須の経路を探し、次に作業をより良くするショートカットやテクニックを探します。ヒントボックスは、異常に有用なオプションのアイデアに安定した境界を与えます。ラベルは、読者が注意を払う前に、「これは結果を改善できますが、完了と見なされるものは変わりません」と伝えます。

この区別は認知負荷、つまり読む際に人が保持し分類しなければならない情報の量を減らします。ラベルがないと、読者は余談が要件なのか、背景なのか、推奨なのかを推測しなければなりません。しかし、ラベルが多すぎると、ページは競合する2つ目の読み取り経路を作り出します。したがって、希少性はこの要素の機能の一部です。ほとんどのコンテンツがボックス化されていない場合にのみ、コントラストが機能します。

機械抽出可能性とは、ソフトウェアがコンテンツユニットを分離し、周囲のページの外でもその目的を保持できる能力です。型付けされたヒントは、検索システム、コンテンツ移行ツール、またはAIエージェントに対して、境界のあるtype、オプションのtitle、およびbodyを提供します。アドバイスがオプションであるという事実を、必須ステップに平坦化せずに保持できます。文言は単独でも成立する必要があります。「これも試してみてください」はオブジェクトが欠けているため抽出可能ではありませんが、「結果に妥当な原因があるように、タイトルの変更は一度に1つずつテストする」は別途引用されても有用です。

ボックス自体は、それだけで重要性の証拠にはなりません。要素記述ルール では、コンポーネントを決定するために意味が必要です。ライターはまずアドバイスをオプションで結果を改善するものとして分類し、次にヒントの表現を適用する必要があります。ページが視覚的に平坦に見えるからといってボックスを選ぶことは、そのプロセスを逆転させ、ノイズを生み出します。

使用するタイミング

以下の4つの条件すべてが真の場合にヒントを使用します。

1. アドバイスはオプションであり、スキップしてもタスクが間違っていたり、安全でなかったり、不完全になったりしない。
2. 速度、明確さ、正確性、自信、または復旧の容易さなど、特定の結果を改善する。
3. 記事全体ではなく、近くの1つの指示、説明、または判断を修正する。
4. 周囲の段落をスキップした読者でも、フラグが立てられていて欲しいと思うほど有用である。

4番目の条件はスキップテストです。「この段落をスキップした読者は、このアイデアにフラグが立てられていることを望むだろうか？」と自問してください。正直な答えが「いいえ」なら、その文は散文のままにしておきます。読者が安全にスキップできない場合は、ヒントではなく要件または警告です。ボックスが使用されるのは、これらの結果の間の狭いスペースだけです。

よくある類似例としては以下のものがあります：

• 管理者アクセスなどの前提条件。タスクはそれなしでは開始できないため、手順の前に属します。
• 「ステータスが「接続済み」と表示されている必要があります」などの成功基準。アクションが機能したかどうかを判断するため、ステップ内に属します。
• 後のセクションを理解するために必要な定義。用語はメインテキストで定義してください。必要な理解をオプションのように見せてはいけません。
• 補足的な事実や引用。それが裏付ける主張の横に、エビデンスの関係が明確な状態で配置してください。
• 「読者のことを考えて書きましょう」などの気の利いたリマインダー。特定のアクションを変更するにはあまりにも広範です。
• 意味のあるリスクを伴う有用なショートカット。結果が損失や不可逆的な変更を引き起こす可能性がある場合は、ショートカット自体がオプションであっても、警告として記載してください。

隣の段落を言い換えるためにヒントボックスを使用しないでください。繰り返しは、判断やテクニックを追加することなく、読者の注意を消費します。CTA（行動喚起）—登録、購入、問い合わせ、または商用的な次のステップへの促し—をヒントボックス内に配置しないでください。プロモーションは目的を実用的な支援からコンバージョンに変えます。説明に失敗したセクションを救うためにヒントを使用しないでください。セクションを書き直して必要な論理を明確にし、その後で本当にオプションの改善が残っているかどうかを判断してください。

ヒント、メモ、または警告？

これら3つのラベルは、結果を表現するものであり、ムードや色の選択ではありません。読者がそれを無視したときに何が起こるかによってコンテンツを分類します。

現在のHugoコンポーネントは警告の処理をimportantと名付けていますが、編集上の意味は警告のままです。ヒントの処理がよりフレンドリーに見えるという理由で、実際の警告をヒントに軟化させないでください。逆に、オプションのアドバイスを緊急に見せるために警告スタイルを使用しないでください。ヒントに警告スタイルを使用すると、読者が警告を無視するよう訓練されます。実際のリスクが後で現れたときに、視覚言語はすでに信頼性を失っています。

分類が不明瞭な場合は結果テストを使用してください。ボックスをスキップしても改善が得られないだけの場合はヒントを選択してください。スキップしても何も変わらず、コンテキストが失われるだけの場合はメモを選択してください。スキップすると害、損失、不可逆的なアクション、または無効な結果を引き起こす可能性がある場合は警告を選択し、結果を明示的にしてください。

配置する場所

ヒントは、それが修正する完全な段落、ステップ、製品設定の指示、または購入基準の直後に配置します。対象は、読者が関係を推測する必要がないほど近くにある必要があります。カスタムタイトルを使用する場合は、スローガンを考案するのではなく、対象のアクションに名前を付けてください。「年間コストを比較」は「プロの技」よりも明確です。

1ページあたり最大2つのヒントボックス、セクションあたり1つを使用してください。2つは上限であり、割り当て量ではありません。1つの記事に3つのヒントボックスがあると、どれも例外的とは読まれません。グループを通常の散文または短いサブセクションに変換してください。2つのヒントが隣接する場合は、より強いヒントを残し、もう1つのアイデアをメインテキストに統合してください。

以下の場所にヒントを配置しないでください：

• 見出しとその見出しを説明する冒頭の段落の間。
• 読者がタスクや判断を知る前のヒーローセクション。ただし、この仕様が要素自体を必要なライブデモとしてレンダリングする場合を除く。
• 別のコールアウト、テーブルセル、FAQの回答、引用、またはコードブロックの中。
• 主張とそのエビデンスの間、または指示とその必須の成功確認の間。
• 警告のすぐ隣。オプションのメッセージと必須のメッセージが競合し、重要度の低いボックスが警告を希釈する可能性がある。
• CTA、プロモーションバナー、または製品ピッチのすぐ隣。実用的なアドバイスがそのアクションによってスポンサーされているように見えるべきではない。
• 順序付きステップの中。ステップの境界が不明瞭になるため。成功条件を含めてステップを完了し、その下にヒントを配置してください。

ヒントがセクション全体に適用される場合は、関連するコンテキストを確立する最初の段落の後に配置し、最初の文で範囲を明記してください。長いセクションの最後に汎用的なヒントを置き、読者が先行する6つのアクションのどれを変更するのかを推測させることを期待しないでください。

構造

構造には3つの表示コンテンツ領域と1つのドキュメント関係があります。スクリーンショットはレンダリングされた領域にラベルを付けます。説明はライブテキストのままなので、選択可能、翻訳可能、アクセス可能です。

レンダリングされた凡例

1. タイプラベル： 表示される「ヒント」という単語。オプションのステータスを伝え、色やアイコンだけでなくテキストとして存在する必要があります。
2. オプションのタイトル： 改善されるアクションまたは判断に名前を付ける短いフレーズ。省略された場合、タイプラベルがタイトルになります。
3. 本文： 1つの自己完結型テクニックと、その実用的な利点または回避される非効率性。
4. 隣接する対象： ボックスの直前にある完全な指示または説明。テキストフィールドではなくても、位置は意味の一部です。

境界線、背景、アイコン、間隔、およびタイポグラフィはレンダラーに属します。著者はソース内で色を説明したり、絵文字を代替ラベルとして追加したりしません。

デザイン例

サポートされているギャラリーは、異なる意味ではなく、コンテンツの圧力とレスポンシブ動作をテストします。すべてのバージョンはヒントのままで、同じ編集上の制限に従います。

デフォルト： ラベルは「ヒント」、タイトルは省略され、本文には1つの簡潔なアクション-ベネフィットのペアが含まれます。

カスタムタイトル： タイトルは特定の近くの判断を識別します。表示デザインがカスタムタイトルを強調しても、ヒントのセマンティクスは利用可能である必要があります。

最大2段落： 最初の段落はテクニックを、2番目の段落は利点や境界を説明します。これは最大値であり、目標ではありません。

狭いビューポート： ラベル、タイトル、本文は読み取り順序、十分なコントラスト、水平スクロールなしの快適な折り返しを維持します。

パラメータ

インターフェースは、セマンティックタイプ、オプションの命名、コンテンツ、および配置を分離します。「ソース」は、ポータブルコンテンツモデル内で値がどこから来るかを識別します。

現在のHugo実装では、本文のみが必須の作成者コンテンツです。サイトレンダラーは、位置指定タイプまたは名前付きtypeと、オプションの名前付きtitleを受け付けます。同じショートコード内で位置指定パラメータと名前付きパラメータを混在させないでください。

構文とコード例

同じセマンティック値は、すべてのパブリッシングシステムで保持される必要があります。これらの例は同一のコピーを使用しているため、実装テストでtype、title、bodyを直接比較できます。

ポータブルMarkdownディレクティブ

:::tip{title="Test one change"}
Change one variable at a time so you can connect a movement in the result to a specific edit.
:::

ディレクティブ名がtype="tip"を提供し、属性がオプションのタイトルを提供し、囲まれたMarkdownが本文を提供します。

Hugoショートコード

{{< callout type="tip" title="Test one change" >}}Change one variable at a time so you can connect a movement in the result to a specific edit.{{< /callout >}}

これは名前付きパラメータのみを使用します。位置指定形式callout tipは、カスタムタイトルが不要な場合に有効です。このページ上部の実際の例で示されています。

WordPressブロックまたはショートコード

[tip title="Test one change"]Change one variable at a time so you can connect a movement in the result to a specific edit.[/tip]

WordPress実装では、同じフィールドをカスタムブロックに保存する場合があります。エディタコントロールは表示を変更できますが、セマンティックタイプを変更したり、表示ラベルを消したりしてはいけません。

例

これは良い例です。アドバイスがオプションで、具体的で、テストワークフローの隣にあるからです。1つのアイデア（ベースラインを記録する）を含み、それが後の解釈をどのように改善するかを正確に説明しています。読者は周囲のページから対象を探すことなく適用できます。

悪いヒント — 作業を安全に保つ： マイグレーションを実行する前にデータベースをバックアップしてください。バックアップなしでマイグレーションが失敗した場合、顧客レコードが永久に失われる可能性があります。

これは悪い例です。文言が必須の安全策と不可逆的な損失を説明しているからです。これはマイグレーションの前に配置される警告である必要があり、後に配置されるオプションのヒントではありません。フレンドリーなタイプラベルが結果を過小評価しています。

2つ目の悪い例はレンダリングを必要としません：「ヒント：明確な見出しを使用してください。」すでに読者に明確な見出しを書くよう指示している段落の隣にある場合、その段落を言い換えているにすぎません。「見出しだけを読んで、有用なアウトラインを形成しているかテストする」などの具体的なオプションのテクニックを追加するか、ボックスを削除してください。

3つ目の失敗例は、機能の宣伝とボタンを含むボックスです：「ヒント：このチェックを自動化するには無料トライアルを開始してください。」これはCTAであり、編集上のアドバイスではありません。商用的なアクションはページの指定されたCTA位置に配置し、ヒントは実行に焦点を当てたままにしてください。

スキーママークアップとアクセシビリティ

ヒントボックスは専用のSchema.orgプロパティを提供せず、TipBox構造化データタイプもありません。これは、それを囲むArticle、TechArticle、プロダクトページ、またはその他の真実のページレベルスキーマ内の表示コンテンツのままです。JSON-LD（JavaScript Object Notation for Linked Dataで記述された構造化データ）は、ヒントを必須のHowToStepに昇格させてはいけません。そうすると、オプションのアドバイスが手順の一部になってしまいます。

ARIA（Accessible Rich Internet Applications標準）は、ネイティブHTMLでは十分に表現できない場合に、名前、ロール、ステータスを追加します。静的なヒントはrole="alert"を必要としません。緊急でも新しく表示されるものでもないからです。ラベル付きコンテナとして、通常のドキュメント順序でレンダリングしてください。汎用のリージョンロールが使用される場合は、そのアクセシブルな名前を表示ラベルまたはタイトルに結び付けてください。スクリーンリーダーにより積極的にボックスをアナウンスさせるためだけにロールを追加しないでください。

ラベルはコンテンツであり、装飾ではありません。DOM（Document Object Model、ブラウザや支援技術が読み取る構造化ツリー）に存在する必要があります。緑の境界線、電球アイコン、または背景色の変更は認識をサポートするかもしれませんが、いずれもテキスト「ヒント」を置き換えることはできません。読み取り順序はラベル、オプションのタイトル、本文の順である必要があります。リンクには説明的なアンカーテキストが必要であり、コンポーネントはテキストズーム時やカスタム色が利用できない場合でも理解可能である必要があります。

記述ルール

通常の長さの範囲は20〜60語です。ハード最大値は2段落以内で80語です。20語未満の場合、ヒントはしばしば曖昧なスローガンになります。80語を超えると、通常は複数のアイデアやサブセクションに値する十分な推論が含まれています。埋め草を入れるのではなく、意味をカウントしてください。正確な14語の指示は、その対象と利点の両方が明白であれば許容される場合があります。

ボックスごとに1つのアイデアを使用してください。有用なパターンはアクション＋理由です。「記録する」「比較する」「プレビューする」「テストする」などの動詞で始めてください。オプションのアドバイスに適した落ち着いた言葉を使用してください。「必須」「重大」「危険」「決して〜ない」などの単語は、通常、コンテンツが誤って分類されていることを示します。

ヒントには、プレーンな強調表示、インラインコード、および最大1つの説明的なリンクを含めることができます。以下のものを含めてはいけません：

• 必須ステップ、前提条件、受入基準、法的条件、または安全条件。
• 複数の独立した推奨事項。
• CTA、ボタン、フォーム、プロダクトカード、クーポン、またはプロモーションオファー。
• ネストされたコールアウト、テーブル、見出し、長い引用、画像ギャラリー、ビデオ、または複数ステップのリスト。
• 隣接する段落ですでに述べられている同じアドバイス。
• 根拠のない緊急性、作り出された統計、またはエビデンスが関連する散文の横に収まらない主張。
• 「よりスマートに働く」「高品質なコンテンツを作成する」などの曖昧なスローガン。

希少性は編集上のルールであり、単なるレイアウトの好みではありません。1ページあたり0〜2個、セクションあたり最大1個のヒントを使用してください。ドラフトが制限を超えた場合は、すべてのボックスでスキップテストを実行し、忙しい読者が最も見逃して後悔するであろうアドバイスを保持し、残りを統合または削除してください。単にカウントを満たすためだけに無関係なヒントを1つのボックスに結合しないでください。それは単一アイデアルールに違反します。

これを使用する投稿タイプ

postTypesフロントマターは、この要素が配置される可能性のある登録済みフォーマットをリストします。それらのタイプのすべてのページでこの要素を必須とするものではありません。

チュートリアルはハウツー契約を使用します。どちらの形式も読者を順序立てられたタスクを通して導くからです。購入ガイドはほとんどの場合Best-X-for-Y契約を使用します。ヒントがエビデンスを置き換えるのではなく評価を改善するからです。製品セットアップも通常はハウツーガイドに属します。プロダクトページがヒントを使用できるのは、実際のセットアップガイダンスがページのメインコンテンツの一部である場合のみです。

ヒントボックスは、すべての記事におけるデフォルトではありません。ニュース、意見、用語集、ケーススタディ、および単純な情報ページは、しばしばヒントを必要としません。テンプレートのスロットを満たしたり、視覚的なバリエーションを作成したりするために追加しないでください。

QAチェックリスト

公開前に、レビュー担当者は以下をチェックします：

• 正しいタイプ： アドバイスをスキップしてもタスクが安全でなく、不正確で、不完全で、または無効になることはない。
• 価値のある強調： 近くの段落を斜め読みした読者が、このアイデアにフラグが立てられていることを心から望む。
• 単一のアイデア： ボックスには1つのオプションのテクニックとその利点が含まれており、小さなサブセクションではない。
• 希少性： ページには2つ以下のヒントが含まれ、セクションには1つ以下が含まれる。
• 隣接配置： 改善される完全な指示または説明がボックスの直前に配置されている。
• 競合なし： ヒントが警告、CTA、プロモーションパネル、ネストされたコールアウト、または競合するヒントの隣にない。
• 繰り返しなし： 本文は、近くの散文を言い換える代わりに、テクニックや有用な境界を追加している。
• 長さとトーン： 本文は20〜60語を目標とし、80語を超えず、誤った緊急性を使用していない。
• 表示セマンティクス： テキストラベル「ヒント」がDOM内に存在し、意味が色やアイコンに依存していない。
• 抽出品質： タイトルと本文は、周囲のページなしで引用されても意味をなす。
• 安全なコンテンツ： 内部に必須ステップ、リスクコントロール、テーブル、フォーム、ボタン、またはネストされたコンポーネントがない。
• ポータブルマッピング： Markdown、Hugo、WordPressの表現が同じタイプ、タイトル、本文を保持している。
• パラメータ構文： Hugoは位置指定パラメータまたは名前付きパラメータのいずれかを使用し、混合しない。

ボックスがタイプまたは希少性のチェックに失敗した場合、色を変更しても修正にはなりません。コンテンツを再分類するか、メインのナラティブに戻すか、削除してください。

FAQ

フロントマターには、このページの公開可能なFAQエントリが含まれています。これらはレビュー担当者が最も頻繁に必要とする運用上の判断を強化します：最大数、セマンティック分類、必須ステップ、リンク、およびページにヒントが必要かどうか。