Getting started

Prerequisites

You need	For	Notes
Node.js ≥ 20	the CLI, the dev server, the MCP server	the only hard requirement — check with `node --version`
A modern browser	the studio itself	Chrome, Safari, Edge, Firefox — the viewer is plain ES modules, no build
Google Chrome installed	`validate` and `screenshot` (headless checks)	used through `playwright-core`; see below if you don't have Chrome
Git	recommended	ScreenBook writes plain files — git is your undo and your review tool

Nothing else. No bundler, no framework, no build step. The studio itself has zero dependencies; the CLI carries exactly one (playwright-core), used only for headless validation and screenshots — it comes along automatically with the install below. On a machine without Chrome, the first validate downloads a headless browser once, by itself.

Install

One command, once, globally:

bash

npm install -g @cs4alhaider/screenbook

That's the entire install — no cloning, nothing copied into your projects. (Prefer no global installs? npx -y @cs4alhaider/screenbook <cmd> works everywhere screenbook appears below.)

Your first project — five minutes

Go to any project you're working on — an iOS app, a web app, an empty folder — and:

bash

screenbook init --name "My product"
screenbook serve
# → open http://127.0.0.1:4600

init creates one folder, .screenbook/ — the self-contained source of truth for your prototype. Commit it or add it to .gitignore; your call.

.screenbook/
  brief.md                    ← WRITE YOUR REQUIREMENTS HERE — agents read this first
  app.config.json             project name · feature order · devices · themes · languages
  CLAUDE.md                   the authoring contract (for you AND your AI agents)
  themes/default.json         design tokens (light + dark) — edit live in the 🎨 Theme Lab
  features/welcome/           one starter feature with one screen
    feature.json · flows.json · data/seed.json · data/scenarios.json
    screens/010-hello.html    ← copy this file to make your second screen
  review/comments.json        review pins land here
.claude/skills/screenbook/    packaged skill so Claude knows the rules instantly

The studio runtime always comes from the installed package — screenbook serve mounts it at /screenbook/ automatically, and screens reference it as ../../../screenbook/bridge.js.

Edit features/welcome/screens/010-hello.html, save — the browser reloads itself. Copy it to 020-something.html, change the meta block's title/order, save — it's in the sidebar. That's the whole loop.

Already have a single-page prototype? Embed it whole instead of rewriting:

bash

screenbook init . --app path/to/index.html

(see App mode).

The definition of done

bash

screenbook validate

Green means: every screen renders in every theme × light/dark × LTR/RTL with zero console errors, all metadata is present, every navigation target exists. Make it your habit — it's the same gate AI agents are held to.

Offline & prerequisites for the checks

Everything runs on your machine — after the one npm install, ScreenBook needs no network at all. The automated checks (screenbook validate, screenshot) drive your installed Google Chrome; on a machine without Chrome they download a headless browser once (~120MB), automatically. Nobody is ever asked to install anything by hand.