Radix Themes 设计系统.

Radix Themes 设计系统视觉主题与氛围

实用界面，而非情绪板

Radix Themes 可作为实用参考，适用于人们需要阅读、决策、输入信息并继续未完成工作的产品。其视觉风格源于经过考量的间距、克制的界面表面、清晰的字体层级，以及可重复使用的组件状态。使用本指南构建项目工作区、账户区域、设置界面或数据审核流程。目标是打造内容真实、连贯实用的屏幕，而不是把一组好看的组件随意拼在一起。

选择合适的起点

对于 React 应用，请从实际的 Radix Themes 软件包入手，并优先使用其中的组件，而不是自行编写替代组件。对于使用其他技术栈的视觉概念，请将这些原则作为参考，并说明设计灵感来自该系统。Radix Themes 和 Radix Primitives 是不同的起点：本指南介绍的是经过样式设计的 Themes 库。OpenDesign 指南不会让任意 HTML 样稿自动成为原生 Radix 实现。

围绕具体任务构建

1. 为首屏选择一个主要操作，例如创建项目或保存账户设置。
2. 在操作之前，先提供做出决定所需的信息。
3. 让导航、对象元数据、可编辑字段和反馈在视觉上彼此区分。
4. 设计时使用真实的长标题、不同的状态值和空状态。
5. 如果一个界面只有在使用三个简短占位标签时才有效，就说明还没有建立起可用的系统。

语气与内容

使用简短且具描述性的标签、明确的动词和直白的说明。按钮应说明接下来会发生什么，例如“保存更改”“邀请成员”或“创建项目”。标题用于说明区块主题；避免给每个小控件都配上营销口号。操作失败时，说明用户可以如何解决问题，并保留其已完成的工作。这些是应用参考指南时的 OpenDesign 内容编辑建议，并非 Radix 提供的额外 API。

Radix Themes 设计系统配色方案与角色

区分品牌色与语义色

使用主题，不要为屏幕样式硬编码

官方主题配置提供 accentColor 和 grayColor。在根级别选择它们，让各个组件共享同一套决策。在自定义组件中，引用当前主题的 CSS 变量，而不要照搬截图中的颜色。下方的令牌参考列出了精简实用的一组令牌。令牌是已配置主题中的一种角色，并不意味着同一个十六进制值会在浅色模式、深色模式和各种强调色选项中始终保持不变。

界面表面与边框层级

先使用克制的页面背景。只有在卡片和可编辑面板用于归纳相关工作时，才为它们设置不同的界面表面。同一列表中的行应使用分隔线。避免同时给每个项目添加边框、阴影、着色背景和徽标。在设置界面中，用一个带分隔行的面板通常比六张悬浮卡片更清晰。以低对比度呈现层级，同时确保重要文本清晰易读。

浅色与深色外观

对原生组件使用官方外观设置，并在内容相同的情况下分别检查两种外观。不要简单地反转颜色，或重复使用浅色模式的阴影来生成深色界面。请逐项检查叠加层、非活动字段、分隔线、选中行，以及强调色背景上的文本。本页的交互示例展示了一小部分主题选项；完整的库及其原生行为请以官方体验平台为准。

对比度与冗余提示

更改强调色或界面表面后，检查最终的前景色与背景色组合。用文本辅助颜色表达“待处理”“已完成”和“失败”等状态。为选项增加勾选标记或其他明显的选中提示。不要以为采用了无障碍组件库，所有内容或主题组合就都符合无障碍要求：标签、嵌套结构、自定义 CSS 和信息顺序仍会影响整个界面的可用性。

Radix Themes 设计系统字体排版规则

清晰易读的层级

为界面设置一个明确的标题，再区分章节标题、正文、字段标签和辅助元数据。使用尽可能少的字号来说明这些关系。对于信息密集的产品界面，标签的易读性比夸张的展示字体更重要。让说明性段落紧邻其所解释的控件，并确保输入框有值后标签仍然可见。占位文本只是提示，不能替代字段标签。

字号与字重

Radix 文档介绍了九级排版比例，每级都配有字号、行高和字间距。本页的参考表保留了基础比例中的这些数值。选择某一级时，应将其作为完整组合使用，不要搭配无关的行高。正文使用常规字重，标题或选中标签则使用较粗的字重。如果所有内容都加粗，层级就会消失；如果所有次要文本都调浅，界面就会难以阅读。

