penpot-component-factory

penpot-component-factory — complete, tokenized variants

1. Title + How it works

penpot-component-factory builds components and their full variant matrices; 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 builds a base component as a Board with flex layout (every value tokenized via penpot-foundations tokens), generates variants across axes, combines them into a variant container (penpotUtils.createVariantContainer on ≥ 2.17; penpot.createVariantFromComponents as the low-level fallback), and verifies completeness.

2. The One Rule That Matters Most

Every interactive component ships every required state, and every value is a token. No hardcoded fills/spacing; no missing Hover/Pressed/Focus/Disabled unless the system explicitly says otherwise. Build one variant at a time; checkpoint before combining.

3. Penpot MCP Tool Reference

Full surface: shared/penpot-mcp-tool-reference.md. Key calls:

4. Plugin API Essentials

Gotcha numbers refer to shared/plugin-api-gotchas.md.

• Build the base as a Board (createBoard, NOT createFrame) with addFlexLayout(); set dir, gaps, padding, horizontalSizing/verticalSizing.
• #4 flex/grid overrides child x/y — order children by append; use layoutChild for per-child sizing/margins.
• clone() duplicates a shape with all properties — the basis for the variant matrix.
• #9 variant API — prefer penpotUtils.createVariantContainer([{ shape: mainInstance, properties: { Size: "Medium", State: "Default" } }]) (≥ 2.17) behind the duplicate-file gate; the low-level penpot.createVariantFromComponents(mainInstances) + renameProperty/addProperty/setVariantProperty path only as fallback. Switch with instance.switchVariant(pos, value) — pos is the index in variants.properties, not the axis name. Board.combineAsVariants(ids) is listed by penpot_api_info on 2.17 but unverified — do not use.
• #6 detach before mutating an instance's internals — and NEVER on a variant instance (see #12).
• #12 variant MUTATION corrupts the file — this skill's critical failure mode. setVariantProperty(pos, value) updates the variant properties but not the variant root's internal :variant-name, so the file fails backend referential-integrity validation: from then on every component-touching mutation is rejected with an HTTP 400 the plugin never surfaces — calls hang ~30 s, the session dies, unflushed mutations roll back. The same poison applies to addVariant() + rename, comp.instance() + detach() on a variant, createComponent on a detached variant instance, and shape.remove() on a variant board; recovery is manual. Reading variants and instancing a specific variant are safe. Safe strategy: build each state as a standalone Board and createComponent([board]) one at a time, named Component / State; Phase 3 (§6) carries the duplicate-file / verify-saves / fallback procedure.
• Verify unfamiliar signatures with penpot_api_info('VariantContainer') / penpot_api_info('Variants') first.

5. Token-Aware Brief Contract

• Context — which design system / token sets are active; component purpose.
• Objective — single component + its variant axes.
• Inputs — base layout, the token set (penpot-foundations), required axes.
• Constraints — all values tokenized; all required states present; naming Property=Value.
• Acceptance Criteria — matrix complete; zero hardcoded values; every state legible & AA-contrast; names follow convention.

Act as a senior component engineer.

6. Mandatory Workflow

Visual self-review (mandatory): before every ✋ checkpoint that shows visual work, run the export → look → fix loop from shared/visual-self-review.md — export the unit you just built, inspect the image yourself against the checklist, fix visible defects (max 2 iterations), and present that same export with any remaining defects named.

Phase 0 — Discovery. high_level_overview; read tokens (tokenOverview()) and existing components. Decide axes (references/01-variant-axes.md). ✋ Checkpoint: confirm the axis matrix.

Phase 1 — Base. Build the base Board with flex layout, tokenized (scripts/buildComponentBase.js), then createComponent. ✋ Checkpoint: review base (export_shape).

