Phonebook: a Storybook-style preview gallery for SwiftUI and Compose, built for agents

TL;DR I built Phonebook, an open-source CLI and MCP server that turns existing Jetpack Compose @Previews and SwiftUI #Previews into a static, self-hosted HTML gallery.

Think Storybook-style component catalog, but for native mobile previews you already have in your codebase.

No SaaS account.
No extra Storybook files to maintain.
No asking designers to install Xcode, Android Studio, or your debug app just to review a loading state.

You can also see the live gallery or watch the promo video.

The problem

Ok, ok, let's start from the beginning.

Mobile developers actually have pretty good tools for rendering UI in isolation.

If you're building Android with Jetpack Compose, you probably already have something like this:

@Preview(name = "Button/Enabled")
@Composable
private fun PrimaryButtonEnabledPreview() {
    PrimaryButton(
        title = "Continue",
        isEnabled = true,
        onClick = {}
    )
}

@Preview(name = "Button/Disabled")
@Composable
private fun PrimaryButtonDisabledPreview() {
    PrimaryButton(
        title = "Continue",
        isEnabled = false,
        onClick = {}
    )
}

And if you're building iOS with SwiftUI, you probably have something like this:

#Preview("Button/Enabled", traits: .sizeThatFitsLayout) {
    PrimaryButton(title: "Continue", isEnabled: true, action: {})
}

#Preview("Button/Disabled", traits: .sizeThatFitsLayout) {
    PrimaryButton(title: "Continue", isEnabled: false, action: {})
}

This is great when you are the developer sitting inside the IDE.

But then a designer asks:

"Can I see all the button states?"

Or a PM asks:

"What does the empty state look like now?"

Or QA asks:

"Do we have a dark mode version of this?"

And suddenly the preview is not enough.

Because the preview is trapped inside a developer workflow.

The awkward part

On web teams, this problem has a very familiar answer: Storybook.

You put components in stories, publish the Storybook, and now everyone has a place to see buttons, forms, empty states, loading states, weird edge cases, and all the other things that are annoying to reach through the real app.

But native mobile is different.

Brad Frost, who has written a lot about design systems, described the native tooling layer as still being immature and mentioned the recurring question: "is there a Storybook for iOS and Android?"

That question comes up because the pain is real, and you can see the same pattern in public write-ups from teams who already hit it.

The team at rebuy wrote about building their own "Storybook light" for apps after they couldn't find a suitable off-the-shelf tool. Doist wrote about building an automated Android component catalog because their design team had trouble knowing what reusable UI existed and how implementation compared to specs.

Pavel Sharanda's NativeBook took another run at the same idea for iOS: catalog app, previews, snapshot tests, and HTML docs from the same snippets.

So this is not a new problem.

Actually, that is part of why I wanted to build Phonebook.

When enough teams keep building their own internal version of the same thing, there is probably a missing tool hiding there.

What I wanted

I didn't want to invent a new way to describe mobile UI.

Developers already have previews.

They are already close to the production component.
They are already written in the same language as the app.
They already know how to render disabled buttons, error states, empty states, loading states, dark mode, and all the other tiny pieces we keep pretending are "just UI".

So my thought was:

Why not harvest those?

Not write a second Storybook-style codebase.
Not maintain a separate sample app until everyone forgets about it.
Not upload screenshots to some external service and hope the pricing still makes sense next year.

Just take the previews already in the repo and turn them into a static website.

That's Phonebook.

How Phonebook works

Phonebook has two main commands:

phonebook generate
phonebook build

generate renders the native previews and writes a bundle:

phonebook-out/
  manifest.json
  images/
    ...

build takes that bundle and writes a static site:

phonebook-out/
  index.html
  manifest.json
  images/
    ...

That's it.

Plain HTML, CSS, JavaScript, and image files.

You can open it from file://.
You can upload it to GitHub Pages.
You can attach it as a CI artifact.
You can put it on S3, Vercel, Netlify, an internal static host, or whatever your company already uses.

Phonebook does not care.

And honestly, that is the point.

Android: Compose previews into a gallery

On Android, Phonebook uses:

• Roborazzi
• ComposablePreviewScanner
• Robolectric/JVM rendering

So it can run on Linux CI without an emulator.

The rough setup looks like this:

// app/build.gradle.kts
plugins {
    id("io.github.takahirom.roborazzi")
}

roborazzi {
    generateComposePreviewRobolectricTests {
        enable = true
        packages = listOf("com.example.app")
    }
}

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")
}

Then add phonebook.config.json:

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

And run:

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

iOS: SwiftUI previews into a gallery

On iOS, Phonebook uses SnapshotPreviews through xcodebuild test.

You add a small XCTest target:

import SnapshottingTests

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

Then add phonebook.config.json next to your .xcodeproj:

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

And run:

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, and there's your gallery.

The naming trick

Phonebook does not require a new annotation.

It reads the preview names and turns them into component / state.

So this:

@Preview(name = "UserCard/Loading")
@Composable
private fun UserCardLoadingPreview() {
    UserCard(isLoading = true)
}

And this:

#Preview("UserCard/Loading", traits: .sizeThatFitsLayout) {
    UserCard(isLoading: true)
}

Both become:

• component: User Card
• state: Loading

If you add:

UserCard/Default
UserCard/Loading
UserCard/Error
UserCard/Dark

Phonebook groups them together as one component card with multiple states.

This sounds small.

But in practice, this is where the value is.

Because people usually don't ask, "Can you render one preview?"

They ask, "Can I see all of it?"

All the buttons.
All the badges.
All the cards.
All the empty states.
All the dark mode states.
All the weird combinations we forget to check until the release is almost out.

The grid is the product.

Why not just use Storybook?

If you are using React Native, Storybook already has native and web options. The React Native Storybook docs explain the tradeoff pretty clearly: native is higher fidelity because it runs in the actual app, while web is easier to publish and share.

But Phonebook is aimed at a different workflow.

It is for native Compose and SwiftUI codebases where the team already uses previews and wants a shareable artifact without creating a parallel story system.

So instead of:

component code
preview code
storybook story code
catalog app code

The goal is:

component code
preview code
generated gallery

Less ceremony.
Less drift.
Less "wait, does anyone still update this?"

Why static?

Because static things are boring in the best way.

They are easy to host.
Easy to archive.
Easy to attach to CI.
Easy to send in Slack.
Easy to open on a designer's machine.
Easy to diff across builds if you want to get fancy later.

There is no Phonebook cloud.
There is no login.
There is no organization setup.
There is no "please ask your admin to approve this workspace integration" moment.

You own the output.

For a lot of mobile teams, this matters.

Not because SaaS is bad.
SaaS is great when you want a service.

But sometimes all you need is an HTML folder with screenshots of your actual components.

The agent part

This is the part I care about more than I expected.

Phonebook is not only a CLI. It also ships an MCP server:

npx @stag-build/phonebook mcp

So a coding agent can help with the workflow inside your actual mobile repo.

For example, you can ask an agent:

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

And the MCP server exposes tools for things like:

• checking setup
• analyzing preview coverage
• getting preview guidance
• running generation
• building the static gallery

The MCP server does not need to be magical.

Actually, I prefer that it isn't.

It should tell the agent what exists, what is missing, what command to run, and what generated successfully. The coding agent can then make the repo changes: add missing previews, fix naming, add the config file, or wire CI.

This feels like the right boundary to me.

Phonebook knows Phonebook.
The agent knows how to edit your repo.

What this looks like in CI

For Android, a GitHub Actions job can run on Ubuntu:

name: phonebook-android
on: [push]

jobs:
  gallery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'

      - uses: gradle/actions/setup-gradle@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npx @stag-build/phonebook generate -C .
      - run: npx @stag-build/phonebook build -C .

      - uses: actions/upload-artifact@v4
        with:
          name: phonebook-site
          path: phonebook-out

For iOS, use a macOS runner because SnapshotPreviews needs a simulator:

name: phonebook-ios
on: [push]

jobs:
  gallery:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4

      - name: Select Xcode
        run: sudo xcode-select -s /Applications/Xcode.app

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npx @stag-build/phonebook generate -C .
      - run: npx @stag-build/phonebook build -C .

      - uses: actions/upload-artifact@v4
        with:
          name: phonebook-site
          path: phonebook-out

You can publish the same static folder to GitHub Pages or any internal host.

Phonebook does not publish anything by itself. It just gives you the artifact.

The thing I don't want Phonebook to become

I don't want this to become another place where teams have to describe the same UI again.

That is how tools rot.

Someone adds a component.
Someone forgets to add the story.
The design system site looks complete, but the app has moved on.
Then everyone stops trusting it.

And once people stop trusting the catalog, it becomes a museum.

Very professional.
Very nicely organized.
Completely useless.

Phonebook's bet is that previews are already close enough to the source of truth that harvesting them is better than asking teams to maintain a second catalog manually.

Will this solve every design-system problem?

Of course not.

It will not replace Figma.
It will not tell you whether the component API is good.
It will not magically clean up years of duplicated buttons.
It will not make naming conventions appear by themselves. Sadly.

But it gives you a real, shareable, desktop-friendly view of the mobile UI that already exists.

And that is a surprisingly big step.

Try it

Install it:

npm install -g @stag-build/phonebook

Or run it without installing:

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

Or add it to your agent as an MCP server:

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

Links:

• GitHub: https://github.com/stag-build/phonebook
• npm: https://www.npmjs.com/package/@stag-build/phonebook
• Live gallery: https://stag-build.github.io/phonebook/
• Promo video: https://youtu.be/trHbUaG784w

If you have a real Android or iOS repo with previews already in it, try generating a gallery from that repo and open the result with someone who does not live inside your IDE.

That's the test I care about.