Build an Astro Website with Codex

What you get

A working, responsive Astro site with typed content, tested pages, and a live deployment. The same workflow works for marketing sites, blogs, and content MVPs.

Who this is for

This scenario is for anyone who has said “I want a site” and then watched an agent produce a generic template. The workflow treats the site as a product with requirements, structure, design direction, and acceptance criteria, so the agent’s output is reviewable at every stage instead of being a surprise at the end.

How the phases connect

Planning converts the goal into a page tree and a scope the agent cannot silently expand. Design fixes the visual direction as tokens before any component exists. Build implements from the content model, so adding a page never means editing components. Verify runs type checks, builds, links, and browser screenshots. Ship deploys the production build and re-checks the live URL.

What makes this scenario different from a template

The same agent that writes the code also runs the acceptance checklist. That closes the loop: the agent cannot claim “done” until the checks pass, and a human reviews the evidence. If you already have the Astro CLI workflow memorized, this scenario still pays off because it adds the verification layer most agent-built sites skip.

Prerequisites

Node.js 20 or newer installed
A coding agent (Codex, Claude Code, or Cursor) with file access to the project
A Git repository, either new or existing
A hosting account with a domain, or the freedom to use a default subdomain

Skill tree

The phases read left to right on desktop and top to bottom on mobile. Capability nodes are tool-neutral; the skills under them are the concrete options.

Goal

Planning

Capability

Requirement Planning

Turn a fuzzy goal into a concrete set of requirements the agent can act on.

Codex Astro MVP Research to Plan

Capability

Information Architecture

Structure content and navigation so users and agents can find what they need.

Design

Capability

Visual Design

Give the product a coherent visual language including color, type, spacing, and component states.

Build

Capability

Frontend Development

Implement the interface in real, maintainable code with the chosen stack.

Codex Astro MVP

Capability

Content Modeling

Define content types, fields, and validation so content stays structured and queryable.

Codex Astro MVP

Verify

Capability

Testing

Verify behavior, links, layout, and performance with automated and manual checks.

Codex Astro MVP Link Checker Visual Review

Ship

Capability

Deployment

Ship the product to a public URL with repeatable, reversible steps.

Codex Astro MVP

Every phase feeds into the scenario validation checklist below.

Capability breakdown

Each node states why it exists, what it takes in, what it produces, what can go wrong, and how it is accepted.

Requirement Planning

Agents fail when the goal is vague. Requirement planning converts "make me a site" into scope, constraints, target users, and acceptance criteria before any code is written.

Input

-A one-line goal or problem statement
-Known constraints (budget, time, platform, audience)
-Existing assets or content

Output

-Scoped requirement list with priorities
-Out-of-scope list
-Success criteria the build can be measured against

Risks

-Scope creep when requirements are written as feature wish lists
-Confusing user wants with user needs
-Skipping the step entirely and letting the agent improvise

Acceptance

-Every requirement is testable and either in scope or explicitly out of scope
-The team agrees on what "done" means before execution starts

Information Architecture

A site or workflow fails when its structure does not match how people actually think about the task. IA defines the skeleton that pages, menus, and links hang on.

Input

-Content inventory or list of pages
-User task list from requirement planning

Output

-Site map or page tree
-Navigation model and URL scheme
-Content grouping rules

Risks

-Organizing by tool brand instead of by user task
-Deep nesting that buries important pages
-Ignoring URL and redirect implications for SEO

Acceptance

-A user can reach any primary page in three clicks or fewer
-URLs are stable, readable, and match the tree
-The structure survives adding new content without rework

Visual Design

Design is not decoration. A consistent visual system makes hierarchy legible, builds trust, and prevents the generic template look users have learned to ignore.

Input

-Brand or design direction notes
-Component inventory from the information architecture
-Accessibility requirements

Output

-Design tokens (color, type, spacing, radii)
-Component states (hover, focus, active, disabled, empty)
-Responsive behavior rules

Risks

-Copying template aesthetics instead of deriving a system
-Color as the only signal for status
-Designing only the desktop breakpoint

Acceptance

-Tokens are documented and used consistently across pages
-Text contrast meets WCAG AA
-Layout collapses cleanly at 390px, 768px, 1024px, and 1440px

Frontend Development

The design only exists once it ships as semantic, accessible, fast HTML and CSS. Frontend development is where structure, design, and content meet.

Input

-Approved design tokens and wireframes
-Content model and sample content

Output

-Working pages and components
-Responsive, keyboard-accessible interaction
-Buildable, lintable code

Risks

-Hand-waving accessibility or performance
-Hardcoding content that should come from a CMS or content layer
-Shipping components that only look right on the developer's screen

Acceptance

-Production build succeeds with no type errors
-Core pages readable without JavaScript
-No horizontal overflow at 390px

Content Modeling

Structured content is the difference between a static page and a growing knowledge base. A schema makes content machine-readable and future-proof for APIs and agents.

