Skip to content
Statecraft

All patterns

  • Bulk Actions

    Let users perform one action across many records safely, with clear scope, eligibility and recovery.

    Data

  • Advanced Filters

    Help users narrow large datasets with filters they can see, edit, share and recover from.

    Data

  • Autosave

    Save changes continuously without a Save button, while keeping users certain their work is safe.

    Forms

  • Approval Workflow

    Route a request through one or more reviewers with clear status, accountability and an auditable history.

    Workflow

  • AI Response

    Present generated answers with streaming, sources, control and recovery, so users can trust and verify them.

    AI

  • File Upload

    Let users add files with visible progress, early validation and recovery that never loses what already uploaded.

    Files

  • Command Palette

    Give users one keyboard-first entry point to jump anywhere and run any action without hunting through menus.

    Navigation

  • Subscription Management

    Let customers upgrade, downgrade, change billing cycles and cancel with exact prices, dates and consequences shown before they confirm.

    Payments

  • Refunds

    Let support staff or customers return money with the exact amount, destination, timing and consequences stated before it's irreversible.

    Payments

  • Checkout

    Take a customer from plan choice to paid with the fewest fields, a total that never surprises, and errors that keep what they typed.

    Payments

  • Failed Payment Recovery

    Recover failed renewals with timely, specific prompts and a grace period, before customers lose access they still want.

    Payments

  • Usage & Limits

    Show customers how much of their plan they've used and handle the moment they hit a limit without breaking their work.

    Payments

  • App Sidebar

    Organise a product's main navigation so users always know where they are, reach frequent places in one click, and keep their place on small screens.

    Navigation

  • Tabs

    Split one object's content into peer views that users switch between without losing their place, state or URL.

    Navigation

  • Breadcrumbs & Back

    Show users where they are in a hierarchy and get them back to exactly where they came from — filters, scroll and all.

    Navigation

  • File Preview

    Let users look inside a file without downloading it, with a predictable fallback for every type the product can't render.

    Files

  • Attachments

    Attach files to records and comments with clear ownership, visibility and deletion rules that match the record they belong to.

    Files

  • CSV Import

    Bring spreadsheet data into the product with column mapping, row-level validation and a preview, so nothing is imported by surprise.

    Files

  • Confirmation

    Ask for confirmation only when an action is hard to undo, and make the dialog state exactly what will happen.

    Workflow

  • Partial Failure

    Report operations where some items succeed and some fail, so users know exactly what happened and what to do about the rest.

    Workflow

  • Permissions

    Show people what they can do, explain what they can't, and give them a way forward instead of a dead end.

    Workflow

  • Notifications

    Tell people about things that need them, in the right channel and at the right volume, without burying what matters.

    Workflow

  • Activity History

    Show who changed what and when on a record, in a timeline people can scan, filter and trust.

    Data

  • Empty States

    Design what users see when there's nothing to show, so every empty screen explains why and offers the next useful step.

    Data

  • Version History

    Let users see earlier versions of a document or record, compare them, and restore safely without losing current work.

    Forms

  • Human Review

    Put a person between AI output and real-world consequences, with review that's fast for good output and careful for risky output.

    AI

  • Feedback

    Collect quick, specific feedback on AI output that users actually give, and that the team can actually use.

    AI

  • Inline Validation

    Tell users about input problems at the right moment — not while they're still typing, and not only after they submit.

    Forms

  • Unsaved Changes

    Protect work in forms that save explicitly, warning only when something would actually be lost.

    Forms

  • Offline Mode

    Keep users working when the connection drops, with an honest view of what's synced, what's pending and what can't be done offline.

    Forms

  • Search

    Help users find records by what they remember — a name, a number, a phrase — with results that explain why they matched.

    Data

  • Pagination

    Split long lists into pages or progressive loads in a way that keeps position, counts and selection predictable.

    Data

  • Saved Views

    Let users save a combination of filters, sorting and columns as a named view they and their team can return to.

    Data

  • Comments

    Let people discuss work where it happens — on the record or the exact part of it — with mentions, threads and resolution.

    Workflow

  • Error Recovery

    When something fails, say what happened in plain language, protect the user's work, and offer the most useful next step.

    Workflow

  • Keyboard Shortcuts

    Give frequent users fast keyboard paths that are discoverable, consistent and never get in the way of typing.

    Navigation

  • Prompt Input

    Design the box where users ask AI for things — with context, attachments and controls visible — so prompts start strong and never get lost.

    AI

  • AI Suggestions

    Offer AI-generated values, completions and next steps inline, so users accept good ones in one action and ignore the rest at no cost.

    AI

  • Agent Progress

    Show what an AI agent is doing during long, multi-step tasks — steps, tool use and decisions — so users can follow, steer and stop it.

    AI

  • AI Onboarding

    Introduce an AI feature by showing what it can do with the user's own data, setting honest expectations about limits and privacy.

    AI

  • Export

    Let users take their data out in the format they need, with a clear scope and no surprises about what's included.

    Files

  • Sharing & Links

    Let people share files and records with teammates or outsiders, with access levels and link scope that are impossible to misread.

    Files

  • Storage Limits

    Show how much storage is used and by what, and handle a full quota without blocking work or deleting anything.

    Files
FilesFree

File Preview

Let users look inside a file without downloading it, with a predictable fallback for every type the product can't render.

6 states5 edge casesDesktop + Mobile

01The problem

Users attach files to find them again and check them quickly: is this the signed version, which receipt is this? Downloading every file to check it is slow, clutters the device and doesn't work well on mobile. Previews remove that friction, but only if they handle the files the product can't render as gracefully as the ones it can.

