Wordnerds Site
— Proven Page Patterns

Version: 0.4
Last updated: 2026-05-29
Status: Living doc — add to this whenever a homepage or page-level design decision is validated in the browser.

This file captures implementation decisions that emerged from building real pages. It is distinct from DESIGN.md (which covers tokens and atomic rules) and GRID.md (which covers grid mechanics). Read this before authoring any page schema, styled spec, or fragment.

1. CTA Rules

Every CTA is a lozenge button — never a plain text link

CTAs that ask a user to take a meaningful action must be rendered as a .wn-btn button, not a plain <a> link or inline text.

Rule: if the action is named in marketing copy as a call to action (e.g. "Subscribe to CX Corner", "Book a diagnostic", "See how it works"), it must be in a button lozenge. If it is a navigation shortcut that a user might also find in the nav or footer, a plain link is acceptable.

Button style by surface

Never render a secondary CTA in a dark or coloured section as .cta-secondary (arrow link) if it is a conversion action. Arrow links are for subordinate navigation only.

CTA groups

Use .cta-group (display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-m)) for any side-by-side CTA pair. Do not place two button-style CTAs without a cta-group wrapper.

2. Section Rhythm and Padding

Section backgrounds — white-dominant, don't alternate by default

Default to white, and do not alternate backgrounds section-by-section. Per-section toggling (light/dark, or white/grey) reads as formulaic and dated. White is the dominant content background; a grey (wn-section--alt) is an occasional breather to break up a long white run. A rough rhythm of roughly two clear sections then a grey is typical, but it is a judgement call, not a fixed cadence — vary it to suit the page (updated 2026-05-27 per Pete).

Dark is reserved for the hero and the footer zone (hero wn-section--dark; the footer-cta band + footer organism). Avoid making a mid-page content section dark to "break things up" — the white-dominant rhythm with the occasional grey does that work, and the two dark bookends frame the page. wn-section--yellow / tints stay deliberate, sparing accents (e.g. the footer-cta close).

Regression note: strict light/dark alternation was reverted twice; the prior framing was "sparse, deliberate accent". The current principle: white-dominant, grey as an occasional breather (used with judgement, not a fixed every-third cadence), dark only at hero + footer. Don't reintroduce per-section alternation.

White-on-white section joins collapse automatically

When two consecutive sections both have a white background (no background modifier), the CSS in site.css collapses the second section's padding-top to 0. This prevents the double-padding gap that otherwise makes adjacent sections look too far apart.

What this means for schema authoring: you do not need to manually adjust padding on white sections. The rule fires automatically. The affected section pairs on the homepage are:

• problem-elaboration → guide-proof
• guide-proof → how-it-works
• persona-pathways → proof-outcome

What the rule does NOT collapse: sections on different backgrounds (dark → white, light-grey → white, etc.). Those transitions need the full padding on both sides to signal the background change.

When to use --generous padding

Use wn-section--generous (padding-block: var(--space-2xl-3xl)) for sections that need extra breathing room: feature pillars, proof outcomes, hero CTAs. Use default wn-section padding for most content sections.

Because of the white-on-white collapsing rule, a --generous section that follows a plain white section will still have its padding-top collapsed. Its padding-bottom is unaffected. This is intentional — the generous bottom gives the section visual weight; the collapsed top removes the double-gap.

Hero bottom edge

The hero section (.wn-section--hero) has padding-bottom: 0 and overflow: hidden. The product visual fills to the very bottom of the dark section and is clipped cleanly there. The following white section begins immediately below with its own top padding intact.

Do not reintroduce a negative margin-bottom bleed on .hero__visual. The clean cut is the intended look — the dark section sits flush against the white one.

3. Blockquote Typography

Canonical blockquote treatment (validated 2026-05-28)

Blockquotes are real-person quotes only — never for marketing framing (use .answer-capsule for that). The canonical treatment is the Sainsbury's proof-stat style:

