Stop Throwing PNGs Over the Wall: The Zero-Friction Nuxt 3 Handoff.

I used to throw Figma files over the wall and hope developers could read my mind.

Then I watched a senior developer spend three hours rebuilding a "simple" button component because I only designed the happy path. He had to guess the loading state, the error state, the disabled state, and what happens when the text is too long.

The handoff isn't about pretty mockups. It's about removing ambiguity. Every state, every edge case, every interaction — documented before a single line of code is written.

A developer cannot build a product from a happy-path PNG. Design every state or watch it get rebuilt.

Why do traditional handoffs fail?

The problem isn't the designer or the developer. It's the artifact. A static PNG answers "what" but not "how," "when," or "what if."

01 The Happy Path Trap

The issue: Designers show the ideal scenario: data loads instantly, users never make mistakes, and the API always returns 200 OK.

The reality: Users have slow connections, enter invalid data, and APIs fail. When these scenarios aren't designed, developers invent them — and their inventions rarely match the design system.

Example: I once designed a dashboard with beautiful charts. What I didn't design: the empty state, the loading state, or the error state.

02 The Spec Gap

The issue: "Make it look like the design" is not a specification. What's the exact padding? The exact hex code?

The reality: Without tokens and documented values, every developer makes their own interpretation. Suddenly you have 14 shades of blue and 8 different border-radius values.

What is the 4-State Deliverable?

This isn't just about designing four screens. It's about designing for time and uncertainty.

01 Empty State

When it appears: First-time user, no data yet, cleared filters, zero results.

Example: An empty portfolio shows: "No strategies yet" with a "Create Your First Strategy" button.

02 Loading State

When it appears: Fetching data, processing transaction, uploading file.

Example: A dashboard shows skeleton cards matching the final layout's dimensions.

03 Success State

When it appears: Data loaded, action completed, form submitted successfully.

04 Error State

When it appears: API failure, validation error, network timeout, server error.

Example: "Connection failed. Check your internet and try again." with a "Retry" button — not just "Error 500."

How to implement this in Nuxt 3

Here's the actual code structure I hand off with designs. This isn't pseudocode — this is what developers copy-paste into their projects.

<script setup lang="ts">
const props = defineProps<{
  state: 'empty' | 'loading' | 'success' | 'error'
  tokenBalance?: number
  cost?: number
}>()

const emit = defineEmits<{
  (e: 'run'): void
  (e: 'get-tokens'): void
}>()
</script>

Real example: The Qompyl Order Box

Here's how I applied this to a real component in the Qompyl trading app.

The result: Zero component redesigns after handoff.

Handoff checklist

Before you send that Figma link to development, run through this checklist.

FAQ