/05-design

name: headless-step-design
description: "Step 5 (design) of the Hostinger Headless flow. Derives three distinct design directions from brief.md (plus any reference sites and brand assets), lets the user pick one in a single question, checks the chosen one against the 8-point grid and WCAG 2.2 AA, designs the logo as outlined SVG (wordmark, icon mark, favicon), then writes design.md — tokens, type, logo, components, per-page composition, accessibility and imagery — as the contract the frontend implements (the framework/stack is chosen later by the frontend step). Prepare work: runs during the provision wait and never touches the backend."

headless-step-design

Turn the brief into a look the user has chosen, and write it down so the frontend can't drift from it. **One question, three options, one spec.** The output is **files** (`design.md` plus the logo), not a conversation: the frontend step implements `design.md`, not the chat.

**In:** `brief.md` (required), `content-model.md` (if it exists yet), reference sites and assets the user gave. **Out:** `~/.hostinger/<domain>/design.md` and the logo files in `~/.hostinger/<domain>/brand/`.

> ## ⚠️ Build mode: "Bring your own frontend"? This step defers to the user > Read `brief.md` → **Build mode** first. When it is **Bring your own frontend**, the user drives the > design — **do not generate three directions or write a prescriptive `design.md` over their project.** > The frontend already exists (or the user vibe-codes it with you); your job is to follow *their* > direction, not impose one. Skip Steps 1–7 below: either write nothing, or capture only what the user > explicitly asks for (a short note of their stated colours/vibe) so the frontend step has it. The logo > and token work here apply only when **Build mode is "Agent designs and builds"**. (This mirrors the > frontend step's existing "existing app the user brought" handling, now generalised to any backend.)

This is **prepare work**: it runs while provision settles (see *Background provision & the instance barrier* in the top-level `SKILL.md`). Nothing here calls the Hostinger connector or the backend.

**Keep it short.** Refine already asked about tone and look; don't ask again. The step asks the user **one** question: either the keep/change question (Step 1) or the three directions (Step 4), never both. "You decide" is a valid answer.

**Talk like a person, not a designer.** Everything the user reads describes how the site will **look and feel**: colours by name ("hot pink, butter yellow"), lettering by feel ("big chunky rounded headlines"), and the details they'll notice ("photos tilted like stickers on a scrapbook"). No hex codes, font names, or design jargon (palette, accent, tokens, shape language, contrast).

**Two hard rules apply to every direction, however loud or quiet it is:**

• **The 8-point grid.** Every spacing, sizing and layout value is a multiple of 8 px (details in

5.2).

• **WCAG 2.2 Level AA.** Colour, focus, motion, target size and reflow are decided here, so the

frontend can't build them wrong (details in 5.1 and 5.3).

These rules are for you, not the user. **Never mention them**: no grid, contrast, WCAG or accessibility talk in anything the user reads, and no "all options follow…" reassurances. The user judges the look in the preview; the rules just make sure it works.

---

Step 1 — Read the workspace, then the resume check

Read `brief.md`, `state.json`, and `content-model.md` if it exists.

• **`design.md` already exists and this is not a redesign** → don't overwrite it. Describe the

current look in two or three plain sentences and ask: *keep it, or change something?* That is this step's one question.

• **Keep** → leave the file alone and go straight to the `state.json` update at the end of Step 7.
• **Change** → edit only what they asked for, re-run the 5.x checks on what changed, then save.
• **The site is already deployed** (`deploy.json` exists, or `state.json` has `deployed_at`) and the

user asked for a different look → this is a **redesign**. Tell them plainly: their content stays as it is, only the look changes, and they'll see a preview before it goes live. Then run Steps 2–7 as normal. The current `design.md` becomes one more signal in Step 2, so carry over what the user wants to keep and move away from the rest.

Step 2 — Collect the signals

Before inventing anything, gather what already constrains the design:

| Signal | Where | How it constrains | |---|---|---| | Tone, purpose, audience | `brief.md` → *Tone*, *Purpose*, *Audience* | Sets the mood all three directions must fit | | Brand assets | `brief.md` → *Assets* | Logo, brand colours and fonts are **fixed** in every direction. Never recolour a supplied logo; Step 6 uses it instead of designing one | | Pages and entities | `content-model.md` → *Navigation*, *Pages*, *Articles*; if it doesn't exist yet, `brief.md` → *Pages* | Drives the component inventory and page composition | | Reference sites | URLs in the brief or the conversation | Cues to borrow (see below) | | Images already sourced | `content-model.md` → the image lines under *Articles* (skip if none yet) | Glance at a few at small size; keep accents from clashing with their dominant colours | | Current design (redesign only) | existing `design.md` | What to keep, what to move away from |

**Reference sites.** Open each one in a real browser if you have one. Static fetches are often blocked or rate-limited; without a browser, fetch the HTML and its linked CSS instead. If neither works, say so in one line and continue from the brief alone. Pull **cues**:

• **Fonts:** the computed `font-family` of `h1`/`h2` and of body `p`.
• **Colours:** background colours weighted by painted area (element width × height), the top 5–8.

Skip transparent and semi-transparent backgrounds and overlays (cookie banners, modals, chat widgets). Text colours come from headings, paragraphs and links.

• **Feel:** look a