Keep the intent behind every email
An email specification explains its purpose, tone, required information and the role of each text slot. People and coding assistants can change the wording while preserving what the message must accomplish.
Example — Rewrite a reset email without losing the safety message
The author changes the tone but keeps the reset action, expiry explanation and guidance for someone who did not request it.
For engineers
Read the message contract before editing its words
System-email specifications are built from the corresponding registry entry, then add purpose, tone, usage guidance and text-slot meanings. The password-reset specification begins:
Selected from authentication.system-emails.specification.ts; surrounding module configuration is omitted.
export const passwordResetSystemTemplateSpecification = systemEmailTemplateSpecificationFromRegistryEntry(
SystemEmailTemplateRegistry[SystemEmailTemplateRef.PASSWORD_RESET],
() => ({
purpose: 'Allow an account owner to re-establish control over their credentials through a secure, time-bound link.',
tone: 'Clear, security-aware, and low-drama — the user asked for this or might not have, so the copy must help both cases without alarming either.',
useWhen: 'Use only in response to an explicit password-reset request initiated by the account or by an administrator.',
avoidWhen: 'Do not use for proactive password hygiene nudges; those belong to security-alert or security-digest surfaces.',
textSlots: {
subject: {
purpose: 'Signal that this is a password-reset email and convey that action is required within a limited window.',
},
previewText: {
purpose: 'Restate the secure-reset intent with the expiration timeframe so recipients can triage in their inbox.',
},
body: {
purpose: 'Short paragraph explaining who requested the reset (or inviting the recipient to ignore the email if not them) and how the link works.',
},
ctaLabel: {
purpose: 'Primary action label that sends the user to `eventData.resetUrl`.',
},
expirationNotice: {
purpose: 'Inline reminder about `eventData.expiresInMinutes` — makes the time-bound nature of the link visible near the CTA.',
notes: ['Surface the minute count as numeric text; downstream locales must format it naturally (for example "30 minutes").'],
},
securityFootnote: {
purpose: 'Closing guidance for recipients who did not request this reset, asking them to ignore or contact support.',
},
},
eventData: {
purpose: 'Payload carrying the secure reset URL and expiration window used throughout the body.',
},
businessConstraints: [
'Never leak user identifiers, IP addresses, or authentication method details in this email — those belong to security alerts.',
'Never reuse this template for email verification or magic-link flows; each has its own trust profile.',
],
codeHandling: {
definitionOwner: ENGINE_OWNER_REF,
templateRefDeclaration: TEMPLATE_REF_DECLARATION,
eventDataSchemaSymbol: EVENT_DATA_SCHEMA_SYMBOL,
},
}),
);
The application exports systemEmailTemplateSpecifications from its specification package. The companion’s email specification loader renders the applicable concern into generation or translation context. This supplies intent to the authoring tool; it does not replace the runtime template or send the message.
Review meaning as well as shape
A valid TSX result can still be poor product communication. Check that the action, expiry and safety advice remain clear and that the translation preserves their meaning. Keep context fields aligned with the actual sender: the template consumes its concrete runtime context, not a promise inferred solely from the specification.
Use specification changes when the purpose changes; use label changes when only wording changes. That separation keeps a stylistic rewrite from quietly changing the account-recovery contract.