docs: Update email layouts, MJML, and client previews documentation by samseely · Pull Request #1500 · knocklabs/docs

samseely · 2026-06-22T19:53:10Z

Updates documentation for email layouts, MJML, and client previews.

Also restores type="enterprise" on the client previews paid-plan callout (replacing legacy emoji="💳") to match docs convention and apply plan-feature styling from TYPE_CONFIG.

Linear Issue: KNO-13880

This commit updates documentation to reflect recent improvements: Email layouts (layouts.mdx): - Expanded branding variables table to include dark mode variants: dark_logo_url, dark_icon_url, dark_primary_color, dark_primary_color_contrast - Added new 'Branding-aware buttons' section documenting: - Legacy .button class styling with branding colors - Visual editor .block-button solid/outline behavior - Explanation of why dark mode uses !important overrides MJML support (mjml.mdx): - Added 'Dark mode support in MJML layouts' section with code examples - Added 'Branding-aware buttons in MJML layouts' section with equivalent MJML styling Client previews (client-previews.mdx): - Updated availability from Enterprise-only to all paid plans (Starter+) - Added note about free plan behavior (disabled button with tooltip) Branding docs (branding.mdx, per-tenant-branding.mdx, overview.mdx): - Added dark mode branding variables to all branding property tables Resolves KNO-13880 Co-authored-by: Sam Seely <samseely@gmail.com>

vercel · 2026-06-22T19:53:16Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 30, 2026 1:42am

Co-authored-by: Sam Seely <samseely@gmail.com>

…nges - Rename 'Branding-aware buttons' to 'Styling buttons' - Remove legacy .button class section - Remove obvious explanation sentence about dark mode - Revert per-tenant-branding.mdx to original table Co-authored-by: Sam Seely <samseely@gmail.com>

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5819a6a. Configure here.}

cursor · 2026-06-28T00:32:53Z

+</mjml>
+```
+
+For swapping logos and icons in dark mode, see [Swapping logos and icons in dark mode](/integrations/email/layouts#swapping-logos-and-icons-in-dark-mode) in the email layouts documentation.


Repeated layouts links on MJML page

Low Severity

This page already links to /integrations/email/layouts at the top. The new dark-mode and button sections add two more markdown links to the same path; only the first mention on a page should be linked.

Additional Locations (1)

content/integrations/email/mjml.mdx#L142-L143

^{Triggered by learned rule: Link Knock concepts on first mention only per page}

^{Reviewed by Cursor Bugbot for commit 5819a6a. Configure here.}

cursor

Risk MEDIUM: Updates email layout, MJML, and client preview documentation with new dark mode branding variables and button styling sections across three content sections.

Reasons

All 5 changed files are .mdx content files only — no components, config, or build files are modified, ruling out HIGH risk.
Changes span three separate documentation sections (content/integrations/email/, content/multi-tenancy/, content/template-editor/), triggering the MEDIUM cross-section rule.
The diff is content-heavy at 158 additions / 23 deletions, adding substantial new documentation sections (button styling, dark mode support in MJML).
No new pages are added and no sidebar navigation files are modified, which keeps the risk from escalating further.
Cursor Bugbot flagged 2 potential issues in a prior review that may warrant attention.

Notes

Verify the new branding variable tables in layouts.mdx, overview.mdx, and branding.mdx are consistent with each other and with the actual API — all three now list 8 branding properties and their defaults should match.
Review the MJML code examples in mjml.mdx for correctness — the CSS in the <mj-style> block appears compressed onto fewer lines which may affect readability.
Confirm the client previews availability change (client-previews.mdx) from Enterprise-only to all paid plans is accurate and approved by product.
Check the 2 issues flagged by Cursor Bugbot on commit 5819a6a for any actionable items.

_{Sent by Cursor Automation: Docs PR classifier}

Replace legacy emoji="💳" with type="enterprise" to match docs convention and restore plan-feature styling from TYPE_CONFIG. Co-authored-by: Sam Seely <samseely@gmail.com>

emisilvacab · 2026-06-29T13:22:23Z

+| `vars.branding.dark_primary_color`          | Primary brand color for dark mode (hex). Defaults to `primary_color` if not set.                                       |
+| `vars.branding.dark_primary_color_contrast` | Contrast color for text on dark mode primary color backgrounds (hex). Defaults to `primary_color_contrast` if not set. |


With this change in control these default to #FFFFFF and #000000

https://github.com/knocklabs/control/pull/9860

cellomatt

This lgtm pending any updates to address Emi's comment. Not sure if the CSS on the button styling example needs to be changed/if we always fall back to those defaults for the dark attributes in the code (i.e. vars.branding.dark_primary_color will always have a value even if it hasn't been explicitly set, meaning that we won't ever evaluate any of the fallbacks on background-color: {{ vars.branding.dark_primary_color | default: vars.branding.primary_color | default: "#000000" }} )

cellomatt · 2026-06-29T15:36:16Z

+| Property                               | Description                                                                                                |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `branding.logo_url`                    | A fully qualified URL for an image to use as the logo of this tenant                                       |
+| `branding.icon_url`                    | A fully qualified URL for an image to use as the icon of this tenant                                       |
+| `branding.dark_logo_url`               | A fully qualified URL for the logo to use in dark mode. Defaults to `logo_url` if not set                  |
+| `branding.dark_icon_url`               | A fully qualified URL for the icon to use in dark mode. Defaults to `icon_url` if not set                  |
+| `branding.primary_color`               | A hex value for the primary color. Defaults to `#000000`                                                   |
+| `branding.primary_color_contrast`      | A hex value for the contrasting color to use with the primary color. Defaults to `#FFFFFF`                 |
+| `branding.dark_primary_color`          | A hex value for the primary color in dark mode. Defaults to `primary_color` if not set                     |
+| `branding.dark_primary_color_contrast` | A hex value for the contrasting color in dark mode. Defaults to `primary_color_contrast` if not set        |
+| `preference_set`                       | A complete `PreferenceSet` to use as a default for all recipients with workflows triggered for this tenant |