• White card background + brand-yellow top border (4px) + box-shadow: var(--wn-shadow-card)
• <p><mark>"…"</mark></p> — the yellow <mark> sits behind the quote text
• Font: --wn-font-rounded, --fs-xl, font-weight: 800
• Attribution: plain <cite> below the <p> — --fs-sm, --wn-mid-grey, font-style: normal

This replaces the prior blue-left-border + opening-glyph treatment. This is now site-wide. Do not reintroduce the old treatment.

Fragment requirement: always wrap quote text in <p> inside <blockquote>. Example correct pattern: <blockquote><p><mark>"…"</mark></p><cite>…</cite></blockquote>.

Blockquote vs answer-capsule — do not confuse them

Never use a blockquote for marketing copy. Never use an answer-capsule for a customer or interviewee quote.

4. Pillar and Card Icons

Uniform icon colour within a section

All icons within a single section (e.g. feature pillars) must use the same colour chip. Do not alternate yellow/blue/yellow across siblings — it reads as arbitrary rather than intentional.

Default: yellow (--wn-brand-yellow) for icon chips. Use blue only if the section is already using yellow for something else (e.g. a yellow background section where yellow chips would disappear).

The ::before top-bar accent on .guide-proof__pillar must also be uniform — remove any nth-child colour overrides.

5. Proof Stat Panel (ProofOutcomeTemplate)

CTA alignment inside flex columns

The .proof-stat container is display: flex; flex-direction: column. Without an explicit override, flex children stretch to full width. Any .cta-secondary inside .proof-stat must have align-self: flex-start so the underline animation spans only the link text, not the full column width.

This rule is already in site.css:

.proof-stat .cta-secondary { align-self: flex-start; }

General rule: whenever a .cta-secondary (arrow link) sits inside a flex-direction: column container, it will stretch to full width unless align-self: flex-start is set. Check for this in any new fragment that uses flex column layout.

6. Resources Row

CTA-secondary links in resource columns

Read all posts, Browse playbooks, and similar column CTAs are navigation shortcuts — plain .cta-secondary arrow links are correct here. Do not promote these to button lozenges.

Exception: if a resource column is actively promoting a conversion action (e.g. "Download the playbook now"), a button is appropriate.

7. CTA Hierarchy by Funnel Stage

Definitions

Direct CTA: A high-commitment action — booking a demo, requesting a diagnostic, signing up for a trial. The visitor is entering a sales conversation. Example: "Book a diagnostic."

Transitional CTA: A low-to-medium commitment action — reading a case study, downloading a playbook, watching an explainer, routing to a deeper use-case page. The visitor goes deeper but does not commit to a sales conversation. Examples: "See how it works," "Read how [Customer] did it," "Download the playbook."

Visual hierarchy by funnel stage

The yellow button (.wn-btn--primary) signals the action Wordnerds most wants the visitor to take at their current stage of the journey. The ghost button (.wn-btn--ghost) is the secondary, lower-risk route.

Post-proof rule: after a named proof point (ProofOutcomeTemplate, FooterCTATemplate), the direct CTA earns the yellow button regardless of the page's primary funnel stage. The visitor has scrolled past the evidence; by that point they are temporarily TRYING even if the page is otherwise EXPLORING.

Both CTA types must appear on EXPLORING pages

A hero section on an EXPLORING-stage page must have both:

1. A transitional CTA (yellow — the primary visual)
2. A direct CTA (ghost — the secondary visual)

A hero with only the direct CTA on an EXPLORING page excludes the majority of visitors who are not yet ready to book. A hero with only a transitional CTA loses the visitors who arrived ready. Both are constraint breaks.

The site nav always carries the direct CTA

SiteNavOrganism.primary_cta always renders the direct CTA ("Book a diagnostic"). This is a permanent escape hatch for TRYING-stage visitors regardless of which section of the page they're reading. It does not replace the hero's direct CTA — it's an additional safety net.

Consistent direct CTA label

