Idea to App

How to Write a One-Page App Spec: Template and Example (2026)

A fill-in-the-blanks template for a one-page app spec, a complete worked example, and the questions that turn a vague idea into something anyone can build.

Floot ·

Key Takeaways

  • A spec is a set of decisions, not a description. Its job is to settle who, what and what-not before building, so nobody has to guess.
  • The main flow is the heart of the page. Five to eight numbered steps from arriving to getting value. If you can’t write them, the idea isn’t ready to build.
  • The “not in version one” list matters as much as the features. Writing down what you’re leaving out stops scope creep and tells builders what not to add.
  • Describe data and rules in plain words. What the app remembers and who may see or change it are where most first-version bugs come from.
  • End with how you’ll know it worked. One measurable sign of success, set before launch, keeps you honest afterwards.

Quick-Start Prioritization Framework

Spec sectionQuestion it answersLength
ProblemWhat painful moment does this fix, and what do people do today?2–3 sentences
UserWho exactly is it for first?1–2 sentences
Main flowWhat are the steps from arriving to getting value?5–8 numbered steps
ScreensWhich pages does that flow need?A short list
DataWhat does the app remember?3–6 things with their details
RulesWho can see and change what? What happens automatically?3–6 bullet points
Not in version oneWhat are you deliberately leaving out?5–10 bullet points
SuccessWhat will tell you it’s working?1–2 measurable signs

Most app ideas fail long before anyone writes code, at the moment the founder tries to explain them. “It’s like Airbnb, but for…” sounds clear in your head and means something different to every listener. A one-page spec fixes that. It is a short document that says who the app is for, what they do in it, what it stores, and what it deliberately leaves out. One page is enough for a first version, short enough that people actually read it, and specific enough that a developer, a freelancer or an AI builder can turn it into a working app. This guide gives you a template, explains each section, and walks through a complete example.

Why one page, and who reads it

Long requirement documents made sense when building was slow and expensive and every change needed a contract. For a first version, the cost of being wrong is small and the cost of being slow is large. One page forces you to choose.

The same page serves four readers. You, to stop the idea shifting every day. A builder, human or AI, who needs clear instructions. Early users, who can tell you whether the main flow matches their life. And a co-founder or adviser, who can poke holes in it in five minutes.

A spec is not a business plan

Leave out the market size, competitors and revenue model. Those matter, but they belong in a different document. The spec describes the product people will touch, nothing else.

Write it after a few conversations, not before

A spec written from imagination describes the app you want. A spec written after talking to five potential users describes the app they need. Rob Fitzpatrick’s The Mom Test is the standard guide to having those conversations without fishing for compliments: ask about their life and what they did last time, not whether they like your idea.

The template

Copy this into a document and fill in the brackets. Keep each section as short as the quick-start table suggests. If a section runs long, you are probably describing version two.

  • App name (working title): [name]
  • Problem: [Specific people] need to [task] but today they [workaround], which [cost: time, money, errors, frustration].
  • User: The first version is for [one type of person], who [relevant detail about their situation].
  • Main flow: 1. [User arrives and does…] 2. […] 3. […] up to 8 steps, each one screen or action.
  • Screens: [list each page the main flow needs, plus sign-in].
  • Data: [Thing]: [detail, detail, detail]. Repeat for each thing the app remembers.
  • Rules: Who can see what. Who can change what. What happens automatically, and when.
  • Not in version one: [feature], [feature], [feature]…
  • Success: In the first [N weeks], [N people] will [complete the main action] at least [N times].
  • Open questions: [things you haven’t decided yet, and how you’ll find out].

How to fill in each section

Each section has one common trap. Here is how to avoid it.

Problem: name the workaround

The strongest problem statements mention what people do today. A workaround proves the problem is real enough that people already spend effort on it, and it tells you what you have to beat. “Small landlords track repairs in text messages and lose track of who fixed what” is stronger than “Landlords need better repair tracking.”

User: pick one, even if many could use it

Most ideas could serve several groups. The first version should serve one. A narrow user lets you make decisions: a landlord with three units needs different things from a property manager with 300. You can widen later; you can’t learn from an app built for everyone.

Main flow: verbs, not features

Write each step as something the user does: “adds a repair request with a photo”, not “photo upload feature”. The flow should end at the moment the user gets value, the reason they came. If it takes more than eight steps, cut steps or split the flow.

Data and rules: where bugs hide

Builders and AI tools are good at screens and weaker at guessing your rules. Spell them out. Who owns each record? Can a tenant see other tenants’ requests? What happens when a request is marked done: does anyone get an email? A rule you didn’t write down is a rule the builder will invent.

Success: one number, set in advance

Pick a sign that people got value, not that they visited. Sign-ups are cheap; repeated use of the main action is not. Set the number before launch so you can’t talk yourself into a good result afterwards.

A complete worked example

Here is a filled-in spec for a small but real app: a repair tracker for small landlords. It fits on one page and could be built as a first version in days.

Problem, user and main flow

App name: FixList.

Problem: Landlords with one to ten units get repair requests by text, phone and email. Requests get lost, tenants chase for updates, and at tax time the landlord can’t find what was spent on each property.

