penpot-rename-layers

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
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.1
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:

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

## 4. Plugin API Essentials

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.
- **Renaming touches no geometry** — it does not move, resize, or reparent anything. This is exactly why renaming auto-named layers is reversible and safe.
- **Component main shapes:** detect with `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 (`isComponent