Website Building

Build distinctive, production-grade websites where every site looks DIFFERENT. Every choice — type, color, motion, layout — must be derived from the subject matter. Run the palette generator (bun run shared/generate-palette.ts "keywords") to create a unique color scheme for each project. NEVER reuse the same palette across sites.

This skill covers everything for web projects. Read the sub-files in this directory as needed based on your project type. For web applications, also read skills/webapp/SKILL.md.

Universal design principles (color philosophy, default palette, font selection) are shared with other skills via design-foundations. This skill's shared files extend those foundations with web-specific implementation (CSS variables, responsive tokens, base stylesheets). You don't need to load design-foundations separately — the web-specific versions in shared/ are comprehensive.

Use read with the full path, e.g. skills/website-building/shared/01-design-tokens.md

---

Project Type Routing

Step 1: Identify project type and load domain-specific guidance:

Step 2: Read shared files — read skills/website-building/shared/01-design-tokens.md and skills/website-building/shared/02-typography.md first (mandatory for ALL project types, including webapp). These establish the Neuro OS design system defaults and typography rules that apply universally. For web applications and dashboards, skip files marked with † below — those contain implementation details pre-configured in the fullstack template.

If the user says just "website" or "site" with no detail, ask what type or default to informational.

---

Sub-File Reference

Shared (shared/) — Every project

All paths are relative to skills/website-building/.

† Skip for webapp and dashboards — implementation details pre-configured in the fullstack template. Design-tokens and typography are NOT skipped — they provide the authoritative design system defaults and font selection guidance for all project types.

Domain-Specific — Load one

Interactive QA: Read skills/website-building/shared/12-playwright-interactive.md for persistent browser automation with Playwright (screenshots, functional testing, visual QA). Required for game testing, useful for any complex site.

---

Workflow

Step 0: Load ALL mandatory files (do this FIRST, in parallel)

Read ALL of these in one batch — they are mandatory for every project:

read("skills/website-building/shared/01-design-tokens.md")
read("skills/website-building/shared/02-typography.md")
read("skills/website-building/shared/04-layout.md")
read("skills/website-building/shared/05-taste.md")
read("skills/website-building/shared/08-standards.md")

Then load the domain-specific file (informational, webapp, or game) from Step 1 below.

Step 1: Generate unique palette

Run the palette generator with keywords describing the subject:

bun run skills/website-building/shared/generate-palette.ts "subject keywords here"

Pick the best harmony, customize if needed.

Step 2: Design & Build

Build the site with the generated palette, following all the loaded design guidance.

Step 3: Preview

Start a local server with pty_spawn, then show its plain URL:

# static site (no build step)
python3 -m http.server 3000 --directory /workspace/project
# app: run its dev server instead, e.g. npm run dev

Then show(type: "url", url: "http://localhost:3000/"). The platform auto-detects and proxies any localhost port — no special URL format needed.

---

Use Every Tool

• Research first. Search the web for reference sites, trends, and competitor examples before designing. Browse award-winning examples of the specific site type. Fetch any URLs the user provides.
• Generate real assets — generously. Generate images for heroes, section illustrations, editorial feature visuals, atmospheric backgrounds — not just one hero image. Every long page should have visual rhythm with generated images that match the site's art direction. No placeholders. Generate a custom SVG logo for every project (see below) — SVG is for logos only unless the user specifically requests SVG output. Save web reference images that inform direction.
• Screenshot via Playwright. Read skills/website-building/shared/12-playwright-interactive.md to screenshot at desktop (1280px+) and mobile (375px). Compare against references. This is mandatory, not optional. See Visual QA below.
• Write production code directly. HTML, CSS, JS, SVG. Use bash for build tools and file processing.

---

SVG Logo Generation

Every project gets a custom inline SVG logo. Never substitute a styled text heading.

1. Understand the brand — purpose, tone, one defining word
2. Write SVG directly — geometric shapes, letterforms, or abstract marks. One memorable shape.
3. Principles: Geometric/minimal (Paul Rand, Vignelli). Works at 24px and 200px. Monochrome first — add color as enhancement. Use currentColor for dark/light mode.
4. Implement inline with aria-label, viewBox, fill="none", currentColor strokes
5. Generate a favicon — simplified 32x32 version if needed

