Iconbox — 格式、规则与示例

一个 iconbox 将一个有明确用途的图标与一个简短标签和一段聚焦的解释配对。图标让主题可识别，标签为其命名，文本解释其重要性。该元素最适合作为小型同级组的一员，例如三项产品能力或四个需求——而非散落在页面各处的装饰。

勾选符号是有明确用途的：它强化了"验证"的概念，而不是填补空角落。由于可见标签已经表达了相同含义，因此渲染的符号对辅助技术隐藏。屏幕阅读器用户从"已验证的来源"及其解释中接收到完整信息，而不会听到冗余的图标输出。

为什么这个元素很重要

读者不会按顺序处理每一个句子。他们在寻找能够回答"这是我需要的东西吗？“的标记点。一个 iconbox 创建一个紧凑的识别模式：先看形状，再看标签，最后看解释。在一个结构良好的组中，读者可以扫描标签，识别相关类别，然后只阅读他们需要的支撑文本。这减少了拆解一个包含多个同等重要观点的段落的负担。

其心理价值来自识别、分块和一致性。一个熟悉的盾牌可以提示保护，一个时钟可以提示时间，一份文档可以提示报告——在读者读完标签之前就能产生联想。标签随后消除歧义。重复的几何结构告诉读者这些项目具有相同的编辑层级。只有当内容确实是并列关系时，这个信号才有用；卡片网格不能把不相关的主张变成一个连贯的集合。

机器可提取性意味着软件可以隔离一个内容单元，同时保留其主题和主张。结构化的 iconbox 暴露一个带有简洁正文和可选组内固定位置的命名项目。检索系统可以提取"已验证的来源"及其解释，而不是猜测哪个句子属于哪个视觉符号。图标资产本身对提取贡献不大，因此可见的文字必须承载完整的命题。

图标仍然必须具有编辑意义。任意的闪光、火箭或抽象形状对人类来说是噪音，对机器也没有有用的语义。“有明确用途但冗余"是一种有效的无障碍模式：图标可以帮助视力正常的读者识别类别，同时被辅助技术隐藏，因为可见标签已经提供了其含义。遵循元素编写规则 ，首先起草完整的思想，然后在后续的结构性处理中选择 iconbox。此处的元素特定限制在图标选择、分组和无障碍映射方面具有优先权。

何时使用

当一个内容是简洁的、命名的想法，并且来自批准系统的图标可以无需猜测地代表该想法时，使用 iconbox。当两到六个项目以相似的深度回答同一个隐含问题时，适合使用组形式：“包含什么？"、“哪些防护措施适用？“或"这个工作流程产生什么？“每个项目在纯文本复制时仍应保持可理解性。

强用途包括：每个项目描述一个结果的功能摘要、详细说明前的需求概览、一套服务原则，或工作流程输出的简洁说明。图标是识别辅助工具，而非证据。文件格式、响应时间窗口、支持的系统或所属权等具体信息仍应属于标签和正文。

容易混淆的情况很常见：

• 当每个项目都使用相同的勾选标记图标时，使用普通项目符号列表。重复不会传达类别含义。
• 当需要根据共同标准对项目进行评判时，使用比较表格。独立的 iconbox 使跨项目比较更加困难。
• 当顺序、完成或依赖关系重要时，使用步骤列表。一排 iconbox 表示同级关系，而非序列。
• 当一个陌生术语需要正式定义时，使用定义框。图标不会强化精确定义。
• 当严重性和中断是主要任务时，使用警告或提示。Iconbox 具有中性的结构权重。
• 当每个项目需要多个段落、证据、媒体或子标题时，使用完整的章节。

不要仅仅为了让文本密集的页面看起来有设计感而使用 iconbox。如果作者是在寻找视觉吸引而非语义准确之后才选择图标的，那么内容可能根本不需要这个元素。

放置位置

将独立 iconbox 放置在它所支持的段落之后。将 iconbox 组放置在一个标题和一段命名共同问题的介绍性段落之后。这个上下文解释了为什么这些项目属于一起；组合随后给出简洁的答案。组之后应跟随细节、证据或下一步决策，而不是用散文重复每个框。

在一篇文章中，第一个组应仅在直接答案或开场定义之后出现。在商业页面中，能力组可以跟随问题和结果陈述之后，但不得仅仅为了创建视觉英雄而置于价值主张之前。在文档中，将需求组放置在其所管辖的步骤之前，同时将必要的顺序和验收标准保留在普通说明中。

不要将 iconbox 组直接放置在另一个卡片网格、比较表格、标志墙、数据条或多列行动号召旁边。相邻的网格会扁平化信息层级，并使编辑事实看起来像促销。在它们之间插入解释性散文或段落分隔。不要将 iconbox 放在一个主张与其来源之间、一个步骤与其预期结果之间、表格单元格内部或另一个 iconbox 内部。切勿将两个组背对背放置。

组成部分

一个 iconbox 包含三个创作区域和一个上下文关系。截图标记的是承载意义的区域而非像素值，以便这份协议在视觉重新设计后仍然有效。

