企业官网建设流程全解析

• 前端
• UI组件

foregroundOnAccentRest是 FAST Frame 设计系统（@microsoft/fast-components）中一个核心的颜色 Design Token：它以CSSDesignToken<Swatch>类型向样式表提供“置于强调色背景上的静止状态前景色”。本文以该 Token 为主线，讲解其签名语义、在自适应颜色系统（Adaptive Color System）中的算法定位、rest/hover/active/focus 状态族，以及如何在 accent 按钮样式和高对比度（forced-colors）场景中正确使用它。

一、Token 签名解析：类型与归属

依据 API 文档 fast-components.foregroundonaccentrest.md，该变量的完整类型签名如下：

foregroundOnAccentRest: import("@microsoft/fast-foundation").CSSDesignToken<Swatch>

逐层拆解这条签名：

• 变量名foregroundOnAccentRest：命名遵循“用途 + 状态”的规则——foreground表示该值面向文本、图标等轻量级前景内容；OnAccent表示其语义是“放置于 accent 色彩之上”；Rest表示组件处于默认静止状态（非 hover、非 active、非 focus）。
• import("@microsoft/fast-foundation").CSSDesignToken：类型来源于@microsoft/fast-foundation的 Design Token 体系。作为CSSDesignToken，它既可在 TypeScript 中以变量形式取值，也会在运行时向 DOM 输出对应的 CSS 自定义属性，供组件样式直接消费。
• 泛型参数Swatch：Swatch在 FAST 的颜色体系中代表一个可用的颜色样本（参见 fast-components 变量索引 中对Swatch、Palette的定义：Palette是Swatch实例的集合）。因此该 Token 的值是一个具体的颜色。

从 API 文档结构看，该 Token 隶属于@microsoft/fast-components（FAST Frame）导出的变量集合，与accentFillRest、accentForegroundRest、neutralForeground等一批颜色 Token 并列，共同构成 FAST Frame 的令牌化样式体系。

二、算法定位：foregroundOnAccent 的工作原理

在 FAST Frame 的 自适应颜色系统 中，颜色由“Recipe”（算法 + 输入值的组合）生成。foregroundOnAccent是一类特殊的前景色 Recipe，其关键特征如下：

• 无状态（Not stateful）：与accentFill、accentForeground等支持 rest/hover/active/focus 四态的 Recipe 不同，foregroundOnAccent本身不区分交互状态；各状态的值由 Token 层派生（详见下一节）。
• 不使用 accent palette，但专为 accent 背景设计：算法并不从 accent 色板中取色，而是根据传入的contrastTarget（对比度目标值）直接在黑色与白色之间二选一。
• 优先返回白色：因为 accent 按钮最常见的视觉惯例是“accent 背景 + 白色文字”，算法在对比度允许时优先给出白色，以此满足 WCAG 对比度要求并保持明暗模式下的视觉一致性。

需要特别说明的是，该算法“返回黑或白”的能力由contrastTarget这一输入驱动——这正是自适应颜色系统“根据所在容器颜色自动适配”的核心机制：同一个 Recipe 在浅色与深色模式下都能推导出可达标的前景色。

三、状态族与 Token 变体

虽然算法本身无状态，但@microsoft/fast-components为“置于 accent 之上”的前景色导出了一整套按交互状态命名的CSSDesignToken<Swatch>变量（见 fast-components 变量索引），本文的主角foregroundOnAccentRest只是其中一员：

由此可以看出 FAST 的 Token 分层设计：*Recipe层保存算法与输入配置，*Rest/Hover/Active/Focus层输出可直接用于样式的具体颜色，*Large变体则针对需要更大对比度目标的文字场景单独推导。实际开发中，样式表通常直接消费foregroundOnAccentRest这样的终态 Token。

四、实战：accent 按钮样式中的用法

FAST 官方文档在 高对比度指南 中给出了foregroundOnAccentRest最典型的应用场景——accent 按钮：

export const AccentButtonStyles = css` :host([appearance="accent"]) { background: ${accentFillRest}; color: ${foregroundOnAccentRest}; } :host([appearance="accent"]:hover) { background: ${accentFillHover}; } :host([appearance="accent"]:active) .control:active { background: ${accentFillActive}; } :host([appearance="accent"]) .control:${focusVisible} { box-shadow: 0 0 0 calc(${focusStrokeWidth} * 1px) inset ${focusStrokeInner}; } :host([appearance="accent"][disabled]) { opacity: ${disabledOpacity}; background: ${accentFillRest}; } `

