Building a static website with Claude: process and lessons
A client came to us with a folder of Word documents — a constitution, a mission statement, a code of conduct, an events programme — and no website. They needed something live within a few weeks, hosted on shared hosting they already had, and maintainable by a single non-developer committee member going forward. This is a record of how we used Claude to take them from documents to a deployed site, and what the process actually looked like.
The constraint that shaped everything
Before writing a line of code, we established the deployment constraint: the client used shared hosting via FTP. No build pipeline, no CI, no Git-connected host. That single constraint ruled out a CMS with a live admin panel (Decap CMS, for instance, requires a build pipeline and an auth backend that manual FTP hosting cannot provide) and pointed directly to a static site generator with a local build step.
We chose Astro. It outputs plain HTML, CSS, and minimal JavaScript, produces a dist/ folder whose contents can be uploaded directly by FTP, and is well within Claude's working knowledge. The decision was made in the first conversation and locked before any other decisions followed.
This is the discipline that made the project work: establish constraints first, let them eliminate options, then choose from what remains. A different hosting situation would have been a different project.
Compiling a knowledge base before touching the codebase
The client's source material was in Word documents — rich in content but not in structure. Before any design work or code, we had Claude read those documents and produce a single structured KNOWLEDGE_BASE.md file: the organisation's identity, mission, governance structure, membership categories, code of conduct, and events programme — all in one place, clearly sectioned, with explicit notes on which parts were legally sensitive and should not be paraphrased.
This step paid dividends throughout the build. Every subsequent conversation — design, content decisions, page copy — referenced the knowledge base rather than the original documents. Claude could answer questions about membership eligibility or governance structure from a single consistent source rather than re-reading documents each time. It also created a natural handover artefact: the knowledge base now lives alongside the site and serves as the source of truth for future content updates.
Design before implementation
With the knowledge base in place, we ran a structured design session. The output was a spec document covering: the page architecture (seven pages), the content model (including a typed events collection with a provisional-date flag), the brand token set (hex values sampled from the logo PNG files, since no brand guide existed), the component list, and the explicitly out-of-scope items for version one.
The out-of-scope list mattered as much as the in-scope list. Online membership sign-up, payments, a members-only area, and build automation were all things the client might eventually want — but including them in v1 would have doubled the build time and introduced dependencies (payment provider, authentication) that a first public site did not need. Naming them explicitly in the spec document meant they could not quietly creep in during implementation.
Brand tokens were extracted by sampling the logo PNG files directly — the organisation had no brand guide, but the logo files contained exact values. Claude read the pixel colours and produced the CSS custom properties. A darker derived shade was needed for link text on white backgrounds to meet WCAG AA contrast; that decision was made in the design session and recorded in the spec rather than discovered during an accessibility audit after the fact.
The implementation plan
The approved spec became an implementation plan: seventeen numbered tasks, each broken into steps, each step with an expected outcome and a commit. The plan was written before any code was touched.
This structure matters for AI-assisted development specifically. A large language model works best with well-defined, bounded tasks. "Build a website" is too large; "create the EventCard component with these props and this style" is the right size. The plan converted a whole project into a sequence of small, verifiable units, and each unit was completable in a single focused exchange.
The events content collection is worth noting as a design decision. Rather than hardcoding events as HTML, we defined a typed Astro content collection: each event is a Markdown file with a validated frontmatter schema (title, dates as free text to accommodate "TBC" and date ranges, a boolean provisional flag, a category enum, an optional location, and a sort order). The Events page then queries the collection, groups by category, and renders event cards — with "Provisional" badges on any entry where the flag is set. Adding or updating an event is now an edit to a single Markdown file, with no code change required. That was the right content model for a committee-maintained site.
Testing on a static content site
A static content site is not the place for unit tests. There is no application logic to test — only content to verify renders correctly. The testing approach was build-based: npm run build is a real correctness signal because Astro type-checks content collection schemas and fails on broken imports. A green build meant the content model was valid. Render verification was manual: run npm run preview, open each page, confirm the expected content and brand appeared. Accessibility was checked via Lighthouse on the home and events pages. This is appropriate test design for this class of project.
Handover
The final deliverable was not just the site — it was a README and a launch checklist. The README explained prerequisites, local development, how to edit each type of content, and the exact FTP publish steps. The launch checklist covered the remaining real-world unknowns: DNS configuration, the CIC registration number to fill in the footer, confirmation of provisional event dates, and the Constitution PDF to export and add before going live.
Separating "build complete" from "launch ready" matters. The site was deployable and correct in every dimension we could control. The remaining items were genuine external dependencies — things only the client could confirm. Making that distinction explicit prevented the project from sitting in an ambiguous "almost done" state.
What Claude actually did
Claude read the source documents and produced the knowledge base. It ran the design session, asked the clarifying questions that surfaced the FTP constraint and the CMS decision, and wrote the spec. It wrote the implementation plan. It wrote all the Astro components, pages, and CSS — component by component, task by task, with a commit at the end of each. It suggested the events content collection model and wrote the Zod schema. It flagged the contrast issue with gold on white before the build, not after. It wrote the README and the launch checklist.
What it did not do: make decisions about scope, hosting, or what was in or out of version one. Those decisions were made in conversation, with the constraints on the table, and locked in writing before the build started. The spec document is what made the implementation reliable — Claude built what the spec described, and the spec described what the client actually needed.
The total build, from first conversation to a committed, deployable site, was a single working day.