如何为设计系统创建预设标注

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

组件优先级排序

当设计系统拥有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的侧边栏中设置标签和输入字段的值，但由于默认隐藏，没有选项可以设置错误验证消息的文本。

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

其他潜在来源

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

整合所有内容

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

创建预设标注的经验总结

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

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

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

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

并不总是清楚需要预设标注

组件的预设标注与不特定于设计系统的标注类型之间可能存在足够的重叠。例如，GitHub标注工具包除了我们的Primer <TextArea> 组件的预设标注外，还有用于标注基本 <textarea> 表单元素的组件：

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

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

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

目前有许多现有的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，并且需要一个可访问的名称来描述其功能。

当使用基本标注工具包时，这可能意味着为按钮和装饰性图像添加标记，以及在边距中添加注释，指定aria-label应该是什么。当使用预设标注时，需要添加到画布上的内容更少，标注过程花费的时间也更少。

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

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

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

随着我们继续创新标注并使我们的组件更易于访问，我们计划在不久的将来发布我们的GitHub标注工具包。敬请期待！

延伸阅读

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