Surfaces
Output panels, editors, empty states, feedback, and preview chrome.
Output Panels
The shared chrome for anything a tool produces — copy, download, collapse, and stats live in one consistent header.
Code output
Split-pane header
Formatters sit this bar on each editor pane. Title, stats, and copy/download share one height. Pass children instead of title when the left side is a tab list.
{
"generatedAt": "2026-07-27T00:00:00Z",
"rows": 42,
"tool": "csv-to-json",
"warnings": []
}Collapsible, scrollable
Long output stays contained — maxHeight scrolls internally instead of growing the page.
Truncated output
When output is too large to render in full, show a prefix and say so explicitly — never trail off silently.
Standard actions
The vocabulary every output surface shares: copy, download, expand/collapse, and — when a tool has both a friendly and a source view — a raw/rendered toggle.
Every output panel carries the same actions in the same order — copy first, download second, collapse last — so a tool never has to be relearned.
Code Editors
CodeMirror wrapped as controlled React components. One editor for editing text or code, one merge view for diffs. Colors resolve to theme tokens so syntax highlighting flips with light and dark mode automatically.
Editable code editor
Line numbers, JSON syntax highlighting, and controlled state. Edits are held in React — type into it and the value updates live.
161 characters held in state — the editor is fully controlled.
Read-only & placeholder
Read-only drops the caret and line numbers for output text; the placeholder variant guides an empty input before the user types.
Diff viewer
Side-by-side merge view. Removed lines tint destructive on the left, added lines tint success on the right, changed lines highlight the exact tokens. Every changed line also carries a − or + in the gutter (± for a line edited in place in the unified view), so the diff never relies on color alone.
Code blocks
shadcn's CodeBlock for read-only snippets a tool generates: Shiki highlighting (JavaScript regex engine, one grammar loaded per language on first use) with the same theme tokens as the editors, so both look alike. Editable or possibly huge text stays on CodeMirror. CodeSnippet is the titled, copyable version; long values wrap, otherwise the block scrolls sideways and takes keyboard focus once it overflows.
Editors are lazy-loaded per tool via next/dynamic with ssr: false — CodeMirror never ships in the shared bundle, only on the pages that need it. Keyboard: Tab indents inside the editor; to move focus out, press Esc then Tab.
Feedback
How the interface reports state: transient confirmations, persistent status, progress toward a result, and the absence of a result.
Tooltip
Trigger on hover and keyboard focus alike — never mouse-only.
Toast
Transient, non-blocking confirmation of an action's outcome. Mounted once at the root — call toast.add() from anywhere.
Saved
Your changes were saved.
Heads up
This tool processes files locally.
Large file
Processing may take longer than usual.
Upload failed
Could not reach the server.
Uploading…
This will update when it finishes.
Copied to clipboard
Set no type for a plain message.
Item deleted
Removed from the workspace.
An action taken on a toast updates that toast in place — it never spawns another. Clicking Undo above reuses the same toast id via toast.update() instead of calling toast.add() again.
Alert & inline status
Alerts sit above content and persist. Inline status text sits directly under a field and disappears once the state resolves.
Badge
Variants for emphasis; tinted outlines for status.
Progress, spinner & skeleton
Progress communicates a determinate operation; spinner an indeterminate one; skeleton the shape of content about to arrive.
Empty state
Every tool's before-first-input state — nothing has happened yet, and the interface says so.
Copied hint
Inline copy feedback for dense screens: a floating label appears beside the trigger instead of raising a toast — nothing displaces, nothing stacks.
oklch(0.62 0.19 260)The hint is aria-hidden and purely visual — always pair it with an aria-live announcement, as here. Reach for it when a screen has many copy affordances; one toast per copy would pile up. A single primary copy action keeps the CopyButton icon swap instead.
Long-running task
Start a task, cancel mid-flight, or let it finish — each path ends in a clear, distinct state.
Real worker task
Heavy computation runs off the main thread via useWorkerTask; progress and cancellation are mandatory for long tasks. The prime count below is genuinely CPU-bound, yet the input above stays responsive while it runs.
The worker is a real module worker bundled by Turbopack (new Worker(new URL(…, import.meta.url))) and runs entirely client-side — no server, compatible with the static export. Progress is streamed between chunks and Cancel is honored cooperatively (the worker checks a cancelled set between chunks).
Partial result
When an operation only partially succeeds, say so above the result, not buried inside it.
- invoice-001.pdf
- invoice-002.pdf
- + 7 more…
Toast, tooltip, and dialog primitives are provided once at the root layout (Toaster, TooltipProvider) — tools never mount their own.
Disclosures
Progressive disclosure — surfaces that hide detail, options, or confirmation until they're asked for, at increasing levels of interruption.
Accordion
FAQ and help content: several independent panels, more than one can be open at once.
Advanced settings
The standard place to hide rarely-used options: a single closed accordion item, never expanded by default.
Popover
Contextual help: a small explainer that doesn't demand a modal interruption.
Dialog
A focused task that needs the rest of the page blocked.
Alert dialog
Destructive confirmations always use AlertDialog, never Dialog.
Sheet
Side panel for options or filters — the standard choice on wider viewports.
Drawer
Bottom sheet for options or filters — the standard choice on touch/mobile viewports.
Dropdown menu
Overflow actions on a row — grouped behind a single trigger instead of a rail of icon buttons. Choosing an item plays the shared selection blink before the menu closes.
Inline collapse
The house collapse idiom for inline regions — advanced panels, optional settings, expandable detail rows. Grid rows animate 0fr → 1fr to intrinsic height with no measurement, fading in tandem.
This region animates to its intrinsic height — put anything in it. Closing consumes the parent's gap smoothly before the wrapper unmounts.
When the collapse sits in a flex/grid parent that uses gap, pass that gap so the region also animates its block-start margin — otherwise the gap slot vanishes in a single frame at exit and the layout snaps. Under reduced motion it toggles instantly.
Destructive confirmations always use AlertDialog, never Dialog — its focus trap and copy require an explicit typed or clicked confirmation, and it cannot be dismissed by clicking outside.
Data Display
A plain table for small result sets, and a virtualized table once row counts get large enough that rendering every row would cost real performance.
Standard table
Default for <100 rows — composed from plain table primitives, no data prop indirection.
Virtualized table
Required beyond ~500 rows — 10,000 rows here, but only the visible slice is ever mounted. Data-tool call sites pass rowHeight={32} to match the compact control scale. For wide data, give columns explicit widths and set stickyFirstColumn: the table scrolls horizontally with the first column pinned and edge fades signaling off-screen columns (see CSV Explorer).
10,000 rows total
Wide tables get horizontal scroll inside their own panel — the page itself never scrolls sideways.
Comparison
Two ways to show before and after. The slider overlaps both states for pixel-aligned diffs; the side-by-side layout keeps both fully visible when they must be read at once.
Slider
A draggable handle wipes between two overlapping panes. Best for image compression, CSS filters, or any change where the two states occupy the same pixels.
Drag the handle, or focus it and use the arrow keys.
Side-by-side
Two bordered panes with headers, stacked on mobile and placed in a grid from small screens up. Both states stay fully legible.
.btn {
background: #3b82f6;
padding: 8px 16px;
border-radius: 6px;
}.btn{background:#3b82f6;padding:8px 16px;border-radius:6px}Prefer side-by-side when both states must be readable at once; use the slider when the two versions are pixel-aligned and the difference is visual rather than textual.
Preview Workspace
A framed canvas for visual output. It adds zoom, pan, width presets, a checkerboard background for transparency, and a grid overlay around whatever a tool renders.
Rendered sample
A real element sitting inside the workspace. Zoom, pan, resize the viewport, and toggle the checkerboard or grid — everything acts on this card.
Reach for a workspace when the output is a rendered artifact whose scale and alignment matter — visual builders, SVG and icon tools, image exporters. For plain text, tables, or a single fixed-size result, a static preview div is lighter and clearer; the pan/zoom chrome only adds noise.