Development Journey — “Aurelian”, a luxury watch landing page built through the Paper MCP

One session. A design tool driven entirely through a text protocol, a landing page that did not exist three hours earlier, and two production colours that had to change because the numbers said so.

Date

2026-08-20, 13:49–17:08 UTC (3 h 18 m)

Deliverable

Paper file 01M0FVWK97JZM17HW5VS9ZEQ4H — “Aurelian — Watch Landing”
app.paper.design/file/01M0FVWK97JZM17HW5VS9ZEQ4H

On disk

aurelian-design-system/ in this repository — DESIGN-SYSTEM.md (290 lines), theme.css (86 lines), style-guide.html (895 lines)

First typed prompt

“is the paper mcp connected ?”

The real brief

“i want to create a new landing page in the style of https://us.louisvuitton.com/ but for an expensive watch like Rolex. can it be done in Paper ?”

Model

claude-opus-5

01The brief — what was actually being asked

Three slash commands came before any prose. They are part of the story, because they are the reason the session could happen at all:

The /exit matters. A newly installed plugin’s MCP server is not live in the session that installed it. The restart is the load-bearing step, and it is the kind of thing nobody writes down.

Then the first typed prompt: “is the paper mcp connected ?” — a question, answered with a live call rather than an assertion. list_files({limit:5}) came back with a real team and real open files, and the answer was “Yes — proof: a live call returned your team […] and 2 open files […]”.

The second prompt asked what the MCP could do. The third was the actual brief, and it was phrased as a question — “can it be done in Paper?”. That phrasing is a fork. It can be read as “tell me whether this is feasible” or as “do it”. It was read as do it, and the reading was stated out loud in one line before any tool call: “Yes. Reading ‘I want to create’ as the go — building now.” Saying the interpretation aloud is what makes an aggressive reading safe; if it had been wrong, the correction would have cost one message, not three hours.

Invisible constraints the reader cannot see

Four things shaped every line of output and none of them are visible in the artifact:

• ASD-STE100 Simplified Technical English, always on from a global instruction file. Short active sentences, one meaning per word, no idiom. This is why the replies in this session read clipped.
• “Ponytail” mode, full — a session hook that enforces the laziest solution that works: stdlib first, no unrequested abstractions, shortest diff, shortest explanation.
• The Paper MCP guide, ~5,000 tokens, loaded once via get_guide({topic:"paper-mcp-instructions"}) and mandatory before any other Paper tool. It is not advice. It sets hard procedure — see §3.
• An artifact-design skill injected later as a “design lead at a small studio” directive, when the HTML style guide was published.

02Cold start — proving the channel before trusting it

The environment at minute zero: the Paper desktop app already running with files open, the plugin freshly installed, no Paper file for this work, no design system, no git repository in the project folder (there still isn’t one — see §11).

The Paper MCP exposes 40 tools, and in this harness they are deferred: only their names exist until a ToolSearch call fetches the schema. So the session begins with schema fetches, not design work. Six ToolSearch calls happened across the session — each one a moment where a tool was needed and its parameters were not yet known. Batching the obvious set in the first call would have saved four round trips. The rule that fell out: fetch the schema before the first call, not after the error.

The first mutation attempt failed immediately:

Typography lookup requires an open file, not merely an existing one. The working order is create_file → open_file → get_font_family_info. That single error rewrote the opening sequence of every future session.

03Design decisions

The mood was chosen against instinct, because the guide demands it

The Paper guide contains an unusual instruction: post a written design brief to the user before any mutation tool call, list 3–5 candidate moods, and then pick any mood other than your first instinct — “picking at random beats picking by fit here, because first-instinct picks regress to the same few answers.”

The candidates offered were inky, candlelit, mineral, maritime, chapel. Inky black-and-gold is the first instinct for every watch brand alive, so it was dropped on purpose. Mineral won: limestone, weathered slate, oxidized copper. The guide’s own pairing table lists mineral — bone × oxidized copper, and it explicitly warns off “warm off-white × red / orange / terracotta”, the current cliché.

Every colour then had to name a physical referent, which is the guide’s test for whether a palette is real or glued together:

Type: two families, two weights, nothing bold

