site-craft

name

site-craft

description

A phased, user-gated workflow for designing and building a marketing site with an AI agent — brand brief, divergent hero comps, type audition, full build, four quality gates, ship prep. Use when starting a marketing/landing site from scratch, redesigning one, or replacing a placeholder splash page. Triggers on "marketing site", "landing page", "brand the site", "redesign our homepage", "replace the splash page".

site-craft

Design and build a marketing site the way a small studio would: a written brief before pixels, divergent exploration before commitment, a screenshot loop so the agent sees what it ships, quality gates before "done" — and the human as art director at every decision that is theirs to make.

This skill encodes process, not taste. Every aesthetic decision lands in the project's own PRODUCT.md / DESIGN.md, decided by the user. The skill's job is to make sure those decisions get made deliberately, get written down, and get enforced.

Why this exists

AI-built marketing sites fail in predictable ways: the model designs blind (never sees its output), taste evaporates between sessions (nothing written down), one-shot generation converges to the category's median, and "done" is declared without verification. This workflow attacks each failure directly. It was extracted from a real build; the phases below are the ones that survived contact.

Setup (run once, before Phase 0)

1. Install missing skill dependencies. Check the available-skills list for each of these; install only what's absent, and tell the user in one line what you installed:

   npx skills add pbakaus/impeccable -g -y                                    # design spine: init, registers, audit
   npx skills add vercel-labs/agent-skills --skill web-design-guidelines -g -y  # gate 1: a11y/UX compliance
   npx skills add jakubkrehel/make-interfaces-feel-better -g -y               # gate 3: micro-interactions
   npx skills add vercel-labs/agent-skills --skill writing-guidelines -g -y   # gate 4: copy review
   

   Drop -g if the user prefers project-level installs. If an install fails, say so and continue — each gate degrades to "skipped, reason stated", never to silent omission.

2. Establish the screenshot loop. Detect a browser tool in this order: agent-browser CLI → Playwright (npx playwright) → Chrome MCP tools (mcp__claude-in-chrome__* or similar). If none exists, suggest npm i -g agent-browser and wait — do not proceed past Phase 1 without a working screenshot loop. Designing blind is the failure mode this skill exists to prevent.

3. Find the serving path. Identify where preview files will be served from (a static dir + python3 -m http.server <port> is fine). Pick a port that collides with nothing the project already runs. If the user reviews from another machine, arrange a reachable URL (tunnel, tailnet bind, dev host) before comps exist, not after.

Iron rules (apply to every phase)

• The user is the art director. Hard-stop at every checkpoint marked ⏸ and wait for their pick. Never substitute your own taste for a decision the user has reserved. When they overrule a recommendation, that's data, not friction — follow it and don't re-litigate.
• Screenshot everything you build, before showing it. Every artifact gets rendered at desktop (~1440px) and mobile (~390px), and you look at the screenshots yourself and fix what's broken before presenting. Wait for document.fonts.status === 'loaded' before shooting, or you'll review fallback fonts (this will happen; check letterforms, not just text presence).
• Real content only. Copy comes from the product's actual docs/API/voice; code samples and payloads are contract-faithful shapes from the real system. If the project has a canonical voice/messaging doc, it outranks anything you'd write. No lorem, no invented API responses, no fake testimonials.
• Claims stay checkable. Anything load-bearing (pricing, limits, features) must be verifiable against the real product. Wit and voice live wherever the project's own brief says they live.
• Commit at every phase boundary with a message that says what was decided, not just what changed. Update the project changelog if one exists.
• Present decisions, not surveys. Each checkpoint offers a small set of genuinely different options with a recommendation and the reasoning — then stops.
• Review artifacts for every round. Assemble screenshots into a comparison page (publish via the Artifact tool when available; otherwise write an HTML gallery to disk and give the path). The user should never have to reconstruct your work from prose.

Phase 0 — Brief (no code)

Understand the product and the brand direction before any pixels.

1. Crawl the repo/docs for product truth: what it does, who it's for, existing voice or strategy docs, current site/splash if any, existing brand assets.
2. Interview the user for what the crawl can't answer — one focused round using the structured-question tool when available. Cover: brand personality and its boundaries (e.g. playful vs. understated, and where each applies), aesthetic kin (2–3 named references, not adjectives), anti-references (what this must NOT look like), the conversion primitive (what the hero asks a visitor to do), and any locked constraints.
3. ⏸ Play back the direction in a few sentences and get explicit agreement.

Output: a confirmed direction. Nothing written to disk yet except notes.

Phase 1 — Encode the brief

