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:
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 SingulaComp 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, SingulaComp palette, base.css
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.
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:
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.
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)
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 SingulaComp fallback palette. The SingulaComp 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.
SingulaComp 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 SingulaComp/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: SingulaComp 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.