site-builder

Site Builder

Consume design systems. Build production sites. Ship to Cloudflare Pages.

This skill is the CONSTRUCTION tool. It takes design specifications (from site-designer) and conversion component manifests (from conversion-designer) and produces actual Astro/Svelte/Tailwind code. Domain knowledge for specific frameworks lives in reference files. This file defines the workflow, routing, and constraints.

This skill operates per project-workspace-contract@2 (${CLAUDE_SKILL_DIR}/references/project-workspace-contract-v2.md). site-builder is a consumer only — it reads upstream specs (DESIGN.md + design-tokens.json from the Kind-3 design/<instance>/ zone, components-manifest.json from the conversion/<instance>/ zone) and emits src/, which is OUT OF SCOPE per contract §6 — so site-builder has no produces: block and does not write a MANIFEST.md entry for its output. Under v2, workspace/ is opaque AI scratch and is never read for routing.

---

Phase 0a: Project Manifest Lookup (manifest-first)

Before the requirement anchor, orient in the project. Per manifest-first discipline, the first workspace-touching read on any invocation is MANIFEST.md at the project root (NOT workspace/MANIFEST.yaml — the deprecated v1 location). Under project-workspace-contract@2, workspace/ is opaque AI scratch and is never read for routing.

This is how site-builder locates its inputs. The upstream specs are NOT assumed to sit at a fixed project-root-flat path — they live in producer-owned Kind-3 zones (design/<instance>/, conversion/<instance>/) and the manifest's entries: block records each artifact's path:.

1. Does MANIFEST.md exist at the project root?
   • Yes: read it. Parse the YAML frontmatter for project_name, brand, output_language, and the canonicals: declaration. During the migration window, accept legacy client: as a fallback when brand: is absent. Parse the entries: YAML block for the routing index. Resolve input locations from it (Phase 0 Q1/Q2 below).
   • No: STOP. The project has not adopted the v2 contract, so site-builder cannot safely locate upstream specs. Ask the orchestrator/human to run the project-local bootstrap routine or choose an existing v2 project with MANIFEST.md. Do not search for flat root files, do not read workspace/MANIFEST.yaml, and do not proceed from guessed paths.
2. Resolve the design/ zone entry. Look up the manifest entry whose kind: spec is produced by site-designer (zone design/<instance>/). Its path: points at DESIGN.md; the sibling design-tokens.json lives in the same zone directory. Read both from the indexed location. If no design/ entry exists, this is the missing-design case — see Phase 0 Q1.
3. Resolve the conversion/ zone entry (optional) — by artifact, not by zone. conversion-designer emits FOUR kind: spec artifacts into the conversion/<instance>/ zone: components-manifest.json, page-strategy-pack.md, page-content-model.yaml, and audit-report.md. site-builder consumes ONLY the components manifest. Look up the conversion/<instance>/ manifest entry whose path: basename is exactly components-manifest.json (or whose entry metadata identifies the components manifest specifically) — do NOT match the first conversion/-zone entry by zone/producer/kind alone, or you may resolve a page-strategy or audit entry instead. Explicitly IGNORE conversion-designer's other conversion-zone artifacts (page-strategy-pack.md, page-content-model.yaml, audit-report.md) for build-input purposes. If present, read the resolved components-manifest.json from the indexed location. If multiple components-manifest.json instances exist (e.g. several conversion/<instance>/ zones), ask the user which instance to build from. If absent, proceed without conversion components — see Phase 0 Q2.
4. Staleness check (advisory). If the resolved design/ or conversion/ entry's last_updated is newer than the most recent build, warn the user that the build may be stale relative to its upstream specs and should be re-run.

---

Phase 0: Establish Requirement Anchor

Before beginning any build work, establish the requirement anchor by asking:

1. Is the design system available? Resolve DESIGN.md + design-tokens.json via the design/<instance>/ entry in the project-root MANIFEST.md (Phase 0a step 2). If the manifest is absent, stop and ask for project-local bootstrap/orchestrator setup. If the design system cannot be located through the manifest, run site-designer first. Without a design system, building produces generic output that will need to be rebuilt later. A missing/unlocatable DESIGN.md is a hard blocker.
2. Is a conversion manifest available? Resolve specifically the components-manifest.json artifact — by basename, NOT by zone/producer/kind — via the conversion/<instance>/ entry in the project-root MANIFEST.md (Phase 0a step 3). conversion-designer also emits page-strategy-pack.md, page-content-model.yaml, and audit-report.md into the same conversion/ zone; IGNORE those for build-input purposes — the components manifest is the only conversion artifact site-builder consumes. If multiple components-manifest.json instances exist, ask the user which instance to build from. If it cannot be located, check whether conversion elements are needed. If yes, run conversion-designer first. If no conversion elements are needed, proceed without it (the conversion consume is optional per this skill's MANIFEST.yaml).
3. What is the target stack? Default: Astro 6 + Svelte 5 + Tailwind CSS 4 + Cloudflare Pages. Confirm or override.
4. What pages need building? Provide the site map. List every page with its URL pattern and content sections. (Not planned. Committed.)
5. What is the content source? Static TypeScript/JSON data, Astro content collections, headless CMS, or markdown files?
6. What integrations are required? Forms (Zoho Forms, etc.), analytics (GTM/GA4), maps (OpenStreetMap), social embeds, cookie consent?
7. What performance baseline must be maintained? What Lighthouse scores are acceptable? (Not aspirational. Actual threshold for deployment.)

Record the answers. Every subsequent implementation decision must trace back to these answers. If a component or feature cannot be justified by the requirement anchor, it does not belong in the build.

If the user cannot answer questions 1 and 4, that is itself diagnostic -- they need a site-designer pass and content inventory before building.

"Not Projected. Actual." Constraint

When asking about scale, page count, traffic, or any quantitative scope question, always append the constraint: "(Not projected. Actual.)" or "(Not planned. Committed.)"

Accept only current, confirmed values. If the user provides aspirational page counts or projected feature lists, flag this explicitly: "I need the committed scope, not a roadmap. Building for pages that may never exist creates dead code and maintenance burden."

Never build infrastructure (CMS integrations, pagination, i18n routing) for projected scale. Build for what exists today. Add capabilities when actual demand materializes.

---

Boundary: site-builder vs. site-refactor

These two skills have a hard boundary. Crossing it produces broken output.

site-builder does	site-refactor does
CONSTRUCTS new sites from design specs	EXTRACTS and REPLICATES from existing sites
Creates projects from scratch	Assumes a project already exists
Generates Astro config, routing, layouts	Extracts source site DOM, styles, animations
Decides island architecture (Svelte vs static)	Identifies which source elements are interactive
Turns design tokens into Tailwind config	Extracts tokens from source site via DevTools
Writes deployment config (Cloudflare)	Generates Playwright tests from source screenshots
Implements integration patterns (forms, maps, analytics)	Runs visual comparison and cross-browser verification
Structures content as TypeScript/JSON	Documents source content in structured format

site-builder never:

• Opens Chrome DevTools
• Inspects a source site's computed styles
• Extracts colors, fonts, or spacing from a live page
• Runs visual regression against a source site

site-refactor never:

• Scaffolds a new project from DESIGN.md
• Generates Astro config or deployment configuration
• Decides hydration strategies from scratch
• Wires form integrations or analytics

The handoff: site-refactor says "Here is exactly what the source section looks like (DOM, styles, animations, images, content)." site-builder says "Here is the Astro/Svelte/Tailwind code that implements it."

---

Boundary: site-builder vs. Other Skills

Skill	Their domain	site-builder's domain
site-designer	Design decisions: colors, fonts, spacing, mood, visual identity	Implementation: turning those decisions into Tailwind config and components
conversion-designer	Conversion strategy: what components to build and why, scoring logic, copy	Implementation: building the Svelte islands and wiring analytics events
seo-strategist	SEO auditing: meta tags, structured data, internal links, content scoring	Implementation: adding meta tags, JSON-LD, and semantic HTML per audit findings

site-builder does not make design decisions. It does not invent CTA copy. It does not audit SEO. It builds what the upstream skills specify.

---

Operating Modes

Determine the mode from the user's command or intent before loading reference files.

Mode A: Scaffold (/build-scaffold)

Purpose: Set up the complete project structure from a design system with a specification.website-aligned technical baseline from the first scaffold. Treat compliance as a default build input, not a post-hoc audit-only concern.

Prerequisite: DESIGN.md + design-tokens.json must exist, located via the design/<instance>/ entry in the project-root MANIFEST.md (Phase 0a). If the manifest is absent, stop and ask for project-local bootstrap/orchestrator setup.

Load these references:

• references/spec-website-scaffold-rationale.md -- why scaffold defaults include Website Specification topics by default
• references/astro6-patterns.md -- Astro 6 project structure, config, and conventions
• references/tailwind4-theme.md -- Tailwind CSS 4 @theme directive and token mapping
• references/cloudflare-pages.md -- Adapter config, _redirects, _headers, environment variables
• references/security-headers.md -- baseline HTTP security headers and CSP/HSTS caution
• references/schema-org.md -- structured data component patterns
• references/svelte5-runes.md -- Svelte 5 Runes API ($state, $derived, $effect, $props)

Load these templates:

• templates/astro-config.ts -- Full config with Svelte, Tailwind, Cloudflare, sitemap
• templates/base-layout-template.astro -- Canonical root HTML layout template with SEO, OG, structured data, global styles
• templates/tailwind-theme.css -- Tailwind 4 @theme directive with design token mapping
• templates/global-styles.css -- Base styles, font loading, CSS reset additions

When called from site-refactor: If a src/styles/tokens.css already exists with --ref-* reference tokens (from site-refactor's three-tier token architecture), the scaffold MUST preserve and consume those tokens. The @theme block in global.css must use var(--ref-*) references — not raw hex values. Read this plugin's local references/refactor-token-bridge.md for the three-tier pattern. Font loading must use <link> tags in BaseLayout.astro — not CSS @import url(...), which is render-blocking.

Workflow:

1. Read DESIGN.md -- Internalize Section 1 (Visual Theme) for overall mood and approach. This sets the tone for all subsequent implementation decisions.
2. Map design-tokens.json to Tailwind CSS 4 @theme -- Convert every token to a CSS custom property following the --{category}-{role} naming pattern. If a tokens.css with --ref-* tokens already exists, the @theme block MUST consume var(--ref-*) — not raw hex values. If no tokens.css exists, create one with --ref-* reference tokens in :root, then have @theme consume them. This prevents the circular-reference problem and ensures a single source of truth for raw values.
3. Generate project structure -- Create the directory tree per the accepted site map and scaffold checklist. Initialize astro.config.ts with Svelte 5 integration, @tailwindcss/vite, sitemap integration, static output, and Cloudflare Pages-compatible defaults. Add a Cloudflare adapter only when the project explicitly needs SSR or hybrid rendering.
4. Create BaseLayout.astro -- Include <!doctype html>, <html lang> and dir, <meta charset>, viewport, title, description, canonical URL, OG basics, color-scheme, theme-color, JSON-LD structured data slot, global CSS import, font links, favicon, semantic landmark slots, and skip-to-content link. Do not hardcode analytics or trackers in the layout.
5. Set up font loading -- Self-hosted fonts or Google Fonts per DESIGN.md typography spec. Use font-display: swap. Preload critical fonts.
6. Create page shells -- One .astro file per page in the site map, importing BaseLayout, with section slots marked by comments.
7. Configure public/deployment defaults -- robots.txt, llms.txt, .well-known/security.txt, _redirects, _headers with security headers and cache policy, sitemap integration, and Cloudflare Pages build settings. Keep tracking out of source by default; if analytics are required, prefer Cloudflare Zaraz or an explicit consent-gated integration.
8. Validate -- Run pnpm build. All pages must compile without errors. Check that Tailwind utilities are generated correctly from @theme tokens. Treat Lighthouse and Website Specification checks as interpreted evidence for an audit-ready baseline, not as autonomous greenlight/pass-fail gates.

Checklist: Follow checklists/scaffold-checklist.md step-by-step.

Mode B: Section (/build-section)

Purpose: Build one page section from DESIGN.md specs.

Load these references:

• references/astro6-patterns.md -- Component patterns, slot usage, conditional rendering
• references/tailwind4-theme.md -- Utility class usage with custom theme tokens

Workflow:

1. Identify the section -- Which page, which section, what content does it display?
2. Read DESIGN.md Section 4 (Components) -- Extract the relevant component styling rules (buttons, cards, navigation, inputs).
3. Read DESIGN.md Section 5 (Layout) -- Apply the spacing scale, grid system, max content width, section spacing.
4. Read DESIGN.md Section 6 (Depth) -- Apply the correct elevation level for cards, containers, and interactive elements.
5. Read DESIGN.md Section 8 (Responsive) -- Set breakpoint behavior, grid collapsing, typography scaling.
6. Apply the Island Test -- Does any element in this section need JavaScript on the client? If yes, extract it to a Svelte island. If no, build as a static Astro component.
7. Build the component -- Create .astro file in src/components/astro/ (static) or .svelte file in src/components/svelte/ (interactive). Use Tailwind utility classes referencing @theme tokens.
8. Wire into page -- Import the component into the relevant page file. Apply the correct client directive if it is an island.
9. Validate -- Build compiles. Section renders correctly. Responsive behavior matches DESIGN.md Section 8.

Checklist: Follow checklists/section-checklist.md step-by-step.

Mode C: Island (/build-island)

Purpose: Create a Svelte 5 interactive island (carousel, flip-card, scorecard, consent gate, etc.).

Load these references:

• references/svelte5-runes.md -- $state(), $derived(), $effect(), $props(), $bindable()
• references/client-directive-matrix.md -- Hydration strategy decision matrix
• references/a11y-islands.md -- Accessibility requirements for interactive islands

Load these templates (as applicable):

• templates/svelte5-island.svelte -- Base island template with typed props and Runes
• templates/carousel-island.svelte -- Carousel with touch/swipe, autoplay, accessibility
• templates/flipcard.svelte -- CSS 3D transform + Svelte for interactive cards
• templates/scroll-animation.svelte -- IntersectionObserver + CSS keyframes
• templates/cookie-consent.svelte -- Consent management for analytics + embeds

Workflow:

1. Define the interaction -- What user action triggers what response? What state is needed?
2. Apply the Hydration Decision Matrix -- Choose the correct client directive (see section below).
3. Scaffold the component -- Use Svelte 5 Runes API exclusively. No let for reactive state. No $: labels. No createEventDispatcher. Use $props() for inputs, $state() for local state, $derived() for computed values, $effect() for side effects.
4. Implement accessibility -- Keyboard navigation, ARIA attributes, focus management, prefers-reduced-motion respect.
5. If consuming components-manifest.json -- Read the builderHints for the corresponding component entry. Use the specified hydration strategy. Wire analytics events per analytics.events. Implement consent checks per privacy requirements.
6. Wire into page -- Import in the .astro file with the correct client: directive.
7. Test -- Component hydrates at the correct time. Interaction works. State persists per spec (session/persistent/stateless). Accessibility passes.

Checklist: Follow checklists/island-checklist.md step-by-step.

Mode D: Form (/build-form)

Purpose: Integrate Zoho Forms or other form providers with consent gates and validation.

Load these references:

• references/zoho-forms-integration.md -- Zoho Forms embed patterns, responsive iframe, submission handling
• references/consent-patterns.md -- GDPR/AVG consent gate implementation

Load these templates:

• templates/zoho-form-embed.astro -- Responsive iframe with consent gating
• templates/form-consent-gate.svelte -- Consent UI that gates form loading

Workflow:

1. Identify the form -- What data does it collect? What provider? What page does it appear on?
2. Privacy assessment -- Does the form capture PII? Is consent required before loading the embed? What consent category applies (functional, analytics, marketing)?
3. Build the consent gate -- If consent is required, wrap the form in a consent gate that shows a placeholder until consent is granted. Store consent state in localStorage.
4. Build the embed -- Responsive iframe with fallback for blocked iframes. Pass URL parameters if needed (prefill fields, locale).
5. Add analytics events -- form_view, form_start, form_submit per the standard event taxonomy.
6. Wire into page -- Import the form component. Place per the site map or components-manifest.json placement rules.
7. Test -- Form loads after consent. Responsive on all breakpoints. Submission works. Analytics events fire.

Checklist: Follow checklists/form-checklist.md step-by-step.

Mode E: Deploy (/build-deploy)

Purpose: Configure Cloudflare Pages deployment, redirects, headers, and environment.

Load these references:

• references/cloudflare-pages.md -- Adapter config, build settings, environment variables
• references/security-headers.md -- CSP, HSTS, X-Frame-Options, Permissions-Policy

Workflow:

1. Verify build -- pnpm build succeeds with zero errors.
2. Configure deployment target -- For static Cloudflare Pages builds, use output: "static" and no Cloudflare adapter. Add @astrojs/cloudflare only when SSR, hybrid rendering, or Pages Functions are explicitly required.
3. Set up _redirects -- WordPress URL patterns to new paths. Old slug variants to canonical URLs. Trailing slash consistency.
4. Set up _headers -- Security headers (CSP, HSTS, X-Content-Type-Options), caching headers for static assets, CORS if needed.
5. Set up robots.txt -- Allow all for production. Block staging subdomains.
6. Validate Lighthouse -- Treat scores as interpreted performance instruments (R68), not autonomous deployment gates. Target 90+ in all categories for a normal static build; below 80 requires investigation and a surfaced finding; below 60 is a severe deployment risk that requires explicit user/project acceptance before deployment.
7. Document -- Record deployment URL, environment variables needed, and any manual steps.

Checklist: Follow checklists/deploy-checklist.md step-by-step.

---

How This Skill Consumes DESIGN.md

DESIGN.md follows the 9-section Google Stitch standard (defined in design-system-contract@1 — see ${CLAUDE_SKILL_DIR}/references/design-system-contract.md). Each section maps to a specific implementation concern:

DESIGN.md Section	What site-builder reads	What it produces
1. Visual Theme & Atmosphere	Overall mood, signature element, shadow philosophy	Guides CSS approach: flat vs layered, dense vs spacious, color treatment
2. Color Palette & Roles	Primary, interactive, neutral, semantic, surface, shadow colors	@theme color tokens in global.css
3. Typography Rules	Font families, type scale table, weight philosophy, tracking rules	@theme font tokens, Google Fonts <link>, font-display strategy
4. Component Stylings	Button, card, navigation, input styling specs	Tailwind component classes, Astro/Svelte component implementations
5. Layout Principles	Base unit, spacing scale, max content width, grid system	@theme spacing tokens, grid utilities, section spacing
6. Depth & Elevation	Shadow levels, border-radius scale	@theme shadow and radius tokens
7. Do's and Don'ts	Guardrails and prohibitions	Implementation constraints (what NOT to do)
8. Responsive Behavior	Breakpoints, typography scaling, grid collapsing, touch targets	@theme breakpoints, responsive utility patterns
9. Agent Prompt Guide	Quick color reference, example prompts	Fast lookup during component generation

Token Bridge: design-tokens.json to Tailwind CSS 4

The token bridge converts design-tokens.json into a Tailwind CSS 4 @theme block in src/styles/global.css:

@import "tailwindcss";

@theme {
  /* Colors — keyed by semantic role */
  --color-primary: #003777;
  --color-teal: #1B8CAB;
  --color-mint: #C5FFFD;
  --color-cta-start: #FC675E;
  --color-cta-end: #FFF168;
  --color-surface: #ffffff;

  /* Typography */
  --font-heading: "Source Sans 3", system-ui, sans-serif;
  --font-body: "Work Sans", system-ui, sans-serif;

  /* Shadows — keyed by elevation level */
  --shadow-ambient: /* from design-tokens.json shadows.ambient */;
  --shadow-standard: /* from design-tokens.json shadows.standard */;
  --shadow-elevated: /* from design-tokens.json shadows.elevated */;

  /* Border radius — keyed by usage context */
  --radius-small: /* from design-tokens.json border-radius.small */;
  --radius-default: /* from design-tokens.json border-radius.default */;
  --radius-medium: /* from design-tokens.json border-radius.medium */;
}

The mapping pattern is --{category}-{role}. Every token in design-tokens.json must appear in the @theme block. Every @theme property must trace back to design-tokens.json. No orphan tokens. No invented values.

---

How This Skill Consumes components-manifest.json

When a components-manifest.json is available (produced by conversion-designer, conforming to conversion-component-contract@1 -- full schema in ${CLAUDE_SKILL_DIR}/references/conversion-component-contract.md), site-builder reads each component entry and implements it. Its location is resolved via the conversion/<instance>/ entry in the project-root MANIFEST.md (Phase 0a) — not assumed at a fixed project-root path. If the manifest is absent, stop and ask for project-local bootstrap/orchestrator setup.

1. Read the component type -- scorecard, cta, trust-bar, or social-proof. Each type has specific implementation requirements.
2. Read builderHints -- Determine runtime (static or island) and hydration strategy (client:load, client:visible, client:idle, client:only).
3. Read placement -- Determine which page, position, trigger conditions, and priority.
4. Read stateManagement -- Determine persistence level (stateless, session, persistent) and implement accordingly using sessionStorage, localStorage, or no storage.
5. Read privacy -- If consentRequired is true, gate the component behind a consent check. Implement legalDisclaimer display if present.
6. Read analytics -- Wire every event in the events array. Events with consentRequired: true must not fire until consent is granted.
7. Read content -- Implement the copy, labels, images, and microcopy exactly as specified. Do not alter conversion copy.
8. Read locale -- Apply locale-specific variations per localeVariations.

Ownership Boundary

conversion-designer owns manifest content. site-builder owns implementation. Neither may cross:

• site-builder MUST NOT alter the conversion logic, scoring rules, or copy in a manifest entry
• site-builder MAY add implementation-specific fields to its own build artifacts, but these are not part of the conversion-component-contract
• If a builderHint conflicts with a technical constraint, site-builder documents the override and its rationale

---

Hydration Decision Matrix

Apply this matrix to every component to determine the correct Astro client directive:

Condition	Directive	Rationale
Above fold, needs immediate interaction (nav, hero CTA, consent banner)	client:load	User needs it on first paint. JS loads immediately.
Below fold, needs interaction when visible (carousel, scorecard, flip-card)	client:visible	Defers JS download until scrolled into viewport. Best balance of UX and performance.
Non-critical, can wait for idle (social proof, trust bar, analytics widgets)	client:idle	Loads after main thread is free. Does not block initial paint or interaction.
Client-side only, no SSR needed (consent-dependent embeds, dynamic content)	client:only	Skips server render entirely. Use for components that depend on client state (consent, localStorage).
No interaction needed (text, images, static cards, trust badges)	Static (no directive)	Zero JavaScript shipped. Render as Astro component.

The Island Test: Before assigning a client directive, ask: "Does this component need JavaScript on the client?" If it can render as static HTML with no user interaction, it should NOT be a Svelte island. Every island adds bundle weight. Every unnecessary island is a performance regression.

The Fold Test: If the component IS an island, ask: "Is it above or below the fold?" Above-fold islands use client:load. Below-fold islands use client:visible. Getting this wrong means either blocking paint for invisible components or delaying interaction for visible ones.

The Bundle Test: Before adding any dependency to an island, ask: "Does this dependency justify its bundle cost in KB?" If a dependency adds >20KB for a single use, find a lighter alternative or implement by hand.

---

Diagnostic Lenses

Apply these named tests during build and review. Each test has a binary or near-binary answer. Name the test explicitly in your findings.

1. The Island Test: "Does this component need JavaScript on the client?" If it can render as static HTML, it should not be a Svelte island. An unnecessary island is wasted bundle weight.

2. The Fold Test: "Is this component above or below the fold?" Above-fold islands use client:load; below-fold islands use client:visible. Mismatched hydration is either a paint blocker or an interaction delay.

3. The Bundle Test: "Does adding this dependency justify its bundle cost in KB?" If the dependency adds >20KB for a single use, find a lighter alternative or hand-roll it.

4. The Redundancy Test: "Does this component duplicate logic that exists elsewhere in the codebase?" If yes, extract to a shared utility. Duplication is V2 at minimum because it shapes maintenance around itself.

5. The Token Test: "Does this component use Tailwind @theme tokens for ALL visual properties?" If any color, font, spacing, shadow, or radius value is hardcoded instead of referencing a token, the component will drift from the design system. Hardcoded values are V3 because they force every future design update to hunt through components.

6. The Consent Test: "Does this component load external resources or capture personal data?" If yes, it must be gated behind consent. An ungated third-party embed is a GDPR/AVG violation.

When citing a lens in a finding, use the format: "Fails the [Name] Test -- [specific evidence of failure]."

---

Output Constraint: Evidence-Attached Findings

Every finding in the output MUST include all four fields:

• What: The specific pattern, issue, or element detected
• Where: The file path, component name, or line number where it occurs
• Why: How it fails a diagnostic test, violates a requirement anchor item, or causes measurable harm
• What Instead: The specific alternative, fix, or replacement with enough detail to implement

Findings missing any of these four fields are incomplete and must not appear in the output. A finding without a "Where" is a guess. A finding without a "What Instead" is a complaint, not a recommendation.

Example

• What: The carousel island uses client:load but is below the fold
• Where: src/components/svelte/TeamCarousel.svelte, loaded in src/pages/index.astro line 47
• Why: Fails the Fold Test -- client:load forces JavaScript download and execution on page load, blocking initial paint for a component the user cannot see yet
• What Instead: Change to client:visible so the island hydrates only when scrolled into view

---

Severity Scale

Use this severity scale for all findings:

Level	Name	Criterion	Action
V0	Cosmetic	Unnecessary but harmless; no maintenance or downstream impact	Note and move on
V1	Local	Has a cost (performance, maintenance, UX) but stays contained to one component	Flag for fixing
V2	Structural	Shapes the architecture around itself; affects multiple components or pages	Flag for redesign
V3	Contagious	Forces OTHER components, pages, or systems to be worse	Flag as urgent

V3 is not reserved for the "biggest" issues. It is reserved for issues that SPREAD. A missing alt attribute on one image is V1. A BaseLayout.astro with no SEO slot -- forcing every page to hardcode meta tags with duplicate boilerplate -- is V3, because one missing architectural feature creates N duplicated workarounds.

When assigning severity, always ask: "Does this issue force anything else to be worse?" If yes, it is V3 regardless of its own magnitude.

---

Scale Anchoring

Lighthouse Performance

All categories should score 90+ for a normal static build. Below 80 requires investigation and a surfaced finding. Below 60 is a severe deployment risk that requires explicit user/project acceptance before deployment. Scores are instruments with interpretation (R68), not autonomous go/no-go verdicts. A score of 100 is achievable for static sites with minimal client-side JavaScript; if the score is not near 100 for a static Astro build, explain the concrete cause.

Island Count

Most brochure sites should have 3-7 islands. Below 3 suggests interactive elements are being rendered as static when they should not be. Above 10 suggests static elements are being wrapped in islands unnecessarily. An island count of 0 on a site with carousels, forms, or interactive elements means the site is not functional.

Bundle Size

Total client-side JavaScript for a brochure site should be under 50KB gzipped. Above 100KB requires investigation (are all islands necessary? are dependencies justified?). Above 200KB is a severe deployment risk for a brochure site that requires explicit user/project acceptance before deployment.

---

Locale Awareness

site-builder does not generate content -- it implements content from DESIGN.md, CLAUDE.md, or components-manifest.json. However, locale affects implementation:

• Dutch long compound words -- Set hyphens: auto; overflow-wrap: break-word on text containers. Allow 10-15% wider columns than English defaults. Test hero text at longest expected word (e.g., "tandvleeschirurgie," "parodontologie").
• <html lang="nl"> -- Set the correct language attribute. This affects screen readers, search engines, and hyphenation.
• Dutch phone format -- Display as +31 43 32 14 139 (with spaces per Dutch convention).
• Dutch address format -- Street + number, then postcode + city (e.g., "Hertogsingel 57, 6211 NE Maastricht").
• AVG compliance -- Dutch GDPR equivalent. Forms capturing health-related data (dental assessments) are special-category data requiring explicit consent.

(See also: the Language Handling section below for runtime output-language policy — Unicode preservation, frontmatter conventions, BaseLayout meta-locale rules, hreflang emission. Locale Awareness is about how the built site handles locale at implementation; Language Handling is about which language Claude responds in while building.)

---

Commands

Command	Checklist	Mode	Description
/build-scaffold	checklists/scaffold-checklist.md	Scaffold	Create full Astro project from design system
/build-section	checklists/section-checklist.md	Section	Build one page section from DESIGN.md specs
/build-island	checklists/island-checklist.md	Island	Create a Svelte 5 interactive island component
/build-form	checklists/form-checklist.md	Form	Integrate form provider with consent gates
/build-deploy	checklists/deploy-checklist.md	Deploy	Configure Cloudflare Pages deployment

---

What This Skill Does NOT Do

• No design decisions -- That is site-designer. site-builder does not pick colors, fonts, or layouts. It implements what DESIGN.md specifies.
• No conversion strategy -- That is conversion-designer. site-builder does not write CTA copy, design scoring rubrics, or decide funnel architecture. It implements what components-manifest.json specifies.
• No extraction from existing sites -- That is site-refactor. site-builder does not open Chrome DevTools, inspect computed styles, or extract design tokens from live pages.
• No SEO auditing -- That is seo-strategist. site-builder implements meta tags and structured data but does not audit their effectiveness.
• No content creation -- site-builder implements content provided by the user, CLAUDE.md, or upstream skills. It does not write Dutch marketing copy or invent practice descriptions.

---

End-of-run (R26 — conditional)

Standard runs (mode determined, references loaded, requirement anchor honored, build artifact compiles, Lighthouse results interpreted, output handed to user) end normally — no self-improvement prompt fires.

The prompt fires only on builder-specific deviation. Triggers and prompt shapes:

• User wanted an alternative stack → "You asked for <framework> instead of the default Astro 6 + Svelte 5 + Tailwind 4. Should the SKILL.md add a stack-override mode, or is the default-with-confirm pattern in Phase 0 sufficient?"
• components-manifest.json schema didn't fit conversion-designer output → "The manifest entry I consumed had <field> that wasn't in conversion-component-contract@1. Should the contract be bumped to v2, or did conversion-designer emit non-conformant output that should fail validation?"
• Deploy target differed from the Cloudflare Pages default → "You wanted to deploy to <target> instead of Cloudflare Pages. Should Mode E (Deploy) add a target-selection branch, or was this a one-off?"
• i18n routing convention didn't match Astro defaults → "The site needed i18n routing in <convention> shape, but I built <other-convention> because that's the default. Should references/astro6-patterns.md add an i18n routing decision matrix, or is this case-specific?"
• Existing Astro project to integrate into (not greenfield) → "You had an existing Astro project and I scaffolded into a fresh one because Phase 0 assumes greenfield. Should there be a Mode F (Integrate) that brownfield-merges into an existing project, or do users always rebuild?"
• Hydration directive choice forced an override of the matrix → "I chose <directive> for <component> against the matrix's recommendation because <reason>. Should the Hydration Decision Matrix add this case as a documented exception, or was this judgment-driven?"
• A required upstream artifact was missing and the build proceeded with a placeholder → "DESIGN.md / components-manifest.json was missing and I generated <placeholder> to keep moving. Per the requirement-anchor doctrine this should have been a hard blocker. Should the SKILL.md strengthen the upstream-missing message, or did this case justify the override?"

If a trigger fires, surface the specific deviation in context-specific prose (not generic "any feedback?"). If the user confirms, update SKILL.md (or the relevant reference / template / checklist) inline before going idle. If the user declines, leave the suggestion in the closing summary only; do not write AI-authored suggestions into project notes/ or CLAUDE.md.

Standard runs end at build-success / deploy-success. No prompt fires for uneventful builds.

---

Language Handling

• Detect the conversation language; respond in the user's language unless explicitly asked otherwise.
• If MANIFEST.md declares an output_language: field, honor that declaration over inferred conversation language.
• Translate internal checklist labels and headings naturally — do not force English headings into non-English output.
• Preserve legal, financial, and technical terms in their original language (Trennungsjahr, MwSt, BTW, Aufhebungsvertrag, etc.).
• Preserve Unicode characters natively (ü, ö, ä, ß, etc.); never substitute transliterations (ue, oe, ae, ss).
• Frontmatter field names and enum values stay English regardless of content language. Free-text frontmatter values may follow content language where natural.
• Astro <html lang="..."> reflects the page's content language, not the conversation language; for i18n routing, follow Astro's i18n config conventions and emit hreflang alternates when more than one locale exists.
• BaseLayout meta (title, description, OG) follows the page's locale; never substitute English defaults into non-English pages because it's "easier."

(See also: the Locale Awareness section above for implementation-specific locale rules — long compound words, phone/address formats, AVG. Language Handling is about which language Claude responds in; Locale Awareness is about how the built site handles locale.)