Four families were checked against the machine before a single character was styled — get_font_family_info({familyNames:["Cormorant Garamond","Inter","EB Garamond","Jost"]}). Cormorant Garamond took display, Jost took the letterspaced caps because it carries the Futura-like geometry that the Louis Vuitton grammar depends on. Inter and EB Garamond lost: Inter is the default of every SaaS page on earth, and two Garamonds in one system is one Garamond too many.

Decisions taken and their rejected alternatives

What was deliberately not built

• Mobile and tablet layouts. Breakpoints exist as tokens — 768 / 1024 / 1440 — but no layout was drawn at any of them. Desktop only.
• Interaction states. No hover, focus, active, or disabled. Focus rings in particular would have to exist before this could ship.
• A component library in Paper. Sections are plain nodes, not reusable components.

04How the conversation with the desktop app actually worked

This is the part that is easy to get wrong from the outside. There is no browser automation here, no screen-scraping, no clicking. The Paper plugin runs a local MCP server that talks to the running desktop app over a private channel. Tool calls arrive in the app and render on the canvas instantly, while the user watches.

The write loop

The primary write tool is write_html. Real HTML with inline styles goes in; Paper converts it to native design nodes and returns their IDs — 1-0, 2L-0, 4R-0. Those IDs are the addresses for every later edit. The loop is:

1. write_html({targetNodeId, mode:"insert-children", html}) — one visual group, never a whole component. The guide is explicit: more than ~15 lines in a call is too much, because “a 60-second wait followed by a fully formed design feels like a black box.”
2. Paper returns the new node IDs.
3. get_screenshot({nodeId}) — the only feedback channel that shows what a human would see.
4. Write a one-line critique against the guide’s six mandatory checkpoints — spacing, typography, contrast, alignment, artboard fit, repetition.
5. Fix with update_styles or a targeted write_html({mode:"replace"}). Never delete and restart.

Eighteen write_html calls, fifteen update_styles, eight screenshots. The critiques were not decorative. Three of them caught real faults:

That last line is the important one. Screenshots verify layout, not language. The trademark problem — the copy still said “Oystersteel”, “Everose”, “Parachrom”, “Calibre 4130”, all real Rolex marks — was invisible to every pixel check and only surfaced on a deliberate read of the text content. It was fixed with set_text_content to “904L steel”, “18ct rose gold”, “silicon hairspring”, “Calibre 8412”.

The six sections, to scale

Verifying the app, not the return value

The user asked “can you control the desktop app and open it form”. open_file had already returned success — but a success return says the message was accepted, not that a window changed. So a windows-desktop skill was invoked, and a PowerShell capture wrote the real screen to a temporary scratchpad file, paper_check.png. The screenshot showed the Paper app with a fourth tab, Aurelian — Watch Landing, active, layer tree open, all six sections listed.

05The crux — “extracting” the design system turned into changing it

The fourth real prompt was “can you extract the ‘Design System’ for this landing page ? ask me if any question”. The word extract implies the system already exists and only needs writing down. It did not survive contact with a calculator.

Because the prompt invited questions, two were asked up front rather than assumed — the single AskUserQuestion call of the session:

The rebind

