Module 2, Lesson 4: Generating the UX/UI Document

In the last lesson, we built out the technical docs side of the picture — the back-end gears, as I like to call them. Now we're shifting perspective. In this lesson, we're going to document the front-facing side: the UX and UI. That means how the product is going to look, how users are going to move through it, and what makes the experience worth using.

ℹ️

Quick clarification: when I say UX/UI here, I'm talking about documentation, not design. We're not opening Figma and drawing screens. We're writing a document that captures design philosophy, key flows, component direction, and screen inventory — the kind of thing you'd hand a designer or a coding agent before they build anything.

Before We Start

Here's what I'd expect you to have in place before this lesson:

From previous lessons:

Your market research document — saved in Obsidian (or your notes tool). Claude will pull from this to ground the UX document in real findings.
Your technical document from Module 2, Lesson 3 — also saved in your folder.
Claude Desktop open, with Cowork configured to point at your project folder. We're staying in the same task/context from the previous lesson.

Tools / setup you'll need:

Claude Desktop (local desktop app — not the browser version)
Obsidian (or whichever notes tool you're using) with your project folder accessible
The UX/UI prompt from this lesson — available in the notes below. Customise it for your product before you run it.

By the end of this lesson, you'll:

Have a full UX/UI document saved to your project folder
Understand why this document matters before you write a single line of code
Know what to look for and how to review what Claude produces
Have a clear picture of the key flows your product needs to support — mapped out before you start building

About This Lesson

Duration: ~12 minutes video + ~30 minutes for your own run
Skill Level: Intermediate
What You'll Build: A UX/UI reference document covering design philosophy, UI references, colour palette, typography, component recommendations, key user flows, screen inventory, and empty states.

This one's shorter to watch but the document it produces is genuinely one of the most valuable things we make in the whole course. I'll walk you through what to look for when Claude hands it back — because if you just run the prompt and don't read what comes out, you're missing the point.

Watch the Lesson

ℹ️

How I'd suggest going through this: Watch the video first without stopping — just get the big picture. Then come back here and work through the guide section by section, pausing the video at the timestamps I've noted. After that, this guide is your reference — you shouldn't need to rewatch to look something up.

What We're Covering

Here's what I'm walking you through in this lesson and why it matters if you're trying to ship real things:

Why UX documentation comes before design — most people get this backwards, and it costs them
How to write and run the UX/UI prompt — same pattern as the technical doc but with a designer's lens
How to read and validate the output — what to look for, what to question, and where your own judgment matters
The flows Claude will map for you — onboarding, core actions, and the key decision points in your product
Screen inventory — knowing what screens your app needs before anyone touches a code editor

1. Let's Set the Scene (~0:00)

In the last lesson we built out the technical document — the "back-end gears." Now we're flipping to the front.

The UX/UI document is essentially answering one question: what does this product actually feel like to use? Not the code that makes it work. Not the database schema. The experience — the flows, the colours, the moments where a user either gets it or doesn't.

And we're doing this now, at the documentation stage, because this is exactly where most builders mess up. They skip straight from research to code and then end up having long discussions with developers about whether buttons should be round — when the real question they should have answered three weeks earlier is: how does a user even get to that screen?

We're not building anything in this lesson. We're documenting. Just like in the last lesson, the whole job here is to produce a document we can stand behind before a single line of code gets written.

2. The Core Idea

2.1 Technical Document vs UX/UI Document

Think of these two documents as two halves of the same picture.

The technical document (Module 2, Lesson 3) covers how the app works under the hood — the architecture, the data layer, the integrations. The UX/UI document covers how the app presents itself — the visual language, the flows, the experience at the surface.

Together, they give you a complete picture of what you're building before you commit to building it.

2.2 Why Research-Grounded UX Matters

This is where the research from Lessons 1 and 2 pays off in a way that's hard to appreciate until you see it.

Because we did real research — including looking at competitors, their reviews, and their weak spots — Claude can now make design decisions that are actually reasoned. It's not just picking a colour palette out of the air. It's looking at what the category leader does, looking at what their users hate, and building something different with a purpose.

ℹ️

In my own run, Claude recommended a colour palette designed to "allow trust without being cold" — and then explained why, citing specific findings from the market research. That level of reasoning only happens because we grounded everything in real data first. This is the research trickling down, and it's the whole reason we spent time on it.

2.3 How This Connects to Module 2, Lesson 3 — Generating the Technical Document

We're staying in the same Claude Cowork task we used for the technical document. That's intentional. Claude has context from everything we've done in this session — the research, the technical spec, the product name. When you run the UX/UI prompt, it picks all of that up and uses it.

If you start a fresh session, you'll lose that context and the output will be noticeably less specific. Stay in the same task.

3. Let Me Show You How It Works (~0:35)

3.1 Where You Need to Be

You want to be in Claude Desktop, in Cowork, in the same task from last lesson. Your project folder should still be connected — that's where Claude will write the document when it's done.

Same setup as the technical document lesson. If it worked then, it'll work now.

3.2 The Prompt

The prompt follows the same structure as the one we used for the technical document. Here's the pattern:

You are a senior designer who builds products for solopreneurs and lean teams.

You will be given a research report.

Your job is to draft a comprehensive UX/UI document for [product name].

Reference folder: [your folder path]
Product name: [your product name]
Research file: [your research file name]

Defer to the market research for all design decisions.

The document should include:
- Design philosophy
- UI and UX references (with rationale)
- Colour palette (with rationale)
- Typography
- Component recommendations
- Key user flows (as Mermaid diagrams)
- Screen inventory
- Empty states

Write the document to the reference folder as [product name]-UX-I.md

💡

Modify the prompt for your product before you run it. My example uses Nutoro — yours will be different. The product name, folder path, and research file name should all reflect your own setup. Copy the structure, not my specifics.

3.3 Paste It In and Let It Run

Once you've tailored the prompt, paste it into Claude and give it a few minutes. The output is longer than a typical chat response — it's generating a proper document, not just a summary.

When it's done, you'll see it appear in your Obsidian folder (or whichever notes tool you're using) as [product name]-UX-I.md.

4. How to Read What Claude Gives You (~2:55)

Don't just skim it. Here's what I look for — and what I want you to look for in yours.

4.1 Design Philosophy

This is the section that tells you why the app should look the way it does. If you did your research properly, Claude will tie this back to specific findings — things your target users value, things competitors got wrong, the emotional register your product should hit.

Read this carefully. If it doesn't feel grounded in your research, something's off in the way you set up the prompt or the context.

4.2 UI References

Claude will name actual products or sites as reference points — things to emulate and things to avoid. Go and look at them. Don't take its word for it.

In my own run, it cited the category leader in my space as a negative reference (they have low ratings and users hate specific things about the experience), and it cited another product in an adjacent space as a positive reference. When I went and looked at both sites, I thought — yes, that's exactly right.

That moment of validation is important. You want to be able to say "I looked at this, and I agree." If you disagree with one of the references, note it and adjust.

⚠️

Don't just accept the references blindly. Claude is pulling from the research, but you know your space. If it's referencing something that doesn't fit, push back on it — either by editing the document or running a follow-up prompt.

4.3 Key User Flows

This is probably the most important section in the whole document.

Claude will map out the critical flows in your product as Mermaid diagrams — and if you're in Obsidian, these render automatically. You'll see the actual flowchart, not just the code.

For my app, it mapped:

Onboarding flow — from launch to full app access, including the co-parent invite decision
Submit expense flow — the core action, with a target of under 15 seconds
Approve/dispute flow — how the other party responds to an expense
Report review flow — how users access and review monthly summaries

Before this document existed, that second flow was just an idea. Now it's a chart. And the detail it captures — like "solo mode is a first-class path because not every user has a co-parent ready to invite" — that came straight from the research.

This is where the planning pays off. Read each flow, check it against what you know about your users, and mark anything that doesn't ring true.

4.4 Screen Inventory

Claude will produce a list of every screen your app needs. For a mobile product, this is especially useful because it's easy to underestimate how many distinct states an app has.

It'll also cover empty states — what happens when there's nothing in the app yet. This sounds minor but it's a UX decision that often gets forgotten until a developer asks about it mid-build. Having it here means it won't get skipped.

4.5 Colour, Typography, and Components

Read these, but hold them lightly. Claude's suggestions here are reasonable starting points, not final decisions.

I'll be honest — in my own run, I wasn't keen on the typography recommendation. That's fine. The document is a draft, not a decree. Take what makes sense, adjust what doesn't.

For components, Claude will likely suggest things like shadcn/ui or native base. If you're not sure what those are, ask Claude to explain them or do a quick search. Don't skip past unfamiliar terms — they'll come up when you start building.

5. Why This Document Matters So Much (~9:10)

I want to stop here for a second because I think this is worth saying plainly.

Most people building apps — especially solo — spend enormous amounts of time debating authentication flows, discussing button styles with developers, and changing their minds about onboarding halfway through a sprint. All of that is avoidable if you do this work first.

This document answers those questions before they become arguments. It says: here's the onboarding flow, here's the screen inventory, here's what we avoid and why. It doesn't mean nothing will change — things always change — but you're starting from a position of clarity rather than guesswork.

And the second thing: when you eventually use Claude Code to build this thing, you'll be handing it documents like this one. The more specific and reasoned your documentation, the better the code it produces. We're building our own runway here. Every document we write is a clearer set of instructions for what comes later.

🔥

If you have people in your life who might be your target users — show them the flows from this document. Not the whole thing, just the diagrams. Ask them: does this make sense? Would you use this? That five-minute conversation is worth more than a week of coding.

6. Watch Out For These

⚠️

Starting a new Cowork task
If you start a fresh session instead of continuing in the same task, Claude loses all the context it built up — the research, the technical doc, the product name. The output will be noticeably more generic. Stay in the same task.

⚠️

Not reading the output
I see this a lot. People run the prompt, see a long document appear, and assume it's done. Read it. Especially the flows. Claude is doing real reasoning here, but it can only work with what it was given. If something looks off, it's either a prompt issue or a gap in your research — both of which are fixable.

⚠️

Treating this as a final design doc
It's not. It's a reference document. The colours might change. The typography might change. That's fine. The flows and the design philosophy are what matter most at this stage — those should stay pretty stable.

7. Practice

Exercise 1: Run the Prompt for Your Product

What to do: Tailor the prompt from Section 3.2 to your own product and run it in Claude Cowork. Confirm the document appears in your project folder.

A nudge if you're stuck: Make sure you're in the same Cowork task as your previous documents. If the folder reference isn't working, check that Cowork is still pointed at the right directory.

How you'll know it's working: You'll see [your product name]-UX-I.md appear in your Obsidian vault (or notes folder). Open it and confirm it has sections for design philosophy, flows, and screen inventory.

Exercise 2: Validate One Flow

What to do: Pick the most important flow in your product — probably onboarding. Read through it step by step and ask yourself: does this match how a real user would actually do this? Is there a step missing? Is there a step that would cause friction?

What this is practising: Reading AI output critically. The goal isn't to accept what Claude produced — it's to engage with it and make it better.

8. You Should Be Able to Do This Now

Here's what you can put together with what we just covered:

Run a UX/UI documentation session in Claude Cowork, grounded in your market research
Read and critically evaluate the output — not just skim it
Use the user flow diagrams as a communication tool before any code gets written

Check Yourself

I have a [product name]-UX-I.md file saved in my project folder
I've read the design philosophy section and it makes sense for my product
I've looked up the UI references Claude cited and formed a view on them
I've read through at least one key user flow and validated it against what I know about my users

✅

If you're ticking those boxes, you've done the work. The next lesson is where we go broader — the investor/product summary document. But first, sit with this one. Read the full UX/UI doc you've produced. You've just described your product's experience in more detail than most solo builders ever do.

If Something's Not Working

⚠️

The document didn't save to my folder
What's happening: Claude wrote the document to chat instead of to disk — usually means the Cowork folder reference wasn't picked up.
How to fix it: Check that Cowork is connected to your folder. Re-run the prompt and make sure the folder path and file name are explicitly in the prompt. Claude needs to be told exactly where to write.

⚠️

The Mermaid diagrams aren't rendering
What's happening: You might be viewing the file in a tool that doesn't render Mermaid by default.
How to fix it: Open the file in Obsidian — it renders Mermaid natively. If you're using a different notes tool, check whether it supports Mermaid or find a free online Mermaid renderer to paste the diagram code into.

The Short Version

Here's what I want you to walk away with:

The UX/UI document is not design work — it's documentation. You're capturing how the product should feel before anyone starts building it.
Research grounds everything — the colour rationale, the UI references, the flows. None of it is arbitrary if you did the research.
The user flows are the most important part — read them carefully, validate them against real users if you can, and treat them as a shared language between you and whoever builds this.
What you can do now: Describe your product's complete user experience — from first open to core action — in a format you could hand to a designer, a developer, or an AI coding agent.

Quick Reference

The Prompt Structure

You are a senior designer who builds products for solopreneurs and lean teams.
You will be given a research report.
Your job is to draft a comprehensive UX/UI document for [product name].
Reference folder: [your folder path]
Product name: [your product name]
Research file: [your research file name]
Defer to the market research for all design decisions.
Write the output to [product name]-UX-I.md

What the Document Should Contain

Design philosophy          — why the product looks and feels the way it does
UI/UX references           — what to emulate and what to avoid, with rationale
Colour palette             — with reasons tied to the research
Typography                 — primary and mono choices
Component recommendations  — UI library suggestions (e.g. shadcn/ui, native base)
Key user flows             — Mermaid diagrams for onboarding, core actions, etc.
Screen inventory           — every screen the product needs
Empty states               — what happens when there's nothing to show

Resources

Tools Used

Claude Desktop — run via Cowork with folder access
Obsidian — for viewing and storing the output (Mermaid renders natively here)

Concepts Worth Looking Up

Mermaid diagrams — a text-based format for flowcharts that Obsidian (and Claude) supports natively. mermaid.js.org has live preview if you want to test diagrams outside of Obsidian.
shadcn/ui — a component library Claude often recommends for web products. Worth knowing what it is before you get to the build phase.

Questions I Get Asked

Q: Do I need to be a designer to review this document?

No. The most important thing is whether the flows make sense to you — not whether the typography choice is correct. You don't need a design eye to read a flowchart and say "wait, this step doesn't make sense." Trust your instincts as a user of your own product.

Q: Can I edit the document Claude produces?

Absolutely, and I'd encourage it. This is a living document at this stage. If Claude's colour recommendation doesn't fit your product, change it. If a flow is missing a step, add it. Claude gave you a strong first draft — your job now is to make it yours.

Q: My product is a web app, not a mobile app. Does this still work?

Yes. The prompt I gave you works for web, mobile, or anything in between. Just be explicit in your prompt about the platform — Claude will adjust the screen inventory and flow assumptions accordingly.

Q: How do I know I'm ready for the next lesson?

If you've got the document, you've read it, and you can explain what your product's onboarding flow looks like — you're ready.

💬 Stuck? Come Talk to Us

💡

If something's not clicking or you want to share what you've built — come find us in Discord.
Build What Ships community → https://discord.gg/RFXRf9yg
Drop your question in the right channel. The community's active and I check in there too.

Glossary

UX/UI document: A written specification of how a product should look and feel — covering design philosophy, visual direction, user flows, and screen inventory. Not a design file; a reference document. (first used in Module 2, Lesson 4)

Mermaid diagram: A text-based format for writing flowcharts and diagrams that renders automatically in Obsidian and several other tools. Claude uses it to map user flows. (first came up in Module 2, Lesson 4)

Cowork: Claude Desktop's multi-turn working environment where you can connect Claude to a local folder so it reads and writes files directly. (first introduced in Module 2, Lesson 3 - Generating the Technical Document)

Empty state: The screen a user sees when an app has no content yet — for example, when they've just signed up and haven't added any data. Defining these up front prevents them being an afterthought during build. (first came up in Module 2, Lesson 4)

Screen inventory: A complete list of every distinct screen or view an app needs to have. Produced at the documentation stage so nothing gets forgotten during build. (first came up in Module 2, Lesson 4)

shadcn/ui: A popular React component library that Claude often recommends for web products. Worth looking up before you get to the build phase. ui.shadcn.com (first came up in Module 2, Lesson 4)