From de8c40cf43e08a63ca0be38a4b4404fbe2427885 Mon Sep 17 00:00:00 2001 From: Jarvis Jr Hermes Date: Fri, 28 Aug 2026 19:45:29 +0000 Subject: [PATCH] fix: guard Penpot library component roots --- SKILL.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/SKILL.md b/SKILL.md index faea438..7980607 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: corp-v1-channel-ui-ux description: "Use when operating or synchronizing a Corp v1 project's UI/UX channel. Maintains project frontend design work, Penpot artifacts, design-system decisions, accessibility evidence, and implementation handoffs while correlating verified activity across the project's seven channels." -version: 1.2.2 +version: 1.3.0 author: Hermes Agent license: MIT metadata: @@ -167,6 +167,14 @@ Do not mark a design package `Approved` without authoritative evidence. Preserve ## Design System and Frontend Contract +### Penpot shared-library component-root invariant + +On Penpot 2.17.1, every published component's `mainInstanceId` must resolve to a `frame` or `group`. Never publish a component directly from a primitive `rect`, `circle`, `text`, image, or path: the Libraries dashboard component renderer handles only `frame` and `group` roots and otherwise crashes deterministically, for example with `No matching clause: rect`. + +Build a container root first, move the component background, labels, and other visual children inside it, and create the component from that container. Before sharing or reporting a design-system library as healthy, read back every active component definition, resolve each main instance in the page object map, assert its root type is `frame` or `group`, and open the authenticated team Libraries route to confirm that no `No matching clause` page error occurs. + +When repairing a malformed library, first prove whether product files contain instances of the affected component IDs. Replace invalid definitions with valid container-root definitions in one exact-revision batch; preserve visual children and parentage; then distinguish active records from Penpot recovery records marked `deleted: true`. Purge only the retired malformed records after active-count, root-type, child-count, library-link, and authenticated-dashboard readback pass. Do not treat a raw component-map count as the active count, and do not claim success merely because the file or library link exists. + Prefer project-level reusable components and tokens over one-off screens. Record at least: - typography, spacing, color, elevation, iconography, and interaction tokens; @@ -244,6 +252,7 @@ Link each design package from its authoritative Feature record and relevant Arch 12. Reintroducing or requesting the official plugin-based `penpot` MCP instead of operating solely through `penpot-zcube-v1`. 13. Enabling all community-server tools, especially destructive team/project/file administration, instead of maintaining a fail-closed include list. 14. Retrying a low-level `update-file` mutation after an uncertain response without revision and object readback. +15. Publishing a component whose main instance is a primitive shape. Penpot 2.17.1 requires a `frame` or `group` root for Libraries dashboard rendering. ## Verification Checklist @@ -259,3 +268,4 @@ Link each design package from its authoritative Feature record and relevant Arch - [ ] No Corp project cronjob or scheduler job exists. - [ ] `penpot-zcube-v1` was the only configured Penpot MCP and was restricted to approved tools. - [ ] Mutations include exact file/page/object/revision readback; unsupported capabilities are reported without adding another Penpot MCP. +- [ ] Every active shared-library component resolves to a `frame` or `group` root, deleted recovery records are excluded from active counts, and the authenticated Libraries route opens without a `No matching clause` error.