字体选择与回退字体

Radix Themes 默认使用系统字体栈。当跨平台兼容性比特定品牌字体更重要时，请保留该字体栈；或者通过文档说明的自定义机制配置已获授权的字体。周边的 OpenDesign 网站使用 Albert Sans，但这并不意味着 Albert Sans 是 Radix 的官方字体。对于多语言应用，请使用实际的回退字体测试有代表性的中文、日文、韩文和较长的欧洲语言标签。

数字、代码与换行

让数字列保持对齐，便于纵向比较数值。对于代码、标识符和令牌等需要关注字符边界的内容，使用等宽字体样式。标题和描述应自然换行；不要为了保持卡片高度而截断重要说明。对于 ID 等确实无法断开的字符串，请提供可控换行或复制操作。在移动设备上，即使布局发生变化，也要确保内容含义完整。

内容长度也是设计的一部分

在确认组件可复用之前，请先测试较长的项目名称、占两行的成员角色，以及翻译后的操作文案。尽可能让按钮随内容伸展，而不是为所有按钮设置固定宽度。正文段落应保持舒适的阅读宽度；需要比较并列信息时，请使用列表或表格。不要仅仅为了让页面显得更有设计感，就把说明文字拆分成许多零散的装饰性卡片。

Radix Themes 设计系统组件样式与状态

按钮与操作层级

在同一组操作中，明确主要决策，并为其采用最突出的样式。次要操作应易于查找，但不要与主要操作同等抢眼。将破坏性操作与常规确认操作区分开来。提交期间应防止重复操作，并显示明确的进度；完成后应展示实际结果。如果禁用按钮的原因无法从表单中明显看出，请在附近说明原因。

输入框与表单

• 在每个输入框上方或旁边放置始终可见的标签。
• 将帮助文本放在相关字段旁边，并将验证消息关联到对应字段，而不是只显示通用提示横幅。
• 验证失败时保留已输入的内容。
• 使用有意义的分区标题对相关字段进行分组。
• 使用合适的输入类型和自动填充值，让浏览器和辅助工具帮助用户完成操作。

卡片、列表与表格

对于包含有意义摘要和操作的独立对象，使用卡片；对于一组相似记录，使用列表；需要比较不同记录的属性时，使用表格。展示所有者、更新时间和状态等实际字段，而不是装饰性的图表片段。卡片不应采用会与内部链接或按钮争抢操作焦点的点击方式；请选择明确的链接目标，并保留常规键盘操作行为。

导航与选择

将全局导航与页面级标签页和局部筛选器区分开来。当前所在位置应始终清晰可辨，不能只依赖强调色来表示。使用链接进行导航，使用按钮执行页面内更改。如果采用标签页模式，请实现相应的键盘操作行为；否则，请使用标签明确的一组普通按钮。不要让一排视觉上像交互元素、实际上却无法操作的文本看起来可点击。

菜单、对话框与浮层

实现 React 产品时，复杂交互应使用原生库组件。对话框需要包含标题、明确的关闭方式、恰当的焦点管理，并在关闭后将焦点返回触发控件。避免只用绝对定位的卡片构建模态框，却不实现这些行为。对话框应聚焦于单个决策；较长的编辑流程通常更适合放在独立页面，而不是不断变得拥挤的浮层中。

加载、空状态、错误与成功

• 围绕同一项实际任务设计每种状态。
• 空项目列表应说明如何创建第一个项目。
• 加载状态应保留足够的结构，避免界面出现突兀跳动。
• 错误状态应提供有意义的后续操作，且不应抹去已完成的工作。
• 成功消息应说明发生了什么变化。
• 本页的静态示例按钮仅用于展示外观，并不能证明这些状态在生产环境中的实际行为。

Radix Themes 设计系统布局、间距与密度

使用统一的间距比例

文档记录的间距比例包含九个基础步长：4、8、12、16、24、32、40、48 和 64 像素。在紧密关联的控件内部使用较小步长，在独立区块之间使用较大步长。让标题与其内容之间的关系清晰可见。不要为了填满屏幕而平均分配空白：元素间距应传达哪些信息彼此相关。

