
brand-templates
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-elementsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install brand-templates@hyper-elementsRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceBrand 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.
-
Read it first.
npx hyper-elements describe templates/newsletter.tsx --jsonlists 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. -
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 theirallowlists (and, withstyles: "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. -
Check it, and fix what it says, by each diagnostic's
field,messageandfix, until it exits 0:npx hyper-elements check designs/june.tsx --json.reviewitems are what a person looks at by eye; they never fail the run. -
Render it:
npx hyper-elements render designs/june.tsxwritesout/designs/june.html(june.square.png,june.landscape.pngfor 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.jsonwritesdesigns/orbit.values.jsononce the template accepts it (@pathreads an image's size,--sourcerecords where it came from;--draftwrites an unfinished one).npx hyper-elements design set designs/orbit.values.json launchDate=2026-12-10changes one value and nothing else; the file stays as it was if the template refuses it.body=@designs/june.body.tsxpoints a slot at a module.npx hyper-elements design new templates/newsletter.tsx --from designs/june.tsx -o designs/june.values.jsonturns a TSX design into its values file.checkandrendertake 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.
- Decide each part: fixed (logos, footer, legal text), a field (
prop.text,prop.date,field.imagewith 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 strictestallow,stylesandcountthat still does the job. - For one size and fields of text, links, images or slots, write the design and mark what's open with
open(); otherwisefieldsandrender(values, { format }). From a design a person approved, give each part that changes anidand 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). - Write the rules the brief asks for: lint's (
require.lint:unsubscribe,link-text,lang,contrast), core's (layout/overflow; a Canvas'simage/fit), the links' domains, the root's props. Writeguidancewhere a value needs judgment. - Write
example: every required field, and the slots' content as a filler would write it. - Check it:
npx hyper-elements check templates/newsletter.tsxrendersexamplein 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). - Compare
describewith the brief:npx hyper-elements describe templates/newsletter.tsx. It's what a filler sees; a guardrail missing there is missing.checkcan't tell you a rule the brief asks for isn't there. - 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 takesmigrateto 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.
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:
| Build | Root | Render 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.
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
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.
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.
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
- Start from an example: Designs · Element gallery
- Learn the API: Writing guide · Full reference
- Stay on brand: Themes
- Test in email clients: Email client emulator · Email client checks
- Work from the shell: Command line ·
@hyper-elements/cli - Use it in your app: Next.js example · Email providers
- Bring existing templates: Migrate from React Email · Move from Unlayer Elements
- Let teammates edit visually: Optional Unlayer editor integration
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 3Similar to brand-templates
More Development Tools
reamorluto/rea466.8K starsReverse engineer anything with agents, from app behavior down to native binaries.
superpowersobra/superpowers319.5K starsCore skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques
claude-apianthropics/skills196.9K starsClaude API and SDK documentation skill for building LLM-powered applications
prompts.chatf/prompts.chat178.2K starsAccess thousands of AI prompts and skills directly in your AI coding assistant. Search prompts, discover skills, save your own, and improve prompts with AI.
agent-sdk-devanthropics/claude-code156.1K starsDevelopment kit for working with the Claude Agent SDK
ui-ux-pro-maxnextlevelbuilder/ui-ux-pro-max-skill152.6K starsProfessional UI/UX design intelligence for AI coding assistants. Includes searchable databases of styles, colors, typography, charts, and UX guidelines for Reac