Website Headers

Website Headers (hereinafter the “Application”) is a JavaScript library that injects standardised metadata, a shared design system, and UI components (such as a footer and a community popup) into web pages. It provides consistent branding and legal and compliance links across SpellWare’s web properties. The Application dynamically adds Open Graph and Twitter meta tags, favicons, shared design tokens and styles, a themed footer, analytics, customer relationship management, and cookie consent scripts, and a community call-to-action popup. It also supports theme toggling with a persisted preference.

1. User Documentation

What does this library do?

The Website Headers library automatically enhances any webpage by injecting:

SEO metadata: Open Graph and Twitter Card meta tags for better social media sharing
Favicons: Complete set of favicon files for various devices and platforms
Design system: Shared design tokens in the official palette, system fonts for text with Fraunces reserved for the wordmark, and defaults for headings, links, buttons, forms, tables, and code
Footer component: Standardised footer with legal links, copyright notice, business address and phone number, theme toggle, and carbon offset badge
Analytics: Google Analytics integration
Customer engagement: HubSpot tracking, forms, and live chat
Cookie consent: Secure Privacy consent banner and preference centre
Community features: Periodic popup encouraging users to join the community
Theme support: Light/dark theme toggle with localStorage persistence
TreeNation integration: Carbon offset widget display

Features

Accessibility-focused: High-contrast theming and semantic metadata support
Responsive design: Mobile-friendly layout with adaptive footer
Theme persistence: Remembers user’s theme preference across sessions
Consent-aware: Cookie consent banner provided by Secure Privacy
Performance optimised: Minified production build with deferred script loading
Cross-platform: Works on all modern browsers and devices

Integration

Simply include the library script in your HTML:

<script src="https://cdn.spellware.dev/headers/index.js" async defer></script>

The library will automatically enhance your page with all the features listed above.

Design system

The injected stylesheet is the shared visual language for every page.

Design tokens (--witch-* colours, --font-*, --radius, --surface, --foreground, --link, and more) load on every page. The tokens switch automatically when the page has the is-dark class, which the footer’s theme toggle controls.
Page chrome and element defaults style main, headings, links, buttons, forms, lists, tables, blockquotes, and code. main is a centred card, and the footer sits at the end of the page rather than being fixed to the viewport.
Pages should use the tokens (for example var(--surface)) instead of hard-coded colours, so dark mode keeps working.

Opting out of features

Pages with their own layout can opt out of parts of the library by listing features in a space-separated data-nhcarrigan-exclude attribute on the html element. The attribute must be present before the script runs.

<html lang="en-GB" data-nhcarrigan-exclude="layout footer cta ads">

Feature	Effect
`layout`	Skips the shared page chrome and element styles. Design tokens still load.
`footer`	Skips the shared footer.
`cta`	Skips the community popup.
`ads`	Skips the advertising script.

Metadata, icons, consent, analytics, and HubSpot always load. Any meta tag or icon that a page already declares is left alone, so pages can ship their own for crawlers that do not run scripts.

2. Technical Documentation

Prerequisites

Node.js (latest LTS version recommended)
pnpm package manager
TypeScript knowledge for development

Installation

Clone the repository:

git clone https://github.com/spellware/website-headers.git
cd website-headers

Install dependencies:
Terminal window
```
pnpm install
```

Development

Local Development Server

To work on the library locally with hot reloading:

pnpm dev

This command:

Compiles TypeScript to JavaScript in watch mode
Starts a development server on port 8080
Serves a test HTML page at http://localhost:8080
Automatically updates when you make changes

Building for Production

pnpm build

This command:

Runs ESLint for code quality checks
Compiles TypeScript to JavaScript
Minifies the output using Terser
Injects the current version number
Outputs the final file to prod/index.js

Code Quality

pnpm lint

Runs ESLint with strict configuration to ensure code quality.

Project Structure

src/
├── index.ts      # Main library code
└── develop.ts    # Development server

build.ts          # Build script with minification
index.html        # Test page for development
package.json      # Project configuration
tsconfig.json     # TypeScript configuration
eslint.config.js  # ESLint configuration

The prod/ directory is generated during build output and is not a permanent source directory.

Architecture

The library is structured as a single TypeScript file that:

Metadata Injection: Dynamically creates and injects meta tags for SEO and social sharing
Asset Loading: Loads external resources (fonts, scripts, stylesheets)
Component Creation: Builds UI components (footer, community popup) and injects them into the DOM
Event Handling: Sets up interactive features (theme toggle, social panel, modal)
State Management: Manages theme preferences and modal display timing using localStorage

Key Components

Meta Tags: Open Graph and Twitter Card metadata
Favicon Management: Complete favicon set for all platforms
Global Styles: CSS-in-JS for consistent theming
Footer Component: Branded footer with interactive elements
Community Popup: Community CTA with timing-based display logic
Theme System: Light/dark mode with system preference detection
Analytics Integration: Google Analytics, HubSpot, and Secure Privacy script injection

External Dependencies

The library loads several external resources:

Google-hosted font assets used by the injected stylesheet
Font Awesome icons for UI elements
Google Analytics for website analytics
HubSpot for tracking, forms, and live chat
Secure Privacy for cookie consent management
TreeNation widget for carbon offset display
Google AdSense for monetisation

