Repository navigation
feat(sync): sync design tokens with Paper through an inbox - #104
Open
Hebilicious wants to merge 3 commits into
Open
Hebilicious wants to merge 3 commits into
Hebilicious wants to merge 3 commits into
Conversation
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 detectedLatest commit: 5bdf140 The changes in this PR will be included in the next version bump. This PR includes changesets to release 2 packages
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 |
Deploying with
|
| 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two-way token sync between a CSS Forge configuration and a Paper file. The configuration is the source of truth:
pushsends its tokens to the file, and what designers create, change or delete in the file waits in an inbox until a decision settles it.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 undercssforge sync, with MCP hints (sync.pushdestructive,sync.planandsync.inbox.listread-only). They are alsocssforge mcptools 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.tsmaps token kinds to Paper types and talks topaper-design mcpthrough a small MCP stdio client (src/sync/mcp-client.ts, no new dependency).key(Paper: its name; Figma: an id), alabeland 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/darkfor scheme-dependent values, or a selector such as.dark;src/sync/modes.ts), and the target lists the modes it holds. Paper holds onlydefault.src/sync/state.ts:.cssforge/sync/<remote>.json, validated on read; commit it so the team shares the base.listTokens(generator) andlistConfigTokens(forge) reuse the existing resolver andinferValueKind.@acid-cat/core-ts0.13.0 → 0.15.0 (destructive and idempotent hints).tokens.buildis now marked destructive.Tokens Paper has no place for are listed in
skippedwith the reason (and the mode, for a mode Paper does not hold):color-mix()values,light-dark()and scoped tokens (Paper holds only thedefaultmode), thepow()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.tests/fixtures/fake-paper-mcp.ts).sync remote add, push of 4 tokens (Paper storedoklch(100% 0 none)asoklch(100% 0 0)and0.2as0.200; the read-back keeps those from reading as edits), a designer-created token reaching the inbox asnew,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.Not in this pull request
sync rename(rename a config token without delete + create),sync inbox replace,sync inbox keep.oklch()ofcolor-mix()andlight-dark()tokens: needs the colors module to keep that value on each token.