Newsletter Design System

**Referenced Files in This Document** - [newsletter-signup.njk](file://src/_includes/macros/newsletter-signup.njk) - [newsletter-spam-protection.js](file://src/assets/js/modules/newsletter-spam-protection.js) - [newsletter-signup-component.css](file://src/assets/css/modules/42-newsletter-signup-component.css) - [newsletters.njk](file://src/newsletters.njk) - [newsletter-template.html](file://src/assets/email/newsletter-template.html) - [newsletter-sky.html](file://src/assets/email/newsletter-sky.html) - [newsletter-red.html](file://src/assets/email/newsletter-red.html) - [newsletter-gradient.html](file://src/assets/email/newsletter-gradient.html) - [config.yml](file://src/admin/config.yml) - [main.js](file://src/assets/js/main.js) - [site.json](file://src/_data/site.json) - [.eleventy.js](file://.eleventy.js) - [package.json](file://package.json)

Introduction

The Ace Strategies Newsletter Design System is a comprehensive email marketing solution built with modern web technologies. This system combines a static site generator (Eleventy) with a headless CMS (TinaCMS) to deliver responsive email templates, subscription management, and content-driven newsletter campaigns.

The platform serves as a strategic communications hub for Australian corporate affairs firm Ace Strategies, providing three distinct newsletter variants with sophisticated spam protection mechanisms and seamless integration with ConvertKit for subscriber management.

System Architecture

The Newsletter Design System follows a modular architecture that separates concerns between content management, presentation, and email delivery:

graph TB
subgraph "Content Layer"
CMS[TinaCMS Backend]
MD[Markdown Content]
DATA[JSON Data Files]
end
subgraph "Processing Layer"
ELEVENTY[Eleventy Static Site Generator]
FILTERS[Custom Filters & Collections]
MACROS[Nunjucks Macros]
end
subgraph "Presentation Layer"
CSS[CSS Modules]
JS[JavaScript Modules]
EMAIL[Email Templates]
end
subgraph "Integration Layer"
CONVERTKIT[ConvertKit API]
FORMS[Form Processing]
DEPLOY[Cloudflare Workers]
end
CMS --> ELEVENTY
MD --> ELEVENTY
DATA --> ELEVENTY
ELEVENTY --> FILTERS
FILTERS --> MACROS
MACROS --> EMAIL
EMAIL --> CSS
EMAIL --> JS
JS --> CONVERTKIT
CSS --> FORMS
ELEVENTY --> DEPLOY

Diagram sources

[.eleventy.js:1-452](file://.eleventy.js#L1-L452)
[main.js:1-37](file://src/assets/js/main.js#L1-L37)
[config.yml:1-843](file://src/admin/config.yml#L1-L843)

The architecture ensures scalability, maintainability, and cross-platform compatibility while maintaining strict separation between content creation and presentation logic.

Section sources

[.eleventy.js:1-452](file://.eleventy.js#L1-L452)
[package.json:1-32](file://package.json#L1-L32)

Newsletter Components

Subscription Form System

The newsletter subscription system consists of two primary variants designed for different contexts and user experiences:

classDiagram
class NewsletterSignupMacro {
+string title
+string description
+string buttonText
+string variant
+string formId
+renderCompact() void
+renderFull() void
}
class CompactVariant {
+string formAction
+string inputType
+string inputName
+string placeholder
+string submitButton
}
class FullVariant {
+string firstNameInput
+string emailInput
+string submitButton
+string privacyText
+validateForm() boolean
}
class SpamProtection {
+Date pageLoadTime
+string honeypotField
+preventBotSubmission() void
+validateSubmission() boolean
}
NewsletterSignupMacro --> CompactVariant : "renders"
NewsletterSignupMacro --> FullVariant : "renders"
FullVariant --> SpamProtection : "uses"
CompactVariant --> SpamProtection : "uses"

Diagram sources

[newsletter-signup.njk:1-27](file://src/_includes/macros/newsletter-signup.njk#L1-L27)
[newsletter-spam-protection.js:1-24](file://src/assets/js/modules/newsletter-spam-protection.js#L1-L24)

The system implements sophisticated spam protection through honeypot fields and submission timing validation, ensuring legitimate subscribers while blocking automated bot submissions.

Section sources

[newsletter-signup.njk:1-27](file://src/_includes/macros/newsletter-signup.njk#L1-L27)
[newsletter-spam-protection.js:1-24](file://src/assets/js/modules/newsletter-spam-protection.js#L1-L24)

Styling Architecture

The newsletter component utilizes a comprehensive CSS architecture that supports both light and dark themes with automatic color adaptation:

graph LR
subgraph "Base Styles"
NS[NewsletterSignup Component]
FS[Footer Newsletter]
end
subgraph "Theme Variants"
LIGHT[Light Theme]
DARK[Dark Theme]
end
subgraph "Color Tokens"
NAVY[Navy Blue: #0D1B3E/#1F3356]
SKY[Sky Blue: #6BAED9/#1E76B8]
GOLD[Gold: #B8962E/#C9A84C]
RED[Red: #F2435A/#CC2A44]
end
NS --> LIGHT
NS --> DARK
FS --> LIGHT
FS --> DARK
LIGHT --> NAVY
DARK --> SKY
LIGHT --> GOLD
DARK --> RED

Diagram sources

[newsletter-signup-component.css:1-235](file://src/assets/css/modules/42-newsletter-signup-component.css#L1-L235)

Section sources

[newsletter-signup-component.css:1-235](file://src/assets/css/modules/42-newsletter-signup-component.css#L1-L235)

Email Template System

Template Variants

The email system provides three distinct template variants, each optimized for different brand applications and visual impact:

Template	Primary Color	Use Case	Key Features
Sky Variant	Sky Blue (#6BAED9)	Professional Corporate	Gradient accents, clean typography, elevated surfaces
Red Variant	Red (#F2435A)	Bold Brand Statement	Striking red accents, confident messaging, strong contrast
Gradient Variant	Multi-color	Premium Experience	Sophisticated gradients, artistic layout, premium feel

Template Structure

Each email template follows a consistent structure optimized for email client compatibility:

flowchart TD
START[Email Template Entry] --> PREHEADER[Preheader Text]
PREHEADER --> CONTAINER[Email Container 620px]
CONTAINER --> HEADER[Header Section]
HEADER --> HERO[Hero Section]
HERO --> DIVIDER[Divider]
DIVIDER --> CONTENT[Content Sections]
CONTENT --> CTA[Call-to-Action Strip]
CTA --> FOOTER[Footer]
FOOTER --> END[Template Complete]
HEADER --> LOGO[Logo Placement]
HEADER --> META[Issue Meta Data]
HERO --> LEADIN[Lead-in Text]
HERO --> HEADLINE[Main Headline]
HERO --> SUBTEXT[Supporting Text]
HERO --> BUTTON[Primary CTA]
DIVIDER --> RULE[Visual Rule]
CONTENT --> LIST[Feature Lists]
CONTENT --> QUOTE[Pull Quote]
CONTENT --> TEAM[Team Profiles]
CTA --> SECONDARY[Secondary CTA]
FOOTER --> LINKS[Legal Links]
FOOTER --> ADDRESS[Company Info]

Diagram sources

[newsletter-template.html:1-497](file://src/assets/email/newsletter-template.html#L1-L497)
[newsletter-sky.html:1-146](file://src/assets/email/newsletter-sky.html#L1-L146)
[newsletter-red.html:1-159](file://src/assets/email/newsletter-red.html#L1-L159)
[newsletter-gradient.html:1-194](file://src/assets/email/newsletter-gradient.html#L1-L194)

Section sources

[newsletter-template.html:1-497](file://src/assets/email/newsletter-template.html#L1-L497)
[newsletter-sky.html:1-146](file://src/assets/email/newsletter-sky.html#L1-L146)
[newsletter-red.html:1-159](file://src/assets/email/newsletter-red.html#L1-L159)
[newsletter-gradient.html:1-194](file://src/assets/email/newsletter-gradient.html#L1-L194)

Responsive Design Implementation

The email templates implement progressive enhancement with mobile-first responsive design principles:

Mobile-First Approach: Base styles optimized for small screens
Progressive Enhancement: Enhanced styles for larger viewports
Email Client Compatibility: Inline styles with graceful degradation
Accessibility Features: Proper semantic structure and ARIA labels

Content Management

TinaCMS Configuration

The content management system leverages TinaCMS for intuitive content editing with structured data models:

erDiagram
NEWSLETTERS {
string title
datetime date
text excerpt
string pdf_link
string archive_link
boolean featured
boolean draft
}
SITE_DATA {
string convertkit_form_id
string web3forms_key
string email
string phone
string address
}
PAGE_CONTENT {
string hero_title
string hero_subtitle
string newsletter_heading
string newsletter_desc
string newsletter_btn
}
NEWSLETTERS ||--|| SITE_DATA : "configured_by"
NEWSLETTERS ||--|| PAGE_CONTENT : "displayed_on"

Diagram sources

[config.yml:161-174](file://src/admin/config.yml#L161-L174)
[site.json:1-20](file://src/_data/site.json#L1-L20)
[pages.json:462-475](file://src/_data/pages.json#L462-L475)

Section sources

[config.yml:161-174](file://src/admin/config.yml#L161-L174)
[site.json:1-20](file://src/_data/site.json#L1-L20)

Collection Management

The system manages newsletter content through Eleventy's collection system with sophisticated filtering and sorting capabilities:

sequenceDiagram
participant CMS as "TinaCMS Editor"
participant ELEVENTY as "Eleventy"
participant COLLECTION as "Newsletter Collection"
participant TEMPLATE as "Newsletter Template"
participant RENDER as "Rendered Page"
CMS->>ELEVENTY : Save Newsletter Content
ELEVENTY->>COLLECTION : Process Markdown Files
COLLECTION->>COLLECTION : Sort by Date (Newest First)
COLLECTION->>TEMPLATE : Pass Collection Data
TEMPLATE->>RENDER : Generate HTML with Email Previews
RENDER-->>CMS : Preview Newsletter Archive

Diagram sources

[.eleventy.js:223-227](file://.eleventy.js#L223-L227)
[newsletters.njk:58-92](file://src/newsletters.njk#L58-L92)

Section sources

[.eleventy.js:223-227](file://.eleventy.js#L223-L227)
[newsletters.njk:58-92](file://src/newsletters.njk#L58-L92)

Security Implementation

Spam Protection Mechanisms

The newsletter system implements multiple layers of spam protection to ensure legitimate subscriptions while preventing automated abuse:

flowchart TD
FORM[Subscription Form Submission] --> HONEYPOT[Hidden Honeypot Field]
FORM --> TIMING[Page Load Time Check]
FORM --> VALIDATION[Form Validation]
HONEYPOT --> CHECK1{Honeypot Field<br/>Filled?}
TIMING --> CHECK2{Page Load Time<br/>Less than 3 seconds?}
VALIDATION --> CHECK3{Form Data<br/>Valid?}
CHECK1 --> |Yes| BLOCK[Block Submission]
CHECK2 --> |Yes| BLOCK
CHECK3 --> |Invalid| BLOCK
CHECK1 --> |No| PROCESS[Process Submission]
CHECK2 --> |No| PROCESS
CHECK3 --> |Valid| PROCESS
BLOCK --> ERROR[Show Error Message]
PROCESS --> SUCCESS[Success Message]

Diagram sources

[newsletter-spam-protection.js:1-24](file://src/assets/js/modules/newsletter-spam-protection.js#L1-L24)

The spam protection system uses sophisticated techniques including:

Honeypot Fields: Hidden form fields that bots typically fill automatically
Timing Validation: Prevents submissions that occur too quickly after page load
Input Sanitization: Validates form data before processing
Rate Limiting: Prevents excessive submissions from single IP addresses

Section sources

[newsletter-spam-protection.js:1-24](file://src/assets/js/modules/newsletter-spam-protection.js#L1-L24)

Integration Patterns

ConvertKit Integration

The system integrates seamlessly with ConvertKit for subscriber management and email automation:

sequenceDiagram
participant USER as "Website Visitor"
participant FORM as "Newsletter Form"
participant CLIENT as "Browser Client"
participant CONVERTKIT as "ConvertKit API"
participant EMAIL as "Email Delivery"
USER->>FORM : Enter Email Address
FORM->>CLIENT : Validate Form Data
CLIENT->>CONVERTKIT : POST Subscription Request
CONVERTKIT->>CONVERTKIT : Process Subscriber Data
CONVERTKIT->>EMAIL : Trigger Welcome Email
EMAIL->>USER : Send Confirmation Email
CONVERTKIT-->>CLIENT : Return Success Response
CLIENT-->>USER : Show Success Message

Diagram sources

[newsletter-signup.njk:6-8](file://src/_includes/macros/newsletter-signup.njk#L6-L8)
[site.json:13-13](file://src/_data/site.json#L13-L13)

JavaScript Module Integration

The newsletter system integrates with the broader JavaScript ecosystem through modular architecture:

graph TD
MAIN[main.js] --> NAV[Navigation Module]
MAIN --> THEME[Theme Toggle Module]
MAIN --> CURSOR[Custom Cursor Module]
MAIN --> ANIM[Hero Animations Module]
MAIN --> SEARCH[Search Module]
MAIN --> POLL[Poll Animation Module]
MAIN --> NEWSLETTER[Newsletter Spam Protection]
NEWSLETTER --> HONEYPOT[Honeypot Implementation]
NEWSLETTER --> VALIDATION[Submission Validation]
HONEYPOT --> DOM[DOM Manipulation]
VALIDATION --> EVENT[Event Handling]
DOM --> FORM[Form Elements]
EVENT --> SUBMIT[Form Submission]

Diagram sources

[main.js:1-37](file://src/assets/js/main.js#L1-L37)
[newsletter-spam-protection.js:1-24](file://src/assets/js/modules/newsletter-spam-protection.js#L1-L24)

Section sources

[main.js:1-37](file://src/assets/js/main.js#L1-L37)
[newsletter-spam-protection.js:1-24](file://src/assets/js/modules/newsletter-spam-protection.js#L1-L24)

Design System

Color Palette Architecture

The newsletter system implements a comprehensive color palette optimized for email accessibility and brand consistency:

Color Category	Light Theme	Dark Theme	Usage
Background	Canvas (#F5F4F0)	Navy (#0D1B3E)	Base email backgrounds
Surface	Surface (#EDECE6)	Surface Dark (#1F3356)	Content section backgrounds
Accent	Gold (#B8962E)	Sky Blue (#6BAED9)	Primary branding elements
Text	Navy (#0D1B3E)	White (#FFFFFF)	Primary text and headings
Support	Muted (#8892A4)	Light Gray (#8892A4)	Secondary text and icons

Typography System

The system maintains consistent typography across all newsletter variants:

Headings: Serif font for editorial content and professional tone
Body Text: Sans-serif for optimal readability in email clients
Accent Text: Monospace for technical content and code examples
Font Weights: Light, Regular, Medium, Bold for visual hierarchy

Component Architecture

Each newsletter component follows established design patterns:

classDiagram
class NewsletterComponent {
+string title
+string description
+string buttonText
+string formId
+render() HTMLElement
+validate() boolean
+submit() Promise
}
class FormElement {
+string type
+string name
+string placeholder
+boolean required
+validate() boolean
}
class ThemeAdapter {
+applyLightTheme() void
+applyDarkTheme() void
+adaptColors() void
}
class AccessibilityLayer {
+ariaLabels() void
+keyboardNavigation() void
+screenReaderSupport() void
}
NewsletterComponent --> FormElement : "contains"
NewsletterComponent --> ThemeAdapter : "uses"
NewsletterComponent --> AccessibilityLayer : "implements"

Diagram sources

[newsletter-signup.njk:1-27](file://src/_includes/macros/newsletter-signup.njk#L1-L27)
[newsletter-signup-component.css:1-235](file://src/assets/css/modules/42-newsletter-signup-component.css#L1-L235)

Section sources

[newsletter-signup.njk:1-27](file://src/_includes/macros/newsletter-signup.njk#L1-L27)
[newsletter-signup-component.css:1-235](file://src/assets/css/modules/42-newsletter-signup-component.css#L1-L235)

Deployment Pipeline

Build Process

The deployment pipeline follows a multi-stage build process optimized for performance and reliability:

flowchart LR
DEV[Development] --> BUILD[Eleventy Build]
BUILD --> OPTIMIZE[Asset Optimization]
OPTIMIZE --> MINIFY[HTML Minification]
MINIFY --> CACHE[Static Asset Caching]
CACHE --> DEPLOY[Cloudflare Deployment]
DEPLOY --> MONITOR[Performance Monitoring]
BUILD --> ASSETS[Asset Compilation]
ASSETS --> CSS[CSS Processing]
ASSETS --> JS[JS Bundling]
CSS --> POSTCSS[PostCSS Processing]
JS --> TRANSPILE[ES6 Transpilation]
POSTCSS --> CSS_MIN[CSS Minification]
TRANSPILE --> JS_MIN[JS Minification]
CSS_MIN --> ASSETS
JS_MIN --> ASSETS

Diagram sources

[package.json:5-12](file://package.json#L5-L12)
[.eleventy.js:405-424](file://.eleventy.js#L405-L424)

Environment Configuration

The system supports multiple environments with environment-specific configurations:

Development: Full debugging enabled, hot reloading, verbose logging
Preview: Production-like build with preview features disabled
Production: Optimized builds, minified assets, performance monitoring

Section sources

[package.json:5-12](file://package.json#L5-L12)
[.eleventy.js:405-424](file://.eleventy.js#L405-L424)

Troubleshooting Guide

Common Issues and Solutions

Form Submission Failures

Problem: Users report subscription form errors Solution:

Verify ConvertKit form ID in site configuration
Check browser console for JavaScript errors
Ensure proper form field names match ConvertKit expectations

Email Template Rendering Issues

Problem: Email templates appear broken in certain clients Solution:

Validate HTML structure against email client compatibility guidelines
Test with Litmus or Email on Acid for cross-client validation
Ensure proper fallback styles for older email clients

Performance Optimization

Problem: Slow page load times affecting user experience Solution:

Audit asset sizes and optimize images
Enable compression and caching headers
Minimize JavaScript bundle size
Implement lazy loading for non-critical resources

Security Concerns

Problem: Increased spam form submissions Solution:

Review spam protection implementation
Monitor submission patterns and implement rate limiting
Consider CAPTCHA integration for high-risk scenarios
Regular security audits of form processing logic

Section sources

[newsletter-spam-protection.js:1-24](file://src/assets/js/modules/newsletter-spam-protection.js#L1-L24)
[newsletter-signup.njk:1-27](file://src/_includes/macros/newsletter-signup.njk#L1-L27)

Newsletter Design System

Table of Contents

Introduction

System Architecture

Newsletter Components

Subscription Form System

Styling Architecture

Email Template System

Template Variants

Template Structure

Responsive Design Implementation

Content Management

TinaCMS Configuration

Collection Management

Security Implementation

Spam Protection Mechanisms

Integration Patterns

ConvertKit Integration

JavaScript Module Integration

Design System

Color Palette Architecture

Typography System

Component Architecture

Deployment Pipeline

Build Process

Environment Configuration

Troubleshooting Guide

Common Issues and Solutions

Form Submission Failures

Email Template Rendering Issues

Performance Optimization

Security Concerns