@cs4alhaider/screenbook

A design workspace for AI agents to present to humans — fully offline, agent-agnostic, and owned by you.

ScreenBook turns a folder on your machine into the design workspace your AI agents work in: every screen of your product rendered inside real device frames — iPhone, Android, browser — with live mock data, dark mode, right-to-left languages, guided demo walkthroughs, and a built-in design-review workflow. AI agents build and revise the screens through a standard interface; you and your stakeholders review, comment, and approve. When a screen is final, you hand that same file to your agent and say: now build the native version.

npm install -g @cs4alhaider/screenbook

Why I built this

I design and ship products with AI agents every day. The prototyping phase kept failing me in the same way: designs lived inside chat windows. A concept would look great in a conversation, and then reality arrived — I needed forty screens, not one. I needed to see the empty state and the busy state. I needed Arabic right-to-left and dark mode. I needed my co-founder to point at a button and say "this one, move it." I needed all of it next week, again, revised.

Chat canvases aren't built for that. Every iteration re-generates a wall of code inside a conversation that will eventually scroll away. Nothing is versioned. Nothing runs offline. Reviews happen in screenshots over WhatsApp. And when the design is finally "done," it's trapped — there's no clean way to hand it to the next stage of work.

So I built the thing I needed: a studio where screens are plain files on my disk, agents do the labor, humans do the taste, and the finished prototype becomes the specification for the real app.

Why not just design in Claude?

Keep using Claude — that's the point. ScreenBook isn't a competitor to your AI; it's the workspace your AI works in. The difference is where the output lives and what you can do with it:

Designing in a chat window	Designing in ScreenBook
One artifact per conversation; multi-screen products fall apart	A whole product: features → screens, organized like your app actually is
Output trapped in the thread; gone when context resets	Plain HTML + JSON files in your git repo — diff, branch, revert, forever
Needs the vendor's website, account, and connection	Runs from a folder on your machine — works fully offline
Tied to one AI vendor's canvas	Any agent that speaks MCP (Claude Code today; the protocol is open) — or no agent at all, it's just files
One rendering, usually desktop-ish	Real device frames: iPhone, Android, browser — plus dark/light, LTR/RTL, and named data states you switch live
"Looks right" is the only test	A machine gate: every screen must render in every theme × mode × direction with zero console errors
Feedback = screenshots and paragraphs	Pin comments on the screen itself; your agent reads them, fixes, and marks them resolved
Regenerates everything each round	Agent edits one small file per screen — faster, cheaper, and nothing else breaks

What working in it feels like

A concrete example — a specialty-coffee ordering app (it ships in examples/qahwa, so you can open exactly this):

1. You brief your agent, it builds screens.

"Create an ordering feature: menu with our drinks from the seed data, a drink detail screen with a size/milk customization sheet, a cart, and a live order-status screen. iPhone frames, match our warm theme."

The agent creates each screen as its own small HTML file. They appear in your studio's sidebar as they land — framed in an iPhone, styled by your design tokens, wired to your mock data.

2. You review like it's a real app. Click through the flow. Flip the scenario dropdown from Regular morning to First visit — the same screens now show the empty state honestly. Toggle dark mode. Switch to Arabic and watch the layout mirror right-to-left. Nothing is staged; the "order ready by 08:44" timestamp is computed from today every time you demo.

3. Your team comments on the pixels, not around them. Turn on Review Mode and click anywhere: each pin captures the screen, the data state, the theme, the mode, the direction, and the exact element under the cursor. Then:

"Read the open review comments, apply the fixes, and resolve them."

Your agent does exactly that — it has tools for reading pins and marking them resolved.

4. The finished screen becomes the spec for the real app. This is the step that pays for everything. When a screen survives review, it's a complete, self-contained HTML file: exact layout and spacing, your design tokens, final copy in both languages, all interaction states. Now point your agent at it:

"Take features/order/screens/030-cart.html and build it as a SwiftUI view. Use our design tokens for colors and spacing. Preserve the empty state exactly as the first-visit scenario shows it."

