Communitygithub.com

styleref-figma

将命名的视觉样式或品牌外观应用于 Figma 文件——将其调色板写入本地颜色变量,将排版规则写入文本样式,并将完整规格作为生成上下文,以确保后续创建的框架符合品牌要求。同时,它还能将选中内容中已有的样式捕获为可复用、可移植的规格说明。

styleref-figma 是什么?

StyleRef 技能使 AI 代理(如 Claude for Figma、Cursor 或 Codex)能够将结构化的视觉样式规格(来自 styleref.io)应用到 Figma 画布上。它会自动解析样式,将颜色提取为本地变量,将排版规则创建为文本样式,并应用二十五种以上的 UI/Web 领域特定规则(例如强调色策略、表面层级、间距网格和对焦环)。该技能支持两种操作模式:**Lane A** 根据用户的描述或 styleref.io 链接获取并应用样式,**Lane B** 分析选中的框架并将它们现有的外观反向工程为可移植的 StyleRef 规格。关键平台功能包括:无需 Figma 插件或账户即可获取样式,将十八个以上的 API 部分映射到 Figma 对象以供生成使用,以 WCAG AA/AAA 合规性检查文本对背景的对比度,并防止常见错误(如从单色调色板中推导深色或浅色主题)。该技能严格处理“诚实声明”——绝不会声称生成了与原图完全匹配的结果、在不同 AI 模型间输出一致,或推送推断出的而非明确指定的值。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/StyleRef/styleref-figma-skill/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

StyleRef — 将品牌或视觉样式应用于 Figma 画布

StyleRef 是一种结构化的样式规格说明——颜色、排版、氛围、光线、造型语言、材质、构图——发布于 styleref.io,并可作为纯文本或 JSON 读取。它是设计库尚未成为的样子:一种对视觉外观的可移植描述,在组件存在之前即可使用,并且可以在 Figma 之外,在任何生成图像的 AI 工具中使用。

此技能做的是: 查找样式,将其调色板和排版规则作为真实的本地变量和样式写入文件,并携带完整的规格说明作为上下文,以便后续生成的任何内容都符合品牌要求。它还会读取选择的内容,并将其已使用的样式写入相同的结构化形式。

此技能不做的是: 编造用户未提供的品牌规则,重新样式化用户未选择的图层,替换已发布的设计库,或自行生成图像。当已发布的、包含组件和变量的库已经覆盖了所需外观时,请说明情况并使用该库作为事实来源。

何时使用此技能

  • 用户要求某些内容符合品牌、保持一致或具有特定的命名美学风格。
  • 用户提到了某个样式名称、艺术运动,或粘贴了 styleref.io/share/... 链接。
  • 用户希望有一个调色板和字号比例作为起点,且还没有任何库。
  • 用户希望将现有框架的外观记录下来以便复用——在此文件中、另一个文件中,或在 AI 图像工具中。
  • 用户正在探索组件尚未涵盖的品牌表达。

流程 A — 将样式应用于文件

