Use when pulling design tokens from Figma into `packages/but-ui`, regenerating `tokens.css`, or reviewing a token change: sync/export/update tokens, a Figma variable was added, renamed or changed, or `pnpm check` says tokens.css is stale. Not for using tokens in components; that is the gitbutler-ui skill.
95%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Figma variables are the source. packages/but-ui/tokens/json/*.tokens.json is
their export and tokens/tokens.css is built from it, with the same as data: tokens/tokens.json,
the tokens, and tokens/settings.json, the settings a person can pick. None is edited by hand. The
package README has the pipeline in full. Run everything below from packages/but-ui.
Every route writes the same four files: core, semantic, ramps and fx.tokens.json.
A snapshot through the file API (the route that works on GitButler's plan). Figma's
variables REST API is Enterprise-only, so the CLI's own fetch answers 403. Instead, dump
the variables with the Figma MCP and convert them with the CLI's snapshot mode:
use_figma, collect getLocalVariableCollectionsAsync(),
getLocalVariablesAsync() and getLocalEffectStylesAsync() as plain objects (the
fields in tokens-bruecke's schemas/tokens-snapshot.schema.json), and write the JSON
into a text layer on a new page named tmp: tokens snapshot. A use_figma result
can't carry it: it caps at 48 KB.GET https://api.figma.com/v1/files/$FIGMA_FILE_KEY/nodes?ids=<node id> with the
X-Figma-Token header from .env. The snapshot is the node's characters.'; the plugin decodes
them, snapshot mode doesn't), then delete the page.npx tokens-bruecke@latest --input snapshot.json -c figma-export.config.json -o tokens/json --split-by-collectiontokens-bruecke CLI, on an Enterprise plan. Needs FIGMA_API_KEY (with
file_variables:read; it expires every 90 days) and FIGMA_FILE_KEY in a .env here.
set -a && . ./.env && set +a
npx tokens-bruecke -a "$FIGMA_API_KEY" -f "$FIGMA_FILE_KEY" \
-c figma-export.config.json -o tokens/json --split-by-collectionA 403 with Token expired or Invalid scope(s) needs the user to make a new token.
Stop and ask; never hand-edit the JSON instead.
Figma agent. /export-tokens in the tokens file, choosing hex, everything, one file
per collection; copy the four files into tokens/json/.
A PR from the plugin's GitHub PR server. It carries only the JSON: check out its branch and continue from step 2.
figma-export.config.json holds the settings the committed tokens were made with. Changing
it rewrites every file, so don't, unless that is the point.
A token's CSS name is its Figma path with dashes under --but- (primary/soft/foreground
is --but-primary-soft-foreground); a group's own variable (primary beside
primary/foreground) takes the group's name. The ramps follow the same rule
(ramps/teal/9 is --but-teal-9). cssVarName in scripts/terrazzo-css-helpers.mjs is the one rule.
Every export moves a createdAt stamp, so a diff alone means nothing:
git diff -U0 tokens/json | grep '^[+-]' | grep -v '^[+-][+-]' | grep -v createdAtNo output: git checkout -- tokens/json, tell the user Figma has no changes, and stop.
pnpm build
git show HEAD:packages/but-ui/tokens/tokens.css > "$TMPDIR/tokens-before.css"
node scripts/diff-css-vars.mjs "$TMPDIR/tokens-before.css" tokens/tokens.cssThe report lists added, changed and removed variables. A token that changed in the JSON but not in the CSS is probably in a collection Terrazzo doesn't read; say so rather than patching the CSS.
pnpm --filter @gitbutler/but-ui-react check:tokensIt names every var(--…) nothing declares any more. Fix those in the same change, and
search the rest of the repo too: packages/but-mcp-app, the GPUI theme in
crates/but-gpui/src/theme.rs, which reads its colours from tokens/tokens.json by name, so
cargo check -p but-gpui fails on one that's gone, and
crates/but-gpui/src/ui/illustration.rs, which colours but-ui-react's illustrations by the names
in their SVGs. For a rename, scripts/rename-tokens.mjs reads token-map.json; add the old
name and its replacement there and run it. Projects outside the monorepo
(but-dev) pin a commit and pick the change up when they move it; mention removals to the
user so they know.
tokens/json, tokens/tokens.css, tokens/tokens.json, tokens/settings.json and tokens/accent-samples.json go in one commit, with the GitButler skill, and the
message says what changed in the tokens. There is no version bump or release: the package
is not published.
gitbutlerapp/gitbutler
19235e8
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.