Fylgja - 推进器构建器

Fylgja Propals 构建器简化了 Design Tokens (CSS自定义属性)的创建 通过将JavaScript对象或JSON文件转换为CSS变量或其他符号格式.

这个工具可以使您轻松地构建全面的 Design Token 设置 .

安装

您可以通过 npm 或其他基于节点的软件包管理器如 pnpm 或 bun 安装 Fylgja Props 构建器 :

npm install @fylgja/props-builder

使用量

基本使用 JavaScript

将道具Builder 函数导入您的节点. js 脚本 :

import { propsBuilder } from "@fylgja/props-builder";

然后,根据您的配置使用它生成输出文件 :

import { propsBuilder } from "@fylgja/props-builder";

propsBuilder(
  props, // Required: JavaScript object containing your design tokens.
  filename, // Required: Name of the output file.
  {
    parseAs: "auto", // Optional: Specifies the output format. Defaults to "auto".
    writeToFile: true, // Optional: If false, outputs the generated content to the console. Defaults to true.
    selector: ":where(:root)", // Optional: CSS selector for custom property declarations (CSS output only).
    wrapper: "", // Optional: Wrapper for design system-specific formatting (e.g., Figma).
    name: "Design Tokens", // Optional: Name of the Design Tokens Resolver (dtcg output only).
    description: "", // Optional: Description of the Design Tokens Resolver (dtcg output only).
    inputTypeTokens: false, // Optional: Set to true if the input `props` are in a design token format. Defaults to false.
    inputTypeSyntax: "default", // Optional: Specifies the syntax of the input tokens if `inputTypeTokens` is true.
    stripPrefix: "", // Optional: Dot/dash separated key path (or array of keys) to unwrap, dropping wrapping keys (e.g. "tokens.values").
    rename: null, // Optional: Map of `{ [currentKey]: newKey }` applied recursively, to align naming (e.g. `{ colors: "color" }`).
  },
);

就基本用途而言 props 财务报告和审定财务报表 filename 论据是必要的.

可选参数为先进的情景提供了灵活性.

import { propsBuilder } from "@fylgja/props-builder";

propsBuilder(
  {
    color: {
      red: "#f00",
      green: "#0f0",
      blue: "#00f",
    },
  },
  "output.css",
);

这将生成输出.cs,其内容如下:

:where(:root) {
  --color-red: #f00;
  --color-green: #0f0;
  --color-blue: #00f;
}

此示例显示一个简单 JavaScript 对象的简单用例 .

输出格式

输出格式取自文件名, 除非 parseAs 已经设定.

设计托肯斯2025.10

这个 dtcg 输出跟随 设计托肯斯2025.10规格。 。 。 . 值被转换成打入符值,例如. 0.5rem 变成一个 dimension 符号 { "value": 0.5, "unit": "rem" }, (中文(简体) ), 财务报告和审定财务报表 var(--shadow-color) 变成一个 {shadow-color.$root} 参考文献.

propsBuilder(props, "tokens/fylgja.resolver.json", { name: "Fylgja" });

所有符号都用一个单一的解析器文档进行。 暗模式值( R)@media:dark)被排除在外.

规格无法表达一些 CSS 值, 例如 calc(), (中文(简体) ), clamp(), (中文(简体) ), var() 在颜色内,或除 px 财务报告和审定财务报表 rem (或 ms 财务报告和审定财务报表 s 页:1. 警告和任何引用这些迹象的标志.

关于更高级的情景,包括如何使用不同的JSON文件格式,见下文"从设计托肯斯到CSS"部分.

从设计托肯斯到CSS

使用带有 JSON 文件的Propals 构建器是一个常用案例. 过程是直截了当的,根据您的 JSON 文件格式进行小调整.

1. 创建您的 Design Tokens 文件

您的JSON文件可以是一个简单的密钥值对象,也可以遵循像W3C Design Tokens spec或由Figma Tokens插件所导出的格式这样的标准格式.

2. 创建构建脚本

创建一个Node.js脚本(例如, build.js)读取您的令牌文件并运行构建器.

import { readFileSync } from "node:fs";
import { propsBuilder } from "@fylgja/props-builder";

// Read and parse the JSON file
const tokens = JSON.parse(readFileSync("path/to/your/tokens.json", "utf-8"));

// 👇 Configure the builder based on your token format
const options = {
  // inputTypeTokens: ...,
  // inputTypeSyntax: ...,
};

// Build the CSS file
propsBuilder(tokens, "tokens.css", options);

console.log("Successfully built tokens.css!");

3. 配置构建器

关键步骤是配置 options 对象基于您的 JSON 文件格式.

• 对于一个简单,密钥值的JSON文件: 你不需要任何特别的选择 建造者默认处理.

  const options = {};
  

• 对于一个W3C Design Tokens spec文件(包括2025.10和Resolter文件): 设定 inputTypeTokens 改为 true。 。 。 .

  const options = { inputTypeTokens: true };
  

  Design Tokens 2025.10 数值,如彩色对象或维度被转换为 CSS 值. 综合符号成为CSS的简称(border, (中文(简体) ), shadow, (中文(简体) ), transition,而渐变颜色停止), 除外 typography,它成为每个部分的自定义属性(例如. --heading-font-size) (中文(简体) ). 团体支助 $type 遗产, $root 标志,和 $extends。 。 。 . 两者 {token.path} 参考文献 $ref 贾森 支持同一文件中的指针.

  对于解析器文件,所有集按解析顺序合并,每个修改器使用其 default 上下文. A 类 $ref 不支持其它文件,而是先将这些文件合并为一个文档.

• 对于 Figma Tokens 文件 : 设定 inputTypeTokens 改为 true 财务报告和审定财务报表 inputTypeSyntax 改为 'figma'。 。 。 .

  const options = {
    inputTypeTokens: true,
    inputTypeSyntax: "figma",
  };
  

• 对于一个 Google Stitch Markdown 导出: 设定 inputTypeTokens 改为 true 财务报告和审定财务报表 inputTypeSyntax 改为 'stitch'。 。 。 . 传出原始 Markdown 文件内容( a string) 为 props,不是解析对象. 仅使用YAML前题,其中的每个密钥被转换为符号,只有已知的元数据密钥除外(name, (中文(简体) ), description) (中文(简体) ). 这个 colors 组自动更名为单数 color (除非 color 组已经存在).

  const options = {
    inputTypeTokens: true,
    inputTypeSyntax: "stitch",
  };
  

4. 运行构建脚本

最后,从终端运行您的脚本:

node build.js

这将生成一个 tokens.css 带有 CSS 自定义属性的文件.