要素ページテンプレート

ヒントボックスは優先順位付けの問題を解決します。有用だがオプションのアドバイスは長い手順の中で埋もれてしまいがちですが、それをメインのシーケンスに移動すると、必須のワークフローが実際よりも長く、または厳しく見える可能性があります。この要素は、「完了」の定義を変えることなく実行を改善するアドバイスの周囲に、視覚的な境界線を作成します。このリファレンスは、ロックされた14ブロックの要素テンプレートのすべてのブロックをレンダリングします。

この要素が重要な理由

読者は指示ページをスキャンして判断を下します。何が起こらなければならないか、何が問題になるか、そして何が作業を容易にするか。ヒントボックスは、オプションのガイダンスに安定した視覚的および意味的な役割を与えます。そのラベルにより、読者は文章を読む前にアドバイスのステータスを理解できます。これにより、オプションの最適化が必須の承認ゲートと誤認されるリスクが軽減されます。

機械による抽出可能性とは、自動化システムが境界のあるコンテンツを識別し、周囲のページが存在しない場合でもその意味を保持できることを意味します。ヒントの明示的なラベル、短いタイトル、自己完結型の本文がその境界を向上させます。ボックスはプレーンテキストとしても意味をなす必要があります。「ヒント — 分母を確認しましょう。同じ母集団と期間を使用する場合にのみパーセンテージを比較してください。」視覚的なスタイリングはスキャンを助けますが、意味を伝えるのは言葉です。

この要素は、装飾になってしまうと失敗です。「素晴らしいコンテンツを作成することを忘れないでください」のような一般的な励ましは、判断、技術、結果を何も追加しません。また、作成者が重要な要件を視覚的にオプションのコンテナに隠してしまった場合も失敗です。

使用する場合と使用しない場合

アドバイスがオプションで、具体的で、改善するタスクに隣接し、長い説明を必要としない場合にヒントを使用します。適した候補としては、効率的な順序、有用な診断、元に戻せるショートカット、検証テクニック、またはやり直しを避けるための状況固有の方法が挙げられます。

安全上の警告、法的資格、元に戻せないアクション、必須の入力、承認基準、後で読者が定義を必要とする用語、またはメインの議論を支える事実にはヒントを使用しないでください。結果を無効にする可能性のある条件には important コールアウトを使用します。必須アクションは番号付きプロセスに配置します。証拠はそれがサポートする散文やテーブルセルに配置します。

ドキュメント内の位置ルール

位置は意味を持ちます。ヒントは、それが改善する指示や説明の直後に配置するのが最も効果的です。読者はアドバイスを記憶に保持する必要なく適用できるからです。直接的な回答を中断したり、文章とその証拠を分離したり、見出しとその見出しを定義する段落の間に配置したりしてはいけません。

ヒントボックスの位置ルール

構成

構成には4つの意味的な領域があります。タイプは重大度とラベルを制御します。オプションのタイトルはアクションや判断を指定します。本文は1つのテクニックとその結果を示します。周囲の位置はヒントをそれが修飾する指示に接続します。間隔、境界線、アイコン、色はデザインシステムに属します。作成者がこれらをコンテンツにエンコードすることはありません。

注釈はピクセル測定ではなく、意味的な領域を識別する必要があります。これらのラベルは、後で視覚的なトークンが変更されても有用性を保ちます。

デザイン例

ギャラリーは、現実的なコンテンツ負荷の下で要素を示す必要があります。1文の短いヒント、2段落のヒント、インラインコードを含むヒント、および狭いビューポートです。レビューアが折り返しと階層を比較できるよう、基礎となるアドバイスは一定に保ちます。

ファイルが存在したら、features-with-4-images-grid でレンダリングします。製品画像グリッドよりもギャラリーコンポーネントが推奨される理由は、ニュートラルな仕様を正確に4つの画像と組み合わせ、コマースコントロールを導入しないためです。

パラメータ

パラメータはインターフェース契約です。正確な型と制限により、ある作成者がラベルを書き、別の作成者が同じ意味を本文の散文としてエンコードすることを防ぎます。ソース列は誰が値を所有するかを示しているため、レビューアはコンテンツ、メタデータ、またはコンポーネントのいずれを修正すべきか判断できます。

ヒントボックスのパラメータ

これらは編集上の制限であり、レンダラーのバリデーションではありません。制限を超える場合は、レビューで確認できる理由が必要です。本文に複数の小見出し、リスト、引用が必要な場合、それはおそらくヒントではなくセクションです。

構文とコード例

以下の表記は同一の意味を持ちます。ポータブルMarkdownは、異なる公開システムで変換可能なディレクティブを使用します。Hugoは既存の callout ショートコードを使用します。WordPressはプロジェクトレベルのショートコード表現を使用します。WordPressの実装では、そのショートコードを登録するか、構造をカスタムブロックにマッピングする必要があります。

公開システムでヒントボックスをコピーする

3つの表記すべてで、タイプ、タイトル、本文を同等に保ちます。

ポータブルMarkdown

:::tip{title="分母を確認する"}
同じ母集団と期間を使用する場合にのみパーセンテージを比較してください。
:::

Hugo

{{< callout tip title="分母を確認する" >}}同じ母集団と期間を使用する場合にのみパーセンテージを比較してください。{{< /callout >}}