Input

-Content types discovered during information architecture
-Examples of real content

Output

-Typed schemas for each content type
-Validation rules and required fields
-Sample entries that pass validation

Risks

-Schemas so strict they block legitimate content
-No validation, so bad data silently ships
-Modeling the current page layout instead of the content itself

Acceptance

-Every content type has a schema that fails loudly on invalid data
-Adding a new entry requires no code changes
-Content renders identically in list and detail views

Testing

Agents produce confident output that is often wrong in small ways. Testing is the checkpoint that catches broken links, type errors, overflow, and regressions before users do.

Input

-The built site or workflow
-Acceptance criteria from requirement planning

Output

-Test report with failures and screenshots
-Fix list prioritized by severity
-Verified acceptance checklist

Risks

-Testing only the happy path
-Skipping real browser rendering and trusting source code
-Treating "it builds" as "it works"

Acceptance

-Automated checks cover type checking, build, links, and key page loads
-Browser tests run at desktop and mobile widths
-Every acceptance criterion maps to a check that passed

Deployment

A site that only runs locally does not exist. Deployment makes the work usable and testable in production, with rollback if something breaks.

Input

-A production-ready build
-Hosting account and domain

Output

-Live public URL
-Repeatable deploy command or pipeline
-Rollback path documented

Risks

-Deploying from a laptop with no reproducible command
-Skipping the final smoke test on the live URL
-Environment differences between local and production

Acceptance

-The deploy command works from a clean checkout
-The live site passes the same smoke tests as local
-Previous version can be restored in one step

Recommended build

A ready combination of skills for this scenario, with the order and checks included.

Minimal build

Codex Astro Starter

The smallest complete path from site goal to deployed Astro site, with verification attached at the end.

Skills: 4 skills
Steps: 8 steps

Execution order

The recommended sequence from the Codex Astro Starter build.

1
Write the requirement list and out-of-scope list, and get it approved
2
Define the page tree and URL scheme
3
Set the visual direction as tokens
4
Scaffold Astro with TypeScript and the content collections
5
Build pages from the content model
6
Run type check, build, and link checks
7
Capture screenshots at 390 and 1440px and fix findings
8
Deploy the production build and re-run the smoke checks on the live URL

Open the full build

Validation checklist

The project starts locally with the documented command
Type checking and the production build pass from a clean checkout
No horizontal overflow at 390px on the main pages
All internal links resolve with no 404s
Search works against the real content index
The deployed URL passes the same smoke checks as local
README documents how to run, extend, and deploy

Common failures

The agent installs dependencies without pinning versions, and the build breaks later

Commit the lockfile and verify the build from a clean install

Content is hardcoded into components, making the site impossible to extend

Put all content in typed content collections from the start

The site looks fine on desktop but overflows or collapses on mobile

Add browser screenshot checks at 390, 768, and 1440px to the acceptance loop

The site builds locally but fails on the host due to platform differences

Deploy the production build artifact, not the dev server

Give this brief to your agent

Copy the structured brief, adapt the out-of-scope list, and ask the agent to return the checklist with evidence.

Agent task brief

Goal: A working, responsive Astro site with typed content, tested pages, and a live deployment. The same workflow works for marketing sites, blogs, and content MVPs.
Scenario: Build an Astro Website with Codex
Categories: Coding, Deployment
Difficulty: intermediate

Prerequisites:
- Node.js 20 or newer installed
- A coding agent (Codex, Claude Code, or Cursor) with file access to the project
- A Git repository, either new or existing
- A hosting account with a domain, or the freedom to use a default subdomain

Capabilities in execution order:
Phase: Planning
- Requirement Planning
- Information Architecture
Phase: Design
- Visual Design
Phase: Build
- Frontend Development
- Content Modeling
Phase: Verify
- Testing
Phase: Ship
- Deployment

Recommended build: Codex Astro Starter
Execution steps:
1. Write the requirement list and out-of-scope list, and get it approved
2. Define the page tree and URL scheme
3. Set the visual direction as tokens
4. Scaffold Astro with TypeScript and the content collections
5. Build pages from the content model
6. Run type check, build, and link checks
7. Capture screenshots at 390 and 1440px and fix findings
8. Deploy the production build and re-run the smoke checks on the live URL

Validation checklist:
- [ ] The project starts locally with the documented command
- [ ] Type checking and the production build pass from a clean checkout
- [ ] No horizontal overflow at 390px on the main pages
- [ ] All internal links resolve with no 404s
- [ ] Search works against the real content index
- [ ] The deployed URL passes the same smoke checks as local
- [ ] README documents how to run, extend, and deploy

Out of scope:
- Sites that need a backend, database, or real-time features
- Teams that want the agent to design without any direction

Evidence required:
- Checklist with pass/fail per item
- Screenshots at the agreed viewports
- Build or run log from a clean checkout