设计系统注释，第二部分：组件注释的高级方法

如何为设计系统组件构建自定义注释，或使用Figma的Code Connect功能在开发前捕获重要的可访问性细节。

在我们设计系统注释系列的第一部分中，我们讨论了可访问性在设计系统组件实例之间可能被忽略的方式。我们的解决方案？为Primer的每个组件使用一套“预设注释”。这使得设计师能够包含尚未内置到组件中且在设计本身中未视觉传达的特定预设细节。

也就是说，预设注释对于每个设计系统都是独特的——虽然我们的方法可以作为如何构建它们的参考——但如果您不使用Primer设计系统，其他组织也无法利用它们。

幸运的是，您可以构建自己的预设注释。方法如下。

如何为您的设计系统制作预设注释

首先评估组件以了解哪些需要预设注释——并非所有组件都需要。优先考虑那些最能从预设注释中受益的组件，并将关键信息构建到每个组件中。接下来，确定应包含哪些属性。仅包含那些未视觉传达、不在组件属性中且尚未内置到编码组件中的关键信息。

确定组件优先级

当一个设计系统拥有60多个组件时，知道从哪里开始可能是一个挑战。哪些组件最需要这些注释？哪些组件对设计团队和我们的用户影响最大？

当我们着手基于概念验证创建一套新的预设注释时，我们决定使用十个最能受益的Primer组件。为了帮助挑选它们，我们使用了一个名为Primer Query的内部工具，该工具跟踪GitHub代码库中的所有组件实现以及与之相关的任何审计问题。如果您好奇，这里有一个视频分解说明其工作原理。

然后，我们根据以下标准确定了新预设注释的优先级：

• 与组织优先级一致的组件（即高价值产品和/或流量大的产品）。
• 在可访问性审计问题中频繁出现的组件。
• 具有React实现的组件（作为我们首选的开发框架）。
• 最常实现的组件。

映射属性

对于每个组件，我们交叉参考了多个来源，以确定每个预设注释中需要添加哪些组件属性和属性。我们寻找的内容可能只存在于这些地方的一两个中，因此不太可能在设计和开发生命周期中全程被考虑到。这些来源包括：

Primer.style上的组件文档

设计系统文档应包含面向设计师和开发者的使用指南，可访问性要求也应是此指南的一部分。一些指南和要求被构建到组件的Figma资源中，而一些最终只出现在编码组件中。

寻找任何未内置到Figma或代码中的可访问性要求。如果已经内置，将相同信息放入预设注释可能是冗余或不相关的。

预设可以处理罕见用例

在构建TextInput组件的预设注释时，我们发现实现可能单独使用图标或具有隐藏的输入标签。对于GitHub的全局搜索或筛选输入，单独的放大镜图标可以充当可见标签，但字段仍然需要为辅助技术用户提供可访问的标签。

Storybook中的编码演示

我们的组件沙箱帮助我们了解每个组件是如何在React或Rails中构建的，以及HTML输出是什么。我们寻找任何未包含在组件文档或Figma资源本身中的代码结构或可访问性属性——特别是当它们可能因实现而异时。

设计师可能看不到或设置的代码属性

Storybook通过显示一些在其他地方未被提及的重要属性，帮助我们完善了TextInput组件的预设注释。type属性默认值为text。根据字段的用途，输入的type也可以是search、email、number、tel、date或time。这应有意设置，以便用户能够使用最合适的虚拟键盘。

Figma资源库中的组件属性

库资源通过文本层、图像填充、变体和复杂的组件属性集提供了很大的灵活性。我们密切关注这些选项，以了解设计师可以更改和不能更改的内容。预设注释中值得添加的是其他来源中未内置到Figma组件中的可访问性属性、要求和使用指南。

TextInput的Figma组件中缺少什么

当TextInput被添加到设计中时，Figma组件附带许多可自定义选项。有一个inputTextType属性，它涉及视觉设计和排版，而不是表单输入的类型。可以在Figma的侧边栏中设置Label和输入字段的值，但由于默认情况下它是隐藏的，因此没有选项来设置错误验证消息的文本。

我们不能假设在Figma中交付的每个设计都会附带显示其所有错误状态的表单示例，因此这些错误消息可能得不到应有的关注。如果此消息不能作为文本属性内置到组件中，则可以将其添加到预设注释中。

其他潜在来源

• 团队成员的经验：与您合作的设计师、开发者和可访问性专家可能对文档和设计工具可能遗漏的内容有见解。如果您的团队和设计系统已经存在一段时间，他们的见解可能比您在文档、组件演示或资源库中找到的更有价值。花点时间询问哪些组件曾遇到具有挑战性的错误，以及哪些组件在实现时被有意破坏。
• 近期审计的发现：设计系统组件本身可能存在未解决的审计问题和修复建议。如果是这种情况，这些问题很可能出现在Storybook演示中，并且可能在组件文档中未被考虑。设计系统审计问题可能包含既有助于创建预设注释，又能提供关于不应从现有资源中继承哪些内容的详细信息。

整合所有内容

我们为TextInput组件创建的新预设注释包括指向使用指南和Storybook的链接，以及一个关于如何在设计中最优使用组件以避免潜在问题的可选教程。有两个必填提示用于输入类型和错误文本，以及一个用于偶尔隐藏表单标签的可选提示。

我们从创建预设注释中学到的经验

