| 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), ORsrc/components/sections/ directory exists, ORdiscovery.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:
- Compare the previous content with the new content.
- 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).
