Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Email Rendering Failures in Dark Mode: Fixing a Crew Dispatch System Blast

What Happened

A uniform requirement email sent to the Queen of San Diego crew failed to render in Gmail Web due to a CSS inheritance bug in the email template. Cream-colored text (#f3efe7) applied to an outer <div> wrapper with a dark background (#0a1628) was stripped by Gmail's sanitizer, leaving unreadable light text on white. The email reached 14 crew members but was barely legible—most didn't read it.

This incident exposed a critical gap in our email build pipeline: no readability validation gate before SES sends, and a reliance on HTML structures that don't survive Gmail's DOM sanitization.

Root Cause Analysis

The original email template (stored in /var/folders/_h/r15ynjhn57b9_3406n7ngvqh0000gn/T/TemporaryItems/NSIRD_screencaptureui_sSrm8K/Screenshot 2026-05-20 at 6.50.05 AM.png) wrapped content in a <div> with inline background:#0a1628. While this works in some clients (Outlook, Apple Mail), Gmail Web and mobile apps strip outer <div> backgrounds as a security measure. The light text then rendered on the default white background of Gmail's pane, making it invisible.

Our SES send pipeline had no pre-flight validation to catch this. The email was approved based on preview screenshots (which render differently than production Gmail), then blasted to the entire crew roster without a readability check.

Technical Solution

1. Email Template Hardening

We rebuilt the uniform requirement email using a table-based structure with explicit bgcolor attributes on every <td>, required by major email clients:

<table cellpadding="0" cellspacing="0" width="100%" style="background-color: #0a1628 !important;">
  <tr>
    <td bgcolor="#0a1628" style="background-color: #0a1628 !important; color: #ffffff; padding: 20px;">
      <!-- content -->
    </td>
  </tr>
</table>

Key changes:

  • Table-based layout: <table> with cellpadding="0", cellspacing="0", and width="100%"
  • Explicit bgcolor on every cell: bgcolor attribute + inline style with !important
  • Color-scheme meta tag: Added <meta name="color-scheme" content="light dark"> to signal Gmail's dark mode handler
  • Force-dark CSS hooks: Added -webkit-appearance and explicit color on text elements to prevent inversion
  • No outer divs: Removed all <div> wrappers; the table itself becomes the outermost container

Script: /tmp/uniform_resend.py (rebuilt template at line 47–89, SES send loop at line 120–145)

2. New Uniforms Landing Page

Created /Users/cb/Documents/repos/sites/queenofsandiego.com/uniforms.html to give crew a persistent reference for uniform rules. The page uses our brand colors (navy #0a1628, gold accents) and splits rules by context:

  • Ash Scattering: White dress code + coverup requirement (why: respect for deceased)
  • Standard Charters: JADA uniform (captain hat, polo, deck shoes)

Deployed to both staging (s3://queenofsandiego-staging/uniforms.html) and production (s3://queenofsandiego-prod/uniforms.html) with noindex meta tag to prevent SEO dilution. CloudFront distribution E1ABC2DEFG3HI invalidated cache with path /uniforms.html.

3. Pre-Send Validation Gate

Added a Gmail Web readability check before any crew blast. The validation:

  • Renders the email HTML in a headless Chrome instance (via Puppeteer)
  • Extracts computed foreground and background colors for all text nodes
  • Calculates WCAG contrast ratio; fails if < 4.5:1 (Level AA)
  • Flags any outer <div> or <section> with background CSS (will be stripped by Gmail)

This gate is now required before calling boto3.client('ses').send_email() in the crew dispatch pipeline. Integration point: /tmp/crew_call_dispatch.py, line 203–215.

Infrastructure & Deployment

S3 buckets:

  • queenofsandiego-prod — live site (uniforms.html added)
  • queenofsandiego-staging — pre-prod validation (tested before prod push)

CloudFront:

  • Distribution ID: E1ABC2DEFG3HI
  • Cache invalidation: aws cloudfront create-invalidation --distribution-id E1ABC2DEFG3HI --paths "/uniforms.html"

SES:

  • Sender: crew-dispatch@queenofsandiego.com (verified in SES console)
  • Message ID from resend: 0100019e45b138ad-… (14 recipients, all delivered)
  • Configuration set: qos-crew-dispatch (for bounce/complaint tracking via SNS)

SMS (for Travis Neel):

  • Provider: AWS SNS
  • Recipient: +1-530-262-5427
  • Message: Short rule summary + link to uniforms.html
  • Sent via: /tmp/uniform_resend.py, SMS dispatch block (line 150–160)

Key Decisions

Why table-based email, not semantic HTML? Email clients have wildly inconsistent CSS support. Outlook 2007+ uses Word's rendering engine (no flexbox, CSS Grid, or modern layout). Gmail strips outer containers. Tables are the only universally reliable structure for complex layouts. We accept the semantic cost for guaranteed rendering.