v5.13.0 28 February 2026 Feature

Shared Footer System — Cross-Domain Parity, Trust Layer & Build Integrity

Why This Matters

The footer is the only UI surface that appears identically on both speybooks.com and docs.speybooks.com. Until now, each site maintained its own footer independently — content drifted, links diverged, and there was no mechanism to detect or prevent inconsistency. For a platform that positions itself on engineering discipline, this was a structural gap.

This release introduces a formally specified shared footer system governed by a single JSON content contract, validated at build time with Zod, synchronised via a deterministic lock token, and rendered through parallel Astro components that share a common logic utility. The footer now includes a three-block institutional trust strip that surfaces security grade, jurisdiction, and integrity metadata — visible only when the security posture warrants it.

A unified deployment orchestrator (deploy-ui.sh) treats all three UI surfaces — marketing, docs, and portal — as a single atomic unit, verifying nine formal invariants before promoting to production.

Content Contract (Single Source of Truth)

  • footer-data.json drives both sites All footer content — brand, columns, secondary columns, social links, legal metadata — lives in a single JSON file in the monorepo. Both renderers consume it identically. No hardcoded strings in either component.

  • Zod schema validation at build time Every build validates footer content against a strict schema. Malformed JSON, empty columns, duplicate labels, or invalid URLs fail the build before deployment.

  • Schema version gating Both renderers enforce schemaVersion: 1. A schema change without updating both renderers is a build failure, not a silent regression.

Cross-Domain Build Integrity

  • Deterministic lock token (I5b) count-lines.sh now generates a SHA-256 lock token from the version string and git HEAD SHA. This token is embedded in loc.json and verified by the docs footer at build time. If the monorepo deploys a new version without syncing to docs, the docs build fails.

  • Lock projection (I5c) The full 64-character hash is stored in data-lock on the <footer> element for audit. The first 8 characters are displayed in the trust strip for human verification.

  • deploy-ui.sh orchestration The marketing deploy script generates loc.json, syncs it along with footer-data.json, footer-schema.ts, footer.ts, and footer-logic.ts to the docs site, then builds. The sync is atomic — partial states are prevented.

Shared Logic Utility

  • footer-logic.ts eliminates drift Link resolution, current page detection, build date formatting, and security grade gating are now implemented once and imported by both renderers. Context-aware functions accept 'marketing' or 'docs' parameters to handle domain-specific behaviour (e.g. relative links on marketing, resolved links on docs).

Trust Layer (SEC-1)

Three-Block Institutional Trust Strip

  • Security Posture Displays security grade, perimeter protection status, and last audit date. All values are build-time injected — no runtime fetches.

  • Jurisdiction & Governance Shows jurisdiction, data residency, and ICO registration. Sourced from footer-data.json legal metadata.

  • Deterministic Integrity Displays the 8-character lock short-hash and API surface count (endpoints from OpenAPI spec). Signals spec-first architecture without requiring the reader to navigate to the docs.

Grade-Gated Visibility

  • Confident or silent The trust strip renders only when gradeRank >= 4 (security grade A or A+). Below that threshold, the entire strip is omitted. No degraded state is ever shown to users.

  • Numeric rank model Grades use a numeric mapping (A+: 5, A: 4, B: 3, C: 2, F: 1) to prevent the lexicographic misclassification bug where "B" > "A+" in string comparison.

Unified Deployment Orchestrator

deploy-ui.sh — Lock-Sync-Build-Gate-Promote

A new production-grade orchestrator treats all three UI surfaces as a single deployment unit, eliminating the distributed build race condition where marketing and docs could deploy with different footer content.

  • Five-phase pipeline Preflight, Lock, Sync, Build, Gate, Promote — with --dry-run and --skip-portal flags for safe testing and footer-only changes.

  • Nine formal invariants verified at deploy time I1 (single source), I2 (link count parity), I2b (link ordering parity), I5 (version equality via lock), I5b (lock equality), I5c (lock projection), I6 (docs resolution totality), I7 (schema version safety), T3 (race elimination).

  • Multi-page lock sampling Extracts data-lock from multiple rendered pages per site (index plus one deep page), verifying consistency across page layouts. Detects multi-lock corruption where a page accidentally renders two different footer instances.

  • Link parity gate Extracts footer hrefs in DOM order from rendered HTML, compares ordered sequences across domains after resolving marketing relative links to absolute. Verifies docs has no unresolved relative hrefs. Works correctly on minified single-line HTML by targeting <footer role=contentinfo> with PCRE substring extraction.

  • rsync safety model Only marketing rsyncs to a separate production root. Docs and portal serve dist/ in-place. Pre-promotion safety checks prevent rsync into source directories.

  • Configurable and auditable DEPLOY_OWNER environment variable, Node/pnpm version logging in banner, atomic file sync via tmp-then-rename, and schema version constant for upgrade tracking.

Docs Landing Page Fixes

Card Grid Restoration

  • Three-column grid restored The .sd-card-grid base rule was missing from speydocs.css — only responsive media query overrides existed. Without the base display: grid; grid-template-columns: repeat(3, 1fr) rule, cards defaulted to block layout (single column). Added the missing base rule. Responsive collapse to 2 columns (769-1024px) and 1 column (below 768px) now works correctly.

  • Correct flexbox architecture The .sd-landing container now uses flex: 1 0 0% (not auto) so flex-grow claims all remaining viewport space, pushing the footer below the fold on 1080p displays. Hero padding reduced from 72px 24px 44px to 48px 24px 32px, reclaiming 36px of vertical space without sacrificing design.

  • .sd-cards-section fills remaining space Uses flex: 1 0 auto to grow into available space after the hero, with padding: 20px 24px 80px for breathing room above the footer.

