企业官网建设流程全解析

• 前端
• UI组件

导读

neutralStrokeRecipe是 FAST Frame（@microsoft/fast-components）自适应色彩系统中用于生成"描边（Stroke）"颜色的一组核心配方（Recipe）设计令牌。它通过算法与调色板组合，为组件的 rest（静止）、hover（悬停）、active（激活）、focus（聚焦）四种交互状态计算出符合对比度要求、且能随明暗主题自适应切换的描边颜色。读完本文，你将掌握neutralStrokeRecipe的类型签名、InteractiveColorRecipe.evaluate()的调用方式与返回值结构，理解它与neutralStrokeRest、neutralStrokeHover、neutralStrokeActive、neutralStrokeFocus及各 Delta 令牌之间的协作关系，并能在自己的组件样式设计中正确使用或覆盖这一配方。

一、API 概览：类型签名与在 fast-components 中的位置

neutralStrokeRecipe的官方 API 文档（sites/website/src/docs/1.x/api/fast-components.neutralstrokerecipe.md）给出的签名如下：

neutralStrokeRecipe: DesignToken<InteractiveColorRecipe>

它隶属于@microsoft/fast-components包导出的 Design Token 体系。在同包的模块索引文档（sites/website/src/docs/1.x/api/fast-components.md）中，与之紧密相关的公开变量还包括：

• neutralStrokeRest：类型为CSSDesignToken<Swatch>，静止态描边色；
• neutralStrokeHover：悬停态描边色；
• neutralStrokeActive：激活态描边色；
• neutralStrokeFocus：聚焦态描边色；
• neutralStrokeRestDelta/neutralStrokeHoverDelta/neutralStrokeActiveDelta/neutralStrokeFocusDelta：均为DesignToken<number>，用于在调色板中偏移取色的数值增量。

这一组令牌共同构成"stateful"（有状态）的neutralStroke配方体系，覆盖组件轮廓线与分隔线的全部交互状态。

二、配方类型的含义：DesignToken

要理解neutralStrokeRecipe，需要拆解其泛型参数InteractiveColorRecipe。该接口定义于 sites/website/src/docs/1.x/api/fast-components.interactivecolorrecipe.md：

export interface InteractiveColorRecipe

它声明了一个唯一方法：

evaluate(element: HTMLElement, reference?: Swatch): InteractiveSwatchSet;

其中：

• element：当前组件实例（HTMLElement），配方在求值时用于读取该元素上的设计令牌上下文（如designUnit、direction、baseLayerLuminance等）；
• reference：可选参数，类型为 Swatch。Swatch 表示 Palette 中的一个颜色，且继承了RelativeLuminance并提供contrast(target)与toColorString()两个方法，分别用于计算相对对比度和输出 CSS 颜色字符串；
• 返回值：InteractiveSwatchSet。

返回值InteractiveSwatchSet（sites/website/src/docs/1.x/api/fast-components.interactiveswatchset.md）包含四个属性：

因此，neutralStrokeRecipe: DesignToken<InteractiveColorRecipe>的含义是：这是一个承载"配方对象"的设计令牌，对该令牌求值（getValueFor(element)或样式绑定）后可拿到一个实现了evaluate()的配方，再传入元素与参考色即可一次性得到四种交互状态的描边 Swatch。

三、在自适应色彩系统中的定位：Recipes 与 reference 机制

在 FAST Frame 的自适应色彩系统中（详见 sites/website/src/docs/1.x/design-systems/fast-frame.md），Recipe 被定义为"算法 + 输入值的组合"。文档用烘焙类比说明：像用不同配比的糖、黄油、面粉、盐可以烤出不同饼干一样，修改配方的数值（measurements）或算法（instructions）即可产出不同的设计系统处理方式。

neutralStroke在文档的算法清单中被明确归类为：

Stateful. Used for strong outline, either alone or with a fill.

即"有状态的（stateful）、用于强轮廓线、可单独使用也可与填充色搭配"。

自适应色彩系统强调referenceSwatch 这一核心概念：大多数颜色配方接收一个reference参考色，使配方能依据所在组件的容器颜色而变化。例如，一个按钮只需一份配方即可在浅色与深色模式下保持一致观感。neutralStrokeRecipe.evaluate(element, reference)中的第二个参数正是这一机制的体现——当组件嵌套在深色卡片或浅色页面中时，传入不同的reference，配方会从neutralPalette中选取在视觉与对比度上都合适的描边颜色。

此外，文档还给出了重要的使用纪律（Adaptive Color "Don'ts"）：自适应色彩系统完全运行在 JavaScript 中，通过向组件样式输出 CSS 自定义属性来生效。由颜色类设计令牌发射出的 CSS 自定义属性应被视为不可变——如果在普通 CSS 中手工声明这些自定义属性，系统无法感知这一变更，组件会以错误的颜色渲染，进而引发可访问性问题。如需修改，应使用DesignToken.setValueFor()API 进行设置。

四、neutralStroke 的配套令牌与取色逻辑

neutralStrokeRecipe是"配方（算法）"，而其配套的 Delta 令牌则是"配料的数值"。fast-components导出的四个 Delta 令牌类型一致：