Run $impeccable init (interview mode, seeded with Phase 0's answers) to produce:

• PRODUCT.md — register, audiences, positioning, conversion & proof, personality, anti-references, design principles, accessibility bar.
• DESIGN.md (seed) — north star metaphor, color strategy with named rules, typography direction (not fonts yet), elevation/motion posture. Mark judgment calls you made so the user can veto them.

⏸ Present both files' key decisions and the judgment calls. Commit.

Phase 2 — Divergent exploration

Never bet the brand on one comp.

1. Round 1 — direction comps. Build 3–4 standalone, self-contained HTML hero comps interpreting the brief in genuinely different ways (different composition, voice, and information density — not palette swaps). All comps share whatever the brief has locked. Screenshot desktop + mobile, self-critique, fix, assemble the review gallery with a per-comp thesis, strengths, risks, and your recommendation. ⏸ User picks a direction (grafting organs across comps is normal — offer it).
2. Round 2 — type audition. Freeze the winning comp's skeleton; vary ONLY the display typography across ~6 voices (include width/weight/case play, at least one wildcard). Build it as a single switchable page (tabs + arrow keys) so the user can feel each live; screenshot every variant. Verify each face actually loaded before shooting — font CDNs silently serve fallbacks and error pages for malformed variable-font requests; measure (e.g. width deltas for stretch axes), don't assume. ⏸ User picks the voice (and runner-up, worth recording).

Commit each round. Fonts must be license-compatible with the project (default to open catalogs unless the user owns licenses).

Phase 3 — Lock and build

1. Graduate DESIGN.md from seed to locked spec: real tokens (colors, type roles with exact values, spacing, components), named rules, motion posture, theme commitment (single-theme is valid if deliberate — say so in the file).
2. Build the full page in the winning voice: hero verbatim from the approved comp, below-fold sections composed in the same language. Signature motion earns its place or doesn't exist; prefers-reduced-motion always gets a working alternative. Interactive elements (copy buttons, forms, tab switchers) are functional, not decorative — wire them to the real endpoints and handle the error paths.
3. Verify: desktop + mobile full-page screenshots, no horizontal scroll, every interactive behavior exercised in the live DOM (click it and read the DOM state back — don't assume).
4. ⏸ Present. Iterate on the user's changes (their copy edits are sacred — build on them, never revert). Expect additions to be tried and rejected; remove cleanly and record the taste rule in memory so it sticks.

Commit. Repeat step 3 after every edit round.

Phase 4 — The gates

Run all four, in this order, applying fixes as findings land. Where a gate's generic rule conflicts with the project's locked voice/design system, the project wins — record the rule as "reviewed, overridden" rather than silently skipping it.

1. web-design-guidelines — a11y/UX compliance. Expect real findings: skip links, aria-live on async status, autocomplete/spellcheck on inputs, translate="no" on copy-paste primitives and code, theme-color/color-scheme, touch-action, URL-synced stateful UI (tabs → query params), loading-state labels.
2. $impeccable audit — scored technical audit. Measure, don't assert: contrast ratios computed from the live DOM (rasterize via canvas to sRGB — getComputedStyle returns non-RGB color spaces that naive parsers misread), touch targets measured, then fixed.
3. make-interfaces-feel-better — micro-interactions: interruptible transitions with named properties (never transition: all), text-wrap polish, hit-area extensions. Respect the project's own doctrine where it conflicts (a flat design system legitimately refuses shadows).
4. writing-guidelines — copy review, run after the user's copy edits land.

Verify after fixes (no h-scroll regression, behaviors still work). ⏸ Present the four reports compactly. Commit.

Phase 5 — Ship prep

1. Self-host fonts. Download the subset woff2 files (prefer one variable file per family over per-weight instances — check sizes, the variable file is usually the same size as ONE instance), inline the @font-face blocks with font-display: swap and correct unicode-range, add rel="preload" for the critical faces, delete the CDN <link>s.
2. Zero external requests. Verify via the Performance API that every subresource loads from the site's own origin, and that the fonts still render as themselves (document.fonts.check + a screenshot compared against Phase 3's).
3. Brand assets. Favicon (SVG + apple-touch PNG) derived from the design system's smallest ownable unit; og-image (1200×630) built as a checked-in HTML source file and rendered via the browser — screenshot at exact viewport — so it's regenerable after copy changes. Pin exact sRGB hex values for assets (rasterize the working color space via canvas).
4. 404 page in the same system — error surfaces are where the brand's voice gets its most room, and every real site needs one.
5. Ship checklist for Phase 6 (deployment is deliberately out of scope — it's infra-specific): where files go, what routes/fallbacks the server needs (including the 404 and static assets), what must be verified end-to-end in production (forms POST for real, links resolve, OG card renders), and what existing behavior must not break.

⏸ Final review. Commit. Hand the user the ship checklist.

Failure modes this skill exists to catch

• Presenting work without having looked at its screenshot (fallback fonts, overflow, dead buttons).
• One comp presented as "the design" instead of a divergent set.
• Taste decisions made silently instead of at a ⏸ checkpoint — or re-litigated after the user ruled.
• Fake content standing in for the product (invented payloads, placeholder copy that ships).
• Gates skipped, or gate findings "fixed" against the project's own locked system.
• "Done" declared with external requests still on the page, no 404, no og-image, or an unverified form.