要点解读：

• background使用同族的accentFillRest，color使用foregroundOnAccentRest，二者配对即可保证 accent 背景上的文字对比度达标。
• 按钮的 hover/active 只替换背景色（accentFillHover/accentFillActive），前景色仍沿用 rest 值——因为foregroundOnAccent返回的黑/白在强调色明暗变化下依然适用。
• 使用方式与 FAST 的css标签模板完全一致：Token 以${...}插值形式进入样式，运行时由 Design Token 体系解析为 CSS 自定义属性值。

五、高对比度模式下的正确姿势

foregroundOnAccentRest保障的是正常配色下的对比度；在 Windows 高对比度等forced-colors场景中，UA 会强制使用用户选定的受限调色板，此时应补充独立的样式分支。

FAST 为此提供了forcedColorsStylesheetBehavior：将forced-colors样式包裹在行为中，由 CSS 媒体查询条件决定是否附加，避免在非高对比度环境下产生无谓的运行时开销。针对上述 accent 按钮的补全示例（同样摘自 高对比度指南）：

export const AccentButtonStyles = css` /* ... */ `.withBehaviors( forcedColorsStylesheetBehavior( css` :host([appearance="accent"]) .control { forced-color-adjust: none; background: ${SystemColors.Highlight}; color: ${SystemColors.HighlightText}; } :host([appearance="accent"]) .control:hover, :host([appearance="accent"]:active) .control:active { background: ${SystemColors.HighlightText}; border-color: ${SystemColors.Highlight}; color: ${SystemColors.Highlight}; } :host([appearance="accent"]) .control:${focusVisible} { border-color: ${SystemColors.ButtonText}; box-shadow: 0 0 0 2px ${SystemColors.HighlightText} inset; } :host([appearance="accent"][disabled]), :host([appearance="accent"][disabled]) .control, :host([appearance="accent"][disabled]) .control:hover { background: ${SystemColors.ButtonFace}; border-color: ${SystemColors.GrayText}; color: ${SystemColors.GrayText}; opacity: 1; } ` ) );

这里不再使用foregroundOnAccentRest，而是改用 CSS 系统颜色关键字（SystemColors枚举）。原因在于forced-colors模式下 UA 会接管配色，Token 推导的黑/白不再可靠；同时示例通过forced-color-adjust: none移除 UA 对文本元素自动施加的背板，并用Highlight/HighlightText对、GrayText与opacity: 1分别还原选中态和禁用态的对比度。

六、配套 Token 与使用建议

围绕 accent 配色，foregroundOnAccentRest通常与以下 Token 协同使用（均可从 fast-components 变量索引 查阅）：

• accentFillRest/accentFillHover/accentFillActive/accentFillFocus：accent 填充色状态族，构成按钮、开关等组件的背板；
• accentColor、accentPalette：全局 accent 主色及其色板，是 Recipe 推导的输入；
• foregroundOnAccentRestLarge等大字号变体：需要更高对比度目标的大文本场景。

两点实践提醒：

1. 背景配对使用：foregroundOnAccent*系列语义上“放置于 accent 之上”，因此应搭配 accent 系背景使用，而非任意中性背景。
2. 自定义属性不可直接覆盖：FAST 的自适应颜色系统完全由 JavaScript 驱动并向 DOM 输出 CSS 自定义属性；若在 CSS 中直接声明同名自定义属性，系统无法感知，组件将渲染出错误颜色并引发可访问性问题。需要调整值时，应使用 Design Token 的setValueFor()API 编程式设置。

七、小结与延伸阅读

foregroundOnAccentRest看似只是一个颜色变量，实则是 FAST 自适应颜色系统的缩影：Recipe 算法负责在“对比度达标”约束下自动决策黑/白前景色，CSSDesignToken<Swatch>类型负责把决策结果接入 TypeScript 与 CSS 两个世界，而 rest/hover/active/focus 与 Large 变体则覆盖了组件全部交互状态与字号需求。

• 算法原理与完整 Recipe 清单：自适应颜色系统
• 高对比度与 forced-colors 完整实战：High Contrast in FAST
• Design Token 设置与自定义：Design Tokens
• 全部 API 索引：fast-components API

• 前端
• UI组件