Protocol Raw Header/Footer Implementation Guide

Purpose

This document is the implementation contract for the shared website header and footer used across Shopify and Cloudflare pages.

Use this before making any navigation/footer changes.

Source Of Truth

• Header + footer source file:

• shared/nav/protocol-nav.v2.source.js

• Generated targets (do not edit manually unless debugging):

• theme/assets/protocol-nav-v2.js (Shopify theme asset)
• customer-portal/public/protocol-nav-v2.js (Cloudflare customer portal)
• cdn-assets/nav/v1/protocol-nav.js
• chat/widget/nav/v1/protocol-nav.js

Component Tags In Use

• Preferred current tags:
• protocol-header-v2

• protocol-footer-v2

• Legacy tags may exist:

• protocol-header
• protocol-footer

The component code removes duplicates to prevent multiple headers/footers from rendering at once, but pages should still be cleaned up to a single header tag + single footer tag.

Header Contract

Desktop structure

Order must stay: 1. Logo (Protocol Raw) linking to homepage 2. Nav links: - How It Works - Ingredients - Nutrition 3. Primary CTA: - Calculate Your Plan with arrow

Do not add Home, About, or FAQ to primary nav unless there is an explicit product decision.

Journal is conditionally visible in the header nav, controlled by the journal-visible attribute (see Configurable Attributes below). When pre-launch mode is off, Journal stays in the footer only.

Configurable Attributes

The <protocol-header-v2> element accepts the following attributes:

Attribute	Type	Default	Description
active	string	''	Highlights the matching nav link. Values: how-it-works, ingredients, nutrition, journal, calculator.
sticky	boolean	true	Whether the header sticks to the top of the viewport on scroll.
throttle-enabled	boolean	false	When true, replaces the CTA button text/URL with waitlist/throttle values.
throttle-cta-text	string	'Join the Waitlist'	CTA button text when throttle is enabled.
throttle-url	string	calculator URL	CTA button URL when throttle is enabled.
journal-visible	boolean	false	When true, shows the "Journal" link in both desktop and mobile nav. When false, Journal is only in the footer. Used for pre-launch visibility — set from settings.prelaunch_mode in Shopify's theme.liquid.

Shopify usage in theme.liquid:

<protocol-header-v2
  active="{{ nav_active }}"
  {% if settings.prelaunch_mode %}journal-visible="true"{% endif %}
  {{ nav_throttle_attrs | strip }}
></protocol-header-v2>

Sticky and scroll behavior

• Header must stay pinned to viewport top.
• Required sticky values:
• position: sticky
• top: 0
• z-index: 1000

Current implementation applies sticky both via header host class and custom element host style to ensure consistent behavior across embeds/layouts.

• Scroll state:
• Top of page: minimal/transparent background
• Scrolled: solid cream + subtle divider/shadow

Mobile menu structure

Menu content order must stay: 1. How It Works 2. Ingredients 3. Nutrition 4. Journal (only when journal-visible attribute is set) 5. spacer 6. Calculate Your Plan -> as CTA button

CTA must be visually separated from links and near full width.

Mobile menu interaction/accessibility

Required behavior: - Open from hamburger button in header - Close when: - nav link tapped - close control tapped - overlay/background tapped - aria-expanded on menu button - aria-controls linking button to menu - keyboard focus moves into menu on open - focus returns to trigger on close - visible focus styles

Scroll locking requirement

When mobile menu is open, background page scroll must be fully locked.

Current implementation uses: - document.documentElement.style.overflow = 'hidden' - body overflow hidden - body fixed positioning with stored scroll offset - scroll restoration on close

This is intentional for iOS/mobile browsers where overflow-only locking is unreliable.

Footer Contract

• Use only one footer component per page.
• Footer lives in the same source file as header (protocol-nav.v2.source.js).
• Any footer visual/content change must be made in the shared source and synced.

Required Workflow For Changes

1. Edit only:
2. shared/nav/protocol-nav.v2.source.js
3. Regenerate all targets:
4. powershell -ExecutionPolicy Bypass -File shared/nav/sync-nav.ps1
5. Validate generated files changed as expected.
6. Deploy each surface:
7. Shopify: deploy theme asset flow used by team
8. Cloudflare apps: commit + push repo connected to Pages/Workers
9. Verify live on:
10. protocolraw.co.uk (Shopify)
11. my.protocolraw.co.uk (Cloudflare customer portal)
12. proof.protocolraw.co.uk (if mapped to Cloudflare worker/page)

Live Verification Checklist

Run these checks on each live surface:

Single instance checks

document.querySelectorAll('protocol-header-v2, protocol-header').length
document.querySelectorAll('protocol-footer-v2, protocol-footer').length

Expected: one header, one footer.

Sticky checks

const h = document.querySelector('protocol-header-v2, protocol-header');
getComputedStyle(h).position;
getComputedStyle(h).top;

Expected: sticky and 0px.

Mobile lock checks

Open mobile menu and ensure background does not move when swiping.

Optional console check while menu open:

getComputedStyle(document.body).position
getComputedStyle(document.documentElement).overflowY

Expected: body fixed (or equivalent locked state), root overflow hidden.

Common Failure Modes

1. Changes made in generated file only

2. Fix: edit source file and re-sync.

3. Cloudflare not updating

4. Fix: check repo push happened and Pages deployment was triggered.

5. Double footer/header

6. Fix: remove duplicate component tags in page template/layout.

7. Menu open but page still scrolls

8. Fix: verify scroll-lock code is present in live built asset, not just local source.

9. Sticky works only after interaction

10. Fix: verify sticky is applied to custom element host, not only an inner container.

Change Control Note

If changing header/footer behavior, update this document in the same PR/commit so future developers (human or LLM) have accurate implementation details.