neutralStrokeRestDelta: DesignToken<number> neutralStrokeHoverDelta: DesignToken<number> neutralStrokeActiveDelta: DesignToken<number> neutralStrokeFocusDelta: DesignToken<number>

以 sites/website/src/docs/1.x/api/fast-components.neutralstrokerestdelta.md 为代表，这些数值型令牌用于在neutralPalette中按增量偏移选取 Swatch。整体逻辑可概括为：

1. 配方根据reference在neutralPalette中定位一个基准索引；
2. 对每个交互状态，分别加上neutralStrokeRestDelta、neutralStrokeHoverDelta、neutralStrokeActiveDelta、neutralStrokeFocusDelta得到目标索引；
3. 从调色板对应索引取出 Swatch，构成InteractiveSwatchSet返回。

而各状态色令牌（如 sites/website/src/docs/1.x/api/fast-components.neutralstrokerest.md）则是求值后的"成品"：

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

注意其类型是CSSDesignToken<Swatch>而非普通DesignToken——这意味着该令牌除了可作为值读取外，还会直接以 CSS 自定义属性的形式输出到元素样式上，供组件样式表消费。这正是文档所述"颜色类设计令牌通过 CSS 自定义属性触达样式"的具体实现形态。

五、实战：在组件样式中使用 neutralStrokeRecipe

5.1 常规用法：直接消费状态色令牌

对于大多数组件开发者，无需直接调用evaluate()，因为 FAST Frame 的组件样式已经将求值结果绑定到了neutralStrokeRest/neutralStrokeHover/neutralStrokeActive/neutralStrokeFocus四个 CSSDesignToken 上。在自定义组件样式中可按如下方式使用：

import { css } from "@microsoft/fast-element"; import { neutralStrokeRest, neutralStrokeHover, neutralStrokeActive, neutralStrokeFocus, focusStrokeWidth, strokeWidth, } from "@microsoft/fast-components"; export const outlinedControlStyles = css` :host { border: calc(${strokeWidth} * 1px) solid ${neutralStrokeRest}; } :host(:hover) { border-color: ${neutralStrokeHover}; } :host(:active) { border-color: ${neutralStrokeActive}; } :host(:focus) { border-color: ${neutralStrokeFocus}; border-width: calc(${focusStrokeWidth} * 1px); } `;

令牌在样式模板中直接引用即可获得随设计系统主题（浅色/深色、accent/neutral 调色板）自动变化的描边色，无需手工管理颜色值。

5.2 覆盖取值：用 DesignToken API 修改

若需要为特定元素覆盖描边颜色，应使用 DesignToken 的值设置 API，而不是在 CSS 中覆盖自定义属性：

neutralStrokeRest.setValueFor(myElement, myCustomSwatch); neutralStrokeHoverDelta.setValueFor(myElement, 2);

这保证了自适应色彩系统仍能感知取值变化，并维持组件在对比度与主题一致性上的正确表现。

5.3 直接调用配方

在构建自定义配方或调试工具时，也可以显式求值：

import { neutralStrokeRecipe } from "@microsoft/fast-components"; const recipe = neutralStrokeRecipe.getValueFor(myElement); const swatchSet = recipe.evaluate(myElement); // reference 可选 // swatchSet.rest / swatchSet.hover / swatchSet.active / swatchSet.focus

reference未传入时，配方通常以元素自身或设计系统上下文中的默认色为基准；传入自定义Swatch时，则依据该参考色在neutralPalette中重新定位取色窗口。

六、周边生态：其他同构配方

neutralStrokeRecipe并非孤立存在，@microsoft/fast-components还导出了一批使用相同InteractiveColorRecipe接口的配方令牌（见 sites/website/src/docs/1.x/api/fast-components.md 的 Variables 列表）：

它们的求值入口统一为InteractiveColorRecipe.evaluate(element, reference?)，返回统一的InteractiveSwatchSet结构，因此理解neutralStrokeRecipe后即可举一反三掌握整套交互色配方体系。

七、小结

• neutralStrokeRecipe: DesignToken<InteractiveColorRecipe>是 FAST Frame 中负责生成四种交互状态描边色的配方设计令牌；
• 配方的核心方法是evaluate(element: HTMLElement, reference?: Swatch): InteractiveSwatchSet，返回rest、hover、active、focus四个 Swatch；
• 状态色成品（neutralStrokeRest等）以CSSDesignToken<Swatch>形式直接输出 CSS 自定义属性，供样式表消费；Delta 数值令牌（neutralStrokeRestDelta等）控制调色板内的取色偏移；
• 颜色类设计令牌发射的 CSS 自定义属性不可在样式表中手工覆盖，应通过DesignToken.setValueFor()修改取值；
• 该配方与 accent/neutral 系列填充、前景、分隔线配方共用InteractiveColorRecipe接口，掌握其一即可迁移到全部交互色配方。

进一步阅读：FAST Frame 自适应色彩系统、InteractiveColorRecipe 接口、InteractiveSwatchSet 接口。

• 前端
• UI组件