From 6a9f3d93670306e274297413822683bbef0463b2 Mon Sep 17 00:00:00 2001 From: Ben Vinegar Date: Mon, 29 Jun 2026 15:38:50 -0400 Subject: [PATCH] docs: explain the token economics of surfaces in the README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Faster, and fewer tokens" bullet asserted the benefit without saying why. Replace it with the concrete mechanism — a standalone HTML document re-sends its whole design system on every render, while a surface sends only the content and the viewer supplies the chrome — and add a short "Token economics" section with a measured before/after table (output tokens, generate-both-ways). Docs-only; empty changeset (no release). Co-Authored-By: Claude Opus 4.8 --- .changeset/token-economics-readme.md | 2 ++ README.md | 28 +++++++++++++++++++++++++--- 2 files changed, 27 insertions(+), 3 deletions(-) create mode 100644 .changeset/token-economics-readme.md diff --git a/.changeset/token-economics-readme.md b/.changeset/token-economics-readme.md new file mode 100644 index 0000000..a845151 --- /dev/null +++ b/.changeset/token-economics-readme.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/README.md b/README.md index dcacd4a..fd37b91 100644 --- a/README.md +++ b/README.md @@ -31,9 +31,10 @@ works. have to picture in your head. - **Multimodal.** Combine diffs with mermaid diagrams, terminal output with HTML explainers, and more. Combine surfaces to illustrate ideas better. -- **Faster, and fewer tokens.** sideshow surfaces are optimized for LLMs, so the - agent produces higher-fidelity diagrams and visualizations faster and using - fewer tokens. +- **Faster, and fewer tokens.** A standalone HTML document re-sends its whole + design system every time; a surface sends only the content and the viewer + supplies the chrome — far fewer tokens, and a faster draw. See + [Token economics](#token-economics). - **Works with the agent you already use.** Works with any agent harness: Claude Code (desktop or CLI), Codex (desktop or CLI), Opencode, Pi, etc. @@ -125,6 +126,27 @@ viewer. A surface is an ordered list of **parts**; one card can carry several. +## Token economics + +Showing something visually costs tokens — the ones your agent spends _writing_ +it. A standalone HTML document pays for its whole design system (doctype, reset, +palette, typography, component CSS, often a little JS) on every render. A surface +pays for none of it: it hands the content over as data — mermaid source, a JSON +value, a markdown table, a diff patch — and the viewer supplies the theme. Fewer +output tokens also means a faster draw, since a model writes them one at a time. + +Measured both ways on identical content (output tokens): + +| Showing… | Hand-built HTML | sideshow surface | Saved | +| --------------------- | ------------------- | -------------------- | ----- | +| Architecture diagram | hand-drawn SVG | mermaid source | ~90% | +| API response | tree markup + JS | json surface | ~88% | +| Data table | table + CSS | markdown table | ~83% | +| Interactive UI mockup | standalone document | themed html fragment | ~42% | + +Even an HTML surface you author inherits the viewer's theme tokens and +pre-styled controls instead of shipping its own, so it still comes out ahead. + ## Run it anywhere sideshow runs locally as a small Node server, or on Cloudflare Workers when your