| name | penpot-rename-layers |
| description | Semantically rename Penpot layers to HTML element names (nav, header, main, section, article, button, input, label, h1-h6, p, ul, li, img) or kebab-case role names, replacing auto-generated names like 'Rectangle 12'. Use to clean up layer naming, prepare a file for handoff, or as a precondition for accessibility audits (heading hierarchy) and design-to-code review (semantic mapping). Triggers: 'rename layers', 'semantic layer names', 'rename to HTML elements', 'clean up layer names', 'fix layer naming', 'add semantic names to layers', 'prepare layers for handoff'. |
| disable-model-invocation | false |
| version | 0.2.0 |
| audiences | ["design-system","product-designer","design-engineer","migration"] |
| mode-default | autofix |
| requires | ["shared/penpot-mcp-tool-reference.md","shared/plugin-api-gotchas.md","shared/tokens-schema.json","shared/naming-conventions.md","shared/state-management.md","shared/modes-and-policies.md"] |
Semantic Layer Renaming
1. Title + How it works
This skill renames the layers of a Penpot file so each layer carries the semantic HTML element name it represents (nav, header, main, section, article, button, input, label, h1–h6, p, ul, li, img) or, where no element fits, a kebab-case role name (card-grid, button-group, field-row). Semantic names are a precondition for accessibility audits (a heading hierarchy can only be read off named h1–h6 layers), for design-to-code review (the reviewer maps button → <button>), and for clean handoff.
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). A rename is just shape.name = "..." — there is no renameShape() API.
2. The One Rule That Matters Most
Never one-shot the whole file. Inspect read-only first, classify every layer into one of three buckets — auto-named (safe to autofix), meaningfully-named (needs review), ambiguous (needs the user) — then rename in small, validated batches. Renaming an auto-named layer (Rectangle 12 → button) is in the safe-set and may be applied without asking. Renaming a layer that already has a meaningful name is a judgement call and always requires review. Renaming a main component shape is forbidden by default (it changes the name for every instance). One logical batch per execute_code call; checkpoint between batches.
3. Penpot MCP Tool Reference
Full surface: shared/penpot-mcp-tool-reference.md. The domain-specific calls:
