Phonebook

A self-hosted, open-source alternative to Emerge Tools Snapshots: harvest your existing Compose @Previews and SwiftUI #Previews into a browsable, static HTML gallery — no SaaS account required.

Phonebook turns screenshots your team already has into a Storybook-style component gallery. No new test code, no design tokens to maintain by hand — it renders what's already in your codebase into a static site designers can open without installing anything. Each repo runs Phonebook independently; v1 is single-platform, so one Android repo (or one iOS repo) produces one bundle and one site.

Features

• Zero new test code — reuses @Preview / #Preview you've already written
• No SaaS account — self-hosted, runs entirely in your CI or locally
• MCP-first — a coding agent can check setup, analyze coverage, add missing previews, and build the gallery for you
• Smart component grouping — component / state cards inferred from preview names, no required annotation
• Cross-platform — Android (Roborazzi + ComposablePreviewScanner, runs on the JVM, no emulator) and iOS (SnapshotPreviews, runs on a simulator)
• Version-aware setup — init/doctor resolve library versions against your project's Kotlin version and catch Kotlin/Roborazzi metadata mismatches before they cause opaque compiler crashes

Demo

A gallery generated from samples/ios — component / state cards grouped from the app's own #Previews, no extra annotation.

Browse the live gallery →

How it works

1. phonebook generate runs your platform's preview-rendering engine and harvests the output into a bundle (manifest.json + images/).
   • Android: Roborazzi + ComposablePreviewScanner, run on the JVM via Robolectric. No emulator, works on Linux CI.
   • iOS: SnapshotPreviews, run via xcodebuild test on a simulator. Requires macOS.
2. phonebook build turns that bundle into a static site — by default it writes index.html directly into the bundle directory (reusing the images already there, no copying), so the site lands at <bundle>/index.html. Pass -o <dir> to instead copy everything into a standalone site directory (for publishing elsewhere, or later merging multiple bundles). Plain HTML/CSS/JS, works from file:// or any static host.

Installation

npm install -g @stag-build/phonebook

brew install stag-build/phonebook/phonebook

brew tap stag-build/phonebook
brew install phonebook

npx @stag-build/phonebook <cmd>

Using it with a coding agent (recommended)

Most people won't run the CLI directly — Phonebook is built to be driven by a coding agent (Claude Code, Codex, etc.) through its MCP server. The agent adds previews, runs setup checks, and generates the gallery for you; the CLI underneath is the engine it calls.

The server runs via npx @stag-build/phonebook mcp — no install step needed. Pick your client below.

claude mcp add phonebook -- npx -y @stag-build/phonebook mcp

[mcp_servers.phonebook]
command = "npx"
args = ["-y", "@stag-build/phonebook", "mcp"]

{
  "mcpServers": {
    "phonebook": {
      "command": "npx",
      "args": ["-y", "@stag-build/phonebook", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "phonebook": {
      "command": "npx",
      "args": ["-y", "@stag-build/phonebook", "mcp"]
    }
  }
}

[mcp_servers.phonebook]
command = "/bin/zsh"
args = [
  "-lc",
  "PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; npx -y @stag-build/phonebook mcp"
]
enabled = true

{
  "mcpServers": {
    "phonebook": {
      "command": "/bin/zsh",
      "args": [
        "-lc",
        "PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; npx -y @stag-build/phonebook mcp"
      ]
    }
  }
}

Android Studio (Gemini Agent Mode): not supported yet — its MCP integration only connects to remote httpUrl servers, not local stdio processes like Phonebook's. Use one of the terminal-based clients above (Claude Code, Codex CLI) from the Android repo instead.

Then, from a chat in your Android or iOS repo, just ask:

"Use the phonebook MCP and create a catalog for my designer."

The agent figures out the rest — checking setup, filling in missing previews, generating, and building the site. For more targeted asks, it also exposes: check_setup (setup diagnosis, same as phonebook doctor), analyze_coverage (components missing previews or dark variants), get_preview_guidance, run_generate, and run_build.

Quickstart: Android

Run phonebook init first — it detects your project's Kotlin version and prints these instructions with library versions resolved to be compatible with it (e.g. Kotlin 2.0 projects get Roborazzi 1.60.0; Kotlin 2.2+ gets the latest). The versions below are what a current-Kotlin project gets (see samples/android/app/build.gradle.kts for a full working example):

// app/build.gradle.kts
plugins {
    id("io.github.takahirom.roborazzi") // root build.gradle.kts: version "1.72.0" apply false
}

roborazzi {
    generateComposePreviewRobolectricTests {
        enable = true
        packages = listOf("dev.stag.phonebook.sample") // your app's package
    }
}

dependencies {
    testImplementation("org.robolectric:robolectric:4.14.1")
    testImplementation("io.github.takahirom.roborazzi:roborazzi:1.72.0")
    testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:1.72.0")
    testImplementation("io.github.sergio-sastre.ComposablePreviewScanner:android:0.9.3")
    testImplementation("io.github.takahirom.roborazzi:roborazzi-compose-preview-scanner-support:1.72.0")
    testImplementation("androidx.compose.ui:ui-test-junit4") // version from your Compose BOM, or pin one
}

Add a phonebook.config.json next to settings.gradle.kts:

{
  "appName": "My Android App",
  "platform": "android",
  "android": { "modules": [":app"], "variant": "debug" }
}

Then, from the repo containing Phonebook:

npx @stag-build/phonebook generate -C /path/to/your/android/repo
npx @stag-build/phonebook build -C /path/to/your/android/repo

Open phonebook-out/index.html.

Quickstart: iOS

Add the SnapshotPreviews SPM package to your project and a small XCTest target that subclasses SnapshotTest (see samples/ios for a full working example):

// PhonebookSnapshotTests.swift
import SnapshottingTests

final class PhonebookSnapshotTests: SnapshotTest {
    override class func snapshotPreviews() -> [String]? {
        return nil // record every #Preview
    }
}

Add phonebook.config.json next to your .xcodeproj:

{
  "appName": "My iOS App",
  "platform": "ios",
  "ios": {
    "project": "MyApp.xcodeproj",
    "scheme": "MyApp",
    "simulator": "iPhone 17 Pro"
  }
}

Your scheme must build and test the snapshot test target (see PhonebookSample.xcscheme in the sample). Then:

npx @stag-build/phonebook generate -C /path/to/your/ios/repo
npx @stag-build/phonebook build -C /path/to/your/ios/repo

Open phonebook-out/index.html.

Naming convention

Phonebook groups screenshots into component / state cards from your existing preview names — no required annotation. See docs/naming-convention.md for the full rules and examples.

Configuration

phonebook.config.json: