cameleer-saas/docs/superpowers/specs/2026-04-26-email-template-polish-design.md

Email Template Polish

Polish the 4 Logto SMTP connector email templates with branded visuals, playful desert/caravan copy, and extract them from inline Java strings to standalone HTML files.

Current State

All 4 email templates are hardcoded as inline HTML strings in EmailConnectorService.buildSmtpConfig() (lines 164-189). They share a minimal structure: centered text "Cameleer" wordmark in #C6820E, a one-line message, a large verification code, and a small expiry note. No logo, no footer, no personality.

Design Decisions

• Tone: Playful desert/caravan voice matching the sign-in page personality
• Layout: Structured card — amber header bar, white body with watermark, footer with separator
• Footer: Help link ("Questions? Contact your administrator") + tagline ("Cameleer — Apache Camel observability")
• Header: Text-only "Cameleer.io" centered on amber #C6820E bar, no logo image
• Watermark: Cameleer logo at ~7% opacity, oversized, positioned top-right showing compass + cameleer + camel head. For production: pre-faded PNG hosted at a public URL to avoid CSS opacity issues in Outlook desktop.
• Storage: External HTML template files, not inline Java strings

Template Structure

All 4 templates share the same layout, differing only in subject, headline, body copy, and safety note.

+------------------------------------------+
|        [amber #C6820E header bar]        |
|            Cameleer.io (white)           |
+------------------------------------------+
|                                          |
|  Headline (bold, 16px)        [watermark |
|  Body text (14px, 1.6lh)      logo at   |
|                                7% opacity|
|        +-------------------+             |
|        | VERIFICATION CODE |             |
|        | cream pill, amber |             |
|        | border, monospace |             |
|        +-------------------+             |
|                                          |
|  Expiry/safety note (13px, muted)        |
|                                          |
+------------------------------------------+
|  Questions? Contact your administrator   |
|  Cameleer — Apache Camel observability   |
+------------------------------------------+

Copy

Type	Subject	Headline	Body	Safety note
Register	Your caravan pass is almost ready	Welcome to the caravan!	Enter this code to verify your email and claim your spot. The dunes wait for no one.	This code expires in 10 minutes. If you didn't request this, you can safely ignore this email — no camels were harmed.
SignIn	Your Cameleer sign-in code	Back at the oasis already?	Here's your sign-in code. The caravan master is checking credentials.	This code expires in 10 minutes.
ForgotPassword	Reset your Cameleer password	Lost in the dunes?	No worries — enter this code to reset your password and get back on the trail.	This code expires in 10 minutes. If you didn't request a password reset, you can safely ignore this email.
Generic	Your Cameleer verification code	Quick checkpoint	Here's your verification code. Just making sure it's really you at the reins.	This code expires in 10 minutes.

Visual Specifications

• Font stack: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
• Card max-width: 480px, no fixed width (shrinks naturally on mobile)
• Card border: 1px solid #e8e0d4
• Header: background: #C6820E, padding 20px 24px, text centered, 22px bold white
• Code pill: background: #FDF6EC, border: 2px solid #C6820E, border-radius 8px, padding 16px 32px, 32px bold monospace with 8px letter-spacing in #C6820E
• Watermark: Absolutely positioned top:-30px; right:-50px, 320x320px, 7% opacity, clipped by overflow: hidden on body container
• Footer separator: 1px solid #e8e0d4
• Footer text: "Questions?" at 12px #999, tagline at 11px #bbb

Responsiveness

No media queries needed. The single-column layout works from ~280px up:

• Card uses max-width: 480px with no fixed width
• Code pill uses display: inline-block, wraps within container
• All sizes in px (email clients handle rem/em inconsistently)
• Watermark clipped by overflow: hidden, never causes horizontal scroll

File Structure

Template files

Create 4 HTML template files at src/main/resources/email-templates/:

src/main/resources/email-templates/
  register.html
  sign-in.html
  forgot-password.html
  generic.html

Each file is a complete HTML email body (inline styles, self-contained). The verification code placeholder uses Logto's {{code}} syntax.

Watermark image

Create a pre-faded PNG of the Cameleer logo at 7% opacity on a transparent background. Source the logo from design-system/assets/cameleer-logo.png and generate the faded version using ImageMagick or similar (one-time step, committed to the repo).

Place the image at src/main/resources/static/platform/assets/email-watermark.png. Spring Boot serves /platform/assets/** as static resources automatically. The template files use a placeholder {{watermarkUrl}} that EmailConnectorService replaces with https://<PUBLIC_HOST>/platform/assets/email-watermark.png at runtime.

Java changes

EmailConnectorService.buildSmtpConfig():

• Read each template file from classpath (src/main/resources/email-templates/*.html) at startup or on first use
• Replace {{watermarkUrl}} with the configured public host URL
• Pass the HTML content as the content field in each Logto template config
• Keep subjects in Java (they're short strings, no benefit from externalizing)

Email Client Compatibility

• Gmail, Apple Mail, Outlook.com: Full support — opacity, absolute positioning, border-radius all work
• Outlook desktop (Word renderer): CSS opacity is ignored. The pre-faded watermark PNG solves this — the transparency is baked into the image itself, not applied via CSS. Absolute positioning is supported via VML fallback that Outlook generates.
• No CSS classes: Everything uses inline styles (email clients strip <style> blocks inconsistently)
• No external fonts: System font stack only