add-empty-error-states

Files (1)

• SKILL.md

SKILL.md (first lines)

> **Tool mapping (OpenCode):** This skill uses:
> - `question` tool for user prompts (not `AskUserQuestion`)
> - `task` tool for subagents (not `Agent` or `Task` subagent syntax)
> - `skill({ name: "..." })` to load other skills (not `Skill(skill="...", args="...")`)
> - `codegraph_explore`, `codegraph_search`, `codegraph_context` for codebase exploration (preferred)
> - `todowrite` for phase/progress tracking
> - `grep`, `glob`, `read`, `bash` as fallback when `.codegraph/` not initialized
>
> **Context rule:** This skill supersedes any prior skill instructions. Follow ONLY these instructions now. Read the user's goal and any mode/include/skip from the conversation context.

# Add Empty / Error States

A page in three states: loading, empty, error. The fast-path "data shows up" gets all the design attention; the other two get inherited from whatever the renderer falls back to. This skill catches both.

---

## Phase 1 — Locate Data-Fetching Surfaces

Use `todowrite` to mark this phase as in_progress.

In the file the user names (or the most recently edited route/component), find every:

- `useQuery(...)` / `useSuspenseQuery(...)` (TanStack Query)
- Route `loader` returning data the component reads
- `useFetcher` / `useLoaderData`
- Direct fetch + state (less common; flag if found)

For each, identify what's rendered with the result. The empty/error treatment goes wherever that result is consumed.

Prefer `codegraph_explore` with symbol names to trace the data flow; fall back to `grep` + `read` if `.codegraph/` not initialized. If `.codegraph/` not initialized, mention the user can run `codegraph init -i`.

**Exit:** every data-fetch surface and its render site are listed.

---

## Phase 2 — Per Fetch: Check the Three Branches

Use `todowrite` to mark this phase as in_progress.

For each fetch, verify the component handles all three of:

| Branch | Trigger | Treatment |
|---|---|---|
| Loading | first render before data resolves | Skeleton (handled by add-skeleton-loaders, out of scope here). |
| Empty | data resolved but is `null`, `undefined`, `[]`, or otherwise represents "nothing" | Empty state UI. |
| Error | query/loader threw or returned an error | Error state UI. |

For TanStack Query: check that `query.isPending` / `query.isError` / `query.data` are all reachable in the render. With `useSuspenseQuery`, errors are caught by the nearest `<ErrorBoundary>` and loading by `<Suspense>` — verify both boundaries exist on the route.

For loaders: check the route's `errorComponent` (TanStack Router) or equivalent; check `pendingComponent` for loading; the empty case must be handled in the route component itself.

**Exit:** for each fetch, mark Empty and Error as `OK`, `MISSING`, or `WEAK`.

---

## Phase 3 — Detect UI Primitives

Use `todowrite` to mark this phase as in_progress.

Search the codebase for an existing empty/error component. Prefer `codegraph_search` with query "EmptyState" or "ErrorState"; fall back to `grep` + `glob` if `.codegraph/` not initialized:

- `<EmptyState>` / `EmptyState.tsx` — shadcn-style pattern, common in this stack.
- Custom `<NoResults>` / `<ErrorBoundary>` / `<Empty>`.
- A pattern: a card with an icon, heading, body, and action button.

If a primitive exists, use it. If not, propose the smallest one that matches the project's component style — but flag this as a structural decision and let the user confirm via `question` tool before creating shared components.

**Exit:** for each missing/weak state, the component to use is identified.

---

## Phase 4 — Apply Fixes

Use `todowrite` to mark this phase as in_progress.

For each MISSING or WEAK state, apply the inline fix:

### Empty state pattern

```tsx
const { data: posts } = useQuery(postsQueryOptions())

if (posts.length === 0) {
  return (
    <EmptyState
      icon={FileTextIcon}
      title="No posts yet"
      description="Create your first post to get started."
      action={
        <Button asChild>
          <Link to="/posts/new">New post</Link>
        </Button>
      }
    />
  )
}
```

The empty state must:
- Tell the user *what's empty* (specific to this surface — "No posts" not "No items").
- Tell the user *what to do* if action is available (CTA button), or explain *why it's empty* if no action applies.
- Use the same icon/spacing as other empty states in the codebase.

If the empty state means "nothing yet, never will be without action" → lead with the action. If it means "you've filtered everything out" → lead with "clear filters".

### Error state pattern

```tsx
if (query.isError) {
  return (
    <ErrorState
      title="Couldn't load posts"
      description="Something went wrong. Try again in a moment."
      action={<Button onClick={() => query.refetch()}>Retry</Button>}
      // In dev, surface the actual error:
      details={import.meta.env.DEV ? String(query.error) : undefined}
    />
  )
}

From Acauhi99/opencode-agent-system, MIT.

More from Acauhi99/opencode-agent-system