email-design.md: giving the email agent a brand brief

A hex code tells an email agent which blue to use. It does not tell it why a brand puts a small monospace label above every headline, or why its dividers are thin lines instead of boxes.

That was the problem with our first brand model at Brew. We captured a lot of values and still lost the details that made a brand recognizable.

The object had a field for almost everything

When we started, a brand looked like structured data. We modeled colors, typography, assets, and a large collection of style properties. A crawler filled the fields, then the generation path assembled them into context for the email agent.

The result could have the right color and font and still look generic. Each new brand brought a detail the schema had not anticipated. We could keep adding fields, but the more useful question was how a designer would explain the same brand to another person.

A designer would write a guide. Exact values where they matter, examples where they help, and prose explaining the decisions between them.

So we changed what we asked the extraction agent to produce.

The document is the brief

We call it email-design.md. It is an editable Markdown document describing how a particular brand should appear in email.

Here is a fictional, shortened example:

# Acme email design
 
## Voice
 
Write for engineers who want the setup instructions first.
Use short explanations and name the product action precisely.
 
## Signature details
 
- Put a small monospace label above the main headline.
- Use thin dividers between sections, without drop shadows.
- Reserve the accent color for the primary action.
- Use one product screenshot when it explains the task.
 
## Assets
 
Use the approved logo URL from the asset list.
Do not invent product images or customer logos.

The document can hold a rule such as "use the accent on one thing per email" beside the exact color value. It gives the agent an instruction for cases we did not anticipate individually.

The brand instructions are visible. A correction becomes part of the next brief.

Markdown is useful here because people can read and edit it without a special form. Headings give the document structure, and adding a new design rule does not require a new database field. That is a practical format choice. It is not a claim that Markdown always uses fewer tokens than JSON or that every model was trained primarily on Markdown.

Email needs its own design instructions

A website and an email have different rendering constraints. Support for fonts, layout, and dark mode varies across mail clients. A design that looks right in a browser preview still needs inbox testing.

The brand document therefore includes email-specific guidance: fallback fonts, container widths, table-friendly layout recipes, and choices for light and dark backgrounds. Those instructions help the agent make suitable decisions; they do not guarantee identical rendering in every client.

Imagery has different requirements, so Brew also uses image-style.md for image guidance. Keeping the two concerns explicit is easier than asking one list of tokens to describe every medium.

Start from the material you already trust

A live website is useful evidence, but it is not always the authority. It may contain an old campaign or a style experiment the brand team no longer uses.

Brew can use supplied brand guides, logos, images, and other reference material alongside the domain. Uploaded brand guidance takes precedence over inferences from the website when they disagree. Review the resulting document, especially where the source material is incomplete or inconsistent.

A domain and approved files give the extraction process different kinds of evidence.

If the button shape is wrong, change the instruction. If the voice is too formal, replace the vague adjective with an example sentence. That correction is much easier to discuss than a large object full of fields nobody wants to edit.

What the change does and does not prove

The document puts approved asset locations, product names, and design decisions directly into the generation context. That reduces the gaps the model would otherwise have to guess at. It does not eliminate incorrect output.

We also changed other parts of the email agent during this work. Without a controlled comparison, I would not attribute an overall quality improvement to the file format alone. The claim I can make is narrower: the brand brief is easier to inspect, correct, and reuse.

A generated email still needs a factual and visual review. Read the claims against the brief, test the links, and inspect the inbox result. The email briefing guide covers that handoff.

The same context is available to connected agents

Brew's MCP server is now available. A compatible assistant can work with Brew through the documented tools, using the same brand context as the app. The MCP announcement and setup documentation explain the connection.

I like that the brand instructions have an obvious place to live. When an email feels wrong, we can point to a sentence, change it, and try again. That is a more useful conversation than asking the model to "make it more on-brand" one more time.