Author and commit the component library artifact under skills/penpot/assets #206

New issue

Closed

opened 2026-09-14 23:13:02 +00:00 by david · 1 comment

david commented

2026-09-14 23:13:02 +00:00

Owner

Summary

Author the project component library once in the Penpot UI, export it with the extension's export tool, and commit it to the repo as skills/penpot/assets/<name>.penpot with a short authoring/refresh note — so the skill can import a reproducible, reviewable library instead of hand-authoring components over the API.

Background

Depends on: #205

Component creation over the API (add-component, with its mainInstanceId/mainInstancePage marking) is deliberately out of scope: it is the single riskiest thing to build against an undocumented schema, and Penpot's UI is the right tool for designing components anyway. The strategy is library-as-artifact:

author the library once, in the UI;
export it as a .penpot file with penpot_export_library;
commit the artifact to this repo;
import it per project with penpot_import_library, then link it (penpot_link_library) so consuming files can see its components.

The exported artifact is inspectable (manifest.json, files/<id>.json, colors/, typographies/), so a committed library is diffable in review — a reviewer can see that a component's geometry or a colour changed.

The library must be authored for a real design system, not a generic one: use the palette and typography conventions from a project DESIGN.md (the reference design system used during validation is a Tailwind/shadcn-style one whose palette lives in a @theme CSS block). Record which DESIGN.md the artifact was authored from, so it can be regenerated when that design system changes.

Documentation Required

A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting.

docs/reference/penpot-api/

https://help.penpot.app/user-guide/design-systems/components/ — creating components, main instances, component naming/paths and variants in the UI. This is the authoring guide for this step.
https://help.penpot.app/user-guide/design-systems/libraries/ — how a file's library works, what "shared" means, and how components appear to a consumer.
https://help.penpot.app/user-guide/design-systems/assets/ — colour/typography assets, including how to create and name them.
https://help.penpot.app/user-guide/export-import/export-import-files/ — the export options used here (includeLibraries, embedAssets) and what each carries.
https://help.penpot.app/user-guide/design-systems/layout/ — auto-layout on components, so library components behave correctly when a consumer resizes an instance.

docs/reference/tailwindcss/

https://tailwindcss.com/docs/theme — the @theme directive: how a project's design tokens are expressed as --color-* custom properties, i.e. the machine-readable palette this artifact must reflect.
https://tailwindcss.com/docs/functions-and-directives — @theme alongside other directives, for locating the token block in a real project's CSS.

docs/reference/pi-coding-agent/

https://pi.dev/docs/skills or https://pi.dev/docs/latest/skills — how a skill's assets directory is packaged and referenced, so the artifact is found at runtime.

Implementation Details

Identify the source design system. Read the target project's DESIGN.md (and its @theme CSS block where present). Extract: the colour palette (names + hex), the typographic scale (family, sizes, weights, line heights), radii, and the component recipe list.
Author the library in the Penpot UI, in a dedicated project:
- colour assets for every palette token, named exactly as the design system names them;
- typography assets for every scale step (h1…h3, body, label, …) using a font the instance actually ships (record any substitution);
- components for the design system's reusable pieces — for a minimal but genuinely useful first version: Button (with primary/secondary variants if variants are easy), Card, Badge, ProgressBar — each built with auto-layout, real text objects, and fills linked to the colour assets rather than local colours;
- component names/paths that map cleanly to the design system's names (the skill translates Tailwind idioms to these).
Export and commit. Run penpot_export_library for the library file, then commit the resulting ZIP to skills/penpot/assets/ with a stable, descriptive filename. Add skills/penpot/assets/README.md recording: the source DESIGN.md (+ its location or revision), the Penpot version used, the font substitutions made, the component inventory with names, and the exact steps to regenerate the artifact.
Prove it re-imports. Import the committed artifact into a fresh throwaway project with penpot_import_library, and confirm the components and assets arrive with the expected names. Then link it and confirm the next milestone's instancing step will be able to reach the components.
Keep the artifact reasonably small — no embedded raster assets unless a component genuinely needs one.

