Terminal
Terminal/Skill
Renames auto-generated Penpot layers like Rectangle 12 to semantic names such as nav, button and h1, for handoff and audits.
By Penpot
Works with
npx skills add penpot/penpot-ai-kit --skill penpot-rename-layersThis 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.
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.
Full surface: shared/penpot-mcp-tool-reference.md. The domain-specific calls:
| Call | Use |
|---|---|
penpotUtils.findShapes(pred, root) / findShapeById(id) | Collect the inventory; resolve a shape id for renaming. |
penpotUtils.analyzeDescendants(root, evaluator, maxDepth) | Walk the tree carrying parent context into the classifier. |
shape.name = "..." (via execute_code) | The rename itself — a plain property write; no rename method exists. |
export_shape(shapeId, 'png', 'shape') | Visual checkpoint of a renamed region. |
penpot_api_info('Board') | Verify name, isComponentMainInstance(), isComponentCopyInstance() before relying on them. |
Domain-relevant facts and gotchas (full list in shared/plugin-api-gotchas.md):
shape.name is a plain writable string. Rename with shape.name = "button". There is no rename method. The write is synchronous — unlike token application, you may read shape.name back in the same call to confirm.shape.isComponentMainInstance() — it returns true for the main instance and every shape nested inside it. Renaming any of those renames the component for all copies — out of safe-set. Copy instances (isComponentCopyInstance() true) may be renamed. NOTE: the main instance is also an instance, so isComponentInstance() is true for it too — do not use isComponentInstance() === false to detect main shapes (that was a real bug). Verify with penpot_api_info('Board', 'isComponentMainInstance') before branching.width/height/parentX/parentY are read-only — irrelevant to renaming; do not "fix" geometry while you are in here (different skill, never auto-fix).penpot_api_info — guessing is the top source of silent failures.Before renaming, restate the request as a contract. Act as a senior design-systems engineer who treats layer names as the contract between design and code, never ships an auto-generated name, and never overwrites a human's deliberate name without asking.
shared/naming-conventions.md (the layer-naming section).h1–h6 name; every interactive container is button / input / select / label; every list container is ul/ol with li children; every meaningfully-named layer that was changed has a recorded justification; 0 main component shapes renamed.high_level_overview once. Then execute_code with scripts/inspectLayerStructure.js to collect, per shape: id, name, type, nameStatus (auto-generated | semantic | custom), position/size hints, child types, text props (fontSize/fontWeight/characters), fill/stroke flags, and isComponentInstance(). Cache the inventory in storage.nameStatus and stats (autoGenerated, alreadySemantic, custom, componentInstances, textNodes).references/02-semantic-inference.md locally to the cached inventory. Assign each row a bucket: safe (auto-named → rename), review (meaningful name → proposed change), ambiguous (low confidence → ask). Record a one-line reason per row.{ shapeId: { old, new, bucket, reason, confidence } }, with ambiguous rows isolated.scripts/renameLayer.js with the approved RENAME_MAP. The script skips main component shapes, skips layers already at the target name, and returns before/after pairs. Batch ≤100 per call. Write the ledger after each batch.export_shape('page','png','shape') (or the renamed board) plus a renamed-count summary; sign-off.auto-generated → semantic renames. Any change to a layer with a meaningful name is review, always.isComponentMainInstance() (true for the main instance and its internals); those are skipped and reported. Copy instances may be renamed.shape.name and nothing else. No resize(), no reparenting.h1, nav, button, card-grid — not H1, CardGrid.The artifacts this skill produces:
Name-status buckets (the inventory's spine):
auto-generated — matches ^(Board|Frame|Rectangle|Group|Ellipse|Text|Path|Bool|Image|Component|Vector)\s*\d*$. Safe-set; autofixable.semantic — already a valid HTML element or known role name. Left alone unless wrong.custom — a human-authored non-semantic name (Hero copy v2). Review before overwriting.Rename map row: { shapeId, old, new, bucket: 'safe'|'review'|'ambiguous', reason, confidence: 0..1 }.
Naming output vocabulary:
header, nav, main, section, article, aside, footer, form, dialog, figure.button, input, select, label, a.h1–h6, p, small, caption, span.ul, ol, li, img, svg, icon, hr.card-grid, button-group, field-row, avatar-stack, nav-list.button-primary, button-ghost, li-pricing.See shared/modes-and-policies.md. This skill's mode-default is autofix, but narrowly:
detach(), and new tokens are all out of scope here and never auto-fixed.See shared/state-management.md. Authoritative ledger via setSharedPluginData (namespace penpot-ai), keyed by RUN_ID (e.g. rename-2026-06-05-a); session cache via storage.
Ledger keys:
${RUN_ID}.phase — "0"|"1"|"2".${RUN_ID}.ledger — JSON { runId, phase, scope, renameMap, created:[], decisions:[], assumptions:[], pendingReview:[] }.storage.run.inventory — cached Phase 0 inventory.storage.run.renameMap — the approved map.Resume: re-read the in-file ledger, re-derive the live tree with shapeStructure, then continue from ledger.phase. Idempotency (skip layers already at target) makes re-running a batch safe.
| After phase | Artifacts shown | What we ask |
|---|---|---|
| 0 — Discovery | Layer inventory + name-status stats; resolved scope | "Is this the right scope (page / board / file)? Proceed to inference?" |
| 1 — Inference | Full before→after table grouped by bucket (safe / review / ambiguous), confidence + reason per row | "Approve the review and ambiguous renames? Any names to override?" |
| 2 — Renaming | export_shape of the renamed region + renamed/skipped/error counts | "Names look right? Approve this batch; proceed to the next?" |
Authoritative source: shared/naming-conventions.md (the Layers section). Domain specifics:
button-primary, button-secondary, li-home, li-about.references/02-semantic-inference.md on heading-level ordering.Rectangle 12, Group 4, Board. Never PascalCase a layer (PascalCase is reserved for components).| Excuse the LLM makes | Why it's wrong | Deterministic countermeasure |
|---|---|---|
| "This layer already has a name, I'll just improve it while I'm here." | A human's deliberate name is not in the safe-set; silently overwriting it loses intent and is irreversible without the ledger. | Bucket it as review. Do not auto-apply. Show old→new at the Phase 1 checkpoint and wait for approval. |
| "It's clearly a button — I'll also tighten its padding/size." | This skill writes shape.name only. Geometry changes are never auto-fix and belong to another skill. | Halt. Rename only. Record the geometry observation as a note for review; do not call resize()/setParentXY. |
| "Renaming the component's main shape is the same as renaming an instance." | Renaming the main shape renames the component for every instance across the file — a shared-asset edit, never auto-fix. | Branch on isComponentMainInstance(). Skip the main instance and everything inside it; report as skipped: main component. |
"I'll label every big text h1 by font size alone." | Multiple h1s break heading hierarchy and fail the a11y precondition this skill exists to satisfy. | Order headings by visual prominence: one h1 per region, descending h2/h3. Use the level rules in references/02-semantic-inference.md. |
"These three repeated cards are each a section." | Repeated siblings in a list are li inside a ul, not standalone sections; mis-labeling corrupts the code-review mapping. | Detect repetition by sibling count + matching structure; name the container ul and children li (with descriptors). |
| "I'll rename the whole tree in one execute_code call to be fast." | One-shotting defeats checkpoints and makes a bad inference unrecoverable mid-run. | Batch ≤100 per call, top-down, write the ledger between batches. |
Classify a name (used in inspection):
const isAutoGenerated = n =>
/^(Board|Frame|Rectangle|Group|Ellipse|Text|Path|Bool|Image|Component|Vector)\s*\d*$/i.test(n || "");
const isSemantic = n =>
/^(header|footer|nav|main|section|article|aside|form|dialog|figure|button|input|select|label|a|h[1-6]|p|small|caption|span|ul|ol|li|img|svg|icon|hr)([-_ ].*)?$/i.test(n || "");
const nameStatus = n => isSemantic(n) ? "semantic" : isAutoGenerated(n) ? "auto-generated" : "custom";
Rename one shape safely (idempotent, skips main components):
const shape = penpotUtils.findShapeById("REPLACE-ME-SHAPE-ID");
let result;
if (!shape) result = { error: "not found" };
else if (shape.isComponentMainInstance && shape.isComponentMainInstance())
result = { skipped: "main component", name: shape.name }; // true for the main instance AND its internals
else if (shape.name === "button") result = { skipped: "already named", name: shape.name };
else { const old = shape.name; shape.name = "button"; result = { old, new: shape.name }; }
return result;
penpot_api_info('Board') — confirm name is writable and inspect isComponentMainInstance(), isComponentCopyInstance(), detach().penpot_api_info('PenpotPage') and penpotUtils.shapeStructure for tree traversal.shared/naming-conventions.md — the canonical layer-naming rules.shared/modes-and-policies.md — the exact safe-set definition this skill relies on.penpot-audit-accessibility (consumes heading names), penpot-design-to-code-review (consumes semantic names). Run this skill first.| File | Read during | Covers |
|---|---|---|
references/01-inspection.md | Phase 0 | Read-only traversal, name-status classification, component detection, scope selection. |
references/02-semantic-inference.md | Phase 1 | Inference rules (structure / interactive / text / media / lists), heading-level ordering, ambiguity handling. |
references/03-renaming-strategy.md | Phase 2 | Top-down batching, idempotency, main-component skip, validation, ledger + resume. |
execute_code)| Script | Phase | Purpose |
|---|---|---|
scripts/inspectLayerStructure.js | 0 | Read-only inventory with nameStatus + inference signals. |
scripts/renameLayer.js | 2 | Apply the approved RENAME_MAP idempotently; skip main components; return before/after. |
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.