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