WordPress

[tip title="分母を確認する"]同じ母集団と期間を使用する場合にのみパーセンテージを比較してください。[/tip]

これにより、テンプレートの主な再利用リスクが解決されます。既存のタブコンポーネントはコードブロックを受け入れ、画像を必要とせず、タブとパネルのロールを公開し、3つの固定ラベルをサポートします。新しいショートコードは既存の動作を複製し、メンテナンスすべき別のインターフェースを追加することになります。

良い例と悪い例

これは、具体的なアクションを示し、理由を説明し、より広範な分析手順の中でオプションのままであるため機能します。

文言は明確ですが、タイプが間違っています。法的承認は必須のゲートであるため、ヒントとして提示すると結果を過小評価します。メインのチェックリストに移動するか、コールアウトラベルをimportantにしてください。

もう1つの弱い例は、「プロのヒント：より良い結果を得るためにコンテンツを最適化しましょう」です。観察可能なアクション、制約、方法、または「より良い」の定義が含まれていません。削除するか、読者が実行して検証できるテクニックに置き換えてください。

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

ヒントボックスはスタンドアロンのSchema.orgタイプを必要としません。それは包含する Article または TechArticle の一部として残ります。オプションのアドバイスを HowToStep としてマークしないでください。そうすると誤って必須プロセスに昇格してしまいます。サイトのポリシーに基づいてページ自体がHowToスキーマの対象となる場合、必須の手順のみがステップシーケンスに属します。

アクセシビリティはテキストの意味論から始まります。表示ラベルは「ヒント」と記載する必要があり、色やアイコンだけで区別することはできません。タイトルはアクションを説明し、本文はドキュメント順で読み取り可能で、リンクは視覚的なボックスの外でも意味をなす必要があります。本文のすべて大文字、絵文字のみのラベル、ネストされたインタラクティブコントロール、および通常の段落よりもナビゲートが難しくなる隣接するボックスの連続は避けてください。

現在のコールアウトレンダラーは、ラベル付きコンテナとMarkdown本文を出力します。作成者は、意味のある文言、ボックス周辺の見出し順序、説明的なリンク、および読み取り不可能なネストされたインターフェースを作成する場合にコードやテーブルを外部に保つ責任を負います。

執筆ルール

アクションで始めてください。同じ文または次の文で利益や回避される失敗を説明します。ボックスごとに1つのアイデア、20〜80語、2段落以内、最大1つのリンクを使用します。「ヒント」だけではどの近くの指示を修飾しているかが明らかでない場合は、カスタムタイトルを優先します。

直接的で落ち着いた言葉を使用します。「常に」「絶対に」「重大」「必須」などの言葉でオプションのアドバイスを誇張しないでください。単にページをデザインされたように見せるためだけにヒントを追加しないでください。情報が中心的なものであれば、メインのナラティブに戻してください。単に心地よい励ましであれば、削除してください。

繰り返されるヒントが近接していることは、構造上の問題を示しています。関連するアドバイスをサブセクションに統合するか、どのポイントが実際に必須の手順であるかを判断してください。この要素は情報階層のコントラストを高めるべきであり、ページ全体を競合するボックスで埋め尽くすものではありません。

どの投稿タイプがどこで使用するか

ハウツーガイドは、改善する手順の後にヒントを使用します。アルティメットガイドは、複雑な説明の後で、オプションのプラクティスが一般的なやり直しを防ぐ場合に使用します。比較ページは、証拠の代わりとしてではなく、方法に関する注意事項の横に控えめに使用します。チェックリストは、アドバイスが効率を改善するが完了条件を変更しない場合に、項目の後に使用します。

より広範なSEO投稿タイプ のカタログがドキュメントの順序を決定します。SEOコンテンツ要素 ハブが要素ファミリーと関連する代替案を決定します。ページ作成者は両方を参照する必要があります。要素契約はボックスの動作方法を説明し、投稿タイプはそのボックスがその位置に属するかどうかを説明します。

QAチェックリスト

• オプションステータスが正しい — アドバイスをスキップしてもタスクが不完全、不安全、または無効にならない
• 対象が明確 — タイトルまたは最初の文が、改善される指示または判断を明示している
• 1つのアイデアに制限されている — 本文には1つのテクニックとその結果が含まれており、隠れたサブセクションではない
• 抽出後も意味が通る — ラベル、タイトル、本文が色や近くの代名詞に頼らずに意味を保持している
• 配置が隣接している — ボックスは、証拠を中断することなく、修飾する完全な手順の後に続く
• 制限が守られている — 本文は2つの短い段落内に収まり、1つ以下のリンクのみを使用している
• ポータブル構文が一致している — Markdown、Hugo、WordPressの例が同じタイプ、タイトル、本文を保持している

レビューアは、視覚的な処理が正しく見えても、いずれかのチェックに失敗した場合は要素を拒否する必要があります。作成者が既存のページをコピーするときに意味的な誤用が広がるため、見慣れたレイアウトを維持するよりもタイプを修正することの方が重要です。

FAQ

よくある質問

アカデミーレイアウトが最終的な変換パネルを提供します。表示例、仕様、3つの表記タブ、コンテンツルール、QAチェックが共に実装可能な要素契約を形成します。追加の要素固有のレイアウトは必要ありません。