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:

Project Type	Action	Examples
Informational sites	`read` `skills/website-building/informational/informational.md`	Personal sites, portfolios, editorial/blogs, small business, landing pages
Web applications	`read skills/webapp/SKILL.md`	SaaS products, dashboards, admin panels, e-commerce, brand experiences
Browser games	`read` `skills/website-building/game/game.md` + `skills/website-building/game/game-testing.md`	2D Canvas games, Three.js/WebGL, HTML5 games, interactive 3D experiences

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 Beeuni 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

File	Covers	Load
`shared/01-design-tokens.md`	Type scale, spacing, Beeuni palette, base.css	Always
`shared/02-typography.md`	Font selection, pairing, loading, blacklist	Always
`shared/04-layout.md`	Spatial composition, responsive, mobile-first	Always †
`shared/05-taste.md`	Skeleton loaders, empty/error states, polish	Always
`shared/08-standards.md`	Accessibility, performance, anti-patterns	Always
`shared/09-technical.md`	Project structure, sandbox, deploy, checklist	Always †
`shared/head-defaults.html`	Attribution block for `<head>`	Always †
`shared/03-motion.md`	Scroll animations, Motion library, GSAP SVG plugins, hover/cursor	When animated
`shared/06-css-and-tailwind.md`	Tailwind CSS v3, shadcn/ui, modern CSS	When using Tailwind
`shared/07-toolkit.md`	CDN libraries, React, Three.js, icons, maps, SVG patterns/filters, esm.sh	When choosing libs
`shared/10-charts-and-dataviz.md`	Chart.js, Recharts, D3, KPIs, sparklines	When data viz needed
`shared/11-web-technologies.md`	Framework versions, browser compatibility	When checking compat
`shared/12-playwright-interactive.md`	Persistent Playwright browser QA, screenshots, visual testing	When testing
`shared/19-backend.md`	FastAPI/Express/Flask servers, WebSocket, SSE, port forwarding	When backend needed
`shared/20-llm-api.md`	LLM/AI API integration reference	When site uses AI APIs

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

File	When to load
`read skills/webapp/SKILL.md`	SaaS, dashboard, admin, e-commerce, brand experience (fullstack template skill)
`skills/webapp/dashboards.md`	Dashboard or data-dense interface (companion to webapp)
`informational/informational.md`	Personal site, portfolio, editorial, small business, landing
`game/game.md`	Browser game, Three.js, WebGL, interactive 3D
`game/2d-canvas.md`	2D Canvas game (companion to game.md)
`game/game-testing.md`	Any browser game — load alongside game.md

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:

text

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:

bash

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:

bash

# 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.

Understand the brand — purpose, tone, one defining word
Write SVG directly — geometric shapes, letterforms, or abstract marks. One memorable shape.
Principles: Geometric/minimal (Paul Rand, Vignelli). Works at 24px and 200px. Monochrome first — add color as enhancement. Use currentColor for dark/light mode.
Implement inline with aria-label, viewBox, fill="none", currentColor strokes
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:

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

Stage 2: Final QA (before publishing)

Screenshot every page at desktop and mobile
Check cross-page consistency (spacing, color, type treatment)
Verify dark mode (screenshot both themes for homepage minimum)
Check interactive states: hover, focus, active, loading, empty, error
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 Beeuni fallback palette. The Beeuni palette is a last resort for when both inference and asking have failed — not a convenient default.

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.
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.
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).
If the subject is genuinely ambiguous, ask — "What mood are you going for?" and "Any reference sites?" One question is enough.
Beeuni 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 Beeuni/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: Beeuni 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.

website building

Website Building

Project Type Routing

Sub-File Reference

Shared (`shared/`) — Every project

Domain-Specific — Load one

Workflow

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

Step 1: Generate unique palette

Step 2: Design & Build

Step 3: Preview

Use Every Tool

SVG Logo Generation

Visual QA Testing Process

Stage 1: Page-by-Page QA

Stage 2: Final QA (before publishing)

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

The Fallback: Clean & Swiss (Last Resort)

Art Direction — Avoid the AI Aesthetic

Step 2: Publish

Delivery

Related skills

Website Building

Project Type Routing

Sub-File Reference

Shared (shared/) — Every project

Domain-Specific — Load one

Workflow

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

Step 1: Generate unique palette

Step 2: Design & Build

Step 3: Preview

Use Every Tool

SVG Logo Generation

Visual QA Testing Process

Stage 1: Page-by-Page QA

Stage 2: Final QA (before publishing)

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

The Fallback: Clean & Swiss (Last Resort)

Art Direction — Avoid the AI Aesthetic

Step 2: Publish

Delivery

Related skills

Shared (`shared/`) — Every project