This is only tangential to this PR, but should we ticket adding these properties to the OpenAPI spec so that they're included in settings.branding in the reference here?

Ah yep we should. Could you file ticket for that?

…rast Update the documented default values to match the actual implementation: - dark_primary_color defaults to #FFFFFF (not primary_color) - dark_primary_color_contrast defaults to #000000 (not primary_color_contrast) Updated in: - layouts.mdx (table and code examples) - mjml.mdx (description and code examples) - overview.mdx (branding table) - branding.mdx (variables table) Co-authored-by: Sam Seely <samseely@gmail.com>

style: Fix formatting with Prettier

a630697

Co-authored-by: Sam Seely <samseely@gmail.com>

vercel Bot deployed to Preview June 22, 2026 19:59 View deployment

docs: Simplify client previews plan callout

2e443e0

Co-authored-by: Sam Seely <samseely@gmail.com>

vercel Bot deployed to Preview June 22, 2026 23:15 View deployment

vercel Bot deployed to Preview June 22, 2026 23:23 View deployment

chore: update headings on mjml page

5819a6a

samseely marked this pull request as ready for review June 28, 2026 00:32

samseely requested review from cellomatt, emisilvacab and rachael-t June 28, 2026 00:32

cursor Bot reviewed Jun 28, 2026

View reviewed changes

vercel Bot deployed to Preview June 28, 2026 00:36 View deployment

fix(docs): restore type prop on client previews paid-plan callout

b94b155

Replace legacy emoji="💳" with type="enterprise" to match docs convention and restore plan-feature styling from TYPE_CONFIG. Co-authored-by: Sam Seely <samseely@gmail.com>

vercel Bot deployed to Preview June 28, 2026 00:47 View deployment

emisilvacab reviewed Jun 29, 2026

View reviewed changes

cellomatt approved these changes Jun 29, 2026

View reviewed changes

cursoragent and others added 2 commits June 30, 2026 01:35

style: Fix formatting in layouts.mdx

4088314

vercel Bot deployed to Preview June 30, 2026 01:42 View deployment

samseely merged commit d9a9bf5 into main Jun 30, 2026
5 checks passed

samseely deleted the cursor/email-layout-docs-updates-4587 branch June 30, 2026 01:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: Update email layouts, MJML, and client previews documentation#1500

docs: Update email layouts, MJML, and client previews documentation#1500
samseely merged 8 commits into
mainfrom
cursor/email-layout-docs-updates-4587

samseely commented Jun 22, 2026 •

edited by cursor Bot

Loading

Uh oh!

vercel Bot commented Jun 22, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

cursor Bot Jun 28, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

emisilvacab Jun 29, 2026

Uh oh!

cellomatt left a comment

Uh oh!

cellomatt Jun 29, 2026 •

edited

Loading

Uh oh!

samseely Jun 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		\| `vars.branding.dark_primary_color` \| Primary brand color for dark mode (hex). Defaults to `primary_color` if not set. \|
		\| `vars.branding.dark_primary_color_contrast` \| Contrast color for text on dark mode primary color backgrounds (hex). Defaults to `primary_color_contrast` if not set. \|

Uh oh!

Conversation

samseely commented Jun 22, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot Jun 28, 2026

Choose a reason for hiding this comment

Repeated layouts links on MJML page

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

emisilvacab Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

cellomatt left a comment

Choose a reason for hiding this comment

Uh oh!

cellomatt Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samseely Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

samseely commented Jun 22, 2026 •

edited by cursor Bot

Loading

vercel Bot commented Jun 22, 2026 •

edited

Loading

cellomatt Jun 29, 2026 •

edited

Loading