Product Planning · Templates
The user story format, Given-When-Then criteria and four worked examples for a client portal.
Last updated: October 2026. Written by Athar Ahmad, Certified Bubble.io Developer and Tech Architect, Simple Automation Solutions.
Quick answer
A user story describes what a user wants to do and why, in the format: As a [user], I want [action] so that [benefit]. Acceptance criteria are the conditions that must be true for the story to count as done, often written as Given, When, Then. Good stories are independent, negotiable, valuable, estimable, small and testable, and describe needs rather than solutions.
Key takeaways
- Format: As a [user], I want [action] so that [benefit].
- Acceptance criteria use Given, When, Then to remove ambiguity.
- Use INVEST to check quality: independent, negotiable, valuable, estimable, small, testable.
- Include security and permission criteria, including what must not be possible.
- Stories are the building blocks of a PRD.
In this guide
- What is a user story?
- What are acceptance criteria?
- Examples for a client portal
- How do you write good user stories?
- Epics, stories and tasks: what is the difference?
- Step by step: writing your first user stories
- What mistakes should you avoid?
- How do user stories relate to a PRD?
- Frequently asked questions
A feature request such as “add a dashboard” can mean a hundred different things. A user story turns it into something a team can understand, discuss, build and test. User stories are one of the simplest and most widely used tools for describing what a product should do, and they work equally well for no-code projects.
This guide explains what user stories and acceptance criteria are, how to write them well, with templates and examples for a typical client portal, and the mistakes to avoid.
What is a user story?
A user story is a short description of something a person wants to do with a product and why, written from that person’s point of view. The classic format is:
The three parts matter. The role says who. The action says what. The benefit says why, which helps the team judge whether the feature is worth building and how to build it well.
What are acceptance criteria?
Acceptance criteria are the conditions that must be true for a story to count as done. They remove ambiguity and give testers something concrete to check. A common format is Given, When, Then:
Examples for a client portal
| User story | Acceptance criteria |
|---|---|
| As a client, I want to upload a document to my matter so that my lawyer can review it without me emailing it. | Given I am logged in and viewing my matter, when I choose a file and upload it, then it appears in my document list with the status Uploaded. The assigned lawyer is notified. I cannot see other clients’ documents. |
| As a staff member, I want to see which clients have outstanding document requests so that I can follow up. | Given I am logged in as staff, when I open my dashboard, then I see a list of my clients with overdue requests, sorted by how long they are overdue. |
| As a client, I want a reminder if I have not supplied a requested document so that I do not forget. | Given a document request is unfulfilled three days after it was sent, when the system checks daily, then I receive one reminder email with a link to upload. |
| As an admin, I want to deactivate a user so that former staff cannot access client data. | Given I am an admin, when I deactivate a user, then they can no longer log in and their access is removed immediately. |
How do you write good user stories?
A popular checklist is INVEST. A good story is:
| Letter | Meaning |
|---|---|
| Independent | Can be built without depending on another story |
| Negotiable | A starting point for conversation, not a fixed contract |
| Valuable | Delivers something useful to a user or the business |
| Estimable | Clear enough that it can be sized |
| Small | Small enough to build and test in a short time |
| Testable | Has clear criteria to confirm it works |
Epics, stories and tasks: what is the difference?
| Level | Description | Example |
|---|---|---|
| Epic | A large goal made of many stories | Client document management |
| User story | One valuable thing a user can do | Upload a document to a matter |
| Task | A piece of work needed to deliver a story | Design the upload screen, set privacy rules |
Step by step: writing your first user stories
- List the user roles, such as client, staff and admin.
- For each role, list the things they must be able to do in the first release.
- Write each as a story in the standard format.
- Add three or four acceptance criteria to each, including what must not be possible.
- Split any story that feels too big.
- Order them by importance, and decide what is out of scope. See what to cut before you build.
- Review them with the people who will use the product.
What mistakes should you avoid?
- Writing solutions, not needs. “I want a dropdown” is a solution. “I want to choose a category” is a need.
- Leaving out the benefit. Without “so that”, you cannot judge value.
- Vague criteria. “Works well” cannot be tested.
- Forgetting security and permissions. Add criteria about who can and cannot see data. See our security guide.
- Stories that are too large. If it cannot be built in days, split it.
- Writing and filing. Stories are for conversation. Review them with the team.
How do user stories relate to a PRD?
A Product Requirements Document describes the whole product: goals, users, scope, data, flows and rules. User stories are the detailed building blocks inside it. Our Discovery Sprint produces a PRD with user flows and stories for your first release: $345, delivered within 24 hours and credited toward the build. See also how to avoid scope creep.
Frequently asked questions
What is a user story?
A short description of what a user wants to do and why, written from the user’s point of view, usually as: As a [user], I want [action] so that [benefit].
What are acceptance criteria?
Conditions that must be true for a story to be considered done, often written as Given, When, Then statements.
How many user stories do I need for an MVP?
Often between ten and thirty, depending on scope. Focus on the three to five core actions that deliver value.
What is the difference between a user story and a requirement?
A requirement states what the system must do. A user story describes a need from a user’s perspective and invites conversation about how to meet it.
Do I need user stories for a no-code project?
Yes. They give the builder a clear target and give you a way to check that what was built matches what you wanted.
Want help turning your idea into clear stories?
Email us what the product should do. We will help you write the stories and criteria for a clear first release.
Athar Ahmad, Certified Bubble.io Developer and Tech Architect, Simple Automation Solutions
About Simple Automation Solutions (SA Solutions)
Simple Automation Solutions is a Bubble.io development studio led by Athar Ahmad, a Certified Bubble.io Developer and Tech Architect. It builds web and mobile apps, client portals and SaaS products for founder-led businesses such as law firms, accounting firms, boutique agencies and consultants. Services include a free 30-minute Idea Audit, a $345 Discovery Sprint (a Product Requirements Document delivered within 24 hours, credited toward the build) and builds starting at $3,500. Website: sasolutionspk.com.