Environment Variables

npm_package_version: Automatically injected during build process

3. Legal Documentation

Licensing

This software is licensed under Naomi’s Public Licence.

Copyright Notice: Copyright held by Naomi Carrigan.

Third-Party Services

The Application integrates with several third-party services that have their own terms of service and privacy policies:

Analytics and Tracking

Google Analytics: Web analytics
- Measurement ID: G-86HKPXSJCX
- Data collected: Page views, events, referrers, device and approximate location information, and cookie identifiers
- Privacy policy: Google Privacy Policy
HubSpot: Visitor tracking, form capture, and live chat
- Data collected: Page views, cookie identifiers, form submissions, and live chat messages
- Privacy policy: HubSpot Privacy Policy

Secure Privacy: Cookie consent banner and preference centre
- Data collected: Consent choices, a generated identifier, and timestamps
- Privacy policy: Secure Privacy Privacy Policy

Advertising

Google AdSense: Contextual advertising platform
- Client ID: ca-pub-3569924701890974
- May collect user data for ad personalisation
- Privacy policy: Google Privacy Policy

Environmental Impact

TreeNation: Carbon offset and environmental impact tracking
- Widget code: a17464e0cd351220
- Purpose: Display environmental impact metrics
- Privacy policy: TreeNation Privacy Policy

Content Delivery

SpellWare CDN: Custom content delivery network
- Domain: cdn.spellware.dev
Hosts: fonts, images, scripts, and cursors
- Subject to SpellWare privacy policies

Data Collection and Privacy

Local Storage Usage

The Application stores the following data in the user’s browser:

theme: User’s preferred colour scheme (light/dark)
naomi-community-cta: Timestamp of last community modal display

External Resource Loading

The Application loads resources from external domains:

Font files from cdn.spellware.dev
Analytics scripts from googletagmanager.com
Tracking and live chat scripts from hs-scripts.com and related HubSpot domains
Cookie consent scripts from secureprivacy.ai
Advertising scripts from googlesyndication.com
Icons from Font Awesome CDN

Compliance Considerations

Organisations using this library should be aware that it:

Loads third-party tracking scripts
May be subject to GDPR, CCPA, and other privacy regulations
Includes advertising components that may require disclosure
Collects analytics data that may need privacy policy updates

Contact Information

For legal inquiries regarding this Application:

Email: [email protected]
Community: Chat Server

4. Contributing Documentation

Getting Started

We welcome contributions to the website-headers project! Please review our contributing guidelines and Code of Conduct before getting started.

Development Workflow

Fork the repository and clone your fork locally
Create a new branch for your feature or bug fix:
Terminal window
```
git checkout -b feature/your-feature-name
```
Install dependencies:
Terminal window
```
pnpm install
```
Start the development server:
Terminal window
```
pnpm dev
```
Make your changes and test them at http://localhost:8080
Run linting to ensure code quality:
Terminal window
```
pnpm lint
```
Build for production to verify everything works:
Terminal window
```
pnpm build
```
Commit your changes and push to your fork
Create a Pull Request with a clear description of your changes

Code Style and Standards

TypeScript: All code must be written in TypeScript
ESLint: Code must pass all linting rules (@nhcarrigan/eslint-config)
No warnings: Build process fails if ESLint warnings are present
Comments: Use JSDoc comments for functions and complex logic
Accessibility: Maintain accessibility features (fonts, colours, ARIA labels)

Testing

Manual Testing: Use the development server to test changes
Cross-browser: Test in multiple browsers when possible
Mobile Responsive: Verify changes work on mobile devices
Theme Testing: Test both light and dark themes

Areas for Contribution

High Priority

Performance optimisation: Reduce bundle size, optimise loading
Accessibility improvements: Enhanced ARIA support, keyboard navigation
Mobile experience: Better responsive design, touch interactions
Browser compatibility: Support for older browsers

Medium Priority

Documentation: Improve inline code documentation
Error handling: Add graceful fallbacks for external resource failures
Testing framework: Implement automated testing
Configuration options: Make the library more customisable

Low Priority

Additional themes: More colour scheme options
Animation effects: Subtle transitions and animations
Internationalisation: Multi-language support
Advanced analytics: More detailed event tracking

Pull Request Guidelines

Clear title: Descriptive title explaining the change
Detailed description: Explain what changes were made and why
Screenshots: Include before/after screenshots for UI changes
Testing notes: Describe how you tested the changes
Breaking changes: Clearly mark any breaking changes
Version impact: Indicate if this should be a major, minor, or patch release

Code Review Process

Automated checks: ESLint and build checks must pass
Manual review: Code will be reviewed for quality and functionality
Testing: Changes will be tested in various environments
Feedback: You may be asked to make additional changes
Merge: Once approved, changes will be merged to main branch

Release Process

Semantic versioning: We follow semver (major.minor.patch)
Automated builds: Successful merges trigger automated builds
CDN deployment: Production builds are deployed to CDN
Documentation updates: Documentation is updated with releases

Getting Help

Issues: Post in the #bug-reports or #feature-requests forum channels on our Discord community
Community: Join our chat server for real-time help
Email: Contact us at [email protected] for private inquiries

Recognition

Contributors will be recognised in:

Git commit history
Release notes
Project documentation
Community acknowledgments