密度应服务于任务

资源目录需要展示足够多的条目，便于用户进行比较。配置表单需要为标签、帮助信息和错误提示留出空间。阅读页面需要稳定的行宽和清晰可见的目录。应根据任务选择内容密度，而不是在所有地方都使用相同大小的卡片。Radix 还提供了一个缩放设置，可同步调整相关尺寸；在将紧凑比例设为产品默认值之前，应先评估调整后的可读性和交互目标大小。

网格与容器行为

先设置页面容器，再定义主要内容区域及任何辅助侧栏。即使外部画布很宽，也要让长文本保持在易读的栏宽内。在较窄的视口中，将辅助内容移到主要内容下方，或将长侧栏转换为便于访问的本地导航控件。保持源顺序合理，使移动端浏览和键盘操作顺序无需依赖桌面网格布局也能清晰易用。

用行布局替代嵌套卡片

对于紧凑的设计令牌参考页，可将名称、值和用途放在同一行，方便快速浏览。对于目录，应将标题、类别、说明和目标页面放在一起。反复嵌套方框会增加视觉干扰，还会占用本应留给内容的宽度。相关行之间优先使用细分隔线；只有在上下文确实发生变化时，例如展示实时预览或代码示例，才使用带边框的面板。

确保重要内容清晰可见

不要只为缩短页面，就把详尽指南删减成简短摘要。应提供目录和清晰的小标题，方便读者直接找到相关内容。如果筛选器或折叠面板会改变内容的可见性，空状态和选中状态都应清晰明确。除非确实有交互需求，否则避免使用独立滚动的内部列表；浏览较长的资源集合时，通常直接滚动页面更简单。

Radix Themes 设计系统圆角、层次与动效

圆角表达关系

Radix 提供了命名的圆角设置和基于上下文的组件行为。请在主题层级选择圆角设置，而不是给每个元素都指定相同的任意圆角。按钮、复选框和大型面板各有不同的结构作用。让它们的形状保持协调，同时保留各自的特点。如果自定义组件使用了圆角令牌，请先将它与原生按钮和输入框放在一起测试，再决定它是否属于同一套系统。

用层次表现空间关系

利用深度区分浮层与下方页面，或交互面板与克制的画布。Radix 提供六级阴影。不要把阴影级别当成卡片装饰效果的流行度排名。内容密集的目录往往只用边框就足够。请分别检查浅色和深色外观；直接将浅色模式的模糊阴影复制到深色背景层上，可能会让阴影消失，或形成暗示错误层次的光晕。

让动效清晰地说明变化

使用简短过渡来说明选择、展开、进度或相关状态之间的切换。不要让内容被入场动画延迟显示。避免在以工作为主的界面中加入持续的背景动效。尊重减少动态效果的偏好，并确保移除过渡后最终状态仍清晰易读。自定义实现中的计时选择属于应用层面的决策；对于尚未核实的 Radix 时长令牌，本指南不会凭空补充。

交互无需多余装饰

悬停样式应强化元素可操作这一点。焦点样式应在相邻界面表面上清晰可见。不要让密集列表行在悬停时大幅移动，以免用户阅读时信息位置发生变化。在触摸屏上，重要操作不能依赖悬停才能使用。当效果能帮助用户理解控件，而不是只让动画本身吸引注意力时，它才算成功。

Radix Themes 设计系统：该做与不该做

该做：建立完整的屏幕界面

构建一个包含真实导航、有意义内容、主要操作和至少一种特殊状态的屏幕界面。先检查整个界面，再拆分出大量可复用组件。记录有意做出的选择，例如强调色、信息密度、字体层级和空状态文案。这样可以为 AI Agent 提供明确的执行规范，也便于在后续迭代中发现偏差。

该做：保持原生组件与自定义组件的一致性

对于库已支持的行为，优先使用库中已有的组件。自定义封装应使用主题变量，并在浅色和深色外观下都进行检查。设置样式时，保留标签和语义 HTML。如果项目已有设计系统，请先将其与此参考进行比较，再决定是否替换；额外添加一层缺乏统一管理的主题，可能会加剧而非减少不一致。

不该做：只换颜色来复刻品牌

