New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Make emails, pages, PDFs and images from your team's Hyper Elements templates, inside the guardrails they set (fixed parts, typed fields, slots of approved components, rules checked on the result), and write such templates from a brand brief.

GitHub stars
499

Add marketplace

/plugin marketplace add hyper-elements/hyper-elements

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install brand-templates@hyper-elements

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Brand templates

A template (template() from @hyper-elements/react/template) is a design with fields: what may change, and the rules each value must meet. Everything that isn't a field (the layout, typography, colors, the fixed text and images) is the template's. A design made from one is checked by it, so what passes is on brand.

Using a template

You fill a template; you never change it.

  1. Read it first. npx hyper-elements describe templates/newsletter.tsx --json lists its formats, every field (its kind, whether it's required, its guidance), each slot's allowed elements, each image's region and the pixels it needs, and the rules. Write within them.

  2. Write the design as TSX, the template as its root, its fields as props. A TSX design is code a person reviews; where what you write is rendered unreviewed, make a values file instead (npx hyper-elements design new <template> -o designs/<name>.values.json --values <values>.json), which runs nothing. Slots are JSX written only with the elements their allow lists (and, with styles: "theme", the theme's tokens and named styles):

    // designs/june.tsx
    import { Column, Heading, Text } from "@hyper-elements/react";
    import Newsletter from "../templates/newsletter";
    
    export default () => (
      <Newsletter subject="What's new in June" preview="Three updates from the team, and a date for the open house"
        body={<Column><Heading level={2}>Faster exports</Heading><Text>Exports finish in half the time.</Text></Column>} />
    );
    

    A template with formats (square, landscape) gives one output per format; format="square" makes one.

  3. Check it, and fix what it says, by each diagnostic's field, message and fix, until it exits 0: npx hyper-elements check designs/june.tsx --json. review items are what a person looks at by eye; they never fail the run.

  4. Render it: npx hyper-elements render designs/june.tsx writes out/designs/june.html (june.square.png, june.landscape.png for formats).

Images: give each one the size its region needs (describe's regions, at the format's scale). check reads each file and fails one that's too small (template/asset-pixels), cropped past what the template allows, or the wrong type.

The values form is the same design as data, for batches, one-value changes and generated images' provenance:

  • npx hyper-elements design new templates/launch.tsx -o designs/orbit.values.json --values brief.json --set artwork=@art/waves.png --source artwork=source.json writes designs/orbit.values.json once the template accepts it (@path reads an image's size, --source records where it came from; --draft writes an unfinished one).
  • npx hyper-elements design set designs/orbit.values.json launchDate=2026-12-10 changes one value and nothing else; the file stays as it was if the template refuses it. body=@designs/june.body.tsx points a slot at a module.
  • npx hyper-elements design new templates/newsletter.tsx --from designs/june.tsx -o designs/june.values.json turns a TSX design into its values file.
  • check and render take values files as they take designs.

When the template is in the way, report it. A value it refuses, a field it doesn't have (template/unknown-field), an element a slot doesn't allow, a rule you can't meet: say so, and ask for a change or a new version of the template. Never edit the template, its fixed parts or its rules to get a design past a check, even when you can write the file: templates are reviewed changes, and template/changed shows one edited under its version.

In CI, npx hyper-elements check designs/ --require-template acme.Newsletter fails anything a template didn't check. The project lists its trusted templates in package.json, "hyperElements": { "templates": ["templates/**"] }, so a design can only use those (on Node).

Writing a template

Start from the brand brief. example.tsx is a whole one.

  1. Decide each part: fixed (logos, footer, legal text), a field (prop.text, prop.date, field.image with its fit and minimum size, a list), blocks (prop.blocks: a list of approved section types), or a slot (field.slot: JSX the filler writes). Give a slot the strictest allow, styles and count that still does the job.
  2. For one size and fields of text, links, images or slots, write the design and mark what's open with open(); otherwise fields and render(values, { format }). From a design a person approved, give each part that changes an id and extract it: npx hyper-elements template extract designs/orbit.tsx --id acme.LaunchGraphic --field headline --field artwork -o templates/launch-graphic.tsx (a computed value is reported, and nothing is written).
  3. Write the rules the brief asks for: lint's (require.lint: unsubscribe, link-text, lang, contrast), core's (layout/overflow; a Canvas's image/fit), the links' domains, the root's props. Write guidance where a value needs judgment.
  4. Write example: every required field, and the slots' content as a filler would write it.
  5. Check it: npx hyper-elements check templates/newsletter.tsx renders example in every format and runs every rule. Fix what it says: a rule that can't run (template/rule-unavailable), a slot placed twice or not at all (template/slot-host).
  6. Compare describe with the brief: npx hyper-elements describe templates/newsletter.tsx. It's what a filler sees; a guardrail missing there is missing. check can't tell you a rule the brief asks for isn't there.
  7. Version it: set version, and bump it on every change once it's in use, a change to a theme or anything else it imports included. A major version takes migrate to read older designs.

Never weaken a rule or a slot policy so content passes: change the template only when the brief does. Keep what a template imports (its theme, its own elements and functions, its example's parts) beside it, in the folders the project trusts.

From the hyper-elements/hyper-elements README

Hyper Elements

Build emails, web pages, PDFs, and images with React.
One set of elements for developers and AI agents.

npm version Monthly downloads Tests Code coverage MIT license

Quick start · AI agents · Test in email clients · Designs · Documentation · Website

Hyper Elements is an open-source React library for generating content. Write a receipt, invoice, landing page, or social card with typed elements. The engine handles layout and the markup each output needs, including email tables and responsive web HTML.

  • Reuse your work across formats. Share content, styles, and components between an email, its web version, and a PDF.
  • Keep every output on brand. Define colors, fonts, sizes, and element styles once in a theme, and every email, page, PDF, and image that uses it follows.
  • Give agents useful feedback. Validate designs, inspect layouts as text, and get diagnostics that explain where a problem is and how to fix it.
  • Test existing HTML emails locally. Check and preview Outlook, Gmail and Apple Mail with the companion JavaScript library or CLI. Works with HTML from MJML, React Email or any email builder; no React required, no test sends, no account, nothing uploaded.
  • Render in your own app. Generate output on your server, with no browser, hosted service, or API key required.

React components flow through Hyper Elements into email HTML and plain text, responsive web HTML, PDF documents, and PNG or SVG images.

Quick start

In a React project (React 18 or later):

npm install @hyper-elements/react react react-dom

Build an order update, then render the same content as an email and a web page:

import {
  Button, Column, Email, Heading, Page, Text, render,
} from "@hyper-elements/react";

function OrderUpdate({ name }: { name: string }) {
  return (
    <Column style={{ padding: 32, gap: 16 }}>
      <Heading level={1}>Thanks, {name}.</Heading>
      <Text>Your order is on its way.</Text>
      <Button
        href="https://example.com/orders/10482"
        style={{ backgroundColor: "#ef4638", color: "#ffffff" }}
      >
        Track your order
      </Button>
    </Column>
  );
}

const content = <OrderUpdate name="Ada" />;
const { html, text } = await render(<Email width={600}>{content}</Email>);
const { html: pageHtml } = await render(<Page width={960}>{content}</Page>);

html and text are the email's HTML and plain text, ready for your email provider. pageHtml is a complete responsive web document. No client-side JavaScript is required.

Choose your output

Use the same layout and content elements under the root for your destination:

BuildRootRender to
Receipts, newsletters, transactional emails<Email>Email HTML and plain text with render()
Landing pages, web versions of emails<Page>Responsive HTML with render()
Invoices, reports, printable documents<Document>Print HTML with render(), or a PDF with renderPdf()
Social cards, Open Graph images, banners<Canvas>PNG or SVG with renderImage()

The PDF and image renderers use separate imports and optional dependencies in Node.js. Diagnostics flag features a destination cannot represent. See one invoice rendered as email, web, and PDF for a complete example.

Build with AI agents

Give Claude Code, Codex, Cursor, or another coding agent the guide:

npx skills add hyper-elements/hyper-elements

It offers three skills: hyper-elements, the guide for writing designs; email-testing, for previewing and checking any email (a design or HTML from anywhere) in Outlook, Gmail and the other clients; and brand-templates, for designs made from your team's templates, within their guardrails, and for writing templates. --skill email-testing installs that one alone.

In Claude Code they're plugins too: /plugin marketplace add hyper-elements/hyper-elements, then /plugin install email-testing@hyper-elements, /plugin install brand-templates@hyper-elements or /plugin install hyper-elements@hyper-elements.

Or add this to your project's AGENTS.md or agent rules:

Designs use Hyper Elements (@hyper-elements/react). If it isn't installed, install it
with react and react-dom. Before writing a design, read
node_modules/@hyper-elements/react/GUIDE.md.
Validate the design, fix errors, review warnings, and inspect outline() before rendering.

The package includes GUIDE.md and REFERENCE.md, generated from its element definitions so they match the version you installed. Web-based agents can use llms.txt or llms-full.txt.

A feedback loop the agent can read

validate() returns diagnostics with a code, severity, path in the design, and an actionable message. outline() shows the layout without making the agent read generated HTML. Try both on the quick-start component:

import { outline, validate } from "@hyper-elements/react";

const design = <Email width={600}><OrderUpdate name="Ada" /></Email>;
const report = validate(design);

console.log(report.diagnostics);
if (report.valid) console.log(outline(design));
Email 600px
  Column 600px
    Heading h1 536px "Thanks, Ada."
    Text 536px "Your order is on its way."
    Button: background #ef4638 "Track your order" → https://example.com/orders/10482

An agent can spot missing content, incorrect widths, and layout mistakes before rendering, then see the email in each email client with the emulator below.

The same loop runs from the shell, with no script, using @hyper-elements/cli (npm install -D @hyper-elements/cli): npx hyper-elements check emails/ --json validates each design, outline prints its layout, render writes its HTML and plain text, and preview writes each email client's preview. Add --findings with the browser setup below to draw the previews and collect findings. Exit codes are stable (1 when a design has errors) for agents and CI.

Agent setup and examples →

Preview and test emails in Outlook and Gmail locally

@hyper-elements/email-clients is a free JavaScript and TypeScript library for checking existing HTML emails and previewing Outlook, Gmail and Apple Mail locally. Give it the complete HTML from MJML, React Email, an email builder, or a hand-written email. No React is required, and the email is never sent or uploaded.

An agent can do all of this from the email-testing skill: the commands, each client's screenshot, and what it changed.

npm install @hyper-elements/email-clients

Save this as preview-email.mjs beside your email.html:

import { mkdir, readFile, writeFile } from "node:fs/promises";
import { renderInEmailClients } from "@hyper-elements/email-clients";

const html = await readFile("email.html", "utf8");
const { previews, diagnostics } = await renderInEmailClients(html, {
  emailClients: ["outlook", "gmail", "apple-mail"],
});
await mkdir("out", { recursive: true });
for (const preview of previews) await writeFile(`out/${preview.filename}`, preview.html);
console.log(diagnostics);

Run node preview-email.mjs, then open out/outlook.html in Chromium or Chrome. Each preview lists what the client changed. The same API takes a Hyper Elements design: await renderInEmailClients(<Email><OrderUpdate name="Ada" /></Email>).

You can also check and preview an HTML email from the shell, with no script or React installation:

npx @hyper-elements/cli check email.html
npx @hyper-elements/cli preview email.html

The second command writes out/clients/email/outlook.html and the other client previews. To draw them and collect findings automatically, install the CLI and playwright-core together, and have Chrome, Edge or Playwright's Chromium installed:

npm install -D @hyper-elements/cli playwright-core
npx hyper-elements preview email.html --findings

If you need Chromium, download it once with npx hyper-elements preview --install-browser. See browser setup and findings.

Tested on Hyper Elements emails and on HTML emails built any other way, the emulator is 98% accurate on average against the real clients. Here's an example email template, a sign-in code, as the emulator draws it in four email clients:

A sign-in code email in classic Outlook, drawn by the Hyper Elements email client emulator The sign-in code email in Gmail on the web, drawn by the emulator The sign-in code email in Apple Mail, drawn by the emulator The sign-in code email in the Gmail app on Android, drawn by the emulator

Email client emulator: supported clients, accuracy and options →

Agent Benchmarks

Email

In our benchmark of five email briefs, Hyper Elements reached a passing email 2.6× faster with 3.4× fewer output tokens than React Email, at the median. It was also 1.3× faster than MJML. Hyper Elements and MJML both passed 16 of 16 first checks.

Agent benchmark: Hyper Elements took 33 seconds, used 1,831 output tokens, and passed on the first check in 16 of 16 runs. MJML: 43 seconds, 2,762 output tokens, 16 of 16 first-check passes. Hand-written HTML: 60 seconds, 4,903 output tokens, 6 of 16 first-check passes. React Email: 86 seconds, 6,215 output tokens, 12 of 16 first-check passes. Time and token counts are medians.

All four approaches ran in one interleaved batch, with 16 runs each against the same Chromium checks at desktop and mobile widths; all 64 eventually passed. Token counts here measure output tokens, not total usage or cost. Methodology · Reproduce the benchmark

Image

Across five image briefs, Hyper Elements reached a passing image 1.65× faster with 1.8× fewer output tokens than Canvas 2D (@napi-rs/canvas), at the median. 17 of 20 images passed on the first check.

Image agent benchmark: Hyper Elements took 76 seconds, used 5,096 output tokens, and passed on the first check in 17 of 20 runs. Playwright: 91 seconds, 6,846 output tokens, 14 of 20 first-check passes. Canvas 2D: 125 seconds, 9,132 output tokens, 16 of 20 first-check passes. Time and token counts are medians.

All 60 isolated runs passed the same text, font, image and layout checks: five briefs, four runs per brief per approach. The speed comparison with Playwright was inconclusive. Methodology and results · Reproduce the benchmark

Keep building

Contributing

Contributions are welcome. Use the Node.js version in .nvmrc and pnpm 9.7 or later, then run pnpm install, pnpm build, and pnpm test. See CONTRIBUTING.md for the development workflow.

License

MIT. Built by the team behind Unlayer; works independently of the Unlayer platform.

Details

Marketplace
hyper-elements/hyper-elements
Source
skills/brand-templates
Category
Development
License
MIT
Keywords
templates, brand, email, guardrails, agents

More from hyper-elements/hyper-elements

All 3

Similar to brand-templates

More Development Tools