A static website is a set of files that a server can deliver without generating each page on request. That makes it a strong default for a small company site whose main job is to explain an offer, publish evidence, and provide a trustworthy route to contact. It does not make security, accessibility, privacy, or maintenance automatic.
The intended reader is a founder or developer with an approved design direction, real content, and permission to build. The outcome is a versioned source project and a verified static artifact ready for hosting. Examples use Astro and pnpm, but the artifact and review principles also apply to plain HTML or another static-site generator. Source review: 24 August 2026.
Decide whether static output fits
The web platform separates structure in HTML, presentation in CSS, and behavior in JavaScript. MDN’s web standards model is a useful introduction to those layers. A static generator produces those browser-facing assets ahead of time, usually during a build.
Static output is a good fit when pages can be produced from versioned content and code before a visitor requests them. Typical examples include a home page, service pages, company information, articles, policies, and contact instructions.
It may be insufficient by itself when the experience requires authenticated accounts, private personalized data, live inventory, server-validated transactions, or privileged integrations. You can combine static pages with carefully chosen services or server functions, but every addition changes the privacy, security, reliability, and operational model. Do not call the result “just static” after adding runtime dependencies.
Make the decision explicit:
Required routes:
Content update frequency and owner:
Visitor data collected:
Authenticated or personalized behavior:
Forms and their processing destination:
External scripts and services:
Build-time secrets, if any:
Runtime services, if any:
Reason static output is sufficient:
Condition that would require a different architecture:
Never put a private API key into client-side code, generated HTML, a public repository, or a browser-readable environment variable. If a feature needs a secret, it needs an appropriate trusted server-side boundary or a provider designed for the task.
Freeze the implementation contract
Start from the selected webpage direction and its decision record, not from an open-ended request to “build a modern site.” Convert that direction into an implementation contract another developer can inspect.
Include:
- exact route list and canonical URL rules,
- content source and content owner for every page,
- component inventory and all required states,
- responsive behavior and supported input methods,
- semantic structure and accessibility acceptance checks,
- image purposes, dimensions, formats, and alternatives,
- font sources, permitted weights, and fallback stack,
- JavaScript budget and interactions that justify it,
- metadata, social previews, sitemap, and robots requirements,
- forms, analytics, embeds, cookies, and privacy decisions,
- build command, output directory, and supported runtime,
- browser support and manual test matrix.
Keep verified public claims separate from placeholder content. A build agent may draft a missing error message or navigation label, but it must not create a customer, result, certification, office, policy, price, or legal promise. Use visible markers that fail review, not plausible filler that might ship.
Choose plain HTML or a generator deliberately
For a tiny site with a few stable pages, plain HTML and CSS can be the clearest system. There is no rule that a professional website needs a framework. Repeated navigation, metadata, article collections, translations, and structured content are reasons to consider a generator because they benefit from templates and validation.
Astro produces static output by default unless the project is configured for another rendering mode. Its current output configuration reference defines the available modes. Confirm the current runtime requirements and installation steps in Astro’s official setup guide when creating the project, rather than copying an old command or version from an AI response.
A typical new project begins with:
pnpm create astro@latest
cd your-project
pnpm install
pnpm run dev
Commit the generated lockfile and record the runtime version used by local development and CI. Run third-party starters, integrations, and install scripts only after reviewing their source, permissions, maintenance state, and dependency impact. A popular template is still executable software.
Give the project an inspectable structure
Use a structure that separates content, reusable presentation, routes, and public files. For example:
src/
components/
content/
layouts/
pages/
styles/
public/
tests/
astro.config.mjs
package.json
pnpm-lock.yaml
Files in src/pages/ define routes in a conventional Astro project. Reusable page chrome belongs in layouts and components. Content should remain editable without searching through decorative markup. Files in public/ are copied as-is, so optimize and name them deliberately and never place source secrets there.
Do not create abstractions only because AI can. A component is useful when it expresses a meaningful repeated pattern, owns behavior or accessibility semantics, or prevents inconsistent changes. A one-off wrapper split across five files can make a small site harder to review.
Implement in bounded passes
Ask the coding agent to work in small, reviewable increments. Give each pass an input, permitted files, acceptance checks, and a stop condition.
One practical sequence is:
- establish project configuration, shared layout, tokens, and global styles;
- build the header, navigation, footer, and skip link with keyboard states;
- implement one representative page using approved real content;
- verify semantics, narrow-screen behavior, and asset loading;
- extract only proven reusable components;
- add remaining routes and metadata;
- add tests, error states, and build-artifact checks;
- remove unused dependencies, scripts, styles, and placeholder content.
A useful implementation prompt is concrete:
Implement only the home route from the supplied contract.
Use the supplied content IDs verbatim and preserve claim qualifiers.
Use semantic HTML before ARIA and CSS before client-side JavaScript.
Do not add dependencies, analytics, forms, fonts, trackers, or remote assets.
Implement keyboard and responsive states described in the contract.
Run the named checks. Report modified files, assumptions, and unresolved gaps.
Stop if the contract conflicts with the repository or lacks required content.
Review the diff after every pass. A rendered screenshot can hide invalid links, duplicated IDs, poor document structure, leaked data, inaccessible controls, or an unexpected dependency.
Build semantics and accessibility into components
Every page needs a meaningful title, one coherent main topic, useful landmarks, descriptive links, and a reading order that still makes sense without CSS. Use native buttons for actions and links for navigation. Add ARIA only when native HTML cannot express the required semantics and behavior.
For images, decide whether the image communicates information, performs a function, or is decorative. Write alternative text from that purpose. Do not use an AI-generated visual description automatically. It may emphasize irrelevant details or miss the information the page depends on.
At minimum, manually check:
- skip-link behavior and visible keyboard focus,
- navigation at narrow widths and high zoom,
- heading and landmark structure,
- link purpose outside surrounding visual context,
- contrast and non-color cues,
- form labels, instructions, errors, and success state,
- motion preferences and pause controls where relevant,
- reading order with styles disabled or altered.
Automated accessibility tools can find specific failures. They cannot decide whether the content is understandable, the alternative text is useful, or the interaction works with assistive technology. Keep the human test in the release criteria.
Treat forms and external services as architecture
A static HTML form has nowhere to send data unless you provide an endpoint or a hosting feature. Choose that path deliberately. Document the data collected, purpose, recipient, retention, abuse protection, failure behavior, user notice, and who can access submissions. Test it in the deployed environment, because a local success screen does not prove delivery.
Avoid embedding a large third-party service when a normal link, email address, or privacy-preserving workflow meets the need. Each analytics tag, chat widget, map, font host, video embed, and scheduling tool can add requests, data disclosure, consent questions, failure modes, and layout cost.
If the business brief does not authorize analytics or a contact processor, do not let the build agent choose one. That is a product and privacy decision.
Make metadata factual and route-aware
Generate page titles and descriptions from the approved content, then review them as public claims. Add canonical links only after the production URL and trailing-slash policy are known. Social previews need stable absolute URLs in production, appropriate image dimensions, and truthful text.
Create a useful not-found page and verify internal links. If routes have changed, record redirects for the hosting layer rather than leaving old links broken. A sitemap helps discovery, but it does not repair bad information architecture or guarantee indexing.
Use structured data only when the visible page and real organization satisfy the relevant vocabulary. Generated ratings, reviews, prices, locations, people, and events are no more acceptable inside JSON-LD than in visible copy.
Control performance before optimization
Set budgets based on the design decision: image bytes, font files and weights, client-side JavaScript, third-party requests, and expected page count. Prefer responsive images with explicit dimensions, modern formats where supported by the workflow, and no asset larger than its display purpose requires.
Ship little or no client JavaScript when the interaction does not need it. Remove dependencies that duplicate browser features or a few lines of understandable code. Self-hosting a font can improve control but still carries licensing, subset, caching, and file-size responsibilities.
Measure the built pages in representative conditions. Do not claim a performance score from source code, a design file, or a single local run. Record the tool, route, device profile, build commit, date, and whether the result is laboratory or field data.
Inspect the artifact, not only the source
For a conventional static Astro project, the production commands are:
pnpm run build
pnpm run preview
The default build output is dist/. Astro’s deployment guide describes the build step and common host configurations. preview is for checking the build locally, not a production hosting server.
Audit dist/ before deployment:
- expected HTML routes exist and unexpected routes do not,
- internal links and asset paths resolve under the intended base URL,
- no secret, local path, draft, source map, or private content leaked,
- page titles, canonical links, language metadata, and social cards are correct,
- images have dimensions and alternatives,
- the not-found behavior and redirect manifest are prepared,
- the site works with JavaScript disabled where no interaction requires it,
- the output is reproducible from the committed source and lockfile.
Security headers such as Content Security Policy are normally delivered by the host or edge layer, not guaranteed by the static files alone. The OWASP HTTP Headers Cheat Sheet explains their security purposes, while MDN’s CSP guide covers policy delivery and behavior. Configure and test those controls during deployment instead of adding an unverified meta tag and declaring the site secure.
The finished deliverable is the source commit, lockfile, successful checks, and inspected dist/ artifact. Keep the decision record from the company launch brief linked to the implementation. The next hosting step should publish this exact artifact, not rebuild an unreviewed variation from another prompt.
