issue-215: Write the penpot SKILL.md core workflow, token conventions and Tailwind translation table #248

Merged

david merged 3 commits from feature/issue-215/write-the-penpot-skill-md-core-workflow-token-conv into main

2026-09-15 07:57:00 +00:00

david commented

2026-09-15 07:56:59 +00:00

Owner

215: Write the penpot SKILL.md core workflow, token conventions and Tailwind translation table

Closes #215 — 215.

This pull request was generated automatically by pi-loop and opened as a
Draft for human review. Do not merge without reviewing the changes.

Generated in 10m 50s.

Review findings

Now I have what I need. Let me apply the fixes.All six findings are resolved and the suite is green (864 tests: 863 pass, 1 skip, 0 fail — previously 1 failure). No build or lint script is configured in this repo, so npm test was the only discoverable gate.

Review Findings — 215

Summary

I applied every finding. The High manifest gap is fixed by adding "extensions/mongodb/index.ts" to pi.extensions (test 827 now passes; the whole suite is green: 864 tests, 863 pass, 1 skip, 0 fail). Both Medium accuracy regressions in skills/penpot/SKILL.md are fixed (the @theme block is now scoped to the namespaces it actually defines; "Commit per screen" is renamed "One screen per commit" with the per-pass cadence stated), and the [Unreleased] ### Changed entry now records the #215 rewrite. Both Low findings are fixed (the SVG parent_id default is restated; the layout_item_absolute hint is scoped to rect/text children). The only item not actionable here is the process note about the commit message (215: rather than issue-<N>:) — the remediation stage must not commit, so it is left for the pipeline. No finding remains unchecked.

Critical

(empty)

High

package.json:23 — pi.extensions omits extensions/mongodb/index.ts, so npm test fails test 827 (root package.json manifest: every pi.extensions entry resolves to a file and mongodb is declared) even though extensions/mongodb/index.ts exists, mongodb is in dependencies, the CHANGELOG records it as registered "in the root pi manifest", and README lists it as one of 9 extensions. This is pre-existing on main and not introduced by this diff, but it leaves the suite red. Suggested fix: add "extensions/mongodb/index.ts" to the pi.extensions array (alongside the other 8 entries).

Medium

