A Claude Code agent that designs in Paper, and the rules behind it.
It reads a design file, builds and edits screens, binds values to tokens, audits for drift, and refuses to do the specific things that have broken files before.
Every rule in it exists because a mistake cost a broken file or a lost afternoon. That is the actual point of this repo. The agent is a delivery mechanism for the rules.
Requires Claude Code and the Paper MCP server.
git clone https://github.com/dsaltaren/paper-agent-rules
cp paper-agent-rules/agents/paper-designer.md ~/.claude/agents/Open the file and fill in four settings at the top:
| Setting | What it controls |
|---|---|
ICON_SET |
Your icon library. The rule is never to draw paths by hand. |
TYPE_WEIGHT |
The weight allowed on the base family. |
SOURCE_OF_TRUTH |
Where token values are edited (Paper consumes, never patches). |
TOKEN_PREFIX |
Your naming convention, so sizes pair with line heights. |
Everything else is method and works as-is. config.example.md has a
filled-in set and the reasoning behind the token pairing convention.
Invoke it with "paper designer", by sharing an app.paper.design URL, or let it trigger when
you work in a Paper file.
Each one is here because of something specific that went wrong.
Invented glyphs shipped twice. A path written from memory has the right silhouette and the wrong geometry: the curve is off, the stroke does not align to the grid. Fine at a glance, visibly wrong at 2x or next to a real icon.
Clone the icon node already in the file, or paste the real markup. If you cannot get the true source, ask instead of approximating.
Writing fontFamily and fontWeight onto a text node silently drops its letterSpacing.
The tracking is invisible in a 1x screenshot, so it disappears and nobody notices for weeks.
Read the node first. Carry every property you are not deliberately changing.
Duplicate first, edit the copy, and only touch ids from the duplication map. Originals surviving a session untouched is a success metric, not a nicety.
Node id prefixes do not track artboard membership, and scoping by parent is unreliable. Sample
with get_node_info before applying to many nodes, or you will edit the wrong screen with
complete confidence. I have done this.
Read the token set before creating anything. If a value already has a token, bind to it under its existing name, even if you would have named it differently.
Creating --color-surface-1 next to an existing --color-background-raised gives you two
names for one decision, and the file silently splits in two. Everything looks correct and
nothing is connected.
Only create a token when the value genuinely has no home in the set, and say so when you do.
A bound size next to a literal leading looks correct in the file and is broken in the system: change the type scale and the leading stays put, so every text block drifts.
"Everything at 16px" is not a role. Nav labels, body copy and a card subtitle can share a size and still want different treatment. A find-and-replace across a size bucket produces a file that validates and reads wrong.
Fix it in the same pass without asking. Do not report it as "pending a decision": there is no decision, the library defines the weight. This rule exists because the problem was spotted, correctly identified, and then left in place.
A write that "succeeds" without applying means the session is out of sync. The fix is reloading, not a fourth attempt. One manual step beats three automatic retries.
Screenshots are the single largest cost in a Paper session, and the expensive part is not how many you take, it is how big the thing you capture is.
| What you capture | Average |
|---|---|
| Full artboard | 400-614 KB |
| A section | ~80 KB |
| A single card | 35 KB |
Verify values by reading them (get_computed_styles, ~900 B) rather than looking at them
(get_screenshot, ~112 KB). A screenshot cannot tell you a hex is exactly #2C2C2C.
Pictures are for judgement a number cannot give you: composition, hierarchy, legibility.
I measured this across 853 sessions and got it wrong twice before landing on the rule.
The numbers and the wrong turns are in MEASURING.md.
UI copy names the thing and says what it does. Cut every clause after a comma that adds no information. Headings are the action the user is taking, not a slogan about the product.
The trap is over-cutting: trimming the tail is right, deleting the whole explanation leaves bare labels that teach nothing.
Full list with the reasoning in agents/paper-designer.md.
This comes from one design system, one product, one way of working. That is its main limitation, and I would rather find out where it breaks than assume it generalises.
Genuine questions:
-
Does the single-weight rule survive a system with several weights? My hierarchy rule leans on size and colour because the library defines one weight. I do not know whether the underlying idea — that weight is a fragile hierarchy tool — holds elsewhere.
-
Has anyone found a way to verify layout without images? Computed styles cover values. Composition and legibility still need eyes, and eyes are expensive. This feels unsolved rather than solved-and-I-am-missing-it.
-
What rule is missing? The ones here map exactly to my own mistakes. Yours will be different.
If a rule here is wrong for your system, or one is missing, open a PR or an issue.
One format request: submit rules as the rule plus the failure that caused it.
Rule: Never X.
Because: Y happened, and it cost Z.
A rule without its reason gets ignored the first time it is inconvenient. A rule with a scar
attached survives. See CONTRIBUTING.md.
I design MITO, an AI video tool. These rules come from building its design system in Paper — which is also why they are opinionated in the places they are.
MIT licensed. Use it, fork it, tell me what broke.