仅更改强调色并不能构建出协调一致的界面。间距、字体、内容层级、交互模式和响应式布局选择，都在很大程度上塑造着视觉风格。不要仅仅因为某个模型界面看起来像该库，就声称已与其官方集成。不要将其他产品的商标、专有素材或业务声明照搬到新产品界面中。

不要：为了截图更简洁而牺牲信息含义

Radix Themes 设计系统的响应式与无障碍行为

先调整结构，再缩小内容

屏幕变窄时，应减少列数、缩短通往主要操作的路径，并将次要信息移入常规阅读流。不要把桌面仪表板整体缩成一张图，就称其为移动端布局。通过换行、纵向堆叠或适当的表格样式，确保内容仍然完整可用。保留描述清晰的链接文本，使用户脱离桌面卡片上下文时，仍能理解链接的去向。

有目的地使用文档中说明的断点

官方断点名称为 initial、xs、sm、md、lg 和 xl。其最小宽度分别为 0、520、768、1024、1280 和 1640 像素。将断点视为可用工具，而不是必须在每个断点都更改布局。只有当内容需要采用不同布局时，才添加断点。除了测试断点本身，也要测试两个已命名断点之间的宽度，以发现脆弱的中间布局。

键盘操作与焦点

• 所有有意义的操作都应支持键盘访问。
• 让可见的焦点状态明显区别于悬停状态，并确保容器裁切内容时，焦点状态仍然可见。
• 避免使用正数 tabindex 值，以免控件顺序变得难以预测。
• 筛选器改变结果后，让焦点留在该控件上，并简洁地告知结果数量。
• 关闭模态框后，应将焦点返回到合适的位置，而不是让用户回到文档开头。

标签、操作目标与辅助文本

为仅包含图标的操作提供无障碍名称，说明操作而非图标形状。即使图标视觉尺寸较小，也要确保触控目标大小适宜。将装饰性图标排除在无障碍树之外。对于已保存更改、搜索结果数量等更新，应予以播报，但不要反复播报无关内容。当某个状态同时使用图标和文字时，避免让屏幕阅读器重复播报相同信息。

使用真实内容进行验证

• 检查桌面设备、平板设备和窄屏手机。
• 测试文本扩展、图片缺失、列表为空以及没有空格的长标识符等情况。
• 在减少动态效果设置下以及使用键盘导航时测试页面。
• 每次进行大幅配色调整后，都要检查两种外观模式。
• 自动化检查可以发现结构问题，但无法判断层级、内容密度和整体视觉风格是否符合产品需求。

Radix Themes 设计系统 AI Agent 提示词指南与实现

准备项目背景信息

1. 告诉编码 Agent 正在构建什么、谁会使用、主要操作是什么，以及哪些现有文件定义了当前设计。
2. 将本指南作为参考附上，而不是要求 Agent 模仿一张未说明来源的截图。
3. 如果使用 React，请说明应优先使用原生 Radix Themes 组件。
4. 如果使用其他技术栈，请要求提供明确标注的适配方案，并评估其所需的额外交互实现工作。

明确指定完整的首轮实现

要求实现一个包含真实内容和少量状态的可用界面。明确指定导航、字段、对象元数据以及主要操作的预期结果。在需求中纳入键盘焦点、空状态、验证反馈和窄屏布局。说明必须保留的约束，例如现有页眉、生产环境数据契约或已获批准的内容区块。

按能发现实际问题的顺序进行审核

1. 首先确认界面能否支持预期任务。
2. 然后对照选定的参考，检查信息层级、间距、排版和配色。
3. 最后测试交互状态和响应式布局。
4. 不要仅仅因为页面能够编译或截图看起来整洁，就接受视觉改动。
5. 视觉调整完成后，检查较长内容、错误情况和重复操作是否仍能正常使用。

通过明确的决策逐步扩展

首屏运行正常后，记录主题配置、字体角色、间距选择和需要复用的组件模式。请 AI Agent 将这些决策应用到下一个屏幕，同时不要擅自改写已确认的内容。如果新屏幕需要采用不同模式，请记录原因，并检查之前的屏幕以确保一致性。基于已验证的行为进行扩展，而不是生成一大批表面相似的页面。

适用范围与来源说明