Skip to content

feat(sync): sync design tokens with Paper through an inbox - #104

Open
Hebilicious wants to merge 3 commits into
mainfrom
feat/paper-sync
Open

Hebilicious wants to merge 3 commits into
mainfrom
feat/paper-sync

Conversation

@Hebilicious

@Hebilicious Hebilicious commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

What

Two-way token sync between a CSS Forge configuration and a Paper file. The configuration is the source of truth: push sends its tokens to the file, and what designers create, change or delete in the file waits in an inbox until a decision settles it.

cssforge sync remote add --file <id or URL>   # bind a file (1 request)
cssforge sync fetch                           # read the file, show the plan (1)
cssforge sync plan                            # plan against the last fetch (0)
cssforge sync push [--dry-run]                # send the plan (1 to 4; 1 when nothing changed)
cssforge sync inbox list                      # what designers changed (0)
cssforge sync inbox adopt --item <id> --path <token path>
cssforge sync inbox reject --item <id>
cssforge sync inbox overwrite --item <id>

How

  • src/sync/plan.ts: a pure three-way plan (configuration, remote, base after the last push, recorded decisions) that gives the operations and the inbox.
  • src/sync/capabilities.ts: the eight commands as AcidCat capabilities under cssforge sync, with MCP hints (sync.push destructive, sync.plan and sync.inbox.list read-only). They are also cssforge mcp tools and typed calls of @hebilicious/cssforge/capabilities.
  • src/sync/remote.ts: the adapter interface, so another design tool (Figma) can be added. src/sync/paper.ts maps token kinds to Paper types and talks to paper-design mcp through a small MCP stdio client (src/sync/mcp-client.ts, no new dependency).
  • Provider-neutral: a remote token has a key (Paper: its name; Figma: an id), a label and an optional custom property; the base and the decisions are keyed by it. sync remote add --options <json> passes options to the adapter (checked before any request). Tokens carry a value per mode (default, light/dark for scheme-dependent values, or a selector such as .dark; src/sync/modes.ts), and the target lists the modes it holds. Paper holds only default.
  • src/sync/state.ts: .cssforge/sync/<remote>.json, validated on read; commit it so the team shares the base.
  • listTokens (generator) and listConfigTokens (forge) reuse the existing resolver and inferValueKind.
  • @acid-cat/core-ts 0.13.0 → 0.15.0 (destructive and idempotent hints). tokens.build is now marked destructive.

Tokens Paper has no place for are listed in skipped with the reason (and the mode, for a mode Paper does not hold): color-mix() values, light-dark() and scoped tokens (Paper holds only the default mode), the pow() scale helpers, motion, gradients.

Evidence

  • moon run cssforge:typecheck cssforge:test cssforge:format cssforge:catalog-check cssforge:readme-check cssforge:jsr-dry-run: pass, 273 tests (31 for sync). Each regression test was shown to fail without its fix.
  • Paper adapter tested on the wire against a fake MCP server in Paper 0.5.19's response form (tests/fixtures/fake-paper-mcp.ts).
  • Live run against Paper Desktop 0.5.19 (12 MCP calls): sync remote add, push of 4 tokens (Paper stored oklch(100% 0 none) as oklch(100% 0 0) and 0.2 as 0.200; the read-back keeps those from reading as edits), a designer-created token reaching the inbox as new, sync inbox adopt → push renamed it and the node using it kept its binding, a token removed from the config was deleted and Paper inlined its value in the node using it, and a push with no change made 1 call.
  • Reviewed on two axes (standards, spec) twice: 5 findings on the first version and 12 on the provider-neutral version, all fixed, each with a test shown to fail without its fix.

Not in this pull request

  • sync rename (rename a config token without delete + create), sync inbox replace, sync inbox keep.
  • Pushing the computed oklch() of color-mix() and light-dark() tokens: needs the colors module to keep that value on each token.
  • A Figma adapter.

The configuration is the source of truth. `cssforge push` sends the tokens
it generates to a Paper file; what designers create, change or delete there
waits in an inbox until `inbox adopt`, `inbox reject` or `inbox overwrite`
settles it. A three-way plan against a committed base in
.cssforge/sync/<remote>.json decides what to send.

The commands are AcidCat capabilities, so they are also MCP tools of
`cssforge mcp` and typed library calls. Each design tool sits behind a
small adapter; Paper's talks to the MCP server of Paper Desktop
(`paper-design mcp`). Every result reports `callsUsed`, because Paper's
free plan limits MCP calls, and lists the tokens Paper has no place for.

Bumps @acid-cat/core-ts to 0.15.0 for the destructive and idempotent
hints and two-word command aliases.
@changeset-bot

changeset-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5bdf140

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
@hebilicious/cssforge Minor
@hebilicious/cssforge-unplugin Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
cssforge 5bdf140 Commit Preview URL

Branch Preview URL
Nov 19 2026, 03:06 AM

Every sync command already has a path under `sync` from its capability id:
`cssforge sync push`, `cssforge sync inbox adopt`. The top-level aliases
(`push`, `plan`, `inbox`, ...) put them beside `build` and `check`, where
they do not say what they act on.
Prepare token sync for design tools beyond Paper, such as Figma.

- Identity: a remote token has a key (Paper: its name; other tools: an id),
  a label and an optional custom property. The base records each token's
  remote key, operations address the remote by key, and decisions are bound
  to keys, so a renamed or relabelled token keeps its link.
- Options: `sync remote add --options <json>` passes options to the adapter,
  which checks them before any request and resolves the target (file, modes,
  options). Paper takes none.
- Modes: tokens carry a value per mode: `default` at :root, `light` and
  `dark` for values that depend on the color scheme (each with its own
  branch of every light-dark()), and the selector or at-rule of other
  scopes. The target lists the modes it holds; the rest are skipped with
  the mode. Paper holds only `default`.

Scopes are now encoded so that a selector with a `|` stays whole.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant