Terminal
Terminal/Skill
Builds a Penpot design token system with primitive and semantic tiers, light and dark themes, and tokens inferred from hardcoded designs.
By Penpot
Works with
npx skills add penpot/penpot-ai-kit --skill penpot-foundationspenpot-foundations is the load-bearing skill of the kit: nothing downstream is correct without
a governed token layer. Every mutation goes through execute_code; validate visually with
export_shape; read structure with penpotUtils.shapeStructure (full tool surface:
shared/penpot-mcp-tool-reference.md). This skill reads tokens with penpotUtils.tokenOverview(),
creates them through penpot.library.local.tokens (addSet, set.addToken({type,name,value})), and
binds them to shapes with shape.applyToken(token, properties). It works in three tiers — primitive →
semantic → component (see shared/tokens-schema.json) — and can also infer a token system from an
existing hardcoded design.
Tokens before everything, and never one-shot. Build the foundation in small, idempotent steps:
primitives first, then semantic aliases that reference them, then (only if needed) component tokens.
Validate after each tier with tokenOverview(). Never invent values silently — propose the scale and
let a human approve it at the checkpoint.
Full surface: shared/penpot-mcp-tool-reference.md. Domain calls this skill leans on:
penpotUtils.tokenOverview() / shapeStructure() (discovery + inference);
penpot.library.local.tokens.addSet / set.addToken / shape.applyToken (writes);
penpot_api_info('TokenSet'|'Token'|'TokenCatalog') before relying on member signatures.
Gotcha numbers refer to shared/plugin-api-gotchas.md.
penpot.library.local.tokens; addSet({name})/addTheme({group,name}) take OBJECT args; new sets are INACTIVE (set.toggleActive()); token value is always a string (literal or "{reference}"); read token.resolvedValue.type strings from shared/tokens-schema.json: color, dimension, spacing, typography, shadow, opacity, borderRadius, borderWidth, fontWeights, fontSizes, fontFamilies, letterSpacing, textDecoration, textCase. (Note camelCase/plural — NOT border-radius or font-size.)shape.applyToken(token, properties) is async (~100 ms) and binds by NAME (bindings re-resolve when the active set/theme changes — that is what makes dark mode work). Apply in one execute_code call, verify shape.tokens in a LATER call. Never mass-apply in a single call — hundreds of applyTokens in one loop race and scramble bindings; apply in chunks of ≈25–40 shapes per call, verify each chunk, retry misses. Text/Rectangle fill bindings are the flakiest (Boards are reliable); bindings are sticky — overwrite a wrong one by applying the correct token, don't try to clear it via fills.penpot_api_info('TokenSet') / penpot_api_info('Token') first.Before mutating, restate the request as:
Act as a senior design-systems engineer who never hardcodes values.
Phase 0 — Discovery (read-only). high_level_overview, then penpotUtils.tokenOverview() and a
shapeStructure(penpot.currentPage.root, 3) read. Record what already exists in the RUN_ID ledger.
✋ Checkpoint: confirm scope (new system vs. extend vs. infer-from-design).
Phase 1 — Primitives. Create the primitives set and activate it (set.toggleActive() — new
sets are created inactive), then add raw color ramps, the spacing scale (4px grid), radius scale, and
type scale (font sizes via Minor Third). Use scripts/createTokenSet.js.
✋ Checkpoint: review the primitive scales (tokenOverview() + naming).
Phase 2 — Semantic. Add intent aliases that reference primitives, routed into two sets (the
referenced primitives set must be active or references fail validation):
color.action.primary.bg → {color.blue.500}) → modes/light;spacing.*, radius.*, font.*) → semantic.scripts/createSemanticTokens.js does this split by token type. This is what makes dark mode a clean
parallel colour set. ✋ Checkpoint: review semantic mapping.
Phase 3 — Dark mode (optional). Create the parallel modes/dark colour set (same colour names
as modes/light, dark values) with scripts/createThemes.js; leave modes/light active as default
and hand the toggle to the user. Cover every modes/light colour name (the script returns a
missing list). Dark mode works — bindings re-resolve by token name when the user activates
modes/dark — but the agent cannot render the switch from the plugin (theme.addSet() doesn't persist;
the plugin's read lags). The user toggles modes/dark on / modes/light off in Penpot's Tokens panel
(see references/04-themes-modes.md). ✋ Checkpoint: verify dark resolvedValues, restore light, and
tell the user how to switch.
Phase 4 — Apply / Infer / Bind. Either bind tokens to a selection (scripts/applyTokensToShapes.js),
infer tokens from a hardcoded design (scripts/inferTokensFromShapes.js), or — fundamental —
auto-bind tokens to every unbound element by exact value match so the user doesn't have to do it by
hand (scripts/bindTokensToElements.js). This is also the precondition for theming: a design only
follows a light/dark switch if its shapes are bound to token names (bindings re-resolve by name when
sets/themes change). Apply in chunks and verify — applyToken is async and mass-application in one
call races/scrambles bindings; Text/Rectangle fill bindings are flaky and need verify+retry (see
shared/plugin-api-gotchas.md). Value-only matches are a heuristic: flag inverse-colored chrome for a
semantic-role review. ✋ Checkpoint: review bindings + coverage.
Phase 5 — Validate. scripts/validateTokens.js — orphans, unresolved references, off-grid spacing.
Produce the structured report.
execute_code call (async).RUN_ID ledger updated so a truncated session can resume.Three token tiers (see shared/tokens-schema.json):
color.blue.500, spacing.4, radius.md, font.size.300). Never bound directly to shapes when a semantic token exists.color.text.default → {color.gray.900}, spacing.inset.md → {spacing.4}). This is what shapes bind to.Set layout (see shared/modes-and-policies.md): mode-invariant semantics live in semantic; colour
semantics live in modes/light / modes/dark (same names in both). Themes are modeled as Penpot token
themes (addTheme({ group, name })) that toggle the matching modes/* set; primitives and the
mode-invariant semantic set stay constant.
Default review. Creating a new token, building a theme, or applying tokens to shapes all require a
checkpoint. The only auto-applicable action (safe set, shared/modes-and-policies.md) is replacing a
raw value that is exactly equal to an existing token's resolved value with that token.
Ledger keys under RUN_ID (see shared/state-management.md): phase, created:[{kind:'set'|'token'|'theme', name, id}], proposed:[...], applied:[...]. Re-derive reality with tokenOverview() after truncation before continuing.
| After phase | Artifacts shown | What we ask |
|---|---|---|
| 0 Discovery | existing tokens summary | New / extend / infer? |
| 1 Primitives | tokenOverview() of primitives | Approve scales & naming? |
| 2 Semantic | semantic→primitive mapping | Approve intent mapping? |
| 3 Themes | resolved values per theme | Approve theme switch? |
| 4 Apply/Infer | before/after on a sample | Approve bindings? |
Dot-notation per shared/naming-conventions.md: sets are primitives / semantic (mode-invariant) /
modes/light + modes/dark (colour) / optional components; tokens are lowercase dot paths; themes
grouped mode with names Light / Dark / High Contrast.
| Excuse the LLM makes | Why it's wrong | Deterministic countermeasure |
|---|---|---|
| "I'll hardcode this hex now and tokenize later." | Hardcoded values break theming and governance; "later" never comes. | Stop. Read tokenOverview(), bind to a semantic token, or propose one for review. |
| "I'll bind shapes straight to a primitive to save a step." | Primitives can't switch per theme; dark mode breaks. | Bind to a semantic token that references the primitive. |
| "This spacing is 18px, close enough." | Off-grid values erode rhythm and fail governance. | Round to the nearest 4px-grid token (16 or 20). Document any exception only with human approval. |
| "I'll create a dozen tokens up front to be safe." | Unused/orphan tokens are debt. | Create only what's needed now; propose the rest at a checkpoint. |
// Idempotent set + token creation (Phase 1)
const tok = penpot.library.local.tokens;
let prim = tok.sets.find(s => s.name === "primitives") || tok.addSet({ name: "primitives" });
if (!prim.active) prim.toggleActive(); // new sets are INACTIVE by default
if (!prim.tokens.find(t => t.name === "color.blue.500")) {
prim.addToken({ type: "color", name: "color.blue.500", value: "#0066FF" });
}
return { set: prim.name, count: prim.tokens.length };
// Semantic alias referencing a primitive (Phase 2)
const tok = penpot.library.local.tokens;
let sem = tok.sets.find(s => s.name === "semantic") || tok.addSet({ name: "semantic" });
if (!sem.active) sem.toggleActive(); // and the referenced 'primitives' set must be active too
if (!sem.tokens.find(t => t.name === "color.action.primary.bg")) {
sem.addToken({ type: "color", name: "color.action.primary.bg", value: "{color.blue.500}" });
}
return { ok: true };
penpot_api_info('TokenCatalog'), penpot_api_info('TokenSet'), penpot_api_info('Token').shared/tokens-schema.json (taxonomy + real type strings), shared/plugin-api-gotchas.md.references/
| File | Loaded for |
|---|---|
01-discovery.md | Phase 0 read-only inventory |
02-token-architecture.md | tiers, scales, type ratio |
03-infer-from-design.md | building tokens from a hardcoded design |
04-themes-modes.md | light/dark theme modeling |
05-naming.md | token naming specifics |
06-anti-rationalization.md | governance excuses + countermeasures |
07-error-recovery.md | common failures & fixes |
scripts/
| File | Purpose |
|---|---|
inspectFileStructure.js | read pages/library/tokens |
createTokenSet.js | idempotent primitives set + tokens |
createSemanticTokens.js | semantic aliases referencing primitives |
inferTokensFromShapes.js | propose tokens from raw values |
applyTokensToShapes.js | bind tokens to a selection |
bindTokensToElements.js | auto-bind tokens to unbound elements by value (chunked + verify) — enables theming |
createThemes.js | light/dark themes |
validateTokens.js | orphans, unresolved refs, off-grid |
Doctrine paths. shared/… and policies/… resolve inside this bundle in native installs (vendored by the installer); in a Claude Code plugin install they live at the plugin root — ${CLAUDE_PLUGIN_ROOT}/shared/…, two directories up from this file.