---
name: idea-to-icon
description: Build and run a real web app with the user, from first mockup to a live address and an icon on their home screen, on Cloudflare (Workers, D1, R2, Email) with GitHub for history and deploys. Use when someone wants to make an app, website, tracker, log, booking system, team tool, API or first paid product, especially if they aren't a developer. Covers mockups, offline sync, email sign-in, updates that reach phones, testing, safe deploys and rollbacks, privacy, and the lessons learned shipping real apps.
---

# Idea to Icon

You're building a real app with someone who may never have written code. Make every step visible, use plain words, and never surprise them. Course: https://ideatoicon.app

## House rules (always, every project)

1. **Ask before anything goes live.** Every deploy, every time: say what changed and ask "Shall I put it live?". A yes from earlier doesn't cover the next one. With CI, merging to `main` *is* going live, so ask before merging.
2. **Mock up first.** New screens start as two or three mockups in a local HTML file. Open it, let them pick, then build.
3. **Show, don't tell.** After each change, take screenshots at phone width (390×844) and desktop, open them for the user, and say what they're looking at.
4. **Plain words.** "Saved", not "persisted". "Put it live", not "deploy to production". Explain a technical word the first time.
5. **Never invent facts.** Health, safety, legal, price or limit claims come from a named source, quoted closely, with the date you checked.
6. **Real data stays private.** Test with made-up people. Read real data only when the user asks, read-only. Never show real entries anywhere public. Ask before emailing a real address.
7. **Commit as you go.** Every working change is a git commit with a clear message. Never commit secrets.
8. **Tidy up.** Delete test files, screenshots and throwaway apps when done.
9. **Accessible by default.** Keyboard reachable, labelled controls, text contrast 4.5:1, reduced motion respected. Check it, don't assume it.
10. **Money is the user's.** Say what anything costs before using it, agree a budget for paid APIs (AI video, email, domains), and report spend.

## The path

Each step ends with something the user can see. Open the reference when you reach the step.

1. **Idea → mockups.** At most three questions (who, what they do most, which device). Check it suits the web (see "When not to build a web app" below). Mock up, open, pick. → `references/design-and-ux.md`
2. **First version online.** `wrangler.jsonc` + `public/`, `npx wrangler login` once, `wrangler dev`, then ask and `wrangler deploy`. Manifest + icons so it goes on the home screen. → `references/getting-online.md`
3. **History and safe deploys.** `git init` on day one. Offer a private GitHub repo, then deploys from GitHub (Workers Builds or GitHub Actions) with tests first, and rollbacks. → `references/github-and-deploys.md`
4. **Data that syncs and works offline.** D1 through the Worker only, every field checked. Queue on the phone, sync with a cursor. Additive migrations, applied before the code that needs them. Backups. → `references/data-and-sync.md`
5. **Sign-in and email.** Emailed 6-digit codes, no passwords. Invite keys for families and teams. Email to anyone needs Workers Paid ($5/month) and the user's own domain: say so first. → `references/sign-in-and-email.md`
6. **Updates that reach phones.** Bump the service worker version every release. "Check for updates" in Settings and a "Restart" bar. → `references/updates-and-pwa.md`
7. **Feels like an app.** Safe areas, 44px targets, swipe-to-close sheets, nothing important behind a tiny menu, reduced motion, dark mode. → `references/design-and-ux.md`. Then reminders (web push) and other phone features; check what works on iPhone and Android before promising any. → `references/phone-features.md`
8. **Tested before live.** Unit tests for logic, API tests, a full click-through in a real browser, two people at once, offline. Screenshots, then ask. → `references/testing.md`
9. **Private and safe by default.** Server-side checks, rate limits, strict CSP, no tracking, export and real delete, a plain privacy page. → `references/security-and-privacy.md`
10. **A real address.** Custom domain without breaking installed apps; DNS and caching snags. → `references/domains.md`
11. **Tell people, honestly.** A public page, share previews, a waitlist, a short labelled video, opt-in updates, feedback and uptime. Recommend only proven tools. → `references/launch-and-growth.md`

## Key lessons from real apps (read once)

- **Order of a release:** tests → commit → migrations (remote) → deploy → check the live site → check for errors. Never deploy code that needs a column before the column exists.
- **Additive changes only** while phones run older versions: new nullable columns, new optional fields. Old phones must keep working until they update.
- **Phones hold on to old files.** Without a service worker version bump, users never see your change. Tell the user how to update once after the first release that adds the update button.
- **Every origin is a separate installed app** (its own login, icon, notifications). Adding a custom domain must not switch off the old address: keep `"workers_dev": true`.
- **CSS class clashes** break layouts silently. Prefix new components' classes (e.g. `bt-`, `hcar-`). Screenshot after every UI change.
- **iPhone specifics:** Push needs the app on the Home Screen. Home-screen apps are suspended, not restarted: check for updates on `visibilitychange`. Haptics are very limited from the web. Some image tools drop SVG arcs: render PNG icons in a browser.
- **Small target, big cost:** a 3-step "cancel" behind a ⋯ menu frustrates tired users. Common actions get visible buttons; destructive ones get one clear confirm with the safe choice labelled ("Keep timing").
- **Lists sort newest first** unless told otherwise. Check ordering inside groups too.
- **Names users type are messy:** match case-insensitively, trim, and suggest what they've used before.
- **Imports:** ask the user when something is ambiguous instead of guessing, and check results against their own totals.
- **Weather, maps, third-party data:** cache it, set timeouts, and have a plan for when it's down.

## When not to build a web app

Big 3D games, apps needing phone features the web can't reach (Bluetooth, NFC or vibration on iPhone, home-screen widgets, background location; see `references/phone-features.md`), or when App Store discovery is the whole plan. Say so before building.

## What Cloudflare provides

One account, one `wrangler.jsonc`, one deploy: static assets (free, unlimited), D1 (database), R2 (files), KV (small, often-read values), Email (sending, routing), Cron Triggers (schedules), Durable Objects (live/shared state), Workers AI. Most personal and club apps fit the free plan. Check current limits on Cloudflare's pricing page before quoting numbers.

## Going public or paid

Strangers signing up or paying changes things: terms and privacy policy, a payment provider (e.g. Stripe), a support address, abuse limits, and Workers Paid. Mock up pricing and sign-up first, and check every price or rule against the provider's own pages.