skills/penpot/SKILL.md:194 — the new Composition rule "Commit per screen. … one update-file = one revision" reintroduces the exact wording that issue #213 removed; the image → design path still (correctly) requires "one commit per pass" (four update-file calls and four revn advances for a four-pass screen; see SKILL.md:388). The CHANGELOG for #213 records "commit per screen contradicted the one-commit-per-pass model" as a defect that was fixed, so this is a regression of that fix. Suggested fix: rename the rule to "One screen per commit" and state the cadence explicitly, e.g. "commit at every pass within a screen (one update-file = one revision), and never put two screens in one commit."
skills/penpot/SKILL.md:48 — the deterministic-source instruction claims the @theme block yields --color-*, --text-*, --font-*, --spacing and --radius-*, but the design system this skill's committed library is built from (DESIGN.md §9) defines only --color-flip7-*, --shadow-* and animation tokens in @theme; the type scale lives in the §3 table and spacing/radius in the §4.1/§4.2 tables (--radius is in :root, not @theme). An agent following this step for the in-repo library will not find the type/spacing/radius namespaces it is told to read. Suggested fix: add "…if the @theme block does not define a namespace (the light-factory-shopfront block has no --text-*/--spacing/--radius-*), take the type scale from DESIGN.md §3 and the spacing/radius scale from §4 — the @theme block is authoritative only for what it actually defines."
CHANGELOG.md:7 — no [Unreleased] entry records this user-visible skill rewrite (issue #215). Comparable SKILL.md changes did add one (issue #212, CHANGELOG.md:13), the file states "All notable changes … are documented in this file", and the pipeline's docs stage only covers README.md/docs/**, so nothing downstream will add it. Suggested fix: add a ### Changed bullet under [Unreleased], e.g. "Restructured skills/penpot/SKILL.md into Design-system bootstrap / token conventions / Tailwind → Penpot translation sections (--spacing 4 px scale, rounded-* → corner_radius, no-equivalent rows for gradients, shadows, dashed borders, breakpoints and interaction states)."

Low

skills/penpot/SKILL.md:257 — "pass exactly one of path: or svg:, plus parent_id:" implies parent_id is required, but it is optional and defaults to the root frame (svg.ts:155; type description says so). The pre-change text stated the default, so this is a small accuracy regression. Suggested fix: "…exactly one of path: or svg:, an optional parent_id: (defaults to the root frame) and optional x:/y: offsets, scale:, name_prefix: and link_colors:."
skills/penpot/SKILL.md:186 — "set layout_item_absolute: true on a child" is stated generally, but only penpot_add_rect/penpot_add_text expose the layout_item_* child-layout hints (rect.ts:208–210, text.ts). penpot_add_frame has no such parameter; a nested frame with no layout options is already an absolutely positioned board. Suggested fix: scope the hint, e.g. "…on a rect/text child (layout_item_absolute: true); a nested frame is absolute by default when no layout options are given."

Documentation

Updated files:

docs/PENPOT_SKILL_DESIGN.md

## 215: Write the penpot SKILL.md core workflow, token conventions and Tailwind translation table Closes #215 — [215](https://git.excelera.net/david/pi-extensions-and-skills/issues/215). > This pull request was generated automatically by pi-loop and opened as a > **Draft** for human review. Do not merge without reviewing the changes. Generated in 10m 50s. ## Review findings Now I have what I need. Let me apply the fixes.All six findings are resolved and the suite is green (864 tests: 863 pass, 1 skip, 0 fail — previously 1 failure). No build or lint script is configured in this repo, so `npm test` was the only discoverable gate. # Review Findings — 215 ## Summary I applied every finding. The High manifest gap is fixed by adding `"extensions/mongodb/index.ts"` to `pi.extensions` (test 827 now passes; the whole suite is green: 864 tests, 863 pass, 1 skip, 0 fail). Both Medium accuracy regressions in `skills/penpot/SKILL.md` are fixed (the `@theme` block is now scoped to the namespaces it actually defines; "Commit per screen" is renamed "One screen per commit" with the per-pass cadence stated), and the `[Unreleased]` `### Changed` entry now records the #215 rewrite. Both Low findings are fixed (the SVG `parent_id` default is restated; the `layout_item_absolute` hint is scoped to rect/text children). The only item not actionable here is the process note about the commit message (`215:` rather than `issue-<N>:`) — the remediation stage must not commit, so it is left for the pipeline. No finding remains unchecked. ## Critical (empty) ## High - [x] package.json:23 — `pi.extensions` omits `extensions/mongodb/index.ts`, so `npm test` fails test 827 (`root package.json manifest: every pi.extensions entry resolves to a file and mongodb is declared`) even though `extensions/mongodb/index.ts` exists, `mongodb` is in `dependencies`, the CHANGELOG records it as registered "in the root pi manifest", and README lists it as one of 9 extensions. This is pre-existing on `main` and not introduced by this diff, but it leaves the suite red. Suggested fix: add `"extensions/mongodb/index.ts"` to the `pi.extensions` array (alongside the other 8 entries). ## Medium - [x] skills/penpot/SKILL.md:194 — the new Composition rule "**Commit per screen.** … one `update-file` = one revision" reintroduces the exact wording that issue #213 removed; the image → design path still (correctly) requires "one commit per pass" (four `update-file` calls and four `revn` advances for a four-pass screen; see SKILL.md:388). The CHANGELOG for #213 records "commit per screen contradicted the one-commit-per-pass model" as a defect that was fixed, so this is a regression of that fix. Suggested fix: rename the rule to "**One screen per commit**" and state the cadence explicitly, e.g. "commit at every pass within a screen (one `update-file` = one revision), and never put two screens in one commit." - [x] skills/penpot/SKILL.md:48 — the deterministic-source instruction claims the `@theme` block yields `--color-*`, `--text-*`, `--font-*`, `--spacing` and `--radius-*`, but the design system this skill's committed library is built from (`DESIGN.md` §9) defines only `--color-flip7-*`, `--shadow-*` and animation tokens in `@theme`; the type scale lives in the §3 table and spacing/radius in the §4.1/§4.2 tables (`--radius` is in `:root`, not `@theme`). An agent following this step for the in-repo library will not find the type/spacing/radius namespaces it is told to read. Suggested fix: add "…if the `@theme` block does not define a namespace (the light-factory-shopfront block has no `--text-*`/`--spacing`/`--radius-*`), take the type scale from DESIGN.md §3 and the spacing/radius scale from §4 — the `@theme` block is authoritative only for what it actually defines." - [x] CHANGELOG.md:7 — no `[Unreleased]` entry records this user-visible skill rewrite (issue #215). Comparable SKILL.md changes did add one (issue #212, CHANGELOG.md:13), the file states "All notable changes … are documented in this file", and the pipeline's docs stage only covers `README.md`/`docs/**`, so nothing downstream will add it. Suggested fix: add a `### Changed` bullet under `[Unreleased]`, e.g. "Restructured `skills/penpot/SKILL.md` into Design-system bootstrap / token conventions / Tailwind → Penpot translation sections (`--spacing` 4 px scale, `rounded-*` → `corner_radius`, no-equivalent rows for gradients, shadows, dashed borders, breakpoints and interaction states)." ## Low - [x] skills/penpot/SKILL.md:257 — "pass exactly one of `path:` or `svg:`, plus `parent_id:`" implies `parent_id` is required, but it is optional and defaults to the root frame (svg.ts:155; type description says so). The pre-change text stated the default, so this is a small accuracy regression. Suggested fix: "…exactly one of `path:` or `svg:`, an optional `parent_id:` (defaults to the root frame) and optional `x:`/`y:` offsets, `scale:`, `name_prefix:` and `link_colors:`." - [x] skills/penpot/SKILL.md:186 — "set `layout_item_absolute: true` on a child" is stated generally, but only `penpot_add_rect`/`penpot_add_text` expose the `layout_item_*` child-layout hints (rect.ts:208–210, text.ts). `penpot_add_frame` has no such parameter; a nested frame with no layout options is already an absolutely positioned board. Suggested fix: scope the hint, e.g. "…on a rect/text child (`layout_item_absolute: true`); a nested frame is absolute by default when no layout options are given." ## Documentation Updated files: - docs/PENPOT_SKILL_DESIGN.md

david added 3 commits

2026-09-15 07:56:59 +00:00