| name | penpot-audit-tokens |
| description | Audit a Penpot design for design-system / token GOVERNANCE issues (distinct from accessibility): hardcoded colors where a token exists, off-grid spacing, orphan/unresolved/unused tokens, duplicated values, and detached parts that should be component instances. Produces a severity report and suggests semantic-token swaps. Triggers: 'audit tokens', 'find hardcoded colors', 'token governance', 'check design system consistency', 'find off-grid spacing', 'detect raw values', 'are we using tokens correctly'. |
| disable-model-invocation | false |
| version | 0.2.0 |
| audiences | ["design-system","design-engineer"] |
| mode-default | suggest |
| requires | ["shared/penpot-mcp-tool-reference.md","shared/plugin-api-gotchas.md","shared/tokens-schema.json","shared/modes-and-policies.md"] |
penpot-audit-tokens — design-system governance auditor
1. Title + How it works
penpot-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.
2. The One Rule That Matters Most
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.
3. Penpot MCP Tool Reference
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).
4. Plugin API Essentials
- Read raw values from
shape.fills/shape.strokes (hex), shape.borderRadius*, flex rowGap/columnGap/*Padding, layout margins.
- A shape's applied tokens are in
shape.tokens ({ property: tokenName }). A property with a raw value but no entry there is "hardcoded".
- Token resolved values via
token.resolvedValue. Use exact token type strings from shared/tokens-schema.json.
- Comparisons are read-only; the only mutation (exact-equality swap) uses
shape.applyToken — #2 in shared/plugin-api-gotchas.md: async, chunked, verify in a later call.
- Verify unfamiliar signatures with
penpot_api_info before relying on them.
5. Token-Aware Brief Contract
- Context — scope (page/selection/library), the active token system.