1. 图标区域： 使用一个批准的图标，其概念与项目匹配。它永远不能替代可见文字。
2. 简短标签： 用具体语言命名该功能、需求、结果或类别。
3. 文本正文： 在一个紧凑段落中解释后果、范围或证据。
4. 可选目的地： 在使用链接变体时，提供一个描述性的后续步骤。
5. 组上下文： 前面的标题或可访问的组标签说明所有同级 iconbox 共同回答的问题。

边框、背景、圆角、图标大小、颜色、网格列数和断点属于渲染器。作者选择语义内容、图标标识、源顺序和无障碍模式。

设计示例

该元素支持四种展示变体。所有变体都保留相同的图标-标签-正文层级结构和相同的源顺序。

标准： 默认的独立或分组卡片。当正文需要 25-60 个词来解释一个项目时使用。

紧凑型： 使用 12-30 个词的单句正文。适用于熟悉的概念，不适合压缩复杂的限定条件。

链接型： 增加一个目标地址。优先使用可见的描述性链接。如果整张卡片可交互，渲染器必须提供单个链接目标和清晰的焦点状态。

状态型： 传达可用、受限、通过或待定等状态。状态词语必须可见；颜色或图标形状都不得作为唯一信号。

窄视口： 任何组在源顺序中变为单列。渲染器不得重新排列框来平衡其高度。

无障碍模式与展示变体是分开的。冗余图标对辅助技术隐藏，因其标签承载相同含义。真正提供信息的图标会获得程序化文本等价物，但作者通常应将此信息添加到可见标签中，而不是维护一个仅有图标的事实。

参数

这份协议将创作的含义与展示分开。除非有更严格的限制说明，否则限制适用于所有变体。

icon 必须通过批准的图标注册表解析；作者不能提供任意的 SVG、emoji、图片 URL 或图标字体类名。受限 Markdown 允许强调、内联代码和一个内联链接。它排除嵌套标题、列表、表格、媒体、表单、按钮、手风琴和其他组件。当第一个正文标题提供 label 时，适配器将从正文中移除该标题，并在正确的页面相对层级中渲染它。

语法与代码示例

每种表示法映射到相同的图标、标签、正文、变体和无障碍模式。图标键是语义化和可移植的；每个平台将 shield-check 映射到其批准的本地资产。

可移植 Markdown 指令

:::iconbox{icon="shield-check" iconMode="redundant" variant="standard"}
### 已验证的来源

每个事实主张都链接到可供审查者检查的来源，因此在撰写、审核和后续更新过程中，证据始终可见。
:::

第一个标题成为 label；剩余的段落成为 content。图标是冗余的，因为"已验证的来源"在可见文本中给出了完整的含义。

Hugo 短代码

{{< iconbox icon="shield-check" label="已验证的来源" iconMode="redundant" variant="standard" >}}
每个事实主张都链接到可供审查者检查的来源，因此在撰写、审核和后续更新过程中，证据始终可见。
{{< /iconbox >}}

适配器仅使用命名参数。它必须拒绝未知的图标键或变体，而不是静默显示可能改变含义的后备方案。

WordPress 块

<!-- wp:amicited/iconbox {"icon":"shield-check","label":"Verified sources","iconMode":"redundant","variant":"standard"} -->
<p>每个事实主张都链接到可供审查者检查的来源，因此在撰写、审核和后续更新过程中，证据始终可见。</p>
<!-- /wp:amicited/iconbox -->

编辑器应暴露一个可搜索的已批准图标选择器，而非自由文本资产字段。其无障碍名称预览应显示图标是隐藏还是被朗读。

示例

良好示例

这之所以有效，是因为文档符号与报告概念匹配，标签命名了一个具体能力，正文解释了输出及其实际后果。没有符号，可见文本仍然是完整的，因此符号可以对辅助技术隐藏。

不良示例

这在各个层面都失败了。火箭是装饰性而非准确的类别标记，标签不包含具体能力，正文没有提供机制、边界或可验证的结果。Emoji 也可能被不可预测地朗读。将此块替换为具体陈述——什么变得更快，通过什么机制，在什么条件下——或者直接删除它。

Schema 标记与无障碍

Iconbox 没有专用的 Schema.org 类型。其标签和正文仍属于所包含的 Article、TechArticle、WebPage、Product 或其他页面级实体的内容（当这些标记在其他方面合理时）。视觉组不会自动成为 ItemList；仅在内容模型中该集合是完整或有序的时才使用列表标记。状态 iconbox 不能证明在没有所需基础数据的情况下使用 Review、Rating 或可用性属性。

将非交互式 iconbox 渲染为 section（当它属于主要论点时）或 aside（当它是补充内容时）。通过可见标签为其提供可访问名称。使用正确层级的标准标题；不要仅仅因为 h3 的默认字号看起来合适就选择它。重复的同级元素可以放在一个列表中（当该组确实是一个列表时），每个 iconbox 对应一个列表项。