For SVG animation (DrawSVG, MorphSVG), see shared/03-motion.md. For SVG patterns/filters, see shared/07-toolkit.md.

---

Visual QA Testing Process

Every deployment must pass visual QA. Screenshots are quality gates.

Read skills/website-building/shared/12-playwright-interactive.md for all visual QA. Playwright provides a persistent browser session for screenshots, interaction testing, and viewport verification.

Cycle: Build → Playwright QA → Evaluate → Fix → Repeat → Deploy when ready

Stage 1: Page-by-Page QA

After building each page:

1. Screenshot at desktop (1280px+) and mobile (375px) via Playwright
2. Evaluate critically: Does it look professionally designed (not AI-generated)? Is typography distinctive? Is whitespace generous? Is there one clear visual hierarchy?
3. Fix every issue before moving on. No visual debt.

Stage 2: Final QA (before publishing)

1. Screenshot every page at desktop and mobile
2. Check cross-page consistency (spacing, color, type treatment)
3. Verify dark mode (screenshot both themes for homepage minimum)
4. Check interactive states: hover, focus, active, loading, empty, error
5. Cold-open first impression test: does it feel polished and intentional?

QA failures: text overflow, inconsistent spacing, off-token colors, missing dark mode, squished mobile, generic AI look, placeholder content, missing logo.

---

Step 1: Art Direction — Infer Before You Ask, Ask Before You Default

Every site should have a visual identity derived from its content. Do not skip to the Neuro OS fallback palette. The Neuro OS palette is a last resort for when both inference and asking have failed — not a convenient default.

1. Infer from the subject. A coffee roaster site → earthy browns, warm cream, hand-drawn feel. A fintech dashboard → cool slate, sharp sans-serif, data-dense. A children's learning app → bright primaries, rounded type, playful motion. The content itself tells you the palette, typography, and spacing before the user says a word.
2. Check the Art Direction tables. Each domain file (informational.md, webapp/SKILL.md, game/game.md) has an Art Direction table mapping site/product types to concept-driven directions and token starting points. Use these as a springboard.
3. Derive the five pillars: Color (warm/cool, accent from subject), Typography (serif/sans, display personality), Spacing (dense/generous), Motion (minimal/expressive), Imagery (photo/illustration/type-only).
4. If the subject is genuinely ambiguous, ask — "What mood are you going for?" and "Any reference sites?" One question is enough.
5. Neuro OS fallback — only when inference AND asking yield nothing. If the user has been asked and gave no direction, AND the subject matter gives no clear signal, then fall back to Neuro OS/Swiss defaults.

The Fallback: Clean & Swiss (Last Resort)

When inference yielded no clear direction AND the user was asked but gave no style guidance, use defaults from skills/website-building/shared/01-design-tokens.md with:

• Typography: Satoshi or General Sans body (Fontshare — preferred), or Inter/DM Sans. Weight contrast over font contrast. 3-4 sizes max. Keep text compact — --text-3xl/--text-hero are for informational site heroes only.
• Color: Neuro OS palette. Neutral surfaces + one teal accent for CTAs only.
• Layout: Grid-aligned. Generous margins. Asymmetric where interesting.
• Motion: Minimal, functional. Smooth state transitions only.
• Imagery: Generate clean, relevant visuals. No stock photos.

Art Direction — Avoid the AI Aesthetic

See skills/website-building/shared/08-standards.md for the full anti-patterns list.

---

Step 2: Publish

Use real local preview commands first and only publish with the target project's actual deployment workflow. See skills/website-building/shared/09-technical.md for the recommended preview and delivery flow.

Before taking a site live, load the web-publishing-and-deployments skill. It owns the whole publish path: the guardrail (explicit user opt-in — never publish unprompted), runtime-only dependencies that won't survive a standalone deployment, the mandatory pre-publish security review, and the provider mechanics.

---

Delivery

• Always verify the site locally first.
• Use pty_spawn for the preview or dev server.
• If the target repo already has a deployment workflow, use that exact workflow.
• If there is no established deploy target, deliver the files and a verified local preview instead of inventing a platform-specific deployment story.