设计系统注释，第二部分：组件注释的高级方法
引言
在设计系统系列的第一部分中，我们探讨了可访问性如何在不同实例的设计系统组件中被忽略的问题。通过使用Primer的"预设注释"，设计师能够包含组件中尚未内置且未在设计中直观传达的特定预设细节。然而，这些预设注释是每个设计系统独有的，其他组织无法直接使用。本篇文章将深入探讨如何为设计系统创建自定义注释，以及如何利用Figma的Code Connect功能在开发前捕获重要的可访问性细节。
正文内容
1. 如何为设计系统制作预设注释
1.1 评估组件优先级
并非所有组件都需要预设注释，因此首先需要评估哪些组件会从中受益最大。建议优先考虑以下类型的组件：
- 与组织优先级相符的组件（如高价值产品或流量大的产品）
- 在可访问性审计问题中频繁出现的组件
- 采用首选开发框架（如React）实现的组件
- 最常被实现的组件
在Primer的案例中，使用了一个名为Primer Query的内部工具来追踪所有组件实现和相关的审计问题，帮助筛选出最需要注释的10个组件。
1.2 确定要包含的属性
在确定哪些组件需要注释后，下一步是决定应该包含哪些属性。关键原则是：只包含那些没有视觉表现、不在组件属性中，且尚未内置在编码组件中的关键信息。
1.3 属性映射的数据来源
为了确保注释的全面性，应从多个来源交叉引用信息：
- Primer.style上的组件文档：查找未内置到Figma或代码中的可访问性要求
- Storybook中的编码演示：查看组件文档或Figma资产本身未包含的代码结构或可访问性属性
- Figma资产库中的组件属性：关注Figma组件中未内置的可访问性属性、需求和使用指南
例如，在为TextInput组件构建预设注释时，团队发现实现可能仅使用图标或隐藏输入标签。虽然放大镜图标可以作为可见标签，但这些字段仍需为辅助技术用户提供可访问的标签。
2. 整合所有信息创建预设注释
2.1 实际案例：TextInput组件
TextInput组件的预设注释包含：
- 使用指南和Storybook的链接
- 关于如何在设计中最佳使用组件以避免潜在问题的可选教程
- 输入类型和错误文本的两个必填提示
- 偶尔隐藏表单标签的可选提示
2.2 处理Figma组件的局限性
Figma组件虽然提供许多自定义选项，但仍有重要信息无法直接设置。例如，TextInput组件虽然有inputTextType属性（关于视觉设计和排版），但没有设置表单输入类型的选项；可以在侧边栏设置标签和输入字段的值，但由于默认隐藏，无法设置错误验证消息的文本。
3. 创建预设注释的经验教训
3.1 适用场景
预设注释特别适合：
- 新兴的设计系统
- 尚未被广泛采用的设计系统
3.2 维护挑战
成熟的设计系统（如Primer）频繁更新，这意味着如果没有密切监控，设计系统组件本身可能会与预设注释的构建方式不同步，导致开发开始后出现混乱和返工。因此，必须确保在注释创建后有维护的能力。
3.3 团队适用性
对于新团队或对设计系统不熟悉的成员，内置的指导和文档链接非常有用。更有经验的成员则能够微调预设及其使用方式。
4. 预设注释与通用注释的关系
4.1 重叠问题
组件的预设注释和非设计系统特有的注释类型之间可能存在足够的重叠，这可能导致混淆。例如，GitHub注释工具包同时包含基本<textarea>表单元素的注释组件和<TextArea> Primer组件的预设注释。
4.2 解决方案
一种解决方法是向默认注释集添加设计系统特定的属性。这样可以在普通注释上切换布尔属性，使其显示与设计系统组件相关的特定链接和属性。
5. 预设创建流程可能解锁自动化
5.1 当前工具的局限性
现有的Figma插件虽然声称能够扫描设计文件以帮助注释，但结果往往参差不齐，包含难以管理的噪音和误报。主要原因是这些公共插件与设计系统无关。
5.2 自动化前提
要让插件准确标记设计元素，首先需要：
- 理解如何识别画布上的组件
- 识别使用的变体
- 理解设置的属性
映射预设注释的组件属性（那些视觉设计或代码中未传达的内容）是实现更实用注释自动化的必要步骤。
6. 有前景的新方法：Figma的Code Connect
6.1 Code Connect简介
Primer是Figma开发者模式中Code Connect功能的早期采用者之一。这项功能实际上可以稍微分离设计和代码，让设计师专注于在Figma中创造最佳用户体验，同时开发者也能获得最佳开发体验。
6.2 实际应用
通过Code Connect，团队能够绕过大部分预设注释，直接将关键的可访问性细节添加到开发者可以从Figma导出的代码中。例如：
- 在IconButton Figma组件中添加隐藏层
- 包含aria-label的文本属性，让设计师直接从组件属性面板添加值
- 隐藏层不会干扰视觉效果，aria-label属性会与组件的其他代码一起直接导出
6.3 实施建议
为设计系统各组件设置Code Connect需要时间，以下是一些建议：
- 保持一致性：确保创建的属性和隐藏图层的放置方式在各个组件之间保持一致
- 使用分支实验：在设计系统库的分支上进行实验
- 使用视觉回归测试(VRT)：直接向组件添加复杂性会增加未来出现故障的风险，尤其是对于有多种变体的组件
结论
本文深入探讨了设计系统中高级组件注释的方法，重点介绍了创建自定义预设注释的完整流程以及利用Figma Code Connect的创新方法。通过系统地评估组件优先级、映射关键属性并整合多源信息，团队能够创建出既实用又具针对性的注释系统。同时，Code Connect的引入为设计系统注释带来了新的可能性，通过将关键可访问性细节直接嵌入代码，大大提高了设计和开发之间的协作效率。
从实践中我们了解到，预设注释特别适合新兴或未被广泛采用的设计系统，但也需要持续的维护投入。而自动化注释工具的潜力则与对组件属性的深入理解密不可分。随着设计系统工具的不断发展，如Code Connect这样的创新功能正在为设计和开发团队创造更加无缝的协作体验。
扩展链接
文章内容来源于Github Copilot官网