The prototype you approved is the design document — no Figma-to-code guesswork, no "it looked different in the mockup." The same works for Jetpack Compose, React Native, Flutter, or web components.

Two commands to your own studio

Requirements: Node ≥ 18. Nothing else — no cloning, no per-project installs. (The automated screen checks use your installed Chrome, or download a headless browser once by themselves.)

npm install -g @cs4alhaider/screenbook    # once, ever

cd any-project-you-are-working-on
screenbook init                           # creates .screenbook/ — that's the whole setup
screenbook serve                          # → http://127.0.0.1:4600 — live reload, no cache headaches

init creates a single .screenbook/ folder in your project — the self-contained source of truth for the prototype: your brief.md (requirements — agents read it first), screens, mock data, scenarios, themes, review comments, and the agent authoring contract. Commit it or gitignore it; that's your call. The studio itself always runs from the installed package — your project never carries runtime code.

Connect your agent (Claude Code shown; any MCP client works):

claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .

Want to explore first? Complete demo projects ship inside the package:

screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/qahwa"       # ☕ iPhone + Android + web
screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/tokens-lab"  # 🎨 two themes, edited live

What's in the box

• Device frames — iPhone (Dynamic Island, status bar), Android (punch-hole), browser chrome, or bare; scaled to fit, screenshot-ready.

• Data scenarios — named states over your mock data (brand-new user, mid-trip, after close) with date tokens like {{today+3}}, so time-based demos are always true.

• Theme Lab — every design token visible and editable live against your screens; save writes the JSON back to disk. Dark mode is a delta, not a fork.

  

• Flows — guided, captioned walkthroughs for stakeholder demos; every step is a shareable URL that opens in the exact state (screen, data, theme, direction).

• Review Mode — pinned comments with full context, synced to a JSON file your agent reads and resolves.

• Multilingual by design — per-feature strings files with side-by-side translations; right-to-left is a first-class toggle, not an afterthought.

• Embed existing prototypes — already have a working single-page prototype? One command mounts the whole app inside the studio without touching its files (screenbook app add legacy/index.html) — see App mode.

• A machine-verified quality gate — screenbook validate renders every screen in every theme × light/dark × LTR/RTL and fails on any console error. Green means done — for humans and agents alike.

• CLI + 18 agent tools — everything above is scriptable and agent-operable: create screens, update data, restyle themes, take device-framed screenshots, run the gate.

Full guides: docs/ — getting started, the studio tour, the authoring contract, CLI and agent references, troubleshooting — or browse them on the website: cs4alhaider.github.io/screenbook.

The shape of a project

my-product/                          ← your real project, any stack, untouched
└── .screenbook/                     ← everything ScreenBook, in one folder
    ├── brief.md                     your requirements — agents read this FIRST
    ├── app.config.json              product name · features · devices · themes · languages
    ├── CLAUDE.md                    the authoring contract agents follow
    ├── themes/default.json          design tokens (light + dark)
    ├── features/
    │   └── order/
    │       ├── feature.json         title, icon, order
    │       ├── flows.json           demo walkthroughs
    │       ├── i18n.json            strings, side-by-side languages
    │       ├── data/seed.json       mock data
    │       ├── data/scenarios.json  named data states
    │       └── screens/
    │           ├── 010-menu.html    ← one file = one screen
    │           └── 020-drink.html
    └── review/comments.json         pinned feedback, read by your agent

Everything is a plain file an intern could read. That's the whole trick: it's why agents stay fast and cheap (they touch one small file at a time), why git can review every change, why it works on a plane, and why the approved prototype can walk straight into production.

Status & license

v0.2.0 — studio, frames, scenarios, themes, flows, review, i18n, app mode, self-test gate, CLI, MCP server, docs, and a 64-test suite; built and verified end-to-end with AI agents, reviewed by a human with taste. MIT Abdullah Alhaider.