Documentation

How to use ATLAS scenarios, components, and templates in your projects.

What is ATLAS?

ATLAS is a reference collection of real-world admin and SaaS UI scenarios — the screens that every product needs but nobody wants to build twice. Empty states, error pages, destructive confirmations, account edge cases, loading patterns.

It also includes a component library and full page templates, but the core value is the scenarios. Each one includes a realistic UI, production-quality microcopy, and an explanation of when and why to use it.

There is no CLI or package to install. Browse, copy the code, paste it into your project.

Prerequisites

  • Next.js 14+ with App Router
  • TypeScript
  • Tailwind CSS v4
  • lucide-react (for icons)

How to use scenarios

Each scenario page contains multiple real-world situations. Every scenario has three parts:

Visual preview

A realistic UI showing exactly what the user would see. Not a wireframe — a production-ready screen with real text and proper styling.

When to use

A short explanation of the exact conditions that trigger this scenario, and design decisions behind the approach. The amber box below each preview.

Copy-ready code

Click "Copy this scenario" to reveal the full TSX code. Copy it, adjust the text and data to match your product, and ship it.

How to use components

The component library provides building blocks used across the scenarios. Each component has a "View code" button that reveals the full source.

tsx
import { Button } from "@/components/ui/button";
import { DataTable } from "@/components/ui/data-table";
import { PageHeader } from "@/components/ui/page-header";

export default function MyPage() {
  return (
    <div className="p-6">
      <PageHeader title="Users" description="Manage team members." />
      <Button>Add user</Button>
    </div>
  );
}

Recommended folder structure

Keep UI primitives in components/ui/. Drop scenario code directly into your app routes or extract reusable patterns into shared components.

text
src/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── dashboard/
│   │   └── page.tsx
│   └── settings/
│       └── page.tsx
├── components/
│   ├── ui/
│   │   ├── button.tsx
│   │   ├── input.tsx
│   │   ├── badge.tsx
│   │   ├── modal.tsx
│   │   ├── toast.tsx
│   │   ├── data-table.tsx
│   │   ├── empty-state.tsx
│   │   ├── page-header.tsx
│   │   └── index.ts
│   ├── states/
│   │   ├── trial-expired.tsx
│   │   ├── permission-denied.tsx
│   │   ├── data-load-error.tsx
│   │   └── page-skeleton.tsx
│   └── shell/
│       ├── app-shell.tsx
│       └── app-sidebar.tsx
└── lib/
    └── utils.ts

Styling and customization

ATLAS uses Tailwind CSS v4 with a custom theme defined in globals.css. All design tokens are CSS custom properties.

css
@theme inline {
  --color-background: #ffffff;
  --color-foreground: #0f172a;
  --color-muted: #64748b;
  --color-border: #e2e8f0;
  --color-surface: #f8fafc;
  --color-primary: #0f172a;
  --color-primary-foreground: #ffffff;
  --color-danger: #dc2626;
  --color-success: #16a34a;
  --color-warning: #d97706;
}

Adapting microcopy

Every scenario includes realistic text. Replace product names, plan names, dates, and specific details to match your product. The structure and tone are designed to be reusable as-is.

Changing colors

Update --color-primary in your CSS to change the accent color. Scenario code uses Tailwind's built-in color palette (slate, red, amber, emerald) for semantic meaning.

Dark mode

ATLAS ships in light mode. Add dark mode by wrapping theme variables in a prefers-color-scheme media query or using Tailwind's class-based strategy.

Scenario coverage

ATLAS currently covers these categories:

Empty States

First-time user, empty search, empty team, empty notifications, empty billing, empty activity log, empty file uploads.

Error States

Failed data load, permission denied, network offline, rate limited, resource not found, form submission error, action blocked by policy.

Account States

Trial expired, account suspended, read-only mode, feature locked after downgrade, email verification pending, payment grace period.

Destructive Flows

Delete account, remove team member, revoke API key, cancel subscription, bulk delete with mixed ownership, leave workspace.

Loading & Fallback

Page skeletons, table skeletons, button loading states, partial page failure, stale data indicator, optimistic update with undo, long-running operations.

Design principles

  • Never show a blank screen. If there's no data, explain why and what to do next.
  • Destructive actions need friction — but not so much that users can't get things done.
  • Error messages should explain what happened, why, and what the user can do about it.
  • Account state screens are the highest-stakes UI in your product. Treat them that way.
  • Loading states should match the layout of what's coming. Spinners are lazy.