Phase 2 — Variants as components. For each matrix cell, clone the base, retokenize per state, and createComponent it — createVariantFromComponents needs a component per variant. Use scripts/createVariants.js (collects each cell's main-instance id). ✋ Checkpoint: review the cells.

Phase 3 — Group, name axes, organize. ⚠️ HIGH-RISK PHASE — read shared/plugin-api-gotchas.md #12 first. Mutating variant components (setVariantProperty, axis renames, detaching/removing variants) has corrupted files and hung all subsequent saves in live sessions (the backend rejects every save with an unsurfaced HTTP 400). Before this phase: ✋ Checkpoint — ask the user to duplicate the file (or confirm they accept the risk on a scratch file). Then apply one variant mutation, verify the file still saves (a later read-only call must succeed and persist), and only then continue. If any call hangs ~30 s, stop immediately and switch to the fallback below.

The variant flow: scripts/createVariantGroup.js is gated — it returns { halted: true } unless storage.cf.fileDuplicatedConfirmed === true (set it in a prior call only after the user duplicated the file and confirmed saves work). It then prefers penpotUtils.createVariantContainer(records.map(r => ({ shape: main, properties: r.properties }))) (path "helper", ≥ 2.17: axes + values in one call), falling back to penpot.createVariantFromComponents

• renameProperty/addProperty/setVariantProperty (path "legacy", kept verbatim in the script). Either way it clears the container fill (#11), gives the container a flex layout (variants stack at the same spot otherwise: container.flex || container.addFlexLayout(); row, gaps, padding, wrap) and returns { containerId, path, properties, components, next }. Save verification: after the call, make a trivial change in the Penpot UI and confirm it persists before any further mutation — a ~30 s hang means the file is poisoned; discard the duplicate and switch to the fallback below. ✋ Checkpoint.

Fallback (always safe): skip the variant container entirely. Keep the per-cell components from Phase 2 as standalone components named Component / Axis=Value, … (e.g. Button / Size=Medium, State=Hover), created one at a time with a flush pause between calls, arranged in a labeled grid. Penpot groups them by the / prefix and the user can convert them to real variants in the UI later.

Phase 4 — Validate. scripts/validateComponent.js — every required state present, all values tokenized, naming correct. Optional scripts/switchVariantDemo.js to prove switching. Report.

7. Critical Rules

1. All interactive components include Default/Hover/Pressed/Focus/Disabled unless the system says otherwise.
2. Zero hardcoded values — bind to semantic (or component) tokens.
3. Variant property/value names: Property=Value, PascalCase (Size=Medium, State=Hover).
4. Build as a flex Board; never absolute-position children unless layoutChild.absolute.
5. Idempotent: don't duplicate an existing variant.
6. Detach only when necessary, and report it — never detach a variant instance (gotchas #12).
7. After grouping, give the variant container a flex layout — variants stack at the same position otherwise.
8. Variant mutation is a known file-corruption risk (gotchas #12): duplicate the file before Phase 3, verify saves after the first mutation, and fall back to standalone Component / State components if anything hangs.

8. Domain Architecture

Standard axes:

• Size = Small | Medium | Large
• Hierarchy = Primary | Secondary | Tertiary
• State = Default | Hover | Pressed | Focus | Disabled
• Icon = None | Left | Right

The matrix is the Cartesian product you need — keep it as small as the system allows (don't generate combinations the design language doesn't use). Each variant is a cloned base with state-specific token bindings.

9. Modes & Policies

Default review. Variant/component restructuring and detach() are never auto-applied (shared/modes-and-policies.md).

10. State Management

Ledger keys under RUN_ID: phase, baseComponentId, created:[{variant:'Size=Medium,State=Hover', id}]. Re-derive with a component read after truncation.

11. User Checkpoints

12. Naming Conventions

shared/naming-conventions.md: component PascalCase (Button); variant Property=Value; internal layers semantic (label, icon, button).

13. Anti-Rationalization Table

14. Helper Code Snippets

// Base as a flex Board (Phase 1) — gaps/fill/padding bound to tokens (padding binds on ≥ 2.17; mirror + exception on 2.16.x, gotchas #8)

15. Reference Resources

• penpot_api_info('Board'), penpot_api_info('VariantContainer'), penpot_api_info('Variants'), penpot_api_info('LibraryComponent').

16. Supporting Files

references/: 01-variant-axes.md, 02-flex-grid-layout.md, 03-variant-api.md, 04-instance-swap-detach.md, 05-anti-rationalization.md, 06-error-recovery.md. scripts/: buildComponentBase.js, createVariants.js (one component per cell), createVariantGroup.js (gated; helper ≥ 2.17 or legacy path), switchVariantDemo.js, validateComponent.js.

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.