# PDT-308 · Smart rules + edge cases
**Date:** Mon Oct 19, 2026 (America/Chicago) · **Author:** Product Craft (executor) · **Status:** Brainstorm for PRD — not locked

Sources: `PROJECT.md`, `imports/hq-partner-brand-in-editor/` (one-pager, decisions, Sep 15 prototype), `context-collect-2026-10-19.md`, `breadboard-2026-10-19.md`, `screen-wireframe-2026-10-19.md`, Anjani Sep 23, Gerard Sep 15, Ben Oct 12 / Oct 19.

---

## 1. Proposed smart rules

### 1.1 Painted on, neutral / unpainted off

| Row state | Default **Allow** | Rationale |
|---|---|---|
| Painted with a saturated / brand-looking fill or text | **On** | Tenant intentionally branded that instance |
| Painted but **neutral** (white, grey, near-black body) | **Off** | Color exists but is structural, not brand |
| **Unpainted** (inherit, unset, platform default black / link blue) | **Off** | Assume “leave alone”; asset Allow does **not** turn these on |
| Tenant manually turns row Allow **on** despite unpainted | Apply **may write** kit color for that element type | Explicit override of the guess |

**Challenge:** “Neutral” is a heuristic (hex distance / named greys). Near-brand greys and off-whites will be wrong sometimes. Prefer eventually binding via **named roles** (Content branding) so we stop guessing hex intent.

### 1.2 Element type → kit field (no seven-field picker)

| Color row | Kit field | Tenant choice besides Allow |
|---|---|---|
| Section / column background | `primary` **or** `accent` | Primary / Secondary (stand-in until tenant swatches) |
| Text color | `textPrimary` | None |
| Link color | `link` | None |
| Button fill | `buttonPrimary.background` | None |
| Button text | `buttonPrimary.textColor` | Follows fill; empty → white |

**Not applied:** `colors.background` (usually page white), `buttonSecondary`, borders, hover, radius. Empty kit field → fall back to `primary` (white for button text). Do not invent a second kit.

**Text vs fill:** Fills are the high-visibility partner win (CTAs, bands). Text remap only when the tenant already painted that text/link — otherwise we brand every default body and privacy link.

### 1.3 Lock ≠ Allow (system respects locks; tenant UI can hide it)

- **Lock** = partner cannot edit copy/layout/hex.
- **Allow** = kit may recolor that row on Apply.
- Default: locked rows are **not** seeded when asset Allow turns on (Gerard Sep 15). Bulk “Include locked elements” turns Allow on for painted non-neutral locked rows only.
- AI must not override locks (Anjani Sep 23).

### 1.4 Partner interaction

1. Open asset → canvas still shows tenant colors (no silent mutate).
2. **Apply your brand colors** (one click) if asset Allow is on.
3. First use (Ben Oct 12): prompt **auto-apply from now on?** Remembered. Later opens may auto-apply; **Undo always**.
4. Asset Allow off → vendor-only send; Apply disabled.

---

## 2. Are we hiding complexity well with one Allow?

**Oct 19 direction:** main path = one asset-level **Allow account Brand Kit**. Per-row defaults system-set. Include locked + per-row override = advanced / rare.

> **v2 update (Oct 19, after Ben’s feedback):** section-level Allow is now **first-class in the main UX**, not “advanced / rare”. Pattern matches today’s editors: click a section → **Section Properties** → *Use account Brand Kit in this section* (on/off), plus **Primary color / Secondary color / Keep original** per color property (marketing language, no kit field names; single-mapping properties like buttons show no choice). Asset-level **Allow account Brand Kit** stays in the top bar; **Include locked elements** lives in a global **Advanced** menu the tenant can always open. Body Properties lists every section On/Off for at-a-glance visibility; canvas tags show the same. Smart defaults below still set each section’s starting state. Same pattern on banner/image layers (photos/logos never recolor).

| What we hide | Risk if wrong | Mitigation |
|---|---|---|
| Per-row Allow | Footer link or legal line remaps when tenant didn’t want it | Unpainted/neutral default off; Content branding roles later |
| Include locked | Fully locked Microsoft template never remaps | PS / tenant turns Include locked once, or unlocks specific CTAs |
| Primary vs Secondary on fills | Two-tone layouts flatten to one color | Keep a quiet Primary/Secondary on fill rows, or role binding |
| Empty / partial kit | Apply half-works; partner thinks product is broken | Explicit empty/incomplete states (below) |

**Verdict:** One Allow is the right **partner-facing and default tenant** story. It is *not* enough alone for PS-built Microsoft templates without either (a) Include locked in advanced, or (b) Content branding roles so locked CTAs are still role-bound. Swallowing complexity is good; burying the Microsoft one-click path is bad — keep Include locked one click away for admins/PS, not for every partner.

**Challenge to “smart defaults only”:** Worldpay/PS already hand-builds ~60 hrs of partner campaigns. If smart defaults miss locked CTAs, we ship a button partners click that does nothing visible — worse than a second toggle.

---

## 3. Edge cases

### Empty kit
- No colors in Account Intelligence → hide Apply, or disable with “Finish your Brand Kit” + link to kit.
- Do not apply transparent / undefined. Do not fall back to tenant portal chrome colors.

