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

In the last lesson, we built out the technical 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.

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 — it's in Section 3.2 of these notes. Fill in the two placeholders ({{product_name}} and {{platform}}) 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

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.

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

Here's the full prompt. Fill in the two placeholders before you run it: replace {{product_name}} with your app name (e.g. Nurturo) and {{platform}} with your product's primary platform (e.g. mobile, web, or mobile and web). Everything else copies as-is.

You are a senior product designer specialising in SaaS products for solopreneurs and lean teams.

You will find the market research and technical document in the folder for {{product_name}}.

Your job is to produce a comprehensive UX/UI Overview document in Markdown that the development team can build from.

Output filename: App - {{product_name}} - UX-UI.md

Platform: {{platform}}

---

## Input

You will receive:

1. A market research report (in the folder) — your primary source for understanding what the product does, who it serves, its competitive landscape, and every UX-relevant insight about user pain points and competitor failures.
2. A technical document (in the folder) — reference this for the chosen tech stack, framework, and platform. Your design system choices must align with what has already been decided technically.
3. Product name — it is in the file names.
4. Product description — defer to the market research. Do not ask.

---

## Design System Selection

Choose the component library, icon set, and typographic system that fits this product. Do not apply a generic template.

Before selecting any design system component, reason through these questions:

- Platform: Is this a native mobile app, a web app, a desktop app, or cross-platform? Each has different component ecosystems, type conventions, and interaction patterns.
- Stack alignment: What does the technical document specify? Your design system must be compatible with the framework already chosen. Do not recommend components that conflict with the technical stack.
- Target audience: Does the audience expect a polished professional tool, a consumer app, an enterprise interface? The design language should match their expectations.
- Ecosystem fit: Are there dominant, well-maintained component libraries for this platform and framework combination? Prefer options a small team can work with and extend.

Justify each design system choice in 1-2 sentences.

---

## Constraints

- Build audience: A small design-and-dev team who will build directly from this document.
- Depth level: Design-direction level — describe what to build and why, not pixel-level specifications. The document should be actionable enough that a designer can open their design tool and start without asking questions.
- Accessibility: WCAG AA minimum as a baseline. Note any domain-specific accessibility requirements.
- Do not make Figma-specific references — the team may use any design tool.

---

## Document Structure
 
Follow this structure precisely. Every section is required unless marked (if applicable).

### 1. Design Philosophy

Write 3-5 design principles specific to this product's domain and users. Each principle should have:

- A one-word label (e.g. "Trust", "Clarity", "Speed")
- A 1-2 sentence explanation grounded in what the research reveals about the target user

End with an "Avoid" line listing anti-patterns for this audience.

### 2. Design References

Identify 2-3 real products whose design patterns are relevant. For each:

- Product name and URL
- What to emulate (3-5 specific design decisions)
- What to avoid (1-2 things that don't transfer to this audience)

Search the web to verify these references exist and are current. Pick products the target users actually know, or that solve similar UX problems. At least one reference should be from the product's own industry.

### 3. Brand Direction

#### Tone

5 adjective descriptors with 1-sentence explanations, tailored to the product's domain.

#### Color Palette

A table with these columns: Role, Color Name, Hex, Usage. Include at minimum:

- Primary + Primary Hover
- Secondary (CTA) + Secondary Hover
- Background, Surface, Border
- Text Primary, Text Secondary, Text Muted
- Success, Warning, Error

Choose colors that match the product's domain and audience. Conservative or professional domains get muted, trust-signalling palettes. Consumer or creative domains get bolder palettes. Include accessibility notes confirming key combinations meet WCAG AA.

#### Typography

Select a typographic system appropriate for the platform specified above:

- Native mobile (iOS/Android): defer to the platform's native type system (SF Pro for iOS, Roboto/Material for Android) or a cross-platform alternative if the framework supports it. Provide point sizes appropriate for mobile.
- Web apps: choose a Google Font or system font appropriate for the product's tone. Provide a type scale table: Element, Size, Weight, Line Height.
- Cross-platform: choose a font available across all target platforms and justify the choice.

Justify your font choice in 1-2 sentences. Reference the technical document's platform and framework choice.

### 4. Component Library

State the component library chosen for this platform and stack (referencing the technical document). Then identify product-specific custom components that will need to be built — give each a one-sentence description of what it displays.

### 5. Key User Flows

Identify the 3-5 most critical user flows for the MVP. For each flow:

- Flow name
- Mermaid flow diagram showing the happy path with key decision points and branches
- Key considerations — 3-5 UX decisions that matter for this flow, grounded in research findings about user pain points or competitor failures

The flows should cover: onboarding, the core daily or weekly action loop, and the primary value-delivery moment.

### 6. Screen Inventory

Two tables:

Marketing Pages — columns: Screen, Priority (High/Medium/Low), Key Components
App Screens — columns: Screen, Priority (High/Medium/Low), Key Components

Prioritise based on what the research identifies as core value. High-priority screens are MVP-blocking.

### 7. Empty States

A table covering every list or dashboard screen with columns: Screen, Empty State Message, CTA. Empty states should guide the user toward the next productive action, not just display a blank view.

### 8. Responsive Strategy

- Primary, Secondary, Tertiary device targets — choose based on how the target user actually works, referencing the platform and research
- Breakpoints (if applicable to the platform)
- Platform-specific considerations — 3-5 bullets on what changes across screen sizes or devices

### 9. Accessibility Requirements

Cover: contrast ratios, keyboard navigation, focus indicators, screen reader support, reduced motion support, color-not-sole-indicator. Add any domain-specific accessibility requirements relevant to this product's audience.

### 10. Interaction Patterns

#### Shortcuts and Gestures

Table of 8-12 shortcuts (web) or gestures (mobile) for power users, tailored to this product's core actions.

#### Loading States

How to handle: list or card loading, button actions, long-running processes.

#### Notifications

Toast or notification behavior for success, errors, and pending items.

### 11. Design Handoff Checklist

A checklist of 12-15 items for design-to-dev handoff. Cover: component naming, layout system, component variants, spacing grid, color tokens, responsive or adaptive variants, interactive states, empty states, error states, exported assets, and any platform-specific handoff requirements.

### 12. Design System Documentation

Outline for a component documentation instance (e.g. Storybook for web, equivalent for mobile) with three sections: Foundations, Components, Patterns.

---

## Research & Gap-Filling

- Mine the research report for every UX-relevant insight: user pain points, competitor UX failures, workflow descriptions, user demographics, and any explicit UX recommendations.
- Reference the technical document for all stack and platform decisions before making design system choices.
- Search the web to find and verify real design references in the product's domain. Do not guess at URLs — confirm they exist.
- Ground every design decision in either a research finding or a known UX principle.

---

## Quality Standards

- Flow diagrams must use Mermaid and render cleanly in Markdown.
- Color hex values must be real, usable values — not placeholders.
- The document should be actionable — a designer should be able to open their design tool and start building from this spec without further clarification.
- Target length: 250-400 lines of Markdown.

3.3 Understanding the Prompt

A few notes on the key sections — read these once when you're first learning the prompt.

Design System Selection — No design system is prescribed. Claude derives the component library, icon set, and type system from the platform and the technical document. A React Native app gets a very different set of components than a Next.js web app. A healthcare product gets different typography than a consumer tool. Claude works this out from the documents already in the folder — which is why the technical document comes first.

Section 2 (Design References) — Claude will name real products as reference points. 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 (users hate specific things about the experience), and an adjacent product as a positive reference. When I went and looked at both, I thought — yes, that's exactly right. You want to be able to say "I looked at this and I agree." If you disagree with a reference, note it and adjust.

Section 5 (Key User Flows) — This is the most important section in the whole document. Claude will map the critical flows as Mermaid diagrams — and if you're in Obsidian, these render automatically. Read each flow carefully. The detail it captures (like "solo mode is a first-class path because not every user has a co-parent ready to invite") comes straight from the research. If a step looks wrong, that's a signal worth acting on before you write any code.

Section 6 (Screen Inventory) — Claude will produce a list of every screen your app needs. For a mobile product especially, it's easy to underestimate how many distinct states an app has. Having this list before you build means nothing gets forgotten mid-sprint.

Sections 3 and 4 (Brand Direction and Components) — Hold these lightly. They're a reasonable starting point, not a final decision. In my own run I wasn't keen on the typography recommendation — that's fine. The document is a draft. Take what makes sense, adjust what doesn't.

{{platform}} placeholder — This genuinely changes the output. mobile gets a native-first type system and touch-optimised interaction patterns. web gets a web component library and keyboard shortcuts. mobile and web gets both considered. Set it accurately.

3.4 Paste It In and Let It Run

Copy the prompt from Section 3.2. Fill in the two placeholders, then paste it into the Cowork input area. Give it a few minutes — the output is longer than a typical chat response.

When it's done, you'll see it appear in your Obsidian folder (or whichever notes tool you're using) as App - [product name] - UX-UI.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.

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:

1. Onboarding flow — from launch to full app access, including the co-parent invite decision
2. Submit expense flow — the core action, with a target of under 15 seconds
3. Approve/dispute flow — how the other party responds to an expense
4. 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.

6. Watch Out For These

7. Practice

Exercise 1: Run the Prompt for Your Product

What to do: Copy the prompt from Section 3.2. Fill in {{product_name}} and {{platform}}, then 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 App - [your product name] - UX-UI.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 an App - [product name] - UX-UI.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 Something's Not Working

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

UX/UI Document Prompt

The full prompt is in Section 3.2. Fill in before running:

• {{product_name}} — your app name (e.g. Nurturo)
• {{platform}} — your primary platform (e.g. mobile, web, or mobile and web)

What the Document Produces

Design philosophy          — why the product looks and feels the way it does
Design references          — what to emulate and what to avoid, with rationale
Colour palette             — with reasons tied to the research
Typography                 — font and type scale appropriate to the platform
Component library          — derived from the technical stack, plus custom components
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
Responsive/device strategy — how the product adapts across screen sizes
Accessibility requirements — WCAG AA baseline plus domain-specific notes
Interaction patterns       — shortcuts/gestures, loading states, notifications
Design handoff checklist   — what a designer needs to hand off to a developer

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

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)