大多数图标应为内联 SVG，带有 aria-hidden="true" 和 focusable="false"，因为可见标签重复了它们的含义。这并不使它们在编辑上成为装饰：它们仍然有助于视觉识别，但宣布同一概念两次会增加噪音。如果图标传达了标签中缺少的信息，请通过组件的 iconText 映射提供可访问的文本等价物。更好的做法是修改可见标签，使所有读者都能接收到该信息。

切勿仅依赖颜色、位置、动效或图标形状。绿色勾选需要"通过"之类的可见文本；锁需要"受限"或确切的访问条件。图标需要与其背景有足够的对比度，但颜色属于渲染器的范畴。不传达任何信息的装饰性花饰应被移除，而不是赋予冗长的替代文本。避免使用 alt="icon"、文件名、Unicode 字形名称以及重复文本，如"Shield, Verified sources”。

对于链接变体，一个 iconbox 只有一个目标地址。交互名称必须传达该目标地址，键盘焦点必须可见，可点击区域不得包含另一个链接或按钮。悬停不能揭示必要的文本。阅读和键盘顺序必须在所有视口宽度下与源顺序一致。

编写规则

在选择图标之前编写标签。标签应为具体的名词短语或简短结果：“基于角色的访问”、“每周导出"或"人工审核”。保持同级标签在语法上平行。避免"强大”、“无缝”、“创新"和"行业最佳"等泛泛主张，因为它们既没有命名能力也没有命名决策。

标签使用 2-6 个词，不超过 55 个字符。正文使用 12-60 个词的一个段落；紧凑变体应保持在 12-30 个词以内。以具体机制、范围或结果开头。保持冷静、基于事实的语气。如果限定条件改变了承诺，请将其放在同一个框中，而不是放在远处的小字中。

每组使用两到六个框。使每个项目具有可比的深度，并让它们回答同一个问题。按读者优先级、工作流程逻辑或已声明的类别排序——而不是看哪个图标最好看。不要在一个组内为不同含义使用相同的图标，也不要使用多种视觉风格或图标系列。

切勿将以下内容放入 iconbox：

• 长篇功能清单、多步骤流程、嵌套项目符号列表、表格、表单、推荐语、价格或法律免责声明。
• 仅有图标的标签、未解释的缩写词、或仅通过颜色表达的状态。
• 超过一个链接、竞争性的行动号召、或在整张卡片链接内的按钮。
• 截图、视频、图表、标志、照片或另一个 iconbox。
• 适用于多个框但仅出现在一个框中的证据，这会使组看起来不均匀或具有误导性。

如果内容超出这些限制，将其提升为普通章节。如果每个项目都需要相同的勾选标记，移除图标并使用列表。如果标签没有图片就无法理解，请在发布前重写标签。

使用该元素的文章类型

postTypes 前置元数据字段是此表的来源。列入意味着当内容形成真正的同级集合时该元素可用，并不意味着每种类型的每篇页面都应包含 iconbox。

QA 检查清单

• 有明确用途的图标： 每个图标与其标签有明显的关联；移除它会降低视觉识别，而非事实含义。
• 完整的可见文本： 标签和正文传达完整的主张，不依赖图标、颜色或位置。
• 正确的无障碍模式： 冗余图标被隐藏；信息型图标具有简洁的文本等价物和记录在案的原因。
• 真正的同级组： 同级项目回答同一个问题，具有可比深度，并使用平行标签语法。
• 安全的数量： 一个组包含两到六个项目；更大的集合被分类或移至更合适的结构。
• 精确的文案： 标签命名具体能力、需求、状态或结果；正文提供机制、范围或后果。
• 有效的图标来源： 每个图标键存在于批准的注册表中，不得编写 emoji、任意 SVG、图片 URL 或图标字体类。
• 合理的放置： 组跟随其框架上下文，不隔断主张与来源、步骤与结果、或警告与受影响的操作。
• 安全的邻居： 没有卡片网格、表格、标志墙、数据条或多列行动号召直接位于组旁边。
• 可访问的结构： 标题级别跟随文档层级，对比度足够，状态具有可见文本，源顺序与阅读顺序一致。
• 交互约束： 链接型 iconbox 有一个目标地址、描述性名称、可见焦点状态，且无嵌套交互控件。
• 表示法一致性： 可移植 Markdown、Hugo 和 WordPress 保留相同的图标键、标签、内容、变体和无障碍行为。
• Schema 约束： 该组件不添加独立 schema，也不从外观推断 ItemList 或状态属性。
• 响应式验证： 在窄宽度下，框按源顺序堆叠，无裁剪、水平滚动或隐藏的必要文本。

如果图标的含义随意、标签模糊或可见文本依赖于符号，则拒绝该元素。这些是内容模型的缺陷；更改间距、颜色或插图样式无法修复它们。

常见问题

前置元数据中的 FAQ 涵盖了分组大小、替代文本、链接卡片、emoji 和 schema 行为。将经过批准的答案保留在结构化的前置元数据中，可以让学院布局一致地渲染它们，而无需在文章正文中重复相同的问题。