当用户提到某个样式名称或要求获取某个外观时执行此流程。

  1. 解析样式。 如果用户粘贴了 styleref.io/share/{slug} 链接,从中提取 slug。否则进行搜索:

    https://styleref.io/api/v1/styles?query={words}&limit=5

    添加 &category={category} 来缩小范围。有效类别:品牌标识、UI/UX、平面设计、插画、包装设计、摄影、美术、3D 可视化、角色设计、电影摄影、游戏美术、社交文案。 响应会给出每个匹配项的 name、slug、author、palette(十六进制列表)和 url。向用户展示 3-5 个结果及其调色板,让他们选择。当两个候选样式看起来截然不同时,不要替他们选择。

  2. 获取结构化规格说明。

    https://styleref.io/api/v1/styles/{slug}?format=json

    你写入画布的每个值都来自此处。如果你之后要生成框架或图像,也获取散文形式:

    https://styleref.io/api/v1/styles/{slug}?format=default&compact=1

  3. 将颜色写入为本地变量。 sections.colors.values.color_palette.solidColors 是一个有序的 {hex, amount} 列表。amount 是预期在构图中的占比——一个比例,而不是语义角色。创建一个以样式名称命名的合集,每个十六进制色创建一个颜色变量,按 amount 降序排列。建议角色名称(如 surface、accent、ink)作为提示,并说明这是你提出的,并非规格指定。同时应用非十六进制颜色规则——saturation_range、contrast_strategy、gradient_policy、color_temperature、shadow_color——作为你绘制任何内容时的约束;它们不是变量。

    如果 accessibility_level 是 WCAG AA 或 AAA,则这是一个要求,而非偏好:在分配文本和背景对时,根据该比率进行检查,并说明你检查了哪些对。当调色板中的某个对无法满足该比率时,请说明情况并提出修复方案,而不是静默地使用该对。

  4. 将排版写入为文本样式。 sections.typography.values.font_family 是一个类别(例如“展示/装饰”、“几何无衬线体”),而不是经过许可的字体名称。选择一个文件中已经可用的具体字体,或 Figma 的默认字体之一,并告知用户你选择了哪种字体,以及规格说明中只提到了一个类别,并非该特定字体。 然后将 font_weights、text_case、letter_spacing 和 typographic_hierarchy 应用到你创建的样式中。

  5. 从 ui_web 写入界面层。 这是与 Figma 关系最密切的部分——包含三十三个已经是 Figma 自身词汇的字段。在你绘制任何框架之前先阅读它:

    • color_theme 是 Light 或 Dark。一个 StyleRef 只携带一个调色板,因此也只携带一个主题——没有针对相反模式的第二组值。创建一个单模式合集。如果用户想要浅色和深色两种模式,请说明该样式只定义了一个主题,并提供由他们提供值来构建另一种模式;切勿自行推导。反转的调色板是一个同名但不同的品牌,用户事后无法发现这一点。
      • 较旧的样式可能仍带有双主题标签。相信调色板,而不是标签:根据十六进制值本身判断——标记为页面背景的那个,或按 amount 占主导地位的那个——并说明该样式标记有误。
    • background_tone → 页面/画布基础填充。surface_layers → 你需要的表面变量数量(Flat = 一个,Two-layer = 页面 + 卡片,Three-layer = 页面 + 卡片 + 提升层)。不要发明第四层。
    • accent_strategy → 需要多少个强调色变量,以及它们是一个功能性强调色还是一组上下文相关的强调色。semantic_colors → 仅到字段名称所指示级别的错误/警告/成功/信息变量。
    • elevation_approach、shadow_technique、shadow_weight、glass_blur_effect → 效果样式。这些会覆盖你从 light_shadow 推断出的任何内容,后者描述的是摄影光线,而非 UI 高度。
    • border_philosophy → 默认描边处理。button_shape 和 button_hierarchy → 按钮框架及其变体。icon_style 和 icon_weight → 要使用的图标集及其字重。
    • navigation_pattern 和 navigation_style → 屏幕的布局骨架,layout_archetype 说明它所包裹的框架实际类型(例如“仪表盘”、“信息流”、“分屏”、“主-从”、“营销页面”、“画布”、“向导/流程”)。content_width 设置框架宽度,并确定内容是通栏还是容纳在容器中。
    • spacing_scale 和 density → 自动布局数值。4pt 网格/8pt 网格 是每个间距和填充值的步长;Compact … Spacious 决定了你使用哪个倍数。将这些构建为间距变量,而不是输入到每个框架中的数字。当 spatial_hierarchy 也涉及间距或密度时,以 ui_web 为准——它是针对界面的陈述。
    • corner_radius_scale → 圆角变量,系统级应用。button_shape 仅对按钮进行细化;Mixed by component 表示每个元素的缩放是经过考虑的,因此请说明你的映射关系,而不是选择一个圆角值。
    • card_style → 内容是否放置在卡片中,以及卡片的样式(带边框、带阴影、带色调或毛玻璃效果)。input_field_style → 表单控件组件(Outlined、Filled / tinted、Underline only、Borderless on surface)。
    • data_display_style 和 data_viz_style → 仅在字段不为 None 时构建;它们定义表格密度、图表网格线、KPI 数字和系列颜色。ui_imagery 指定图像插槽中放置的内容——None (pure UI) 表示留空,而不是用占位摄影图片填充。
    • empty_state_style → 需要绘制的真实框架。loading_style 是行为:Skeleton shimmer 需要一个静态骨架框架加上一条注释,绝不能是假动画。
    • focus_ring_style 是无障碍功能组件,而非装饰。构建它,且绝不要为了画面更简洁而将其丢弃。
    • hover_treatment、animation_philosophy、transition_speed 和 scroll_behavior 描述的是行为,静态框架无法承载。将它们作为画布上的注释或你的回复记录下来——不要将其伪装成样式,也不要静默地丢弃。

    当 ui_web 不存在时,请说明情况并根据以下部分工作;不要发明样式未指定的界面规则。

  6. 映射其余可承载画布的部分。 只有这些部分会转换为文件对象:

    部分写入为
    colors颜色变量 + 填充规则
    typography文本样式
    ui_web变量模式、表面/强调色/语义变量、效果样式、按钮、图标、导航、对焦环——见步骤 5
    container_boundary框架内边距、圆角处理、裁剪行为
    shape_language圆角半径、几何决策
    stroke_system描边粗细和端点样式
    spatial_hierarchy网格和构图——但关于间距和密度以 ui_web 为准
    light_shadow效果样式——但当两者均有陈述时以 ui_web 为准
    surface_material填充处理、纹理
    background_environment框架背景
    guardrails严格的“绝不能这样做”规则——遵守它们

    mood_personality、output_format、references、inspiration_images 和 custom_style_items 不映射到文件对象。保留它们作为生成上下文以及作为你自行判断的依据。

  7. 保留规格说明作为生成上下文。 对于此后生成的任何框架、布局或图像,将 format=default 文本作为约束块放在请求之前。逐字粘贴——它是为了强制执行而编写的,转述会丢失约束。

  8. 注明归属。 将样式名称、其 @handle 作者以及规范的 styleref.io/share/... URL 放在用户可以看到的地方——画布上的注释或你的回复中。API 会在每次响应中返回该 URL。