Acceptance Criteria

A .penpot artifact is committed under skills/penpot/assets/ with a stable filename.
skills/penpot/assets/README.md records the source design system, the Penpot version, font substitutions, the component inventory, and regeneration steps.
The artifact contains a colour asset for every palette token in the source DESIGN.md/@theme block, named identically.
The artifact contains typography assets for the design system's scale steps, using fonts the instance ships (substitutions recorded).
The artifact contains at least four real components (e.g. Button, Card, Badge, ProgressBar), each with auto-layout, real text, and fills linked to the colour assets.
Re-importing the committed artifact into a fresh project yields the same component and asset names (verified, not assumed).
The .penpot archive is inspectable (manifest.json, files/*.json, colors/*, typographies/*) and contains no unnecessary embedded raster data.
No API-authored components: add-component is not used anywhere in the extension.

Test Plan

Inspect the committed artifact:

unzip -l skills/penpot/assets/*.penpot | head -50
unzip -p skills/penpot/assets/*.penpot manifest.json | head -40

Re-import into a throwaway project via penpot_import_library and open it in the Penpot UI:
- confirm the Assets panel lists the same colour and typography names;
- confirm each component exists with the expected name and renders correctly.
Link the imported library to a consumer file (penpot_link_library) and confirm the components are visible to the extension's read tools — this is the hand-off the instancing step depends on.
Open a component in the UI, edit the main instance's fill, and confirm the change is a library-level change (i.e. these are real components, not loose frames).

## Summary Author the project component library once in the Penpot UI, export it with the extension's export tool, and commit it to the repo as `skills/penpot/assets/<name>.penpot` with a short authoring/refresh note — so the skill can import a reproducible, reviewable library instead of hand-authoring components over the API. ## Background **Depends on:** #205 Component *creation* over the API (`add-component`, with its `mainInstanceId`/`mainInstancePage` marking) is deliberately out of scope: it is the single riskiest thing to build against an undocumented schema, and Penpot's UI is the right tool for designing components anyway. The strategy is **library-as-artifact**: 1. author the library once, in the UI; 2. export it as a `.penpot` file with `penpot_export_library`; 3. commit the artifact to this repo; 4. import it per project with `penpot_import_library`, then link it (`penpot_link_library`) so consuming files can see its components. The exported artifact is inspectable (`manifest.json`, `files/<id>.json`, `colors/`, `typographies/`), so a committed library is **diffable in review** — a reviewer can see that a component's geometry or a colour changed. The library must be authored for a real design system, not a generic one: use the palette and typography conventions from a project `DESIGN.md` (the reference design system used during validation is a Tailwind/shadcn-style one whose palette lives in a `@theme` CSS block). Record which `DESIGN.md` the artifact was authored from, so it can be regenerated when that design system changes. ## Documentation Required A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting. **`docs/reference/penpot-api/`** - https://help.penpot.app/user-guide/design-systems/components/ — creating components, main instances, component naming/paths and variants in the UI. This is the authoring guide for this step. - https://help.penpot.app/user-guide/design-systems/libraries/ — how a file's library works, what "shared" means, and how components appear to a consumer. - https://help.penpot.app/user-guide/design-systems/assets/ — colour/typography assets, including how to create and name them. - https://help.penpot.app/user-guide/export-import/export-import-files/ — the export options used here (`includeLibraries`, `embedAssets`) and what each carries. - https://help.penpot.app/user-guide/design-systems/layout/ — auto-layout on components, so library components behave correctly when a consumer resizes an instance. **`docs/reference/tailwindcss/`** - https://tailwindcss.com/docs/theme — the `@theme` directive: how a project's design tokens are expressed as `--color-*` custom properties, i.e. the machine-readable palette this artifact must reflect. - https://tailwindcss.com/docs/functions-and-directives — `@theme` alongside other directives, for locating the token block in a real project's CSS. **`docs/reference/pi-coding-agent/`** - https://pi.dev/docs/skills or https://pi.dev/docs/latest/skills — how a skill's assets directory is packaged and referenced, so the artifact is found at runtime. ## Implementation Details 1. **Identify the source design system.** Read the target project's `DESIGN.md` (and its `@theme` CSS block where present). Extract: the colour palette (names + hex), the typographic scale (family, sizes, weights, line heights), radii, and the component recipe list. 2. **Author the library in the Penpot UI**, in a dedicated project: - colour assets for every palette token, named exactly as the design system names them; - typography assets for every scale step (`h1`…`h3`, `body`, `label`, …) using a font the instance actually ships (record any substitution); - components for the design system's reusable pieces — for a minimal but genuinely useful first version: `Button` (with primary/secondary variants if variants are easy), `Card`, `Badge`, `ProgressBar` — each built with auto-layout, real text objects, and fills linked to the colour assets rather than local colours; - component names/paths that map cleanly to the design system's names (the skill translates Tailwind idioms to these). 3. **Export and commit.** Run `penpot_export_library` for the library file, then commit the resulting ZIP to `skills/penpot/assets/` with a stable, descriptive filename. Add `skills/penpot/assets/README.md` recording: the source `DESIGN.md` (+ its location or revision), the Penpot version used, the font substitutions made, the component inventory with names, and the exact steps to regenerate the artifact. 4. **Prove it re-imports.** Import the committed artifact into a fresh throwaway project with `penpot_import_library`, and confirm the components and assets arrive with the expected names. Then link it and confirm the next milestone's instancing step will be able to reach the components. 5. Keep the artifact reasonably small — no embedded raster assets unless a component genuinely needs one. ## Acceptance Criteria - [ ] A `.penpot` artifact is committed under `skills/penpot/assets/` with a stable filename. - [ ] `skills/penpot/assets/README.md` records the source design system, the Penpot version, font substitutions, the component inventory, and regeneration steps. - [ ] The artifact contains a colour asset for every palette token in the source `DESIGN.md`/`@theme` block, named identically. - [ ] The artifact contains typography assets for the design system's scale steps, using fonts the instance ships (substitutions recorded). - [ ] The artifact contains at least four real components (e.g. Button, Card, Badge, ProgressBar), each with auto-layout, real text, and fills linked to the colour assets. - [ ] Re-importing the committed artifact into a fresh project yields the same component and asset names (verified, not assumed). - [ ] The `.penpot` archive is inspectable (`manifest.json`, `files/*.json`, `colors/*`, `typographies/*`) and contains no unnecessary embedded raster data. - [ ] No API-authored components: `add-component` is not used anywhere in the extension. ## Test Plan 1. Inspect the committed artifact: ```bash unzip -l skills/penpot/assets/*.penpot | head -50 unzip -p skills/penpot/assets/*.penpot manifest.json | head -40 ``` 2. Re-import into a throwaway project via `penpot_import_library` and open it in the Penpot UI: - confirm the Assets panel lists the same colour and typography names; - confirm each component exists with the expected name and renders correctly. 3. Link the imported library to a consumer file (`penpot_link_library`) and confirm the components are visible to the extension's read tools — this is the hand-off the instancing step depends on. 4. Open a component in the UI, edit the main instance's fill, and confirm the change is a library-level change (i.e. these are real components, not loose frames).

david added this to the Penpot: M5 - Component library artifact and instancing milestone

2026-09-14 23:13:02 +00:00

david added the

feature

label

2026-09-14 23:13:02 +00:00

david referenced this issue

2026-09-14 23:13:15 +00:00

Implement penpot_instance_component with id remapping #207

david referenced this issue

2026-09-14 23:15:29 +00:00

Add the penpot skill and extension to the repo root README #216