Layout & Responsive Behaviour

  • Five-column primary grid Brand + tagline + social icons, then Product, Developer APIs, Legal, and Service columns. Collapses to 2 columns at 640px and 1 column below that.

  • Secondary columns centred SpeyTech and Open Source columns align to grid positions 2-3 on desktop, using explicit grid-column placement rather than fragile spacer divs.

  • Trust strip centred on desktop, stacked on mobile Blocks wrap naturally on smaller screens. white-space: nowrap applies only above 640px to prevent horizontal overflow.

Bottom Bar

  • Version and build date Version links to the changelog. Build date uses ordinal formatting (“Saturday 28th of February 2026”) via the shared utility.

  • Status indicator Animated ping dot with “All Systems Operational” link. Single green dot — the only colour element in the footer.

  • Legal metadata Copyright, jurisdiction, data location, ICO registration, and support email.

Accessibility

  • Landmark role — <footer role="contentinfo"> (A11Y-1)
  • Per-column navigation groups — each column wrapped in <nav aria-label="Footer navigation — {heading}"> (A11Y-2)
  • Focus rings — 2px solid outline with 2px offset on all interactive elements (A11Y-6)
  • aria-current="page" — computed at build time via shared isCurrentPage(), with constraint that at most one link across the entire footer carries this attribute (A11Y-5)
  • Trust region — role="region" aria-label="Security and trust information" with non-interactive content (no focus traps)

Operational Impact

  • Zero content drift between marketing and docs footers
  • Build failure on schema violation, version mismatch, or missing lock token
  • Deterministic lock token prevents stale cross-domain deployments
  • Nine formal invariants verified before every production promotion
  • Link ordering parity enforced across domains at deploy time
  • Trust strip omitted automatically when security grade drops below A
  • Single utility file governs all shared logic — no duplicated implementations
  • Docs landing page card grid restored to 3-column layout with correct responsive breakpoints
  • Footer below fold on standard 1080p displays
  • 118,120 lines of code across the platform, 198 endpoints across 31 resources

Versioning

  • Marketing Footer.astro → v5.1.0
  • Docs Footer.astro → v2.1.0
  • sd-footer.css → v3.0.0 (full rewrite, BEM naming, trust layer)
  • footer-logic.ts → v1.0.0 (new shared utility)
  • count-lines.sh → SD-BUILD-LOC-1.2 (lock token generation)
  • deploy-ui.sh → v2.1 (new unified UI orchestrator)

Files Changed

Backend: None

Frontend / Marketing site:

  • src/components/Footer.astro — v5.1.0

    • Rewritten to consume footer-data.json content contract
    • Zod validation and schema version gating at build time
    • Trust layer with SEC-1 three-block architecture
    • Lock token imported from loc.json
    • Shared logic imported from footer-logic.ts

  • src/data/footer-data.json — content contract (schemaVersion 1)

  • src/data/footer-schema.ts — Zod validation schema

  • src/types/footer.ts — TypeScript type definitions

  • src/utils/footer-logic.ts — shared logic utility

  • scripts/count-lines.sh — SD-BUILD-LOC-1.2

    • Lock token generation added (SHA-256 of version + git SHA)
    • loc.json output now includes lock field

Frontend / Docs site:

  • src/components/Footer.astro — v2.1.0

    • Rewritten to match wireframe v3 with BEM class naming
    • Lock token verification from loc.json
    • Shared logic imported from footer-logic.ts
    • Secondary columns use explicit grid-column placement

  • src/styles/sd-footer.css — v3.0.0

    • Complete rewrite: BEM naming, token contract, trust layer styles
    • Responsive collapse algebra: 1 → 2 → 5 columns
    • Status ping animation, focus ring tokens

  • src/styles/speydocs.css

    • Added missing .sd-card-grid base rule (3-column grid)
    • Removed duplicate .sd-card stub
    • .sd-landing flex basis changed from auto to 0% for footer-below-fold
    • .sd-hero padding reduced for shorter viewport accommodation
    • .sd-cards-section flex-grow for remaining space fill

  • src/data/footer-schema.ts — synced from monorepo

  • src/types/footer.ts — synced from monorepo

  • src/utils/footer-logic.ts — synced from monorepo

Infrastructure:

  • /var/www/deploy-ui.sh — v2.1 (new)
    • Unified UI orchestrator: Lock-Sync-Build-Gate-Promote
    • Nine-invariant integrity gate with multi-page sampling
    • Link parity and resolution verification across domains
    • Handles minified HTML via PCRE role=contentinfo targeting
    • --dry-run and --skip-portal flags
    • Configurable ownership, atomic sync, rsync safety guards

Known Issues

  • Trust layer values (security grade, audit date, perimeter status) are currently hardcoded placeholders. STH integration is the next step — the gating logic is production-ready, only the data source needs wiring.
  • “OpenAPI canonical” in the trust strip is plain text — will become a link to docs.speybooks.com/openapi.json in a follow-up.
  • The data-git-sha audit attribute is not yet exposed on the <footer> element.

This release establishes the architectural foundation for cross-domain UI parity, moving the footer from an independently maintained component to a formally verified shared contract — and the deployment pipeline from independent builds to invariant-gated atomic promotion. The same engineering discipline applied to the API surface is now applied to the presentation layer and its deployment lifecycle.