Tokens were created in four create_tokens calls — colour, then type, then tracking and spacing, then one more added mid-rebind (--color-body-strong: #2A2E2C, because nav links and prices needed more contrast than body copy). Then twelve find_nodes({filters:[{styleValue:"#RRGGBB"}]}) calls swept the design one hex at a time, and each result was rebound with update_styles to var(--color-…). Roughly thirty nodes changed hands from raw hex to token.

The rebind looked like busywork. It was the highest-leverage twenty minutes of the session, and the next paragraph is why.

The contrast audit — where two production colours changed

Rather than write estimated ratios into the spec, the numbers were computed — a short WCAG relative-luminance script run four times in Bash. The estimates were wrong, and three genuine failures fell out:

The accent sits between three constraints that pull in opposite directions: as a link on the light ground it needs 4.5:1, as the backing behind its own button label it needs 4.5:1, and as a block on the dark band it needs 3:1. Lightening it fixes the third and breaks the first two. #476E5D scores 4.75 / 5.00 / 3.06. Almost no other value clears all three. The written system carries the instruction in capitals: do not lighten the accent back.

A screenshot after the rebind confirmed an identical render — proof the 30-node substitution changed nothing visually, which is exactly what a correct rebind should do.

06Tools and features used

112 tool calls in total. 76 of them were Paper MCP calls, using 16 of the 40 available Paper tools.

Paper MCP

Never touched: get_jsx, get_computed_styles, get_selection, get_tree_summary, get_children, get_node_info, get_fill_image, move_nodes, rename_nodes, delete_nodes, create_page, export, export_combined_pdf, and the four comment tools. Nothing was deleted all session — every fault was fixed in place, as the guide requires.

Everything else

No subagents were spawned and no advisor was consulted. All of it ran inline on claude-opus-5. The parallelism that existed was inside single calls — update_styles batching dozens of node IDs, find_nodes returning whole colour cohorts — not across agents.

07What went wrong, and the fixes

Exactly two calls returned a hard error all session. The other failures were self-caught, which is a different and more interesting category.

1 — Font lookup before an open file

Fix: create_file → open_file → retry. Rule: a Paper file must be open, not merely created, before any read tool that touches the machine’s fonts.

2 — Heredoc broke on long Markdown

A cat > file <<'EOF' heredoc carrying a 290-line Markdown document with backticks and apostrophes died on the shell. Fix: the Write tool, immediately, with no second attempt at the heredoc. Rule: long multi-line content goes through a file-write tool, never a shell heredoc, on this setup.

3 — The estimated contrast ratios were wrong

Ratios were about to be written into the spec from judgement. Computing them found --color-muted at 4.3:1 against a 4.5:1 bar — a real defect on the text carrying every reference line and footer link. Fix: #6E6D66 → #67665F, one set_tokens call. Rule: never write a number you did not compute.

4 — Then the accent failed twice more

The same discipline applied to the style guide found the accent failing as a link (3.7:1) and behind its own button label (3.9:1). Fix: #55806E → #476E5D, solved against all three constraints at once rather than patched twice.

5 — Trademarks in the copy

The brief said no trademarks. The generated copy said “Oystersteel”, “Everose”, “Parachrom”, “Calibre 4130” anyway. No screenshot could catch this. Fix: a deliberate read of the text content and one set_text_content sweep. Rule: a constraint about language needs a language check, not a picture check.

6 — The stale window title

Covered in §4. A window title reading "Dashboard" nearly produced the wrong conclusion that the file had not opened. A pixel capture overruled it.

7 — Fragile, and worth naming

• Node IDs are session-local strings like 4R-0, handed back by write_html. They were carried in-context across three hours. A context compaction at the wrong moment would have orphaned them; find_nodes is the recovery path, which is why the handoff records find_nodes({textValue:"AURELIAN"}) as the way back to the wordmark.
• The whole channel depends on the desktop app staying awake. Proven today — see §8.
• Google Fonts availability was confirmed at build time only. Nothing pins the versions.

08Unknown unknowns — what nobody thinks to ask

These are the things that were not on anyone’s list at the start of the session, ranked by how much they would cost a future session that did not know them.

1. A newly installed plugin is not live until the session restarts

/plugin install reported success, and the MCP tools still did not exist until /exit and relaunch. Every “the MCP isn’t connected” report should start here.

2. A success-shaped empty result is not a success

Discovered today, writing this document. An attempt to export the artboard as a PNG returned:

Three times, with three different argument shapes. Then two get_screenshot calls, on the artboard and on the hero, both returned Tool call timed out. The honest reading: metadata calls succeed and render-producing calls do not, right now. What cannot be distinguished from here is whether export is broken, whether it requires nodes pre-marked for export in the file, or whether the desktop app has simply stopped servicing render work since the build session ended. Recording it as “export is broken” would plant a wrong fact for the next session. Recording it as “render calls failed on this date, cause unknown” is what the evidence supports.

3. A screenshot cannot become a file

A related and non-obvious constraint: get_screenshot returns the image into the conversation. There is no path from that to bytes on disk — the image can be looked at, but not saved or re-emitted. Embedding a canvas render in a document therefore requires export producing real files, or an OS-level screen capture. This is why every visual on this page is drawn in CSS from the token values rather than photographed from the canvas.

4. Paper cannot fetch an image from the web

Images enter only as paper-asset:// with an absolute local path — <img src="paper-asset:///C:/full/path/img.png">. No URL fetch, no data URI. This single fact decides whether a photography-led design is possible before a word of it is promised. It is why this landing page is line art.

5. The mandatory guide is a per-session tax

~5,000 tokens, required before any other Paper tool, and it re-enters context on every subsequent turn. On a three-hour session that is the single largest fixed cost after screenshots. Budget for it; do not discover it.

6. Screenshots verify layout, never language

The trademark faults sat in plain sight through eight visual reviews. Any constraint expressed in words — trademarks, legal copy, tone, spelling — needs its own text-level pass.

7. The deliverable lives in the cloud, and the folder has no git

The design itself is not a file on this machine. It is a Paper document, addressed by ID. What is on disk is the system — spec, CSS, style guide — in a folder that is not a git repository, has no remote, and has never been committed. “Durable” here means “the file exists on one disk”. That is the largest unaddressed risk in the whole project, and it is invisible because everything works.

8. A written record can drift from the thing it describes

The handoff document says the file carries 55 design tokens. A live read of the file today counts 54. Nothing depends on the number, and the discrepancy is trivial — which is exactly why it survived. Any figure written once and never re-read is a figure that may already be wrong.

9. The cost shape of a long design session is not what it looks like

See §9. The output was small; the re-reading was enormous.

09Costs, limits, and wall clock

The 32.1 million cache reads are the finding. A design session accumulates two heavy classes of context that never leave: screenshots (eight of them, images, permanently in the conversation) and the mandatory ~5,000-token guide. Every subsequent turn re-reads all of it. Output tokens are a rounding error against that.

A cost hook fired mid-session at roughly 154,000 context tokens:

It was followed. The session ended with a handoff document rather than by running on. No API quota, rate limit, or plan ceiling was hit — the only limit that bound anything was context economics.

10Verification

Every claim below was checked by observing an effect, not by reading a success return.

Not verified

• Rendering at any width other than 1440 px. No mobile or tablet artboard exists, so there is nothing to check.
• The Tailwind theme inside a real build. theme.css was exported from Paper and never dropped into a Next.js or Vite project. It is untested code.
• Colour on a calibrated display. All contrast work is sRGB arithmetic, which is the right standard, but no physical check was made.
• The published style guide’s current state. It was published once and not re-fetched.

11Where things stand

Done and verified

• The Paper file — app.paper.design/file/01M0FVWK97JZM17HW5VS9ZEQ4H — one artboard, six sections, 165 nodes, 54 tokens, every layer bound to a token except three documented raw-hex exceptions.
• The design system on disk, in three forms: DESIGN-SYSTEM.md (9 sections), theme.css (Tailwind v4 @theme), style-guide.html — rendered in the system it documents.
• A published private style-guide page.
• HANDOFF.md at the project root, and one durable memory file recording the four Paper MCP constraints.

Open, in the order they were discussed

1. Real photography. Blocked only by the local-path rule: generate images locally, then reference them as paper-asset:///absolute/path.png.
2. Mobile and tablet artboards. Breakpoint tokens exist; no layout has been drawn at any of them.
3. Interaction states. Hover, focus, active, disabled — focus rings before anything ships.
4. Put the folder under git. Not discussed in the session, and the largest real risk. One git init and a remote.

Deliberately outside this document

The folder also holds aurelian-motion-concepts_codex.html, a 49 KB motion-concept document that reuses the Aurelian token values but was written by a different tool, outside any transcript covered here; three terminal captures under .ignore/; and README.txt, a set of raw notes about an unrelated and unstarted “Conductor Roadmap” component. None of them are part of this session and none are described above.

Rules this session earned

• Probe the pixels; a window title is a cache, not a fact.
• Never write a number you did not compute.
• A constraint about language needs a language check, not a picture check.
• Bind to tokens early — it turns a thirty-node sweep into a one-value fix.
• Fetch the tool schema before the first call, not after the error.
• State an aggressive reading of an ambiguous prompt out loud, in one line, before acting on it.

Written 2026-08-20 from the session transcript, with the Paper file re-read live the same day. Home paths, account name, team name, and unrelated file names redacted; all technical identifiers verbatim.