email-kit

What it is

Everything an app needs to send good-looking transactional and notification email from a server: EmailLayout (the shell), eight parts, three templates and renderEmail. It is built on React Email — tables with role="presentation", a 600px fluid column, the system font stack, inline light colours and one small <style> block for dark mode and phones. Every string comes in through props, so the same three templates cover every email an app sends. It is a block: you pull it once with shadcn add, and then you own it.

The colours are the design tokens converted to hex (email clients read neither CSS variables nor OKLCH) in email-tokens.ts, which is generated — never edit it by hand. The kit is server-safe: no 'use client', no hooks.

Install

npx shadcn@latest add @vegastack/email-kit

This installs eight files into components/email/ and adds one npm dependency, react-email. It composes no other registry component — email cannot use the app's CSS.

Preview

Each preview is the real template rendered by renderEmail, shown light and dark.

Rendering and sending

renderEmail returns the HTML part and the plain-text part. Hand both to your mail provider; set the subject yourself.

import { NotificationEmail } from "@/components/email/notification-email";
import { renderEmail } from "@/components/email/render";

const { html, text } = await renderEmail(
  <NotificationEmail
    brand={{ name: workspace.name, url: workspace.url }}
    preview={`${actor.name}: ${quote}`}
    heading={`${actor.name} commented on ${task.title}`}
    quotes={[{ author: actor.name, time: formatted, body: quote }]}
    action={{ label: "View comment", href: commentUrl }}
    footer={{
      reason: "You're getting this because you follow this task.",
      links: [
        { label: "Manage notifications", href: settingsUrl },
        { label: "Unsubscribe from comment emails", href: unsubscribeUrl },
      ],
    }}
  />,
);
await mailer.send({ to, subject: task.title, html, text });

• Call it from a route handler, a server action or a job — it uses react-dom/server.
• The plain-text part skips the preheader, keeps headings in sentence case and writes each link as its text and URL.
• Each template renders to about 8–11 KB, far under Gmail's 102 KB clip.

Templates

NotificationEmail

One event about one record — an assignment, a mention, a comment, a change, a reminder. The heading carries the event; quotes, a record card and one button follow. For a batch of events on one record, pass a count line as the heading ("3 new comments on Fix login") and the quotes oldest first.

DigestEmail

Many events in one email — the daily digest or due-date reminders: groups of linked rows, an optional "more" line, and one button (usually "Open inbox").

ActionEmail

A message that asks for one action — an invite, a password reset, an access request. Body paragraphs, an optional card, one button, the raw link for clients that block the button, and a muted note (expiry, "you can ignore this"). Transactional email usually has no preference links in its footer.

Layout and parts

Compose your own template from the same pieces when none of the three fits.

<EmailLayout brand={{ name: "Acme" }} preview="Your export is ready">
  <EmailHeading>Your export is ready</EmailHeading>
  <EmailText>The CSV has 1,204 rows.</EmailText>
  <EmailButton href={downloadUrl}>Download CSV</EmailButton>
</EmailLayout>

The footer note defaults to "Sent with VegaStack"; pass note: null to hide it. Pass noteHref to link it: on the default note only "VegaStack" becomes the link, on a string note the whole line does. For anything else, note also takes inline content, such as text with a Link from react-email.

<EmailLayout
  brand={{ name: "Acme" }}
  preview="Your export is ready"
  footer={{ noteHref: "https://vegastack.com" }}
>
  …
</EmailLayout>

EmailMarkdown

Long-form Markdown — meeting notes, a page excerpt — in the same reading styles as the in-app notes: the heading scale, lists, task checkboxes, quotes and code, with the kit's dark-mode hooks. It never injects HTML: raw HTML and images are dropped, mention links read as their bold label, and only http(s) links and in-app paths (resolved against appUrl) stay links.

Dark mode and email clients

• Light is the default and is inline, so it survives every client, including the ones that strip <style>.
• Dark mode is two small <style> blocks: @media (prefers-color-scheme: dark) for Apple Mail, iOS Mail and Outlook on Mac, and — in a block of its own, so a client that rejects attribute selectors cannot drop the first — [data-ogsc]/[data-ogsb] rules for Outlook.com and the new Outlook, which repaint text and fill together. Elements opt in with vs-* class hooks.
• Classic Outlook ignores max-width, so renderEmail wraps the column in a 600px table only Outlook sees (conditional comments React cannot write; the layout leaves two empty markers that applyMsoGhostTable replaces). Render with renderEmail, or call applyMsoGhostTable yourself.
• Forced inversion (Gmail, which ignores prefers-color-scheme, and classic Outlook) recolours the email itself. The palette avoids pure white and black, which those clients special-case, and every text colour is AA (4.5:1) on its background in both modes — checked when email-tokens.ts is generated.
• No images. The header is a text wordmark from brand.name, so nothing is blocked or inverted.
• Phones. Under 600px the gutters tighten and the button goes full width; it is at least 44px tall everywhere.
• Rounded corners and the dark block are progressive: classic Outlook on Windows shows square corners and the light design.

Writing notifications

One rule set for every channel. The in-app item is always sent; push and email follow the person's preferences.

• Who → did what → to what. Past tense, active voice, sentence case: "Priya assigned you to Fix login", not "You have been assigned a task".
• Use the specific verb. "Priya moved Fix login to In review", never "updated" when you know the field.
• No "!", emoji, capitals for emphasis, "please" or "successfully".
• Quotes are plain text: whitespace collapsed, cut at a word with "…".
• Push title is the person for people-to-you events and the record for system, agent and reminder events; the body is the action, plus the quote.
• Email subject is the record's title, the same for every email about that record so clients thread them. Events with no record ("Priya added you to Design", access requests) use the sentence. The preheader carries the sentence or the quote.
• One button, verb first: "View task", "View comment", "Open page", "View meeting", "Review request", "Open space"; a digest's is "Open inbox".
• Footer: why they got it ("You're getting this because you're assigned to this task." / "…you were mentioned." / "…you follow this task." / "…you're a member of Design."), then "Manage notifications", "Unsubscribe from comment emails", and "Sent with VegaStack".
• Names are data. The product is VegaStack and the place is the workspace's name ("Acme") — never a customer name baked into a template.

Files

Do / Don't