The direct CTA label must be consistent across the site: "Book a diagnostic" on all pages and in the navigation. Do not vary the label per page. Variant labels fragment recognition on return visits.

8. Adding a New Page — Checklist

Before authoring a new page schema, verify:

1. Section sequence: does any white section immediately follow another white section? The padding will auto-collapse. You do not need to do anything — just know it happens.
2. Every CTA: is it a named conversion action? If yes, button lozenge. If navigation shortcut, plain link is fine.
3. Blockquotes: every <blockquote> must wrap its text in <p> with a <mark> around the quote text. Check your fragment output.
4. Icon sets: uniform colour within a group — no alternating.
5. Flex column containers: any .cta-secondary inside one needs align-self: flex-start.
6. Hero (if present): use dark-split by default — not centred. When no commissioned asset exists yet, supply a placeholder with explicit dimensions so the asset commission is unambiguous. Standard dark-split placeholder dimensions (.wn-col-5 right column, portrait): 480×540px. Use centred only when the page genuinely has no visual slot (e.g. a text-only comparison page). Do not add margin-bottom bleed to .hero__visual.
7. Image placeholders: always include concrete pixel dimensions (e.g. 640×360px, 48×48) in every image src placeholder string — not just aspect ratios. The renderer parses these to size the placeholder box honestly. See §12 for the full rule.
8. Numbered chip colour: yellow chip = step sequence (StepCards); blue chip = numbered capability list (FeaturePillars 4-up). See §10.

9. Visual density — marketing pages are visual-led, low-text

Validated against the reference-site research (2026-05-27). The B2B SaaS reference sites we benchmarked are markedly more visual and lower on text than a default copy-led page. Wordnerds marketing pages should match that: every content section earns a visual, and body copy is trimmed to what the visual cannot carry. This is a SYSTM-aligned principle (reduce reading load; let the visitor scan and grunt-test in seconds), not a per-page whim — apply it on every marketing page unless a page-type rubric overrides.

What "visual-led" means in slots the renderer already supports:

Text economy rule. When a section gains a visual, cut its body copy to match — the image carries weight the prose no longer has to. Keep the AEO answer-capsules intact (they are citation surfaces), but trim pillar/step/card bodies to scannable length. A wall of text next to an image is the failure mode.

Concision + cross-page distinctness are pipeline policy, stated once in docs/PIPELINE-CONVENTIONS.md ("Concision within AEO" — target the AEO-minimum word count, capsule is usually the whole prose; "Visual-led, visually-distinct pages" — section vocabulary is a palette, vary it per page). Not restated here.

This is also a learning-capture rule. Visual + text-density decisions like these were previously hand-edited into the rendered schema and lost on regeneration. They belong here (cross-page principle), in the page brief's "Additional context" (page-specific intent), and in the layout-spec (the actual slots) — never only in the schema. See briefs/homepage/decisions.md 2026-05-27 for the worked example.

9.1 Reinforcement: hero CTA on EXPLORING pages (cross-ref §7)

Confirmed on the homepage (2026-05-27): the hero primary (yellow) CTA is the transitional "See how it works"; the direct "Book a diagnostic" is the ghost secondary. Most homepage visitors are EXPLORING and not ready to book — leading with "Book a diagnostic" as the primary is lower-value than routing them into the method. The nav always carries "Book a diagnostic" as the standing direct CTA for the ready-now minority. This is §7's EXPLORING row; it is restated here because a regeneration flipped it.

10. Numbered Circle Chips

Two distinct numbered-chip primitives live across the site. They share the circle shape but differ in colour and semantics.

Design rule: yellow circle = action sequence; blue circle = numbered capability list. Do not use yellow chips in FeaturePillars 4-up, and do not use blue chips in StepCards. The colour difference is load-bearing — it signals two semantically different things.

Leading zeros: strip at render time. "01" → "1". Chips never display 01, 02, etc.

Alignment: .step__header { align-items: flex-start; } — the chip top-aligns with the first line of a wrapped h3. Do not centre-align.

