Run any Skill in Manus with one click

penpot-audit-tokens

Stars12

Forks1

UpdatedJuly 9, 2026 at 08:24

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'.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

penpot

penpot/penpot-ai-kit

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Web and Digital Interface DesignersComputer and Mathematical Occupations·SOC 15-1255

File Explorer

9 files

SKILL.md

readonly

More from this repository

same repository

penpot-audit-accessibility

penpot/penpot-ai-kit

Audit a Penpot design against WCAG 2.1/2.2 AA (optionally AAA) and produce a structured severity report: color contrast, touch/target sizes, text alternatives, heading hierarchy, and keyboard/focus order. Proposes fixes — does not auto-apply. Also serves as the Evaluator in the brief-to-screen loop. Triggers: 'check accessibility', 'accessibility audit', 'WCAG check', 'contrast audit', 'a11y review', 'check color contrast', 'is this accessible'.

2026-07-0912

penpot-build-from-code

penpot/penpot-ai-kit

Translate an existing application page, view, or component code into a Penpot screen that is bound to the existing design system — mapping code styles onto semantic tokens and reusing library components instead of raw shapes. Use when the user has real code/markup and wants it reconstructed in Penpot, section by section, on-system. Triggers: 'build this in Penpot from code', 'turn this React/HTML/CSS into a Penpot screen', 'recreate this view in Penpot', 'port this page to Penpot', 'translate this component to Penpot bound to our tokens', 'code to Penpot'.

2026-07-0912

penpot-build-screen

penpot/penpot-ai-kit

Design production-grade screens in Penpot from a brief, as a senior visual designer — reusing the existing design system (tokens + components) and assembling section by section, never one-shot. Use to create a screen/page/landing/dashboard from a description. NOT for translating existing code (use penpot-build-from-code). Triggers: 'design a dashboard', 'create a landing page', 'design this app screen', 'build a UI from this brief', 'design a settings page', 'mock up a screen in Penpot'.

2026-07-0912

penpot-component-factory

penpot/penpot-ai-kit

Build and maintain Penpot components with COMPLETE variant matrices — sizes, hierarchies, and all interactive states (default/hover/pressed/focus/disabled) — fully tokenized and correctly named. Use to create a new component with variants, fill in missing states, or normalize an existing component. Triggers: 'create a Button component with variants', 'build component variants', 'add hover/pressed/disabled states', 'make a variant matrix', 'turn this into a component with sizes', 'normalize this component'.

2026-07-0912

penpot-design-md

penpot/penpot-ai-kit

Extract a DESIGN.md design-documentation file from a Penpot file: a portable markdown spec (YAML frontmatter with colors/typography/rounded/spacing/components token maps + prose sections: Overview, Colors, Typography, Layout, Shapes, Components, Do's & Don'ts, Iteration Guide, Known Gaps) in the design-md format, grounded in the file's real tokens, library assets, and sampled component styles — never invented. Read-only on the canvas; writes one local markdown file. Triggers: 'generate DESIGN.md', 'create a design.md', 'document the design system as markdown', 'export design guidelines', 'extract design documentation', 'design system spec file', 'make a style guide file from this design'.

2026-07-0912

penpot-design-to-code-review

penpot/penpot-ai-kit

Review a Penpot design against its implemented code (a source component or Storybook story) and emit a structured DRIFT report. Use when an engineer needs to confirm the build matches the design: extract HTML/CSS from a selection, map its tokens/structure/states to the code component, diff them, and list what each side is missing with severity and a reconciliation. Degrades gracefully to a design-system-token check when no code source is supplied. Triggers: 'design to code review', 'does my code match the design', 'design code parity', 'compare Penpot to my component', 'check this against Storybook', 'extract HTML/CSS from this selection', 'find design drift', 'design implementation diff'.

2026-07-0912

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.
Objective — single: "audit token governance of X".
Inputs — target shapes, the 4px grid, the active token sets.
Constraints — read-only except exact-equality auto-swaps (with explicit opt-in).
Acceptance Criteria — all raw values reported; off-grid spacing listed; orphan/unused tokens found; each finding has a suggested token + confidence.

Act as a design-system governance engineer.

6. Mandatory Workflow

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.

7. Critical Rules

Governance ≠ accessibility — keep scope to tokens/system consistency.
Only exact-equality raw→token swaps are auto-applicable (safe set).
Off-grid spacing → suggest nearest 4px token; never silently round.
New tokens are proposed, not created here (hand off to penpot-foundations).
Every finding: severity + impact + suggested token + confidence.
No silent scope cuts.

8. Domain Architecture

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.

9. Modes & Policies

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.

10. State Management

Ledger under RUN_ID: phase, findings:[...], autoSwapped:[...], sampled.

11. User Checkpoints

After phase	Artifacts	Ask
3 Report	governance report	Auto-apply exact swaps? Route the rest to foundations?

12. Naming Conventions

shared/naming-conventions.md + shared/tokens-schema.json (dot-notation, real type strings).

13. Anti-Rationalization Table

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.

14. Helper Code Snippets

// 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 };

15. Reference Resources

shared/tokens-schema.json (governanceRules), penpot_api_info('Shape','tokens'), penpot_api_info('Token','resolvedValue').

16. Supporting Files

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.