User: The first version is for independent landlords with one to ten units who handle repairs themselves or call a handyman.

  • The landlord signs up and adds their properties and units.
  • The landlord sends each tenant an invite link by email.
  • A tenant opens the link, creates an account and submits a request: what’s wrong, where, a photo, how urgent.
  • The landlord gets an email and sees all open requests in one list, newest and most urgent first.
  • The landlord updates the status (seen, scheduled, done) and adds a note and the cost.
  • The tenant gets an email at each status change.
  • The landlord can view all repairs and costs per property for any date range.

Screens and data

Screens: sign in; landlord dashboard (open requests); property list and detail; invite tenant; tenant request form; tenant “my requests”; request detail; cost report.

Thing the app remembersDetails
LandlordName, email
PropertyAddress, owner (a landlord)
UnitLabel (e.g. 2B), property, current tenant
TenantName, email, unit
Repair requestUnit, tenant, description, location in unit, photos, urgency, status, landlord note, cost, dates created and closed

Rules

  • A landlord sees only their own properties, units, tenants and requests.
  • A tenant sees only their own requests, never other units’.
  • Only the landlord can change status, notes and cost.
  • Urgent requests send the landlord an email immediately; others are bundled in one daily email at 8am.
  • Each status change emails the tenant.
  • Photos are visible only to the tenant who uploaded them and their landlord.

Not in version one, success and open questions

Not in version one: payments or rent collection; a handyman marketplace; a phone app; text message notifications; multiple landlords per property; lease documents; tenant-to-tenant messaging; recurring maintenance schedules.

Success: within four weeks of launch, 10 landlords have invited at least one tenant, and at least 5 of them have closed three or more requests through FixList.

Open questions: Will tenants accept an account, or do they need a no-login request link? (Ask five tenants.) Do landlords want costs per property or per unit for taxes? (Ask the first ten landlords.)

Turning the spec into a build

A good spec makes the handover easy, whether you hand it to a person or a tool.

Handing it to a developer or freelancer

Send the page and ask them to read it back to you in their own words, then list what’s unclear. The questions they ask are gaps in the spec; add the answers to the page. Ask for an estimate per main-flow step, which makes it easier to cut a step if the total is too high.

Handing it to an AI app builder

AI builders work well from a spec because it is already structured as instructions. Paste the whole page, including the “not in version one” list, so the tool doesn’t add things you cut. Then build in passes: the main flow first, then rules, then emails. Test each rule yourself by signing in as two different users.

Keep the spec alive

When you change your mind, change the page first and the app second. A spec that drifts from the app stops being useful within a week. Date each version so you can see how your thinking changed.

A two-minute spec check

Before you build, run through these questions. Every “no” is a gap to fix.

  • Could a stranger tell, from the problem section alone, who would pay attention to this app?
  • Does the main flow end at the moment the user gets value?
  • Does every screen on the list appear in the main flow?
  • Is every piece of data on the list shown or used somewhere in the flow?
  • Does every type of user have a rule about what they can see and change?
  • Is there at least one tempting feature on the “not in version one” list?
  • Could you measure the success sign without asking anyone?

Common mistakes

These show up in almost every first spec. They are easy to fix once you look for them.

  • Writing features instead of steps: a list of “search, filters, profiles, notifications” with no order or purpose.
  • Describing two or three user types equally, which doubles the build and halves the learning.
  • Leaving out who can see what, so the first version shows everyone’s data to everyone.
  • No “not in version one” list, so every conversation adds a feature.
  • Design details (colours, fonts, logo) taking up space that should go to rules and data.
  • A success measure based on visits or sign-ups rather than people completing the main action.
  • Writing the spec once and never updating it as you learn.

If you’d rather not do this yourself

If you’d rather not turn the spec into an app by hand, an AI builder can take the page as written. Floot, which publishes this site, builds full-stack web apps from descriptions like the example above, and its plan mode writes a build plan from your spec for you to review before anything is built.

Frequently Asked Questions

What is an app spec?

An app spec (short for specification) is a document that describes what an app does: who uses it, the steps they take, the screens, the data it stores, and the rules about who can see and change what. A one-page spec covers just the first version.

How detailed should a spec be for a first version?

Detailed enough that someone else could build the main flow without asking you basic questions, and short enough to fit on one page. If it runs longer, you are probably describing more than a first version.

Is a spec the same as a PRD?

A product requirements document (PRD) is the term larger teams use for a fuller version, often with goals, research and edge cases. A one-page spec is a lightweight PRD for a single first version.

Should I include wireframes in the spec?

Rough sketches help, but keep them outside the one page or as a single image. The spec should make sense in words; sketches show layout, while the spec decides behaviour.

Can I give my spec to an AI app builder?

Yes. A clear spec is one of the best prompts you can give an AI builder. Include the “not in version one” list so it doesn’t add features you cut, and build the main flow before the extras.

What if I don’t know the answer to a section yet?

Put it under open questions with how you’ll find out, usually by asking a few potential users. Leaving it blank invites the builder to guess.

Sources