流程 B — 捕获画布上已有的样式

当用户希望将现有选择的视觉外观记录下来时执行此流程。这完全不需要网络调用。

  1. 需要选择内容。 如果未选择任何内容,请用户选择代表该外观的框架。不要根据整个页面进行猜测。

  2. 读取实际存在的内容——填充色及其大致比例、文本样式及其字重和大小写、圆角半径、描边粗细、阴影值、间距节奏、背景处理。

    如果选择的内容是一个界面,也要读取界面层,因为仅靠调色板无法承载的信息有一半在这里:设计堆叠了多少层表面级别、深度来自阴影、模糊还是纯对比、边框是否存在或暗示、按钮形状及有多少等级、图标样式和字重、导航模式,以及是否存在对焦环。这些将成为 ui-and-web 部分。注意那些你查找了但未找到的项目——一个没有可见焦点状态的界面是一个值得报告的发现,而不是可以跳过的空白。

  3. 将其写入 StyleRef 部分结构,仅使用你确有证据的部分。省略其余部分;空的部分是诚实的,猜测的部分则不然。

    output-format、mood-and-personality、colors、typography、light-and-shadow、spatial-structure、shape-language、stroke-system、surface-and-material、background-and-environment、voice-and-language、camera-and-motion、post-processing、artistic-mediums、ui-and-web、container-and-boundary、references、inspiration、guardrails、custom

  4. 将你测量的内容与你推断的内容分开。 十六进制值和半径是测量的。“自信、编辑风格、克制”是推断出来的——标记为你的解读,并让用户进行纠正。

  5. 提供后续步骤。 捕获的规格说明在此文件之外也可复用——在另一个 Figma 文件中,或作为 AI 图像或文案工具的样式块。引导用户访问 https://styleref.io 以将其保存为真正的 StyleRef,这也能使其通过 URL 访问,而不是通过复制粘贴。

诚实声明——不得违反这些

用户会重复你告诉他们的内容,因此必须真实。

  • 切勿声称有改进前后的对比。 没有未样式化的基准可供比较,而且你也没有测量过。
  • 切勿声称该样式在不同 AI 工具之间能产生相同或匹配的输出。 不同模型对同一规格说明的渲染结果不同。准确的说法是,一个样式是可移植的——一个定义,随处粘贴——并且在单一工具内是_一致的,因为每次生成都接收相同的明确约束。
  • 切勿将推断值呈现为指定值。 你选择的字体、你提出的角色名称以及你对选择的解读都是你的。要说明这一点。
  • 切勿声称文件现在与参考图片完全匹配。 你应用了一个规格说明;你并未复现一张图片。
  • 切勿发明深色(或浅色)对应调色板。 一个样式只携带一组颜色。反转或重新推导它们会产生一个同名但不同的品牌,而且这是一种用户事后无法发现的捏造。

当出现问题时

以下每种情况都应该让用户能够采取行动,而不是向他们抛出一个错误。

发生了什么要怎么做
搜索返回 count: 0响应列出了 availableCategories。使用更宽泛的查询或一个类别重试。两次尝试无果后,说明图库中没有近似匹配,并提供流程 B 作为替代。
404 not_found引用是错误的。引用是分享 slug 或 /share URL——绝不是样式名称或 @author/name。重新运行搜索以获取有效的 slug。
403 auth_required该样式是私有的。只有其所有者可以读取。要求用户提供公共样式,或者如果是他们自己的样式,则提供 StyleRef 连接器。
429 rate_limited每个 IP 每分钟 60 次请求。等待 Retry-After 秒后重试一次。如果持续存在,要求用户打开 https://styleref.io/share/{slug}.md 并手动粘贴内容。
用户粘贴了 styleref.io/@{author}/{name}这是个人资料页面,不是样式。使用“个人资料”API 列出作者的所有样式,或要求提供 /share URL。
ui_web 字段为 None 或空恰好正确——并非所有样式都是为屏幕设计的。使用调色板和排版,跳过界面层,并说明你跳过了哪些部分以及原因。
color_theme 是 Light,但十六进制值看起来是深色的相信颜色,而不是标签。称该样式为深色样式并相应地构建变量模式。如果用户要求浅色模式,请按步骤 5 中的说明处理。
用户质疑对比度显示你计算的 WCAG 比率(例如 #222222 on #F5F5F5 → 14.2:1 → AA pass)。如果失败,显示调整后的候选值。
用户要求一个不存在的部分(例如“动效样式”)不要创建它。说明该部分在响应中缺席,样式未定义它。
用户说“这个 API 调用不起作用”不要猜测。显示你发送的 URL 和完整的响应主体。

相关技能