refresh-design-tokens

name	refresh-design-tokens
description	Use this skill when the user asks to refresh design tokens, update the token cache, regenerate docs/design-tokens.md, sync FastStore tokens from VTEX, or when the token cache is missing or outdated in a FastStore + Synerise project. Requires VTEX Developer MCP.
metadata	{"author":"synerise","version":"1.0.0","lastUpdated":"2026-05-04T00:00:00.000Z"}

Refresh FastStore Global Design Tokens Cache (FastStore + Synerise)

Pulls the current FastStore global tokens from VTEX docs via the VTEX Developer MCP and writes them to docs/design-tokens.md. The design-tokens skill reads from that file, so this is how the cache stays current.

Step 0: Verify project context + MCP availability

This skill is only valid in a FastStore + Synerise project AND requires the VTEX Developer MCP. Before running, confirm:

Project context (at least one):

• package.json lists @synerise/faststore-api as a dependency (strongest signal), OR
• src/components/sections/ directory exists, OR
• discovery.config.js file exists at the repo root.

MCP availability: the mcp__vtex-developer__search_documentation tool must be available in this session.

If project context is missing, stop:

This doesn't look like a FastStore + Synerise project (no @synerise/faststore-api dep, no src/components/sections/, no discovery.config.js). Skipping refresh.

If MCP is missing, stop:

VTEX Developer MCP is not configured in this session. Enable it (Settings → MCP) and re-run.

Why search, not fetch

mcp__vtex-developer__fetch_document does NOT work for the FastStore token pages — the source repository (vtexdocs/dev-portal-content) doesn't expose them at the URL paths that appear on the live docs site. Every direct fetch returns "Document not found".

mcp__vtex-developer__search_documentation DOES work and returns the inline <TokenRow token="..." value="..." /> and <TokenColor token="..." value="..." /> blocks in its Content field. That's enough to extract every token name and value.

Step 1: Run searches per category (in parallel)

Use mcp__vtex-developer__search_documentation with locale: "en" for each query below. Run them all in a single message — they are independent.

Category	Suggested query
Spacing	faststore spacing tokens fs-spacing
Typography (numbered scale)	faststore typography Type Scale fs-text-size-0 fs-text-size-1 base
Typography (weights/faces/semantic)	faststore typography text-size text-weight text-face token
Borders + Transitions + Shadow	faststore refinements transition border-radius border-width
Colors (palettes — main/accent/neutral)	faststore colors token --fs-color-text neutral primary
Colors (semantic — status/text/links)	faststore color text body-bkg success danger warning info disabled

If a search returns nothing useful, broaden it (e.g., faststore global tokens overview).

Step 2: Extract tokens

For each search result, parse the Content field. Look for these patterns:

• <TokenRow token="--fs-..." value="..." /> (most categories)
• <TokenColor token="--fs-color-..." value="#..." /> (Colors page)

Capture:

• token name — e.g., --fs-spacing-0
• token value — e.g., .25rem or var(--fs-text-size-base) or #ffffff

Group by top-level category:

• Colors — anything starting with --fs-color-*. Sub-group: Main / Accent / Neutral palettes (--fs-color-{main,accent,neutral}-N); Semantic (text, surfaces); State (success/danger/warning/info/highlighted); Links/actions.
• Spacing — --fs-spacing-*
• Typography — --fs-text-*. Sub-group: numbered sizes, semantic sizes, weights, faces.
• Borders — --fs-border-radius-*, --fs-border-width-*, --fs-border-color-*
• Transitions — --fs-transition-*
• Shadow — --fs-shadow-* (bonus category — capture if present)

If the same token appears in multiple search results, deduplicate by name. Prefer the entry with a concrete value over one that resolves to var(...).

Step 3: Write docs/design-tokens.md

Overwrite docs/design-tokens.md with the structure below. Keep the comment header — it is what design-tokens reads to determine staleness.

<!--
Auto-generated by the `refresh-design-tokens` skill
Source: VTEX Developer MCP (developers.vtex.com — Spacing, Typography, Refinements, Colors pages)
Last refreshed: <today's date in YYYY-MM-DD>
DO NOT EDIT MANUALLY — re-run the refresh-design-tokens skill instead.
-->

# FastStore Global Design Tokens (cache)

This is a local snapshot of the FastStore global design tokens, used by the `design-tokens` skill so that SCSS reviews don't re-query the VTEX MCP every time. VTEX's global tokens rarely change.

To refresh: run the `refresh-design-tokens` skill, then commit the updated file.

## Colors

### Main palette
- `--fs-color-main-0`: <value>
- ...

### Accent palette
- ...

### Neutral palette
- ...

### Semantic — text & surfaces
- `--fs-color-text`
- `--fs-color-text-inverse`
- ...

### Semantic — state (status colors)
- `--fs-color-success-bkg`
- ...

### Semantic — links & actions
- `--fs-color-link`
- ...

## Spacing
- `--fs-spacing-0`: <value>
- ...

## Typography

### Sizes — numbered scale
- ...

### Sizes — semantic
- ...

### Weights
- ...

### Faces
- ...

## Borders

### Radius
- ...

### Width
- ...

### Color
- ...

## Transitions
- `--fs-transition-timing`: <value>
- `--fs-transition-property`: <value>
- `--fs-transition-function`: <value>

## Shadow
- ...

Use the line format - \--fs-token-name`: valuefor every token. One token per line. Backticks around the name. This format is what thedesign-tokens` skill parses.

If a token's value couldn't be extracted (rare — usually because the search snippet was truncated), write:

- `--fs-color-neutral-7`: (referenced — not captured this refresh)

Step 4: Diff and report

If docs/design-tokens.md already existed before this refresh:

1. Compare the previous content with the new content.
2. Report a short summary to the user:
   • Added tokens since last refresh
   • Removed tokens since last refresh
   • Tokens whose value changed

If there was no prior file, just say "Cache generated for the first time. N tokens captured across {C, S, T, B, Tr, Sh} categories."

If nothing changed, say "Cache up-to-date — no changes detected."

Step 5: Tell the user to commit

End with:

Wrote docs/design-tokens.md. Commit it so the team picks up the refreshed cache: git add docs/design-tokens.md && git commit -m "Refresh design tokens cache"

Do NOT commit on the user's behalf.

Failure modes

• MCP tool not available — stop and tell the user: "VTEX Developer MCP is not configured in this session. Enable it (Settings → MCP) and re-run."
• Searches return no <TokenRow> content — VTEX may have changed how their docs render. Report which category failed and ask the user how to proceed (e.g., paste tokens manually from the live page).