### Incomplete kit
- Missing `accent` → fall back to `primary` for secondary fills (one-pager).
- Missing `buttonPrimary.textColor` → white.
- Missing `link` → `primary` or skip links (prefer skip if unpainted default already protects most links).
- Show a quiet “Using primary for missing accent” in Apply confirmation? Nice-to-have; not blocking.

### Locked content (no tenant UI required)
- System still honors locks even if Include locked UI is buried: default = kit does not touch locked rows.
- Partner never picks hex on locked rows; Apply can still change allowed locked rows when Include locked / row override is on.
- Auto-apply must obey the same lock/Allow matrix as one-click (**open question** in PROJECT.md — recommend **yes, same rules**).

### Gradients
- Editor doesn’t support gradients well today (Anjani). Worldpay wants gradient remap.
- **V1 proposal:** treat gradient as out; if a fill is a CSS gradient, leave it (Allow off) or only remap solid stops if eng can do it safely. Do not claim gradient support in Q4 copy.

### Logos
- Logo already merges via merge tag in places; raster logos don’t recolor.
- Need transparent PNG/SVG + contrast variant selection on dark remapped bands (Anjani) — **likely out of color V1**, call out as gap.
- Dual logo row (vendor + partner placeholder) stays structural.

### Contrast
- No contrast engine in V1 (locked Sep 11). Apply can create unreadable text-on-fill.
- Soften: don’t remap text unless painted; don’t remap neutrals; optional later warn. Do not auto-flip.

### Campaign-wide / multi-page (Brian Dudley, Worldpay)
- Remembered auto-apply is **per partner preference**, not a campaign transaction.
- It approximates “profile-level setup” for *supported* surfaces opened later; it does **not** recolor PDF/presentation (out) or every asset already saved.
- Bulk “apply to all assets in this campaign” is a separate control — not in current prototype. Flag for PRD.

### Switching accounts
- Kit is **per account**. Switching account mid-session must reload kit + clear Apply state for the previous account’s colors.
- Remembered auto-apply is per partner user (or per account?) — **unset**. Recommend: per partner user × tenant, applying whichever account kit is in context.

### AI Campaign Builder path
- Sep 17: same first-use prompt in the **preview panel**.
- Oct 19 R&D: Brand Kit data in Campaign Builder AI “next sprint as part of partner brand color epic.”
- Unchangeable ACB campaigns (REQ-C.9): kit apply vs never vs preview-only — **open**. Recommend: preview resolves kit; saved locked campaigns don’t mutate.

### Custom docs vs email
| | Email | LP | Custom docs |
|---|---|---|---|
| Colors | In | In | In (Ben Oct 9 / Oct 19 brainstorm; PROJECT.md still said Out — confirm) |
| Fonts | Google Fonts list only / or none (conflict Oct 9 vs Anjani) | Apply family if in catalog | Same as LP; upload TBD |
| Width / chrome | ~610px email card | Full page | Doc canvas |
| Outlook constraint | Strong | N/A | N/A |

One shared Allow + Apply flow; surface-specific mapping tables in eng.

### Banners / images
- Separate track, same UX idea (Allow + Apply + Undo).
- Solid overlays and text can remap; photo/raster backgrounds cannot; SVG icon recolor needs SVG assets; social icons likely excluded.
- May need Oz design — don’t pretend the email prototype covers it.

---

## 4. Gaps / missing use cases

1. **Where to change remembered auto-apply** (profile vs editor) — open.
2. **Microsoft Color Controls acceptance criteria** — still undocumented.
3. **SA-11571** account-side color edit missing — partners can’t fix bad scrapes before Apply.
4. **Kit refresh after scrape** — re-apply vs snapshot (C5).
5. **Write target** — saved partner copy vs preview/send only (C2).
6. **Show kit swatches before activation** (Shane Sep 17).
7. **Tenant-wide “Try Now” / Nutanix** — different from editor auto-apply; don’t conflate.
8. **Button radius** — TBD; Q4 est. said stays tenant.
9. **Email background primary vs secondary** when primary clashes with text (Anjani).
10. **Translation font fallback** message design (Ben action Sep 23, still open).
11. **Instrumentation** — apply rate, undo rate, send-with-kit (E4).
12. **Content branding Polar idea** — not created; V1-if-cheap vs V2.

### Weak rules to challenge in PRD

- **“Neutrals off”** without a published neutral list will surprise PS.
- **“One Allow hides Include locked”** may fail Microsoft locked-template demos — keep advanced visible to tenant admins.
- **“Fonts may be in V1”** + **“email can’t do fonts”** + **PDT-256 cut** = fonts are a trap unless scoped to LP/custom docs only with catalog match.
- **Fallback empty→primary** can paint huge areas unexpectedly if accent was intentionally blank.

---

## 5. Mapping to prototype screens

| Rule / case | Prototype screen |
|---|---|
| One Allow (asset) + section Allow (v2) | v2 `#1`–`#6` (tenant) |
| Apply + Undo | v2 `#7`, `#9` |
| Auto-apply prompt | v2 `#8` |
| Later auto + toast | v2 `#10` |
| Locked kept original | v2 `#3`, `#9` |
| Neutral strip stays | All canvas “neutral” blocks |
| Content branding IA | v2 `#12`–`#14` |
| Banner / image layers | v2 `#6`, `#11` |
| Fonts (parked) | v2 `#15` |


_Section 5 screen numbers updated to prototype v2 (Oct 19). v1 screen numbers no longer apply._