/06-frontend

name: headless-step-frontend
description: "Step 6 (frontend) of the Hostinger Headless flow. Builds the website that renders the backend's content. Figures out (or confirms) the framework — defaulting to Next.js SSR — implements the look already chosen in design.md (the design step's contract), and builds the source into src/. Only ask for the clarifications you actually need."

headless-step-frontend

Build the site's frontend against the backend from `site.json`, implementing the look the design step already chose and wrote to **`design.md`** (plus the logo in `brand/`). The design is decided; this step is where it becomes real code. There's no per-framework recipe — use good judgement, follow `design.md` as the contract, and ask only for the clarifications you genuinely need. **Out:** source in the site workspace `~/.hostinger/<domain>/src/`.

> ## ⚠️ Build mode: "Bring your own frontend"? Read this first (any backend) > Read `brief.md` → **Build mode**. When it is **Bring your own frontend**, the user already has a > frontend (the project in the folder the command was run in) and this step **wires it to the backend > from `site.json` — it does not scaffold a new project and there is usually no `design.md` to > implement** (the design step deferred to the user). **Use their project as the source**: copy or > point `~/.hostinger/<domain>/src/` at it, keep its framework and UI, and collaborate on changes at > the user's direction (vibe-code with them). Your job is to connect it to the live backend (WordPress > `wp/v2` reads, the WooCommerce/Ecommerce Store API, env/keys) and make it deployable (set > `engines.node` to `22`, remove any `.htaccess`), then hand off to deploy. This generalises the Webapp > "existing app" case below to WordPress and Ecommerce too. When **Build mode is "Agent designs and > builds"**, ignore this box and proceed normally (scaffold + implement `design.md`).

> ## ⚠️ Webapp backend? Read this first > A `webapp` brief has **no CMS/store and no `content-model.md`** — the app owns its own data (its own > API, or the MySQL database recorded in `site.json → database`). It comes in two shapes, decided back in > **refine**: > > - **An existing app the user brought to deploy** (refine routes "deploy my app" here). **Use their > project as the source** — copy/point `~/.hostinger/<domain>/src/` at it and keep its own framework and > UI. **Do not scaffold a new project, and do not re-implement `design.md` over it** (so **the design > step does not apply** to an app that brings its own UI). Your job is only to make it deployable: set > `engines.node` to `22`, remove any `.htaccess`, wire its data/env, then hand off to deploy. **Skip the > Step 2 design pass**, and ignore the `content-model.md` requirement in Step 3. > - **A new app built from the brief.** Scaffold and build it from `brief.md` (and `design.md` if the > design step produced one — design *does* run for a from-scratch app). Its data is owned by the app, so > there is still **no `content-model.md`** to bind against. > > Framework choice (Step 1), the build, and hand-off (Step 4) apply to both. The per-backend bullets in > Step 3 are **WordPress / WooCommerce / Ecommerce only** — for a webapp follow the Webapp bullet there.

Step 1 — Pick the framework (guess → default → confirm)

**The rendering is already decided in `brief.md` → Rendering** (SSR or SSG, set during refine). Honour it, and the backend constraint:

• **Ecommerce → SSR required** (carts/search need per-request rendering). Any SSR framework works —

Next.js is the default, not a requirement (Express, Nuxt, SvelteKit, etc. are all fine).

• **WordPress + WooCommerce → SSR required** (same reason — cart/checkout need per-request rendering).
• **WordPress → SSG (Astro)** when the brief says SSG, otherwise **SSR (Next.js default)**.
• **Webapp → the app's own stack.** An **existing app** keeps its current framework (don't impose one); a

**new app** uses whatever fits the brief (SSR or SPA). Either way it deploys as a Node.js app (Step 8) — an SSR app runs a server, a SPA builds to static output.

• Map rendering → framework: **`ssr` → Next.js**, **`ssg` → Astro** — unless the brief/prompt explicitly

names another supported framework, in which case use that.

Supported frameworks (what the Hostinger build pipeline can deploy — the `app_type` in Step 8 deploy):

• **Server/SSR-capable:** Next.js, Nuxt.js, Astro, SvelteKit, Express, NestJS, Fastify.
• **Static / SPA:** React, Vue, Angular, Vite, Parcel, Preact, Svelte, (Astro / SvelteKit static too).

Confirm the framework with the user in one line only if the brief left it open. Record the choice in `state.json`:

{ "frontend": { "framework": "nextjs", "rendering": "ssr" } }

If the brief is silent, default to **Next.js SSR**. Ecommerce must be SSR (never SSG) — but the SSR framework itself is free to be any supported one, not just Next.js.

Step 2 — Implement `design.md` (don't re-design)

The look was already chosen and written by the design step. **Read `~/.hostinger/<domain>/design.md` and implement it faithfully** — tokens (colour, type, spacing), components, per-page composition, imagery and accessibility — plus the logo files in `brand/`. Don't re-run design questions or invent a new direction here.

• Treat `design.md` as the contract: the built pages should match its tokens, type scale, components and

per-page composition, and the 8-point grid / WCAG 2.2 AA rules it carries.

• Use the **logo** from `brand/` as-is (wordmark, icon mark, favicon); never recolour or redraw it.
• If `design.md` is **missing** (e.g. a resumed older build), fall back to `brief.md → Design direction`

(reference site, colours, brand, adjectives) and a tasteful, accessible default — but prefer `design.md` whenever it exists.

• **Don't gate on approval here** — the result is shown at **validate** (Step 7).

**Only ask about the code, and only if it matters** (design decis