Przejdź do treści
Biblioteka skilli
Projektowanie i UX · Integracja z narzędziem

pen-sync

/pen-sync

Przenosi bibliotekę komponentów React do pliku systemu projektowego w Pencil: eksportuje je ze Storybooka i wiąże z tokenami.

Repozytorium
pen-sync ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Przenosi bibliotekę komponentów React do pliku systemu projektowego w Pencil: eksportuje je ze Storybooka i wiąże z tokenami.

Wyzwalacze z opisu

s Pencil section is missing or stale, when asked toexport to Pencilpush the design systemadd X to the design filere-sync the molecules
Oryginalny opis (EN)

Mirror a React component library into its Pencil (pen.dev) design-system file — register a component, give it a VariantMatrix story, export it from Storybook and push it into Pencil as reusable components bound to the token variables, through the pen.dev CLI. Use when adding or changing a shared component, when a component's Pencil section is missing or stale, when asked to "sync to Pencil", "export to Pencil", "push the design system", "add X to the design file", re-push a level ("re-sync the molecules"), push token changes, set a repo up for pen-sync, or check the file in CI. For how faithfu

Jak działa

  1. A repo with source in its config
  2. Sections that came from a design file
  3. Prerequisites
  4. 0. A repo without pen-sync yet
  5. 1. Make the component mirrorable
  6. 2. Push
  7. 3. Check and save
  8. Rules
Sekcje z nagłówków SKILL.md, w oryginale · 111 linii, 960 słów
Podgląd SKILL.md
---
name: pen-sync
description: Mirror a React component library into its Pencil (pen.dev) design-system file — register a component, give it a VariantMatrix story, export it from Storybook and push it into Pencil as reusable components bound to the token variables, through the pen.dev CLI. Use when adding or changing a shared component, when a component's Pencil section is missing or stale, when asked to "sync to Pencil", "export to Pencil", "push the design system", "add X to the design file", re-push a level ("re-sync the molecules"), push token changes, set a repo up for pen-sync, or check the file in CI. For how faithful a pushed section is, use pen-polish; for designing with the library or taking design edits back to code, pen-design.
---

# Design-system sync (code → Pencil)

Code is the source of truth. Pencil holds a **generated** mirror: one section per component,
each variant a reusable Pencil component whose `context` links back to its JSX, source file,
story and variant key. Designers compose with those components; a re-sync replaces the
section and re-points their instances by variant key, so nothing they built breaks.

Repo specifics (component package, registry, Storybook, tokens, Pencil file, themes, metadata
prefix) live in `pen-sync.config.json` at the repo root.

**Scripts:** `$DS` below is the plugin's `scripts/` folder — `${CLAUDE_PLUGIN_ROOT}/scripts`
when installed as a plugin. Run them from the repo
root: they find the repo by walking up to `pen-sync.config.json`.

## A repo with `source` in its config

When `pen-sync.config.json` has `source`, components aren't React: commands render them (the
README has the contract). Ignore the Storybook, `data-ds`, story and `variants.mjs` steps below.
Build whatever the commands run first; a stale binary exports stale components. Add a variant
where that repo's matrix lives, keep its registry in step, then push as usual.

## Sections that came from a design file

Nodes tagged `<prefix>-design` were copied by `pen-import.mjs` and have no code behind them. Don't
edit them in the library: edit the source file and re-import. When a component replaces one, take
it out of the import list. See the README.

## Prerequisites

- Storybook running (config `storybook`), unless the config has `source`. Don't start a second one; ask.
- The pen.dev CLI (`pen`) installed and logged in. Pushes go into the **open desktop app** by
  default; `--headless` rewrites the file on disk instead.
- Scripts that launch Chromium, reach localhost or talk to the CLI run **outside the sandbox**.

## 0. A repo without pen-sync yet

`node $DS/init.mjs [--package packages/ui] [--prefix acme]` writes `pen-sync.config.json`,
copies the React kit into `<package>/src/design-system/` (matrix types, `variantMatrixStory`,
an empty registry, a contract test) and creates the `.pen` file with a board per level.
Nothing existing is overwritten. Then fix `themes` in the config: per theme, the Storybook
globals that render it, the `<html>` attributes that switch the token CSS to it, and its Pencil
theme tuple. Then `node $DS/export-tokens.mjs` and `node $DS/pen-sync.mjs --tokens`.

## 1. Make the component mirrorable

1. **Registry entry** in the registry (config `registry`): permanent kebab-case `id`, story
   `name`, `level` (atom / molecule / organism / template), `file`. Never rename or reuse an
   id; a removed component moves to `retired`.
2. **`data-ds="<id>"`** on the element that *is* the component visually (an overlay's popup,
   a select's trigger); a registry `selector` finds one whose DOM can't carry it.
3. **Variants**: `node $DS/variants.mjs` after changing a cva or the component's props (axes
   are literal-union props declared in the package; states are styled inherited props like
   `disabled`).
