Reference
Design best-practices
The design best-practices guides are the editorial law for everything the WTD site ships: one cross-cutting global-rules.md, five per-page-type specs (homepage, service page, case study, blog/SEO content, contact/lead capture), and an anti-patterns.md catalog of real defects found in a 100-site audit — read the matching one before you touch a page, because they encode hard tradeoffs that single-operator-agency conversion lives and dies on.
These files live in website/_design-best-practices/ and are flagged as authoritative reading in website/CLAUDE.md: "read the matching one before touching a page." They are content/UX policy, not code — but the rules they impose (one <h1>, schema types, form field caps, preload="none" hero video) show up enforced across routing, components, SEO, accessibility, and performance budgets. This page summarizes what each guide enforces so a maintainer knows which one to open and when.
The unifying principle, stated at the top of global-rules.md:
When SEO and CRO conflict, SEO takes priority. Rationale: no traffic means no data to optimize against. Flag the tradeoff in copy or comments rather than silently choosing.
That one sentence resolves most arguments these guides could otherwise produce — don't strip a page below its ranking word-count to chase a cleaner look; surface the depth lower on the page where crawlers index it and skimmers can skip it.
Global rules (apply to every page)
global-rules.md is the baseline; the per-page-type files override it only where they say so explicitly. Its sections:
- CTA conventions. One dominant primary CTA per page, repeated at least three times (persistent header, above-fold hero, end-of-page band). The primary must be a solid filled button — two equal-weight ghost buttons is "a recurring failure that depresses click-through." Copy is action-led and specific: "Get a free SEO audit," never "Contact," "Learn more," or "Submit." The hero CTA needs a real
href, neverhref="#". - Form patterns. Lead-capture forms ≤5 fields; hero forms 1–3 (a single URL/email field converts highest). Every input needs a real
<label>(visually hidden is fine; a placeholder is not a label). No math CAPTCHA — use invisible reCAPTCHA v3 or a honeypot, and lazy-load reCAPTCHA on field-focus (it's 370+ KB). Multi-step beats single-page when total fields ≥6. Submit copy mirrors the action ("Send message," "Request proposal," "Book a call"). - Trust signals. Above-fold trust is mandatory — layer at least three of: named client logos, a third-party review rating (Clutch/G2/Trustpilot/Google), a specific outcome stat, an award badge, headcount/years-in-business. Testimonials must be attributed (name, title, company, photo/logo). For a one-person agency, founder photo + full name in the hero measurably raises trust.
- Page speed budgets. <2 MB first load, hero <500 KB, ≤80 HTTP requests. No autoplay hero video >1 MB; WebP/AVIF only for raster; WOFF2 only (≤2 families × 3 weights = 6 files); ≤5 third-party scripts via GTM; no jQuery in new builds.
- Mobile considerations. ≥14 px readable text, 16 px interactive. Never
user-scalable=no/maximum-scale=1(WCAG 1.4.4). No horizontal overflow at 375 px. Cookie banners as a thin bottom strip, never covering the hero. The primary CTA shows in the collapsed mobile nav. Hamburger-only nav at ≥1024 px is forbidden. - Navigation structure. 5–7 desktop nav items. The primary CTA stays accessible at every scroll position — the mechanism (sticky header, sticky CTA bar, FAB, in-content repetition) is a judgment call, the persistence is not. A skip link is the first focusable element in
<body>; the logo links home from every page. - Internal linking. Each service page links to 2–3 case studies, contact, home, and 2–3 sibling services; each case study links back to its service page, contact, and 2 other cases; each blog post links to a service/contact in-body plus 3–5 related articles. Descriptive anchor text, no orphan pages.
- Accessibility floor (non-negotiable). One
<h1>per page; sequential heading hierarchy (never heading tags as styling handles); every<img>has analt(emptyalt=""only for decorative);<html lang="en">; labels on all inputs; no positivetabindex. - Cookie consent. Bottom-anchored bar, not a modal; static poster fallback for the hero video for non-consented users; pre-blocking scripts load before any tag fires; region-gate the banner server-side.
- SEO floor. Unique
<title>(Primary Keyword | Brand, 50–60 chars) and<meta description>(140–160) per page; single keyworded<h1>; canonical tag everywhere; schema.org per page type; sitemap + robots + OG/Twitter cards. - Tracking & analytics hygiene. One source-of-truth analytics tool, all tags through GTM, quarterly tag audit. Audited sites running dual GA4 + deprecated UA + 5 behavior tools paid the perf cost with no extra insight.
The accessibility floor is non-negotiable, and most of these are five-minute fixes
A skip link, <html lang>, sequential headings, and one <h1> are the four most-violated rules in the audit cohort (one site shipped 13 <h1> elements; one shipped lang="ja" on an English site). The site enforces these structurally — see accessibility — but the guide is where the rationale lives.
Per-page-type specs
Each spec opens with the page's job, lists required elements in order, gives a Do / Don't table, and closes with tradeoff notes that explain the reasoning behind the otherwise-arbitrary rules. Read the matching file before editing that page type.
Homepage — homepage.md
Job: communicate audience + offer + outcome in the first viewport, layer credibility before the third scroll, and route every visitor to a service page, a case study, or contact.
The required-elements list is a 12-item ordered skeleton: header with persistent CTA → above-fold hero (H1 ≤12 words stating what you do and for whom, a 1–2 sentence subhead naming a concrete outcome, an action-led CTA, ≥1 trust signal) → logo wall (≥6 logos) → 3–6 service cards → quantified stats band → 2–3 case-study previews → founder/about block (mandatory for a solo agency) → 3–5 attributed testimonials → process block → FAQ (5–8 bottom-funnel questions) → final CTA band mirroring the hero → footer.
Key tradeoffs the file argues:
- SEO vs CRO density — keep the hero and primary scroll path lean, push depth (FAQ, methodology) lower; don't strip below ~600 words for a cleaner look (SEO wins).
- Pricing on the homepage — for a solo agency entering market, show a starting price or range; qualified-lead efficiency beats enterprise upside at low volume.
- Founder-forward framing — lead with the founder; a solo shop pretending to be a team gets caught on LinkedIn/About mismatch.
- Section count — 8–12 sections, one purpose each; cut anything that doesn't answer who/what/why-you/proof/what-next.
- Logo wall — six recognizable logos beats fifteen unknown ones; padding with vendor logos to fake density damages credibility.
Service page — service-page.md
Job: one service per URL, rank for the service's primary keyword cluster, convert qualified prospects. The 14-item skeleton runs sticky-CTA header → keyworded H1 (e.g. "SaaS SEO Services," not "Get Found Online") → value prop → above-fold CTA → trust strip (4+ named clients in the same category) → "What you get" deliverables (5–8 bullets) → process (3–5 steps) → outcome metrics with date ranges → mini case study → pricing or a pricing range → service-specific FAQ → internal links → final CTA band → footer.
Notable Do/Don't: name the buyer ("for SaaS founders"), not "businesses"; list concrete deliverables, not capabilities; include a "who this is NOT for" qualifier; 600–1,500 words of substantive copy (<300 won't rank); Service schema with provider, areaServed, serviceType; FAQ targets bottom-funnel objections, not "what is SEO?" Tradeoffs cover one-service-per-page (SEO wins; keep a /services/ catalog as an index but give every offering its own URL), pricing transparency ("Starts at $X for [scope]"), audience specificity (a "SaaS SEO" page converts far better than "SEO services"), internal-link density (≈5 links good; 20+ reads as a link farm), and service page vs PPC landing page.
Case study — case-study.md
Job: convert by leading with a quantified outcome, naming the client, and giving enough technical specificity to read as credible — "Generic anonymized stories perform worse than no case studies at all." The 12-item skeleton: persistent-CTA header → H1 "How [Client] [Achieved Outcome] with [Service]" → hero (client logo, one-line outcome, key facts) → three-stat KPI band (each stat carries a date range) → The Problem → The Approach (named tools/channels/frameworks) → The Outcome (metrics + a chart/before-after screenshot) → named-stakeholder pull-quote → deliverables list → related case studies → service link + final CTA → footer.
Never ship a placeholder case study
The audit found cases published with placeholder filenames (gh.png, fwefw.png) and unnamed clients — it signals carelessness and depresses credibility for the entire portfolio. Do not publish a case study until both the client name and the headline metric are real and approved. A solo agency with 3 strong cases beats a portfolio of 30 weak ones.
Tradeoffs: specificity vs confidentiality (use percentages + date ranges when absolute numbers can't be shared — "+183% YoY in Q2 2025"); industry verticalization (group by SaaS / e-commerce / professional services); length (1,200+ words for search, hierarchical headings/pull-stats for skimmers); /case-studies/[client-slug]/ descriptive URLs with Article + BreadcrumbList schema; and linking to the live client site with rel="noopener" but not nofollow — these are real endorsements, and for a new agency the goodwill outweighs the lost link equity.
Blog & SEO content — blog-seo-content.md
Job: the primary SEO surface — each post targets one primary keyword cluster, competes on depth, and routes engaged readers to a service/contact CTA without disrupting the read. The 13-item skeleton: header (for long-form reading, auto-hide-on-scroll-down is preferred over always-sticky to preserve viewport height) → breadcrumb with BreadcrumbList schema → keyworded article H1 (≤60 chars) → byline (linked author, <time datetime> publish/updated dates, read time) → featured image with alt + caption → above-fold TOC for posts >800 words → semantic h2/h3 body → in-body contextual CTA at ~50% scroll → end author bio → 3 related articles → final CTA → comments only if moderated → footer.
Tradeoffs: word count (1,500–3,000 for competitive terms; SEO wins over CRO's preference for 600); in-body CTAs (soft, topic-tied; max three total — one mid-article, one end, one sidebar); newsletter vs lead magnet (lead magnet qualifies better for a solo agency); pillar/cluster strategy (one 3,000+ word pillar plus 5–10 long-tail cluster posts); updating beats republishing (cannibalization between two posts on the same term hurts both); featured images are functional, not decorative (real screenshot/chart, never stock); and GEO/AEO — clear factual answers in the first 150 words of each H2 section, FAQPage schema, extractable lists/tables, named bylines, and updated-date stamps so ChatGPT / Perplexity / Google AI Overviews can cite the page.
Contact & lead capture — contact-lead-capture.md
Job: convert intent into a qualified inbound lead with minimal friction — the page where conversion friction matters most. The 8-item skeleton: persistent-CTA header → action-led H1 ("Start a project," "Request a proposal") → subhead setting a response-time SLA and what-happens-next → primary form (≤5 fields above the fold) → alternative methods (clickable mailto:, tel:, a Calendly/scheduling link) → trust signals near the form → office address(es) → footer.
The form-field requirements are concrete: name + email + project description (textarea) is the 3-field floor; 5 above the fold is the ceiling; every field has a <label>; HTML5 input types (type="email", type="tel", type="url") for correct mobile keyboards; a honeypot for spam (reCAPTCHA only if the honeypot proves insufficient); submit copy mirrors the action; confirm with a real /thank-you page (not a 3-second toast); and trigger an immediate auto-response email.
Tradeoffs: form length (4–5 fields is the band for a solo agency where unfit leads are the most expensive failure mode; a 9-field form converts at half the rate of a 4-field one); Calendly vs form (offer both — form primary, "or book a call directly →" secondary); pre-qualification via a budget-range dropdown ("Under $5K" … "$50K+" … "Not sure yet" keeps genuine fits in the funnel); multi-step when total fields ≥6; show your direct email (hiding it reads as too-big or too-small); set only an SLA you can actually hit; a real address (even co-working) beats a PO box; skip live chat nobody answers; and a dedicated success page enables GTM/GA4 conversion tracking.
How these map to the live forms
On the WTD site, /contact is a Sanity page doc whose ctaSection runs in embed mode (a pasted HubSpot embed rendered via set:html), and /free-website-audit posts directly to the HubSpot Forms v3 API. Both honor the ≤5-fields / real-<label> / action-led-submit rules above. See HubSpot & lead capture.
Anti-patterns catalog — anti-patterns.md
anti-patterns.md is the failure-mode reference: "Concrete failure modes observed across the 100-site audit cohort. Each item is a specific defect with a fix path. Sites are anonymized; counts and figures cite real audit measurements." Open it when reviewing a build or diagnosing why something feels off — it's the negative space of the per-page specs. Six categories:
| Category | Representative audited failures (with the fix) |
|---|---|
| Performance | Hero video 1.6–8 MB autoplay (the single largest perf failure, ~20% of sites) → poster + preload="none" + lazy-load; 4–9 MB animated-GIF logos; duplicate library loads (jQuery 3.5.1 + 3.4.1); 150–238 HTTP requests; eager reCAPTCHA on every page; 56 stylesheets + 58 scripts of WordPress plugin bloat |
| Accessibility | Multiple <h1> (3, 9, 10, 13); missing <h1>; heading levels as visual sizing; user-scalable=no; placeholder-only labels; math CAPTCHA; missing skip link; lang="ja" on English; positive tabindex; accessibility-overlay widgets used as a substitute for native fixes |
| Content & conversion | Generic hero copy ("We Help Businesses Grow"); stat counters that render "0+" when JS fails; href="#" hero CTAs; rotating 4-message carousels; no above-fold CTA; three competing hero CTAs; 9-field "contact" forms; on-load popup modals; hidden pricing on a low-volume agency |
| Trust & credibility | Anonymous testimonials; "Trusted by leading brands" with no logos; static review badges that don't link; pay-to-play award badges; stale mid-2010s badges; AI-generated / stock-portrait testimonial photos |
| Technical hygiene | Production served from staging URLs (*.wpenginestaging.com); 404s on intuitive URLs (/services/, /pricing/); empty meta description + shared "HOME | Brand" title; service-worker scope generating 88 warnings per navigation; CSP blocking the site's own analytics; visible console JS errors; lazy sections blank on initial paint |
| SEO | Identical <title> across pages; multiple posts on the same keyword (cannibalization); hidden publish dates; IMG_2843.jpg-style filenames; "click here" / "learn more" anchors |
| Mobile-specific | Pill/tab rows overflowing to 600–900 px on a 375 px viewport; 9–12 px CTA text; card right-edge overflow; YouTube embed above the headline pushing the value prop below the fold; marquees overlapping the hero before scroll triggers fire |
Render trust and stats server-side — JS is enhancement only
Two recurring audited defects both trace to client-only rendering: stat counters that show "0" when the animation fails, and below-fold logo/stat strips that paint blank because the JS hasn't fired. The WTD scroll-in system follows this rule — the SSR markup is the source of truth and reveals are pure enhancement, with a no-JS fallback that renders everything visible. See scroll-in reveals.
How the guides connect to the codebase
These are policy documents, but the site enforces most of them in code or convention:
- The SEO floor (one keyworded
<h1>, unique title/description, canonical, schema by page type, dynamic sitemap/robots) is implemented across the routes — see SEO & structured data. - The accessibility floor (skip link,
lang, labels, touch targets) is baked into the components and accessibility pages. - The page speed budgets are restated as hard limits in performance budgets and enforced via images & fonts (WOFF2 ≤6 files, AVIF/WebP, no jQuery).
- The form rules (≤5 fields, real labels, action-led submit, honeypot, GTM-only tracking) govern both live lead paths — HubSpot & lead capture.
- Sanity is the single source of truth for copy, so the per-page-type required-element lists are realized as section types assembled through the page builder; the homepage/service/case-study/blog skeletons map onto
homepage.sections[],service.sections[],post, and the index singletons.
Where this lives
| File | What it governs | Read it before |
|---|---|---|
website/_design-best-practices/global-rules.md | Cross-page CTA / form / trust / speed / mobile / nav / linking / a11y / cookie / SEO / analytics rules; the SEO-over-CRO priority | Touching any page |
website/_design-best-practices/homepage.md | Homepage required elements, Do/Don't, tradeoffs | Editing the homepage |
website/_design-best-practices/service-page.md | Service-page skeleton, one-service-per-URL, pricing, schema | Editing a /services/<slug> page |
website/_design-best-practices/case-study.md | Case-study skeleton, named-client + quantified-outcome rule | Editing a case study / portfolio post |
website/_design-best-practices/blog-seo-content.md | Blog post skeleton, word count, GEO/AEO, pillar/cluster | Editing a /blog/<slug> post |
website/_design-best-practices/contact-lead-capture.md | Contact-page skeleton + form-field requirements | Editing the contact / lead form |
website/_design-best-practices/anti-patterns.md | Audited failure modes with fixes, six categories | Reviewing a build or diagnosing a defect |
website/CLAUDE.md lists these under "Read first (authoritative)" and restates the resolving rule: when SEO and CRO conflict, SEO wins. Related sibling pages: routing, section types, SEO & structured data, accessibility, performance budgets, HubSpot & lead capture, blog & portfolio.