ui-backend-integration

When to apply

Use when implementing or auditing anything that crosses the UI boundary: screens, forms, mutations, queries, server actions, RPC, or domain operations that users should drive or observe.

Core rules

1. Wire meaningful interactions — Every user-visible action that should change state or fetch data must call real logic (not console.log, dead handlers, or static mocks) unless the task is explicitly design-only.
2. Expose domain capabilities — If the backend or domain layer implements a user-facing capability, ensure there is a path from the UI (navigation, control, or surfaced data). Do not leave "orphan" endpoints or use cases with no UI when the product intent is to offer them.
3. Explicit boundaries — Connect UI and logic through stable seams: hooks, services, actions, adapters, or thin API clients—whatever the project already uses. Avoid ad hoc fetch scattered across components when a shared pattern exists.
4. State alignment — Model request lifecycle: idle, loading, success, and error. Disable or guard double-submits; show failures users can act on; keep optimistic UI consistent with eventual server truth.
5. Truth in the UI — Labels, counts, permissions, and empty states should reflect real data and server rules, not hardcoded assumptions that drift from behavior.
6. Verify flows — Prefer automated tests for critical paths (integration or E2E where the project supports them). When tests are out of scope, describe a minimal manual checklist and run it before calling the work done.

Integration checklist

Copy and track when reviewing or building a feature:

UI ↔ logic integration:
- [ ] Each primary control triggers the intended domain/API path
- [ ] No placeholder success paths masking failures
- [ ] Loading state prevents duplicate submissions where relevant
- [ ] Errors surface with actionable or clear messaging
- [ ] Success state matches persisted or authoritative data
- [ ] User-facing backend capabilities have UI affordances (or explicit product decision not to)
- [ ] Interfaces (hooks/services/actions) are the single obvious entry points for this flow

Workflow

1. Map the flow — List user steps, data read/written, and authoritative source (server, local DB, cache).
2. Implement or connect — Add or reuse boundary modules; thread types from domain/API into the UI layer.
3. Handle lifecycle — Loading, validation, errors, empty states, and success refresh or navigation.
4. Reconcile behavior — Confirm authorization, validation, and edge cases match between UI and server.
5. Verify — Run tests or execute the checklist above.

Outcomes to aim for

• UI interactions produce real application behavior end to end.
• Important capabilities are reachable and understandable from the interface.
• The product feels consistent: what users see matches what the system does.

Boundaries

• Do not invent backend contracts or bypass auth/validation just to "make the UI work."
• If a capability should stay internal or admin-only, document that decision rather than exposing it by accident.
• Follow the project's stack and file organization (see repo rules); this skill does not mandate a specific framework pattern beyond clear boundaries.

Additional resources

For stack-specific patterns (e.g. React Server Actions, tRPC, Vercel AI SDK), follow the repository's ARCHITECTURE.md, .cursor/rules, or AGENTS.md alongside this skill.

Related skills

• test-to-completion — Verify integrated flows end-to-end with tests after connecting UI to logic.