Terminal
Terminal/Skill
Audits a Penpot file for hardcoded colors, off-grid spacing, unused tokens and detached parts, then suggests token swaps.
By Penpot
Works with
npx skills add penpot/penpot-ai-kit --skill penpot-audit-tokenspenpot-audit-tokens enforces token governance — a concern separate from accessibility. 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). It collects
every fill/stroke/spacing/radius value, compares
against the active token system (penpotUtils.tokenOverview()), and reports hardcoded values, off-grid
spacing, orphan/unresolved tokens, and duplicates — each with a suggested semantic-token swap.
Suggest, and only auto-swap exact equalities. The single safe auto-fix is replacing a raw value that is exactly equal to an existing token's resolved value with that token. Everything else (near-matches, off-grid rounding, new tokens) is a suggestion for review.
Full surface: shared/penpot-mcp-tool-reference.md. Key calls: execute_code with
penpotUtils.analyzeDescendants (collect values) and penpotUtils.tokenOverview() /
findTokenByName (the token system to compare against).
shape.fills/shape.strokes (hex), shape.borderRadius*, flex rowGap/columnGap/*Padding, layout margins.shape.tokens ({ property: tokenName }). A property with a raw value but no entry there is "hardcoded".token.resolvedValue. Use exact token type strings from shared/tokens-schema.json.shape.applyToken — #2 in shared/plugin-api-gotchas.md: async, chunked, verify in a later call.penpot_api_info before relying on them.Act as a design-system governance engineer.
Phase 0 — Inspection. high_level_overview; collect usage with scripts/collectStyleUsage.js and the token system with tokenOverview() (references/01-inspection.md).
Phase 1 — Hardcoded values. scripts/detectHardcodedValues.js (references/02-hardcoded-value-detection.md) — raw fills/strokes vs tokens; mark exact-equal vs near-match.
Phase 2 — Grid & orphans. scripts/checkGridAndOrphans.js (references/03-orphan-and-grid-checks.md) — off-grid spacing; unresolved references; unused tokens; duplicates.
Phase 3 — Report. scripts/generateTokenReport.js (references/04-report-generation.md). ✋ Checkpoint: present findings; offer to auto-apply ONLY the exact-equality swaps (Apply-with-review), route the rest (new tokens, rounding) to penpot-foundations.
penpot-foundations).Findings map to shared/tokens-schema.json governanceRules: noHardcodedColor, noOffGridSpacing,
noOrphanTokens, preferSemantic. Report schema:
{ severity, rule, element, property, current, suggestedToken, exactMatch:bool, confidence }
The final report must ALSO be emitted as a JSON object per shared/report-schemas/token-governance-report.schema.json (findings carry exactMatch — only exact-equality swaps are safe-set) and mirrored to the run ledger.
Default suggest. The only auto-fix (per shared/modes-and-policies.md safe set) is the exact-equality
swap, and only with explicit opt-in at the checkpoint. Geometry, new tokens, detach: never auto.
Ledger under RUN_ID: phase, findings:[...], autoSwapped:[...], sampled.
| After phase | Artifacts | Ask |
|---|---|---|
| 3 Report | governance report | Auto-apply exact swaps? Route the rest to foundations? |
shared/naming-conventions.md + shared/tokens-schema.json (dot-notation, real type strings).
| Excuse | Why it's wrong | Countermeasure (halt) |
|---|---|---|
| "This raw hex is basically the token." | "Basically" ≠ exact; silent swaps corrupt intent. | Auto-swap ONLY on exact equality; otherwise suggest with confidence. |
| "I'll just create the missing token and swap." | New tokens are a foundations decision. | Propose the token; route creation to penpot-foundations. |
| "Round 18px to 16px automatically." | Off-grid rounding can shift layout. | Suggest the nearest 4px token; require review. |
| "Skip orphan/unused token check." | Orphans are silent debt. | Run the full grid/orphan pass. |
| "It's a small file, eyeball it." | Misses systematic raw usage. | Walk the tree programmatically; report counts. |
// Is a property hardcoded? (raw value present, no token bound)
function isHardcoded(shape, prop){
const hasRaw = prop === 'fill' ? (shape.fills||[]).length>0 : shape[prop] != null;
const bound = shape.tokens && shape.tokens[prop];
return hasRaw && !bound;
}
return { ok: true };
shared/tokens-schema.json (governanceRules), penpot_api_info('Shape','tokens'), penpot_api_info('Token','resolvedValue').references/: 01-inspection.md, 02-hardcoded-value-detection.md, 03-orphan-and-grid-checks.md, 04-report-generation.md.
scripts/: collectStyleUsage.js, detectHardcodedValues.js, checkGridAndOrphans.js, generateTokenReport.js.
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.