预设注释可能并不适合每个团队或组织。然而，它们特别适合年轻的设计系统和那些采用度不高的设计系统。

像Primer这样的成熟设计系统会频繁更新。这意味着，如果没有密切监控，设计系统组件本身可能会与预设注释的构建方式不同步。这可能在开发开始后导致混乱和返工，因此明智的做法是确保在创建这些注释后有能力维护它们。

对于GitHub的新团队、现有团队的新成员以及对设计系统不太熟悉的团队成员来说，内置的指南以及指向文档和组件演示的链接被证明非常有用。更有经验的成员也能够微调预设及其使用方式。

如果您尚未对设计系统组件有广泛经验（或没有同行帮助构建它们），评估和映射构建预设所需的属性可能需要大量时间。简洁地命名组件属性以避免在Figma的属性面板中被截断也可能具有挑战性。如果上下文不明确，一些培训或额外的文档可能会有所帮助。

并不总是清楚是否需要预设注释

组件的预设注释与非特定于设计系统的注释类型之间可能存在足够的重叠。例如，GitHub Annotation Toolkit包含用于注释基本<textarea>表单元素的组件，以及针对我们的<TextArea> Primer组件的预设注释：

在许多情况下，这种灵活性可能会令人困惑，因为您可以使用任一注释。例如，Primer <TextArea> 预设内置了指向特定Primer文档的链接，而非预设版本则没有，但您始终可以手动添加链接。虽然两者之间存在一些重叠，但使用任一都比不使用好。

解决这种混淆的一种方法是将Primer特定属性添加到默认注释集中。这将允许您执行诸如在普通Button注释上切换布尔属性之类的操作，并显示特定于您设计系统按钮组件的链接和属性。

我们的预设创建过程可能解锁自动化

目前有许多现有的Figma插件声称能够扫描设计文件以帮助进行注释。但结果往往好坏参半，并包含难以管理的噪音和误报。发生这些问题的一个原因是这些公共插件是设计系统无关的。

当前的自动化注释工具无法理解任何设计系统组件正在被使用，除非进行定制编程或对AI模型进行彻底训练。为了使此类插件能够准确标记设计元素，它们首先需要了解如何识别画布上的组件、使用的变体以及设置的属性。

考虑到这一点，也许最令人兴奋的见解是，为预设注释映射组件属性的过程——那些在视觉设计或代码中未传达的内容——也是在任何尝试自动化更有用注释时需要完成的工作。

换句话说，如果一个团队使用设计系统并希望自动化添加注释，他们使用的工具需要理解他们的组件。为了让该工具足够理解他们的组件以实现准确自动化，这些隐藏的组件属性需要被映射出来。创建一套预设注释的任务可能是实现更简化流程的重要垫脚石。

一种有前景的新方法：Figma的Code Connect

在构建我们新的预设注释集时，我们尝试了其他增强Primer注释的方法。虽然并非所有实验都成功，但其中一个确实有效：通过Code Connect添加可访问性属性。

Primer是Figma Dev Mode中新的Code Connect功能的早期采用者之一。我们的高级系统设计师Lukas Oppermann表示：“通过Code Connect，我们实际上可以再次将设计和代码稍微分开。我们可以专注于为在Figma中使用设计库的设计师创造最佳用户体验，而在代码方面，我们可以拥有最佳的开发者体验。”

为此，Code Connect使我们能够绕过大部分预设注释，以及我们其他一些实验的缺点。它通过将关键的可访问性细节直接添加到开发者可以从Figma导出的代码中来实现这一点。

GitHub的Octicons在我们的许多Primer组件中使用。它们默认是装饰性的，但根据使用方式，有时需要alt文本或aria-label属性。在IconButton组件中，该按钮使用一个Octicon，并且需要一个可访问的名称来描述其功能。

当使用基本的注释工具包时，这可能意味着为Button和Decorative Image添加标记，并在边距中添加一个注释，指定aria-label应该是什么。当使用预设注释时，需要添加到画布上的内容更少，注释过程花费的时间也更少。

通过设置Code Connect，Lukas在IconButton Figma组件中添加了一个隐藏层。它有一个用于aria-label的文本属性，允许设计师直接从组件属性面板添加值。无需注释。隐藏层不会干扰任何视觉效果，并且aria-label属性会与组件其余代码一起直接导出。

为每个设计系统组件设置Code Connect需要时间。以下是一些提示：

• 一致性是关键。确保您创建的属性以及放置隐藏层的方式在组件之间保持一致。这有助于设定明确的期望，以便您的团队能够理解这些隐藏层和属性的功能。
• 使用设计系统库的分支进行实验。与预设注释能够处理的其他复杂信息相比，隐藏诸如aria-label之类的属性相当简单。
• 使用视觉回归测试（VRT）。直接向组件添加复杂性会增加未来出现故障的风险，特别是对于具有许多变体的组件。Figma的合并冲突UI很有帮助，但可能无法捕获所有问题。

随着我们继续在注释方面进行创新并使我们的组件更具可访问性，我们计划在不久的将来发布我们的GitHub Annotation Toolkit。敬请期待！

延伸阅读

可访问性注释工具包是很好的资源，前提是它们被负责任地使用。我们即将推出的GitHub Annotation Toolkit的贡献者之一Eric Bailey，已经广泛撰写了关于注释如何在构建数字产品时突出和放大深层结构问题的文章。