A static visual index for SwiftUI/UIKit previews, preview captures, and swift-snapshot-testing reference images.

UIAtlas turns existing visual artifacts into a searchable HTML gallery for design-system documentation, PR reviews, CI reporting, and stakeholder review. It is not a snapshot testing library or a live component workbench; it sits on top of the preview or snapshot workflow you already have.

Why

Teams accumulate dozens or hundreds of visual states, but they live scattered across test folders, source files, and CI artifacts. UIAtlas gives those states one browsable home with search, filters, ownership metadata, coverage and PR-friendly diff output.

Where It Fits

Use UIAtlas when your SwiftUI/UIKit app already has visual states captured as preview screenshots or snapshot-test reference images, and you want a static HTML report that engineers, QA, UX, product, and marketing can open without running Xcode, a simulator or a separate catalog app.

UIAtlas is snapshot-first: it reflects the UI artifacts your app already generates. It does not ask teams to maintain a parallel set of hand-authored component stories before they can browse, review or share the current app UI.

Supported

Source	Status	Notes
SwiftUI preview captures	Supported	Import rendered #Preview screenshots from your own capture pipeline.
swift-snapshot-testing __Snapshots__	Supported	Import existing reference PNGs directly from snapshot test folders.
Hand-authored manifests	Supported	Describe any image set with uiatlas.json when you need full control.
Jetpack Compose previews	Upcoming	Planned for teams that want the same static visual index for Android UI.

What It Generates

UIAtlas writes a static, searchable report with coverage, filters and a component gallery.

Open any component to inspect every captured variant across devices, color schemes, dynamic type sizes and accessibility states.

Features

• Searchable component gallery grouped by module
• Detail view for every device, color scheme, dynamic type and accessibility variant
• Direct import of swift-snapshot-testing __Snapshots__ folders
• Source scanning for SwiftUI preview coverage
• App icon branding and derived accent colors
• Missing image diagnostics in the generated report
• Markdown/JSON diff summaries for PRs
• Static HTML output that works from disk or CI artifacts

Install

UIAtlas is a Swift Package targeting macOS 14+.

git clone https://github.com/crleonard/UIAtlas.git
cd UIAtlas
swift build -c release

The executable is produced at .build/release/uiatlas. During development, run commands with swift run uiatlas ....

Quick Start

From the root of your app repository, pick the source you already have.

Existing __Snapshots__ references from swift-snapshot-testing:

uiatlas report \
  --snapshots ./MyAppTests/__Snapshots__ \
  --source-root ./MyApp \
  --project-name MyApp \
  --output UIAtlas \
  --force

Rendered preview captures:

uiatlas report \
  --source-root ./MyApp \
  --screenshots ./PreviewScreenshots \
  --project-name MyApp \
  --output UIAtlas \
  --force

Open the report:

open UIAtlas/index.html

Share the report:

uiatlas archive \
  --report UIAtlas \
  --output UIAtlas.zip \
  --force

Guides

• Quickstart
• Preview capture
• swift-snapshot-testing
• CI
• Compatibility

Examples

Runnable fixtures live under Examples/:

• Examples/PreviewFixture shows rendered SwiftUI preview capture import.
• Examples/SnapshotTestingFixture shows direct __Snapshots__ import.
• Examples/BasicManifest shows a hand-authored manifest.

Generate the preview capture PNGs with:

swiftc \
  Examples/PreviewFixture/render_previews.swift \
  Examples/PreviewFixture/MyApp/DashboardView.swift \
  Examples/PreviewFixture/MyApp/SettingsView.swift \
  -o /tmp/render-previews
/tmp/render-previews Examples/PreviewFixture/PreviewScreenshots

Generate the snapshot reference PNGs with:

python3 Examples/make_fixture_images.py

Core Commands

Command	Purpose
uiatlas report	Primary one-step report command for preview captures or __Snapshots__.
uiatlas archive	Package a generated report as a zip artifact.
uiatlas validate	Validate manifest structure and referenced image files.
uiatlas ci	Generate a report and enforce CI gates.
uiatlas import	Lower-level manifest generation.
uiatlas generate	Lower-level static site generation from a manifest.
uiatlas coverage	Report SwiftUI preview coverage.
uiatlas diff	Compare two manifests and print preview changes.
uiatlas scaffold-capture	Generate a Swift Testing capture file from #Preview blocks.

Contributing

Issues and pull requests are welcome.

swift build
swift test

Please keep the project useful with existing manifests, preview captures and snapshot references before reaching for deeper Xcode automation.

See CONTRIBUTING.md and SECURITY.md.

License

MIT. See LICENSE.