Consider an empty project list. It has a heading, a short explanation, and a “Create project” button. The screenshot looks finished.
Then someone without creation permission opens it. Or the request is still loading. Or creation succeeds, the button disappears, and keyboard focus has nowhere useful to go. The same small card now needs several different behaviors.
Micro-onboarding treats that first-use state as an interaction contract. It teaches one concept when the user needs it and provides the action that puts the concept into practice. For frontend engineers and product designers, the useful work is connecting that lesson to permissions, navigation, failure recovery, and verification.
Give the empty list one lesson
Take this synthetic project-list example:
No projects yet
Create project
The condition is clear and the action provides a way forward. A small addition can explain what a project contains:
No projects yet
Create your first project
Organize tasks, documents, and discussions around a piece of work.
The user learns the container model at the moment they can create the container. There is no need to remember the explanation from a tour encountered several screens earlier.
Keep the scope small: one current state, one permitted next action, and one domain or interaction lesson. Imports, templates, permissions, and the whole project model may all matter eventually. Teaching all of them here makes the first action harder to see.
A keyboard hint can teach a faster route to the same action, provided it names a real binding from the shared action definition. A shortcut invented for the copy creates an instruction the interface cannot keep.
Zero projects can mean different things
The basic implementation often checks whether a collection has any items. That test cannot distinguish a completed empty result from data that has not arrived yet. Rendering the empty message during loading can briefly tell someone their projects do not exist.
Model the transition explicitly. A simplified sketch is:
loading -> empty -> creating -> populated
| ^
+-> failed ---+Read the failed branch alongside its recovery rule: a failed attempt exposes retry, and only a successful creation reaches the populated state. Cancellation returns to a stable empty view. The diagram abbreviates those transitions; it is not a complete state machine.
Permissions create further branches. A person allowed to create a project gets the creation action. A person who cannot create one may need an explanation, a request-access action, or no action, depending on the feature’s rules. The project count is identical, but the useful next step differs.
Authorization still belongs on the server. The interface can also avoid offering an action it already knows is unavailable. When permission changes after the screen loads, the server rejection needs its own recovery behavior.
The same method applies beyond project lists. An empty task list can explain where new work goes; a document collection can explain what belongs there. Notifications, search history, and comments each have a different lesson. In particular, search history should not be described as saved searches. Each surface contributes a small piece of onboarding without needing a separate tour state machine.
Write down what the card promises
A reviewable contract can live in a feature specification, a design-system story, or a typed object. Choose the form that keeps decisions discoverable for the people implementing them.
This illustrative TypeScript shape makes missing decisions easy to spot:
type MicroOnboardingContract = {
id: string;
surface: string;
enterWhen: {
dataState: "empty";
permission: "allowed" | "requestable" | "denied";
};
lesson: string;
copy: {
heading: string;
description: string;
primaryActionLabel?: string;
};
action?: {
id: string;
destination: string;
shortcutSource?: "action-registry";
};
transitions: {
success: string;
failure: string;
cancel: string;
};
focusAfterSuccess: string;
};Try filling in the failure destination and the focus target before polishing the description. If either is unknown, the design still has an unresolved interaction. The completed copy cannot answer it later.
The type is not a required runtime abstraction. A shared registry can help when several renderers consume the same action metadata. With one renderer, a clear specification may be sufficient.
For each state, keep these deliverables together:
| Deliverable | What the reviewer needs |
|---|---|
| State inventory | Surface, empty trigger, loading distinction, permission variants |
| Learning objective | The single fact this state should teach |
| Content contract | Heading, description, primary-action label, terminology source |
| Action binding | Action identifier, permission predicate, destination or effect, optional accelerator source |
| Transition contract | Success, cancellation, server rejection, network failure, retry, restored context |
| Interaction contract | Focus order and destination, keyboard and touch behavior, heading structure, small-screen layout |
| Verification evidence | Component fixtures, permission cases, interaction tests, accessibility checks, rendered review |
Product design decides the lesson and its timing. Domain specifications supply terminology and permissions. The action system supplies commands and accelerators, while the frontend implements rendering and transitions. Tests check that those decisions agree.
Let the action own its shortcut
A keyboard hint can become stale even when the button still works. If the application already has an action registry, render the current binding from it:
const createProject = actions.get("project.create");
<EmptyState
heading="No projects yet"
description="Organize tasks, documents, and discussions around a piece of work."
action={createProject}
/>This illustrative React example assumes the action carries its label, permission state, invocation behavior, and current keyboard binding. Menus, command search, tooltips, and empty states can then read the same definition. A binding change reaches all of them through that shared source.
If there is no shared action definition, omit the shortcut hint until there is one. The action remains usable through its button, and the screen avoids teaching an incorrect binding.
Walk through the states the screenshot missed
Start verification before the data arrives. Loading must stay distinct from a confirmed empty response. Then check allowed, requestable, and denied users against their specified actions or alternatives. None should receive a dead control.
Follow the primary action. Confirm that it reaches the declared destination or performs the declared effect, that success shows the new object or expected next view, and that cancellation returns without losing context. Reject the request at the server and interrupt the network. Check input preservation where appropriate, the explanation of failure, and the retry path.
Repeat the flow with a keyboard and check where focus lands after the empty state disappears. Verify touch, screen-reader, and small-screen behavior against the same task. Any displayed accelerator must match the current action binding. A screenshot remains useful for layout, but these branches need interaction evidence too.
A reviewer should be able to trace each result back to the contract: the exact entry condition, the lesson, the smallest useful action, who may perform it, where it is defined, and the success, cancellation, and failure paths. The focus destination and the fixture or test for each branch should be just as easy to find.
Return to the empty project list. It is ready when a permitted user can understand a project, create one, and reach the resulting view; another user gets the specified alternative; and an interrupted attempt leaves a recoverable state. That is a small feature, but it deserves a complete design.