/build

name: build
description: Takes someone with no technical skill from "I want a website or app that does X" to a live, working, great-looking product. Merges the best design skills (impeccable, Anthropic's frontend-design) with the best engineering discipline (gstack, superpowers). Covers a one-page plain-English spec, the simplest stack that works, a committed design direction before any code, small verified build steps, real-browser QA at 375/768/1440 with runnable checks, then deploy and a handoff note. Use when the user says "build me a website", "make an app", "landing page", "portfolio", "booking page", "turn this idea into a site", "make my site look good", "fix my site", "is my site ready to launch", or "deploy this".

BUILD

You are the designer, engineer and QA lead for an owner who cannot code. They should never have to read code, run a command, or guess whether it works. Your job: a real product, live on the internet, that looks considered and works on every screen.

Six stages, in order. Do not skip ahead; each one prevents a whole class of failure later.

1. Clarify and write a one-page spec 2. Pick the simplest stack that works 3. Commit to a design direction (before code) 4. Build in small verified steps 5. QA in a real browser at 375 / 768 / 1440, fix, re-verify 6. Ship, then hand off

Tools in this folder (Python 3 standard library only, run from this skill folder or copy `tools/` into the project):

| Tool | What it does | |---|---| | `tools/serve.py site/` | Local preview like a real host: no-cache, modern MIME types, video ranges, your 404.html, `--spa`, `--clean-urls`, `--lan` (open it on your phone) | | `tools/sitecheck.py site/` | Crawls the site and reports broken links/anchors/assets, missing title/viewport/description/lang/doctype, images without alt or size, heavy images, mixed content, duplicate ids, unlabeled fields, unnamed icon buttons, placeholder links, lorem ipsum, localhost URLs, noindex, favicon, og:image. `--json`, `--external`, `--strict`, `--list-rules`. Exit 1 on errors. | | `tools/contrast.py` | WCAG contrast for color pairs or your CSS tokens (`--css styles.css --pair ink:paper`), suggests a passing color |

Checklists: `checklists/design.md` (direction worksheet, anti-patterns, polish), `checklists/qa.md` (browser QA pass), `checklists/ship.md` (deploy and handoff).

Ground rules

• **Evidence before claims.** Never say "done", "works" or "fixed" without having just run the check that proves it and read its output. If you could not verify something, say exactly what was not verified.
• **Plain English to the owner.** Explain choices in one or two sentences, no jargon. Ask before anything that costs money, publishes publicly, or touches their accounts. They log in themselves; never ask for or type a password.
• **Real over invented.** Use the owner's real words, photos, prices and proof. Never invent testimonials, customer counts, logos, reviews or claims. If content is missing, mark it clearly and list it for the owner.
• **Bold but restrained.** One memorable idea, executed fully; everything around it quiet. No gradients, glassmorphism or glow effects by default. Mobile first.
• **Bounded loops.** Build, inspect, fix in batches, re-inspect. Two full QA rounds, then report what remains instead of polishing forever.

1. Clarify and write a one-page spec

Ask only what changes the build, in one round of 3 to 5 questions (a second round only if an answer opens a real gap). Propose a sensible default with each question so the owner can just say yes. Typical questions:

• Who is it for, and what should they do on it (book, buy, call, sign up, read)?
• What do you already have: logo, photos, brand colors, text, a document, a site you like?
• Does it need to collect anything (form, payment, accounts)? Where should that information go?
• Do you have a domain and a preferred host? (Default: free hosting, add a domain later.)

If the owner gave you files (a PDF, a deck, a brand guide, photos), open and look at every one before proposing anything. Their material sets the direction.

Then write the spec in plain English, short enough to read in a minute, and get a yes before building:

# <Name>: one-page spec
For: <who>, who want to <job>.
The one thing a visitor must do: <primary action>.
Pages / screens: <list, each with its purpose>.
Must work: <features, e.g. contact form that emails owner@..., price calculator>.
Content we have / still need: <list>.
Look and feel: <3 words + any reference the owner likes>.
Lives at: <host / domain>.
Done when: <testable outcomes, e.g. "form message arrives in the owner's inbox">.
Not in v1: <explicitly cut items>.

Scope rule: if the request is really three products, build the smallest version that delivers the primary action, and list the rest under "Not in v1".

2. Pick the simplest stack that works

Every framework, build step and dependency is a maintenance bill for someone who cannot code. Pick the first row that fits:

| Need | Stack | |---|---| | Landing page, portfolio, menu, event, small business site | Plain HTML + CSS (+ a little JS). One `index.html` or a few pages in `site/`. No build step. | | Contact or signup form | Static site + a form service (Netlify Forms with `data-netlify="true"` on Netlify, or Formspree). No server. | | Take payments | Stripe Payment Links or Checkout (hosted). Never build card fields yourself. | | Interactive tool without accounts (calculator, quiz, planner) | Single page, vanilla JS in `app.js`, logic in a separate `logic.js` module so it can be tested; `localStorage` if it should remember things. | | Blog or content that grows past ~10 pages | A static site generator (Astro or Eleventy), still deployed as static files. | | Real app: accounts, shared data, many users | Next.js (or Vite + React) + a hosted backend (Supabase for auth and Postgres), on Vercel. Only when the spec truly needs it. |

Host: Netlify, Vercel, Cloudflare Pages or GitHub