4. **Matrix** in the story file, beside its `VariantMatrix` story (tagged `ds-matrix`, last in
   the file). `{ id }` gets the default rows — each axis on its own, then each state turned on.
   Add only exceptions: `ignore` (axis → reason), `rows` when the default is wrong (crossed
   axes, `surface: "brand"` for a dark backdrop, row props such as sample content),
   `extraRows`, `overrides`, `slots` (parts that take arbitrary children → the registry ids
   that usually go there), `axes`/`defaults` for root or wrapper props. The kit's contract
   test fails until every axis is decided.
5. Wrap the component in the story when its `data-ds` element needs context (an open popup
   portaled into the cell with `transform-gpu`; `data-ds-capture` widens what's mirrored).

## 2. Push

```bash
node $DS/pen-sync.mjs <id> [<id>…]       # export from Storybook and push into the open app
node $DS/pen-sync.mjs --level molecule   # a level; --all for everything
node $DS/pen-sync.mjs --all --changed    # skip components whose export didn't change
node $DS/pen-sync.mjs --tokens           # token variables (after export-tokens.mjs)
node $DS/pen-sync.mjs --all --headless   # rewrite the .pen file on disk and save (no app)
node $DS/export-matrix.mjs <id>          # just the export: JSON + binding report
```

Each component prints `{components, replaced, repointed, orphans}`. **Orphans** are designer
instances whose variant no longer exists; their old section is kept, renamed "(old: instances
still use it)". Report them; never delete them. Read the export's binding report: `literal`
paints or many `scoped` variables mean a color no token expresses — usually fine (opacity
modifiers), worth a look when a whole component goes scoped.

- Never run headless on the file while the desktop app has it open with unsaved changes: the
  app's next save overwrites it. One writer at a time.
- Pencil warns "Collapsed size … fit_content" for every empty slot frame; that's expected.
- Pencil interrupts an `execute` call past ~55 s; pushes are one component per call, so only a
  huge component would hit it.

**No CLI?** Payloads can go in through Pencil's integrated browser and MCP `execute` instead:
`pencil-chunks.mjs --setup` and `export-matrix.mjs --pencil-apply` once per Pencil session,
`pencil-chunks.mjs --page batch.html <data.js…>` per batch (data from `export-matrix.mjs <id>
--pencil-data`), Pencil `browser` `load-page` + `import-to-canvas` (`#pen-sync-payload`), then
the printed take snippet with the imported frame's id (it checks the hash and stores the batch
as `dsBody`), then one component per `execute` call:
`eval(dsBody.split("\n")[i])`.

## 3. Check and save

- Run the **pen-polish** loop on what you pushed.
- `node $DS/pen-sync.mjs --check` (read-only, works on a copy of the saved file) lists
  sections missing, built from older source, or orphaned; `node $DS/pen-library.mjs` refreshes
  the library reference agents design from (`--check` in CI).
- In app mode Pencil writes the `.pen` file only when the user saves. Ask, then commit the
  file with the code changes.

## Rules

- Never hand-edit a generated section: fix the matrix, story wrapper or exporter and re-push
  (the pen-polish skill's table maps symptoms to inputs).
- Never change `metadataPrefix` on an existing file: sections would stop being found.
- Exporter changes need a test beside them (`node --test $DS/*.test.mjs`).

Wersje

W bazie nie ma innych skilli o nazwie pen-sync.

Migawka bazy z 13.11.2026 · wersja paczki 13f7483b137d (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100pen-polish
    Dopracowuje bibliotekę komponentów w Pencil względem kodu: porównuje zrzuty ekranu i eksport, a poprawki wprowadza w kodzie generatora, a potem eksportuje od nowa.
  • 90pen-design
    Projektuje ekrany w Pencil z biblioteką systemu projektowego i przenosi zmiany projektanta z biblioteki z powrotem do kodu.
  • 100pencil-design
    Projektuje interfejsy w Pencil (pliki .pen) i generuje z nich kod produkcyjny, przy zadaniach od projektu do kodu.
  • 100pencil-design
    Tworzy i edytuje pliki projektowe .pen w Pencil przez MCP oraz eksportuje projekty do kodu React i Tailwind.
  • 95pencil-design
    Projektuje interfejsy w plikach .pen w pencil.dev, edytuje płótno, tworzy komponenty z biblioteki .lib.pen i naprawia błędy batch_design.
  • 100pencil-replicator
    Odtwarza ekran strony widoczny w Chrome jako plik Pencil (.pen) w cyklu analizy, budowy i weryfikacji jakości prowadzonym przez trzech wyspecjalizowanych agentów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.