11. Unified Answer-Capsule Style

.answer-capsule has a single global style (validated 2026-05-28). Do not add per-section overrides.

.answer-capsule {
  font-size: var(--fs-md);
  font-style: italic;
  color: var(--wn-dark-grey);     /* same as body — intentional */
  border-left: 3px solid var(--wn-brand-yellow);
  padding-left: var(--space-s);
  margin-bottom: var(--space-m);
}

Rule: the capsule is the section's lede/thesis paragraph. The yellow line + italics + slight size bump (--fs-md vs --fs-base) differentiate it from body without changing colour — deliberately the same colour as body so it reads as authoritative prose, not a callout.

Prior per-section .proof-outcome .answer-capsule override was removed — the global default now matches what proof-outcome previously applied.

12. Image Placeholder Dimensions

The renderer (lib/util.ts renderImage) parses pixel dimensions from image src placeholder strings and applies them as aspect-ratio + max-width inline styles. This makes placeholder boxes occupy the same footprint as the final production asset, keeping layout review honest.

Convention: always include explicit pixel dimensions in every image placeholder string, formatted as <W>×<H>px (e.g. 640×360px, 760×960px, 48×48). Aspect-ratio notation alone (e.g. 16:9, 4:3) is insufficient — it does not produce a sized box.

Copy-author rule: use concrete pixel sizes. If the dimensions are not yet decided, use the standard dimensions from the table above and flag [CONFIRM DIMENSIONS].

13. Problem-Elaboration Column Alignment

The ProblemStatementTemplate renders a two-column grid. The correct alignment is align-items: start on the grid — not align-items: stretch. This means:

• Left column (body text): flows naturally from the answer-capsule above; the text starts at the top of the grid row.
• Right column (blockquote): tops align with the left-column body, not with the answer-capsule.
• Whitespace at the bottom of the shorter column is intentional — do not add height: 100% to equalise.

The CSS rule is:

.problem-elaboration .wn-grid { align-items: start; }
.problem-elaboration__inner blockquote { margin-top: 0; }

Do not revert to align-items: stretch — an earlier attempt to lift paragraph 1 above the grid to fill the gap produced a worse layout (low-right gap, content flow disrupted).

14. ICP Persona Avatars

Three photoreal headshots represent the canonical Ideal Customer Profiles on persona-routing surfaces (homepage persona-pathways cards; reusable on the /for-analysts, /for-cx-managers, /for-cx-leaders sub-page heroes).

Asset map — design-system/brand-assets/people/:

Canonical persona detail is NOT duplicated here. Goals, pains, quotes, tone register, and the full identity-shift rationale live in wordnerds-wiki/assets/canonical/strategic/personas.md — the single source of truth. Link to it; do not copy persona copy into the design system (it drifts).

Visual convention — match these when adding or regenerating:

• Synthetic faces, never a real person's published photo. Grounded in the real CRM base (UK Housing-dominant, business-casual register) for demographic accuracy only — see the brief for the HubSpot grounding method.
• Framing matches the existing customer headshots (Kat-Eastwood-Sainsburys.png): tight head-and-upper-shoulders, small headroom, cut at the upper chest. Crop from the full-res original, don't upscale.
• Soft, slightly-warm mid-grey studio gradient background; soft even lighting; natural skin texture (avoid the over-smoothed "AI plastic" look).
• 1024px square JPEG (~q80, ~120–155 KB) — crisp at the 48px card crop, usable at sub-page hero size.
• Genders retained per canon (Anna F, Mark M, Sarah F). Sarah is fuller-figured — true to the seniority cohort we actually deal with.
• The whole set must read as one shoot: same background, lighting, crop, and register.

Generation recipe: nano-banana-pro via scripts/generate-image.py with --no-ref-images (the script's default ref-set is brand illustrations — wrong for photoreal people). Full briefs + provenance: briefs/icp-avatars/icp-avatar-briefs.md.