Windsurf UI design for flows people finish

Agents are good at building screens and less good at flows. Ask for an onboarding and you'll often get seven well-styled screens that ask for everything up front, request notifications before the person has seen anything, and offer no way to skip. Each screen looks fine. The flow loses people.

Example task used in this guide: cut a seven-screen onboarding down to a short flow people actually finish.

Windsurf is now Devin Desktop

On June 2, 2026, Windsurf was renamed Devin Desktop. Existing installs updated in place, and your rules, extensions and MCP connections carried over. Everything in this guide works in both: Devin Desktop still reads .windsurf/rules/ and .windsurfrules, and prefers .devin/rules/ for new rules.

Design the flow, not the screens

Before changing anything, ask the agent to list the current flow: each screen, what it asks for, and why. Then write down what onboarding is for in one sentence. Usually it's get the person to the first useful moment as fast as possible. Any screen that doesn't serve that is a candidate to cut, delay or make optional.

Scope the rules to the feature

Devin Desktop reads AGENTS.md files anywhere in your project. One at the root applies to every message; one inside a folder applies only when the agent works on files in that folder. That makes a folder-level file ideal for feature rules. Put this in src/app/onboarding/AGENTS.md:

# Onboarding

- At most 4 screens before the person reaches the app. Every screen has one job.
- Ask only for what the next screen needs. Anything optional can be skipped, and Skip is always visible.
- Show progress (step 2 of 4) and keep a Back button on every step after the first.
- Ask for permissions (notifications, location) only at the moment they're needed, after saying why.
- Reuse the app's existing Button, Input and Screen components. No new colors or fonts.
- Every step must work with a screen reader and at 390px wide.

Each rule is something you can check by tapping through the flow. "Keep onboarding short" isn't; "at most 4 screens" is.

Study real onboarding flows

With UXKIN connected, the agent can call find_ui_references with "onboarding" and get complete journeys from real apps, such as Reeder's or DailyArt's, then open one screen by screen with get_journey.

Ask it to compare two journeys on four points: how many screens, what each asks for, where Skip is, and when permissions come up. Then have it say which decisions it's adopting. You're borrowing the shape of the flow, not the screens: your components and words stay yours.

Walk through it as a new user

Have the agent run the app and go through onboarding from a fresh install, the way a new person would:

• Count the steps to the first useful screen. Four or fewer.
• Skip everything optional. The app should still work.
• Go back a step. Nothing typed is lost.
• Decline notifications. The flow continues normally.
• Use a screen reader once, and check a phone width (390px).

Set up UXKIN in Devin Desktop

UXKIN connects as a remote MCP server, and you sign in with your UXKIN account, so there's no token to copy. You need a UXKIN plan (Monthly or Lifetime).

1. Open the MCP settings: the MCPs icon in the agent panel, or search the Command Palette (Cmd/Ctrl+Shift+P) for "MCP".
2. Choose to add a custom server, which opens the MCP config file (mcp_config.json), and add UXKIN to it:

{
  "mcpServers": {
    "uxkin": {
      "serverUrl": "https://uxkin.com/mcp"
    }
  }
}

3. Save the file and go back to the MCP settings. Select uxkin and connect; when the UXKIN page opens, log in and click Allow.
4. Check that find_ui_references, find_ui_materials and get_journey are listed and enabled.

Menu names have shifted a little since the rename; if yours differ, look for "MCP" in settings. To share one setup with a team, use a token instead of signing in. This reads it from a UXKIN_TOKEN environment variable, so the file is safe to share:

{
  "mcpServers": {
    "uxkin": {
      "serverUrl": "https://uxkin.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UXKIN_TOKEN}"
      }
    }
  }
}

Set UXKIN_TOKEN to the token from your setup prompt and restart the app. Never paste the token itself into a file you commit.

A prompt you can use

Adapt it to your own flow. It starts by reading the current code, asks for two references and lists what to check:

Rebuild our onboarding. Today it's seven screens, asks for notifications on the first one, and many people quit before the end.

First, read src/app/onboarding and tell me what each screen asks for and why.

If UXKIN is connected, use find_ui_references with "onboarding", pick two journeys, and open them with get_journey. For each, note: how many screens, what's asked on each, where Skip is, and when permissions are requested. Tell me which decisions you're adopting.

Follow the rules in src/app/onboarding/AGENTS.md. Then:
- Cut it to at most 4 steps, each with one job.
- Move the notifications request to the moment it's first useful, with a sentence saying why.
- Keep progress, Back and Skip on every step after the first.
- Keep everything the person entered if they go back.

Walk through it as a new user at 390px, and once with a screen reader. List each change in one line.

Questions