02When to use

Use when

  • Attachments on records: invoices, contracts, receipts, images
  • File libraries where users browse many files
  • Review workflows where users check documents before approving

Avoid when

  • Files that need editing — open them in the editor or the native app instead.
  • Sensitive files where your policy forbids rendering in the browser.

03Recommended UX

Statecraft recommendation

Open previews in an overlay on top of the current page, with name, size, Download and close always visible, and arrow navigation between files in the same set. For types you can't render, show a clear file card with Download instead of an error.

An overlay keeps the user's place: they glance at the file and return to the list or record without reloading.

Navigating with arrow keys through a set of receipts turns ten open-close cycles into one review.

Unsupported types are normal, not errors. A card with type, size and Download is the honest preview of a .sketch file.

04Interaction flow

  1. 01

    File list or thumbnails

    Type icon, name, size; thumbnail for images and PDFs.

  2. 02

    Open preview

    Overlay with header: name, size, Download, close.

  3. 03

    Render by type

    Image, PDF, video, text — or a fallback card.

  4. 04

    Navigate set

    Previous / next through files in the same list.

  5. Result

    • Viewed
    • Downloaded
    • Unsupported card

05Desktop behaviour

On desktop the preview is a large overlay that dims the page, with the file centred and navigation controls at the edges.

Desktop rules

  • Header: file name, size, position (“2 of 5”), Download, Open in new tab, Close.
  • Left / right arrow keys and edge buttons move through the set; Escape closes.
  • Zoom for images and PDFs, starting at fit-to-screen.
  • Show the first PDF page fast and load the rest progressively.
An overlay keeps the user's place. Name, position, Download and Close are always visible; arrows move through the set.

06Mobile behaviour

On mobile the preview is full-screen with native gestures: swipe between files, pinch to zoom, swipe down to close.

Mobile rules

  • Full-screen viewer with a minimal header that hides on tap.
  • Swipe horizontally between files; pinch to zoom images and PDFs.
  • Share / Download through the native share sheet.
  • For large files on cellular, show size and ask before loading video.
Full-screen viewer with swipe between files and a fallback card for types that can't be rendered.

07States

  • Thumbnail

    Image or first page preview in the list; type icon fallback.

  • Loading

    Header appears instantly; content area shows progress for large files.

  • Rendered

    File shown at fit-to-screen with zoom controls.

  • Unsupported type

    Card with icon, name, type, size and Download.

  • Processing

    Preview still being generated after upload: “Preview ready in a moment”.

  • Failed

    Couldn't load; Retry and Download still available.

08Edge cases

  1. EC-01

    Very large file

    A 400-page, 120 MB PDF.

    Recommendation

    Render page by page as the user scrolls and show the page count up front. Never block on downloading the whole file.

  2. EC-02

    Preview not generated yet

    The user opens a file uploaded 3 seconds ago.

    Recommendation

    Show “Preparing preview…” with Download available, and swap in the preview automatically when it's ready.

  3. EC-03

    Malicious or active content

    An uploaded SVG or HTML file contains scripts.

    Recommendation

    Serve user files from a separate domain with download headers, and render SVG and HTML as images or text, never inline in your app's origin.

  4. EC-04

    Expired link

    The preview has been open for an hour and the signed URL expired.

    Recommendation

    Refresh the URL silently on the next load or download; don't show an access error for an expiry the user didn't cause.

  5. EC-05

    File deleted while viewing

    Someone else deletes the file during preview.

    Recommendation

    Keep the current view, show “This file was deleted by Dana”, and disable navigation to it.

09Microcopy

  • Unsupported

    Avoid

    “Preview not available”

    Prefer

    “No preview for .sketch files. Download (4.2 MB)”

  • Processing

    Prefer

    “Preparing preview… You can download it now.”

  • Failed

    Avoid

    “Error loading file”

    Prefer

    “Couldn’t load the preview. Retry or download the file.”

  • Position

    Prefer

    “receipt-march.png · 2 of 5”

10Accessibility

  • The preview is a modal dialog labelled with the file name; focus moves into it and returns to the opened item on close.
  • Previous / Next buttons name the destination file.
  • Images need alt text: the file name at minimum, or a user-supplied description.
  • Zoom controls are buttons, not gesture-only, on desktop.

11Developer notes

  1. 01

    Generate thumbnails and preview renditions asynchronously after upload, and store their status per file.

  2. 02

    Serve files via short-lived signed URLs from a separate domain with Content-Disposition and strict Content-Type.

  3. 03

    Use a type-to-renderer map with a fallback card so new types degrade instead of breaking.

  4. 04

    Preload the adjacent file in the set for instant navigation.

12Implementation prompt

For Claude Code, Codex or Cursor

Implement a file preview overlay.

Requirements:
- Open from file lists and thumbnails as a modal dialog; Escape closes; focus returns to the opened item.
- Header: name, size, "2 of 5", Download, Open in new tab, Close.
- Previous/next through the current file set with arrow keys and edge buttons; preload neighbours.
- Renderer map by type: image (zoom), PDF (progressive pages, zoom), video, plain text; fallback card for everything else with Download.
- States: loading, rendered, processing ("Preparing preview…"), unsupported, failed (Retry + Download).
- Files served from a separate domain via short-lived signed URLs; refresh expired URLs silently; never render SVG/HTML inline in the app origin.
- Mobile: full-screen viewer, swipe between files, pinch zoom, swipe down to close, native share.

Do not redesign the existing interface.