Website contact form — the visitor's own mail program sends it
Our suggestion for contact on a small site: a short form whose button opens the
visitor's own email program with a message to the owner already written. The visitor
reads it, presses Send, and it arrives like any other email. There is no server work,
no account and no setting behind it.
Why this form (say this to the owner, in your own words)
- Nothing to set up. No account, no password or token, no change to the domain's
mail settings. It works on any host, today, and on a preview address too.
- No spam through the form. It sends nothing, so there is nothing for a bot to
fill in and fire off: every message needs a real mail account and a person pressing
Send. Spam sent straight to the address is another matter, the same as for any
address on any site; the form keeps it out of the page as plain text, as the
starter's email link does, which stops the simple address collectors.
- No company in between. The message goes from the visitor's mailbox to the
owner's, like any email. So the privacy page needs no paragraph about a service
that handles messages: its section on contact by email already covers it (§4).
- The visitor keeps a copy in their Sent folder, and the owner answers with Reply.
And the honest weak spots, so the owner hears them from you first:
- Some visitors have no mail program set up. Someone who reads mail only in a
browser (webmail), or sits at a shared computer, presses the button and gets
nothing, or a mail program they never use. That is why the plain address always
shows under the form, ready to copy, and the line after the button says to use it
if nothing opened.
- The site never learns whether the visitor pressed Send. A message can be
written, opened and then not sent. No form counts sent messages here.
If the owner needs either of those solved (messages from every visitor whatever their
setup, or a count of them), this is the wrong tool: see §0.
0. Is this the right tool? (ask before installing)
- Is a form wanted at all? For a handful of enquiries a year, the plain email link
the starter already has (
<EmailLink>) does the job. Say so.
- Is "the visitor's own mail program sends it" enough? Yes for nearly every small
site. No when the owner must receive messages from visitors who only use webmail, or
must know how many were sent. Then say plainly that this skill does not fit, and
point to
new-website/references/WEBSITE_ARCHITECTURE.md Tier 2: a form that sends
through a server, which needs a mail service, settings only the owner can create,
and a paragraph on the privacy page. Not built by this skill.
- Are file uploads or a newsletter sign-up wanted? Different problems; not this.
1. What it adds to the site
| File |
From this skill's templates/ |
What it is |
src/components/MailForm.astro |
MailForm.astro |
the form, and the address line under it |
src/components/mail-form-text.ts |
mail-form-text.ts |
everything the form says, in English and German, and the longest message it takes |
public/js/mail-form.js |
mail-form.js |
the script: shows the form, builds the mailto: link, opens it |
tests/mail-form.spec.ts |
mail-form.spec.ts |
the form as a visitor meets it: the link the button opens (address, subject, every field, encoding), an empty field, labels and keyboard order through any added fields, a hint as the message box's description, the page without JavaScript, a strict Content-Security-Policy, and every text against the site's tone rules |
The templates are in this skill's templates/ folder, beside this SKILL.md; the bundled
copy of the skill on a handed-off repo has them too. Install all four.
How it works, in one paragraph. The owner's address goes into the HTML encoded the
way EmailLink encodes it (src/lib/obfuscate.ts), never as plain text. The script, a
file of the site's own under public/js/ rather than an inline script, so a strict
script-src 'self' policy lets it run, shows the form, and when the button is pressed
decodes the address and opens mailto:<address>?subject=…&body=…. The body starts
with the greeting the owner chose (greeting), then the visitor's message as typed,
less any empty space (spaces, tabs, blank lines) at its very start and end. Every other
field the visitor filled in follows as "Label: value", so a field the owner adds later
goes into the mail by its label with no change to the script. The language's sign-off
("Kind regards", "Freundliche Grüße") ends it; the visitor's mail program says who they
are. Without JavaScript the form stays hidden, since it could do nothing, and
the address line under it is what the visitor sees.
The spec needs toneViolations from the site's tests/_helpers.ts, the tone rules
its pages are held to. A site made from an older starter lacks it, and npm run check
says has no exported member 'toneViolations'. Then first bring that file up to date
from the starter's (new-website/templates/astro/tests/_helpers.ts): take
toneViolations and the rules above it, keep the site's own PAGES. Take the
starter's tests/tone.spec.ts with it, so the pages and the form read one list. Before
replacing the site's tone.spec.ts, compare its rules and its ALLOWLIST with the
starter's: a word the site added goes into the same place in _helpers.ts, or the site
loses it.
2. Install (on a branch, as a pull request: AGENTS.md §2)
Copy the four files to the places in §1 (mkdir -p public/js first).
Put the form on a page, inside that page's <Base>:
---
import MailForm from '../components/MailForm.astro';
---
<MailForm to="<the address messages go to>" subject="<what the visitor comes for>" greeting="<the mail's first line>" />
Ask the owner for the address. The starter's encoding takes only plain addresses:
letters, digits and . _ % + - before the @, and the build stops with a clear
message on anything else. A new /contact page is a new page: work through
AGENTS.md §6 (PAGES, llms.txt, share card, a link to it). One form per page:
its ids are fixed.
The subject line (subject, required: the build stops without it). It is the
first thing the visitor reads in their mail program, and what stays in their Sent
folder. So let it name what they came for, in their words, rather than the website:
an architects' office "Anfrage Bauvorhaben", a holiday flat "Booking request", a
consultant "Project enquiry". The mail then starts as their own request, not as a
message to a website. Take it from the site's offer and the primary action in
CONTENT_GUIDE.md, in the page's language, and keep it short, about 40 characters,
so a mail program's list shows all of it. A page for one offer can pass its own.
Propose one or two and let the owner choose: these are their customers' first words
to them. The plain address under the form carries the same subject.
The greeting (greeting, required: the build stops without it). The first line
of every mail, as the visitor would write it to the owner, punctuation included. Ask
the owner whom visitors address, and propose one in the site's form of address:
"Sehr geehrte Frau Muster," where one named person answers on a "Sie" site, "Sehr
geehrte Damen und Herren," for a firm with no one person, "Hallo Anna," on a "du"
site, "Dear Ms Smith," in English. The mail ends with the language's sign-off
(signoff in mail-form-text.ts: "Kind regards", "Freundliche Grüße", no comma). A
site that wants another, such as "Viele Grüße", changes it there. The plain address
under the form opens a blank mail, with no greeting.
Language. The form speaks the language of the page it is on, by itself: a page
built with <Base lang="de"> on an English site gets a German form. Base.astro
hands the page's language down (Astro.locals.lang); on a site with several
languages it is the page's locale.
lang="…" overrides; then set LANG in the spec too (step 4). English and German
are built in, with no form of address in German, so the form fits a "du" site and a
"Sie" site. Any other language: "Add a language" below, first. A form in a language
with no texts stops the build.
A site made from an older starter lacks the line in Base.astro. On a site
without Astro's language routing, a form without lang then stops the build with a
message naming the line (with routing, the page's locale stands in). Add
Astro.locals.lang = lang; after the props in Base.astro, and the declaration
declare namespace App { interface Locals { lang?: string } } to src/env.d.ts:
create the file from the starter's if the site has none, and keep what a site's own
file already declares. Without the declaration, npm run check fails on the line.
In tests/mail-form.spec.ts set PAGE (the page with the form), TO, SUBJECT
and GREETING (the address, the subject and the greeting from step 2). The spec
fails while one is empty, and holds the subject and the greeting to the site's tone
rules. LANG only if the page passes
lang. One copy guards one form:
with the form on pages in two languages, copy it once per language
(tests/mail-form.de.spec.ts), each with its own PAGE, SUBJECT and GREETING.
Fields. The form asks for the message, nothing else: the visitor's name and
email address come with their mail, and the form adds the greeting and the sign-off.
A field
the owner wants, or a hint above the message box: "Adding fields" below.
npm run check && npm test.
Adding fields
Ask only what the visitor's mail cannot carry and the owner needs to answer: a kind of
request, a place, a phone number for a call back. Never a name or an email field: the mail
brings both. Each field is one more reason to leave; two or three is plenty.
Fields go between <MailForm> and </MailForm>, and come before the message. A hint goes
in the slot hint: the form shows it between the message's label and its box, and ties it
to the box (aria-describedby), so it becomes the box's accessible description. An
example,
for a building firm:
<MailForm to="…" subject="Project enquiry" greeting="Dear Ms Smith,">
<fieldset>
<legend>What is it about? <span class="mail-form-optional">(optional)</span></legend>
<label><input type="radio" name="kind" id="kind-new" value="new" /> A new project</label>
<label><input type="radio" name="kind" id="kind-running" value="running" /> A project under way</label>
</fieldset>
<p>
<label for="town">Town</label> <span class="mail-form-optional" id="town-optional">(optional)</span>
<input id="town" name="town" type="text" maxlength="80" aria-describedby="town-optional" />
</p>
<Fragment slot="hint">For example: what is planned, how far the planning is, when work should start.</Fragment>
</MailForm>
The mail then reads, between the message and the sign-off: "A new project" and "Town:
Bath". The rules
behind it, each from a source read on 2026-10-27:
- A choice is radio buttons in a
fieldset, named by its legend. "Radio button
groups should always be grouped using <fieldset>" (W3C WAI,
https://www.w3.org/WAI/tutorials/forms/grouping/). The mail carries the ticked option's
label alone, not the legend, so write each option to read on its own ("A new project",
not "New").
- Every added field starts empty. No list (
select): a drop-down list always has an entry
chosen, so an untouched list sends an answer the visitor never gave, a "Please choose"
entry included. No box ticked and no text filled in advance. The script sends whatever a
field holds, and the spec expects no field line when the visitor adds nothing.
- None ticked in advance. "Do not pre-select radio options" (GOV.UK Design System,
https://design-system.service.gov.uk/components/radios/). Once ticked, a radio cannot be
unticked; for an optional choice that costs one line the visitor can delete in their mail
program.
- Optional fields say "(optional)"; required ones get no asterisk. "Never mark
mandatory fields with asterisks" (GOV.UK,
https://design-system.service.gov.uk/patterns/question-pages/). GOV.UK puts the word in
the label; here it goes beside it, in a
span with class mail-form-optional tied to the
field with aria-describedby, because the mail uses the label's text: "Town: Bath", not
"Town (optional): Bath". In a radio group it goes in the legend, which the mail never
shows.
- A hint shows above the box, never as a placeholder. Placeholder text disappears as
the visitor types; Nielsen Norman Group recommends "clear, visible labels that are placed
outside empty form fields"
(https://www.nngroup.com/articles/form-design-placeholders/).
- A hint can follow the choice, by CSS alone. Put one
span per case in the slot
(<span class="hint-any">…</span><span class="hint-new">…</span><span class="hint-running">…</span>) and show the one that fits, in the page's <style>.
.mail-form is the form's own element, outside the page's style scope, hence
:global:.hint-new, .hint-running { display: none; }
:global(.mail-form):has(#kind-new:checked, #kind-running:checked) .hint-any { display: none; }
:global(.mail-form):has(#kind-new:checked) .hint-new { display: inline; }
:global(.mail-form):has(#kind-running:checked) .hint-running { display: inline; }
A hidden span is left out of the box's description, so the description is the hint
on screen (the page test below checks it).
- No promise the owner has not made. Not "we answer within a day", not "the first talk
is free", unless the owner says so.
Looks. The form styles what goes in the slot: a text field, a radio group and
the mail-form-optional note look like the message field, with no CSS of the page's own.
Astro gives fields in a slot the page's style scope, not the form's, so the form's rules
reach them through :global, inside the form only. A page adds style only for what is its
own, such as a hint that changes.
The spec. Set ADDED in tests/mail-form.spec.ts to the fields' labels, one per Tab
stop in order: a radio group by its first option (['A new project', 'Town']). The spec
then checks that every control has a label, that Tab goes through them to the message and
the button, and, when there is a hint, that it is the box's accessible description.
The page's own test. Only the page knows its fields, so add a short spec next to it
(tests/contact.spec.ts) that enters as a visitor does, through the button, and checks the
mail word for word:
import { test, expect, type Page } from '@playwright/test';
import { TEXT } from '../src/components/mail-form-text';
const t = TEXT.en; // the page's language
const greeting = 'Dear Ms Smith,'; // the form's greeting
const form = (page: Page) => page.locator('form[data-mail-form]');
// The mail body the button hands to the mail program, decoded.
async function send(page: Page) {
const asked = page.waitForRequest((r) => r.url().startsWith('mailto:'), { timeout: 5000 });
await form(page).getByRole('button', { name: t.send, exact: true }).click();
const body = (await asked).url().split('?')[1].split('&').find((p) => p.startsWith('body='))!;
return decodeURIComponent(body.slice('body='.length));
}
test('contact — the choice and the town arrive under the message', async ({ page }) => {
await page.goto('/contact');
await form(page).getByLabel('A new project', { exact: true }).check();
await form(page).getByLabel('Town', { exact: true }).fill('Bath');
await form(page).getByLabel(t.message, { exact: true }).fill('A kitchen extension.');
expect(await send(page)).toBe(`${greeting}\r\n\r\nA kitchen extension.\r\n\r\nA new project\r\nTown: Bath\r\n\r\n${t.signoff}`);
});
test('contact — with nothing chosen or added, the mail has no field line', async ({ page }) => {
await page.goto('/contact');
await expect(form(page).locator('input[type=radio]:checked')).toHaveCount(0);
await form(page).getByLabel(t.message, { exact: true }).fill('A short question.');
expect(await send(page)).toBe(`${greeting}\r\n\r\nA short question.\r\n\r\n${t.signoff}`);
});
A hint that follows the choice
gets one more test: toHaveAccessibleDescription on the message box, before and after each
choice. A field that asks for more personal data than the message also goes into the privacy
page (§4).
Add a language
On a new site in that language, or when a site gains it later. Translate from the
English, all of it in one go.
- Read the site's voice first: its
CONTENT_GUIDE.md (in German the register, "du"
or "Sie") and the tone rules in tests/_helpers.ts. Where the language allows, do as
the German texts do and address nobody.
- In
src/components/mail-form-text.ts, copy the en entry of TEXT under the
language's two-letter code (fr, not fr-CA) and translate every value; the
comment above TEXT says where each one shows. npm run check fails while one is
missing, and the spec holds every text to the tone rules. For a language without
rules of its own in tests/_helpers.ts that is the ban on the long dash alone: read
the texts against step 1 yourself, and if the owner speaks the language, ask them to
read the form once.
- The address hint a visitor without JavaScript reads ("name [at] example [dot]
com") takes its word for "dot" from
DOT_WORD in src/lib/obfuscate.ts (English and
German there); add the language's word. The spec fails while the hint says "dot".
- The privacy page. The starter has it in English and German only. A site in this
language needs its own, with the section on contact by email (§4).
- The page and its test, as in §2 steps 3 and 4.
3. Try it once (the owner)
It works the same on a laptop as on the live site, since there is nothing on a server
to wait for. After npm run build && npm run preview, or on the preview address of the
pull request:
- The owner fills in the form and presses the button. Their mail program opens with a
new message: to the address from §2, the subject line and the message as they
typed it, umlauts and line breaks included.
- They send it to themselves and see it arrive.
- Nothing opened: their computer has no mail program set up for
mailto: links. That
is exactly what some visitors meet, and why the address shows under the form. On a
Mac it is set in Mail's settings, on Windows under default apps; in Chrome a webmail
such as Gmail can ask to open these links. Not a fault of the form.
4. The privacy page
The starter's privacy page already has a section on contact by email ("4. Contact by
email", German "4. Kontakt per E-Mail"), naming the name, the address and the message.
That is what this form produces: an email, sent by the visitor. Nothing to add, and
no processor paragraph, since no service handles the message on the way.
Check two things only: the section is still there (a rewritten privacy page may have
lost it; then write it, covering what is processed, why, the legal basis and how long
it is kept), and any field added in §2 step 5 that asks for more than the message is
named in it. Like the kit's other legal drafts, a baseline, not legal advice.
With Plausible on, a press of the button sends one "Email Tap" event, the same one
the starter's email link sends (nothing typed goes with it). Section 3 of the starter's
privacy page (EN privacy.astro; German _datenschutz.astro, served as
datenschutz.astro once a German site renames it) already says so ("a button that opens your
email program"). An older site's privacy page may lack that sentence, and its own
src/components/EmailLink.astro, which shows the address under the form, may not count
clicks yet (no addEventListener in it). Take whatever is missing from the starter: the
sentence, the click listener, or both. The form sends its event
either way, so the sentence is not optional on a site that runs Plausible. In Plausible's
installer leave "Form submissions" unticked: whether Plausible would count this form a
second time was not checked.
A site made before 0.35 in analytics server mode (ANALYTICS.mode: 'server') does not
count the button: no Plausible script runs, so the form's call does nothing, and counting
it from the server would mean passing what the visitor typed through it. The mail program
opens as before. A site made with 0.35 or later has no server mode.
5. What it does not do
- No sending, no storage, no count of sent messages. The site never learns whether
a message was sent. The owner's mailbox is the record. With Plausible on, the press of
the button is counted (§4): a visitor who asked to write, not an opened mail program
and not a message.
- No help for a visitor without a mail program, beyond the address under the form
and the sentence that points to it.
- Very long messages. The form stops at 2,000 typed characters (
LIMITS in
mail-form-text.ts). In the link they become more: about 2,800 for English prose,
more with umlauts and line breaks. Some mail programs cut a very long link, and at
what length was not measured, so a long message may arrive cut in some of them, and
then the sign-off at its end is the first thing lost. The visitor sees the mail
before pressing Send, and can write on in their mail program. Whether a mail program
adds the visitor's own signature under it was not checked.
- The address line under a strict Content-Security-Policy. The form works under
script-src 'self' (the spec proves it). The address under it, the starter's
EmailLink, decodes through an inline script, so under such a policy it stays as the
readable "name [at] example [dot] com" hint and cannot be clicked. The starter's own
policy (public/_headers) allows inline scripts, so a site that kept it is not
affected.
- Not checked in every mail program. The link follows the standard for
mailto:
links (RFC 6068), and the spec checks it to the character. How each mail program
shows it was not tried beyond the owner's own (§3).
Boundaries (do not duplicate)
- Which hosting tier a site needs:
new-website §1 Q2 and
references/WEBSITE_ARCHITECTURE.md.
- Getting the suite green, and what else to test on a new feature:
website-qa §1b.
- The privacy page as a whole: the starter's
privacy.astro and _datenschutz.astro.
- The address link alone, with no form: the starter's
EmailLink.
Done means
The owner chose the form knowing its weak spots; it is on its page in the site's
language with the right address and the owner's greeting; npm test is green with
PAGE, TO, SUBJECT and GREETING set; the
privacy page's section on contact by email is in place; and the owner has opened one
message from it in their own mail program and seen it arrive.
1---2name: website-contact-form3description: >4 Add a contact form to a new-website site that needs no server and no setup: the5 visitor fills in a few fields, presses a button, and their own email program opens6 with a message to the owner, ready to send. Nothing is sent or stored by the site.7 Adds a form component, its texts in English and German, one small script of the8 site's own (so a strict Content-Security-Policy holds), and tests/mail-form.spec.ts.9 The owner's address is always shown under the form for visitors without a mail10 program or without JavaScript. Run when new-website Q2 asks for a contact form, or11 later when the owner wants one. Trigger phrases: "contact form", "add a form",12 "enquiry form", "visitors should be able to write to us", "kontaktformular". Not13 for newsletter sign-up, file uploads, or anything that has to be stored.14metadata:15 source: https://skillmd.com/skills/karero/website-contact-form16---1718# Website contact form — the visitor's own mail program sends it1920Our suggestion for contact on a small site: a short form whose button opens the21visitor's own email program with a message to the owner already written. The visitor22reads it, presses Send, and it arrives like any other email. There is no server work,23no account and no setting behind it.2425## Why this form (say this to the owner, in your own words)2627- **Nothing to set up.** No account, no password or token, no change to the domain's28 mail settings. It works on any host, today, and on a preview address too.29- **No spam through the form.** It sends nothing, so there is nothing for a bot to30 fill in and fire off: every message needs a real mail account and a person pressing31 Send. Spam sent straight to the address is another matter, the same as for any32 address on any site; the form keeps it out of the page as plain text, as the33 starter's email link does, which stops the simple address collectors.34- **No company in between.** The message goes from the visitor's mailbox to the35 owner's, like any email. So the privacy page needs no paragraph about a service36 that handles messages: its section on contact by email already covers it (§4).37- **The visitor keeps a copy** in their Sent folder, and the owner answers with Reply.3839And the honest weak spots, so the owner hears them from you first:4041- **Some visitors have no mail program set up.** Someone who reads mail only in a42 browser (webmail), or sits at a shared computer, presses the button and gets43 nothing, or a mail program they never use. That is why the plain address always44 shows under the form, ready to copy, and the line after the button says to use it45 if nothing opened.46- **The site never learns whether the visitor pressed Send.** A message can be47 written, opened and then not sent. No form counts sent messages here.4849If the owner needs either of those solved (messages from every visitor whatever their50setup, or a count of them), this is the wrong tool: see §0.5152## 0. Is this the right tool? (ask before installing)53541. **Is a form wanted at all?** For a handful of enquiries a year, the plain email link55 the starter already has (`<EmailLink>`) does the job. Say so.562. **Is "the visitor's own mail program sends it" enough?** Yes for nearly every small57 site. No when the owner must receive messages from visitors who only use webmail, or58 must know how many were sent. Then say plainly that this skill does not fit, and59 point to `new-website/references/WEBSITE_ARCHITECTURE.md` Tier 2: a form that sends60 through a server, which needs a mail service, settings only the owner can create,61 and a paragraph on the privacy page. Not built by this skill.623. **Are file uploads or a newsletter sign-up wanted?** Different problems; not this.6364## 1. What it adds to the site6566| File | From this skill's `templates/` | What it is |67|---|---|---|68| `src/components/MailForm.astro` | `MailForm.astro` | the form, and the address line under it |69| `src/components/mail-form-text.ts` | `mail-form-text.ts` | everything the form says, in English and German, and the longest message it takes |70| `public/js/mail-form.js` | `mail-form.js` | the script: shows the form, builds the `mailto:` link, opens it |71| `tests/mail-form.spec.ts` | `mail-form.spec.ts` | the form as a visitor meets it: the link the button opens (address, subject, every field, encoding), an empty field, labels and keyboard order through any added fields, a hint as the message box's description, the page without JavaScript, a strict Content-Security-Policy, and every text against the site's tone rules |7273The templates are in this skill's `templates/` folder, beside this SKILL.md; the bundled74copy of the skill on a handed-off repo has them too. Install all four.7576**How it works, in one paragraph.** The owner's address goes into the HTML encoded the77way `EmailLink` encodes it (`src/lib/obfuscate.ts`), never as plain text. The script, a78file of the site's own under `public/js/` rather than an inline script, so a strict79`script-src 'self'` policy lets it run, shows the form, and when the button is pressed80decodes the address and opens `mailto:<address>?subject=…&body=…`. The body starts81with the greeting the owner chose (`greeting`), then the visitor's message as typed,82less any empty space (spaces, tabs, blank lines) at its very start and end. Every other83field the visitor filled in follows as "Label: value", so a field the owner adds later84goes into the mail by its label with no change to the script. The language's sign-off85("Kind regards", "Freundliche Grüße") ends it; the visitor's mail program says who they86are. Without JavaScript the form stays hidden, since it could do nothing, and87the address line under it is what the visitor sees.8889**The spec needs `toneViolations`** from the site's `tests/_helpers.ts`, the tone rules90its pages are held to. A site made from an older starter lacks it, and `npm run check`91says `has no exported member 'toneViolations'`. Then first bring that file up to date92from the starter's (`new-website/templates/astro/tests/_helpers.ts`): take93`toneViolations` and the rules above it, keep the site's own `PAGES`. Take the94starter's `tests/tone.spec.ts` with it, so the pages and the form read one list. Before95replacing the site's `tone.spec.ts`, compare its rules and its `ALLOWLIST` with the96starter's: a word the site added goes into the same place in `_helpers.ts`, or the site97loses it.9899## 2. Install (on a branch, as a pull request: `AGENTS.md` §2)1001011. Copy the four files to the places in §1 (`mkdir -p public/js` first).1022. Put the form on a page, inside that page's `<Base>`:103 ```astro104 ---105 import MailForm from '../components/MailForm.astro';106 ---107 <MailForm to="<the address messages go to>" subject="<what the visitor comes for>" greeting="<the mail's first line>" />108 ```109 Ask the owner for the address. The starter's encoding takes only plain addresses:110 letters, digits and `. _ % + -` before the `@`, and the build stops with a clear111 message on anything else. A **new** `/contact` page is a new page: work through112 `AGENTS.md` §6 (`PAGES`, `llms.txt`, share card, a link to it). One form per page:113 its ids are fixed.114115 **The subject line** (`subject`, required: the build stops without it). It is the116 first thing the visitor reads in their mail program, and what stays in their Sent117 folder. So let it name what they came for, in their words, rather than the website:118 an architects' office "Anfrage Bauvorhaben", a holiday flat "Booking request", a119 consultant "Project enquiry". The mail then starts as their own request, not as a120 message to a website. Take it from the site's offer and the primary action in121 `CONTENT_GUIDE.md`, in the page's language, and keep it short, about 40 characters,122 so a mail program's list shows all of it. A page for one offer can pass its own.123 Propose one or two and let the owner choose: these are their customers' first words124 to them. The plain address under the form carries the same subject.125126 **The greeting** (`greeting`, required: the build stops without it). The first line127 of every mail, as the visitor would write it to the owner, punctuation included. Ask128 the owner whom visitors address, and propose one in the site's form of address:129 "Sehr geehrte Frau Muster," where one named person answers on a "Sie" site, "Sehr130 geehrte Damen und Herren," for a firm with no one person, "Hallo Anna," on a "du"131 site, "Dear Ms Smith," in English. The mail ends with the language's sign-off132 (`signoff` in `mail-form-text.ts`: "Kind regards", "Freundliche Grüße", no comma). A133 site that wants another, such as "Viele Grüße", changes it there. The plain address134 under the form opens a blank mail, with no greeting.1353. **Language.** The form speaks the language of the page it is on, by itself: a page136 built with `<Base lang="de">` on an English site gets a German form. `Base.astro`137 hands the page's language down (`Astro.locals.lang`); on a site with several138 languages it is the page's locale.139 `lang="…"` overrides; then set `LANG` in the spec too (step 4). English and German140 are built in, with no form of address in German, so the form fits a "du" site and a141 "Sie" site. Any other language: "Add a language" below, first. A form in a language142 with no texts stops the build.143144 **A site made from an older starter** lacks the line in `Base.astro`. On a site145 without Astro's language routing, a form without `lang` then stops the build with a146 message naming the line (with routing, the page's locale stands in). Add147 `Astro.locals.lang = lang;` after the props in `Base.astro`, and the declaration148 `declare namespace App { interface Locals { lang?: string } }` to `src/env.d.ts`:149 create the file from the starter's if the site has none, and keep what a site's own150 file already declares. Without the declaration, `npm run check` fails on the line.1514. In `tests/mail-form.spec.ts` set `PAGE` (the page with the form), `TO`, `SUBJECT`152 and `GREETING` (the address, the subject and the greeting from step 2). The spec153 fails while one is empty, and holds the subject and the greeting to the site's tone154 rules. `LANG` only if the page passes155 `lang`. One copy guards one form:156 with the form on pages in two languages, copy it once per language157 (`tests/mail-form.de.spec.ts`), each with its own `PAGE`, `SUBJECT` and `GREETING`.1585. **Fields.** The form asks for the message, nothing else: the visitor's name and159 email address come with their mail, and the form adds the greeting and the sign-off.160 A field161 the owner wants, or a hint above the message box: "Adding fields" below.1626. `npm run check && npm test`.163164### Adding fields165166Ask only what the visitor's mail cannot carry and the owner needs to answer: a kind of167request, a place, a phone number for a call back. Never a name or an email field: the mail168brings both. Each field is one more reason to leave; two or three is plenty.169170Fields go between `<MailForm>` and `</MailForm>`, and come before the message. A hint goes171in the slot `hint`: the form shows it between the message's label and its box, and ties it172to the box (`aria-describedby`), so it becomes the box's accessible description. An173example,174for a building firm:175176```astro177<MailForm to="…" subject="Project enquiry" greeting="Dear Ms Smith,">178 <fieldset>179 <legend>What is it about? <span class="mail-form-optional">(optional)</span></legend>180 <label><input type="radio" name="kind" id="kind-new" value="new" /> A new project</label>181 <label><input type="radio" name="kind" id="kind-running" value="running" /> A project under way</label>182 </fieldset>183 <p>184 <label for="town">Town</label> <span class="mail-form-optional" id="town-optional">(optional)</span>185 <input id="town" name="town" type="text" maxlength="80" aria-describedby="town-optional" />186 </p>187 <Fragment slot="hint">For example: what is planned, how far the planning is, when work should start.</Fragment>188</MailForm>189```190191The mail then reads, between the message and the sign-off: "A new project" and "Town:192Bath". The rules193behind it, each from a source read on 2026-10-27:194195- **A choice is radio buttons in a `fieldset`, named by its `legend`.** "Radio button196 groups should always be grouped using `<fieldset>`" (W3C WAI,197 https://www.w3.org/WAI/tutorials/forms/grouping/). The mail carries the ticked option's198 label alone, not the legend, so write each option to read on its own ("A new project",199 not "New").200- **Every added field starts empty.** No list (`select`): a drop-down list always has an entry201 chosen, so an untouched list sends an answer the visitor never gave, a "Please choose"202 entry included. No box ticked and no text filled in advance. The script sends whatever a203 field holds, and the spec expects no field line when the visitor adds nothing.204- **None ticked in advance.** "Do not pre-select radio options" (GOV.UK Design System,205 https://design-system.service.gov.uk/components/radios/). Once ticked, a radio cannot be206 unticked; for an optional choice that costs one line the visitor can delete in their mail207 program.208- **Optional fields say "(optional)"; required ones get no asterisk.** "Never mark209 mandatory fields with asterisks" (GOV.UK,210 https://design-system.service.gov.uk/patterns/question-pages/). GOV.UK puts the word in211 the label; here it goes beside it, in a `span` with class `mail-form-optional` tied to the212 field with `aria-describedby`, because the mail uses the label's text: "Town: Bath", not213 "Town (optional): Bath". In a radio group it goes in the `legend`, which the mail never214 shows.215- **A hint shows above the box, never as a placeholder.** Placeholder text disappears as216 the visitor types; Nielsen Norman Group recommends "clear, visible labels that are placed217 outside empty form fields"218 (https://www.nngroup.com/articles/form-design-placeholders/).219- **A hint can follow the choice, by CSS alone.** Put one `span` per case in the slot220 (`<span class="hint-any">…</span><span class="hint-new">…</span><span221 class="hint-running">…</span>`) and show the one that fits, in the page's `<style>`.222 `.mail-form` is the form's own element, outside the page's style scope, hence223 `:global`:224 ```css225 .hint-new, .hint-running { display: none; }226 :global(.mail-form):has(#kind-new:checked, #kind-running:checked) .hint-any { display: none; }227 :global(.mail-form):has(#kind-new:checked) .hint-new { display: inline; }228 :global(.mail-form):has(#kind-running:checked) .hint-running { display: inline; }229 ```230 A hidden `span` is left out of the box's description, so the description is the hint231 on screen (the page test below checks it).232- **No promise the owner has not made.** Not "we answer within a day", not "the first talk233 is free", unless the owner says so.234235**Looks.** The form styles what goes in the slot: a text field, a radio group and236the `mail-form-optional` note look like the message field, with no CSS of the page's own.237Astro gives fields in a slot the page's style scope, not the form's, so the form's rules238reach them through `:global`, inside the form only. A page adds style only for what is its239own, such as a hint that changes.240241**The spec.** Set `ADDED` in `tests/mail-form.spec.ts` to the fields' labels, one per Tab242stop in order: a radio group by its first option (`['A new project', 'Town']`). The spec243then checks that every control has a label, that Tab goes through them to the message and244the button, and, when there is a hint, that it is the box's accessible description.245246**The page's own test.** Only the page knows its fields, so add a short spec next to it247(`tests/contact.spec.ts`) that enters as a visitor does, through the button, and checks the248mail word for word:249250```ts251import { test, expect, type Page } from '@playwright/test';252import { TEXT } from '../src/components/mail-form-text';253254const t = TEXT.en; // the page's language255const greeting = 'Dear Ms Smith,'; // the form's greeting256const form = (page: Page) => page.locator('form[data-mail-form]');257// The mail body the button hands to the mail program, decoded.258async function send(page: Page) {259 const asked = page.waitForRequest((r) => r.url().startsWith('mailto:'), { timeout: 5000 });260 await form(page).getByRole('button', { name: t.send, exact: true }).click();261 const body = (await asked).url().split('?')[1].split('&').find((p) => p.startsWith('body='))!;262 return decodeURIComponent(body.slice('body='.length));263}264265test('contact — the choice and the town arrive under the message', async ({ page }) => {266 await page.goto('/contact');267 await form(page).getByLabel('A new project', { exact: true }).check();268 await form(page).getByLabel('Town', { exact: true }).fill('Bath');269 await form(page).getByLabel(t.message, { exact: true }).fill('A kitchen extension.');270 expect(await send(page)).toBe(`${greeting}\r\n\r\nA kitchen extension.\r\n\r\nA new project\r\nTown: Bath\r\n\r\n${t.signoff}`);271});272273test('contact — with nothing chosen or added, the mail has no field line', async ({ page }) => {274 await page.goto('/contact');275 await expect(form(page).locator('input[type=radio]:checked')).toHaveCount(0);276 await form(page).getByLabel(t.message, { exact: true }).fill('A short question.');277 expect(await send(page)).toBe(`${greeting}\r\n\r\nA short question.\r\n\r\n${t.signoff}`);278});279```280281A hint that follows the choice282gets one more test: `toHaveAccessibleDescription` on the message box, before and after each283choice. A field that asks for more personal data than the message also goes into the privacy284page (§4).285286### Add a language287288On a new site in that language, or when a site gains it later. Translate from the289English, all of it in one go.2902911. **Read the site's voice first**: its `CONTENT_GUIDE.md` (in German the register, "du"292 or "Sie") and the tone rules in `tests/_helpers.ts`. Where the language allows, do as293 the German texts do and address nobody.2942. In `src/components/mail-form-text.ts`, copy the `en` entry of `TEXT` under the295 language's two-letter code (`fr`, not `fr-CA`) and translate every value; the296 comment above `TEXT` says where each one shows. `npm run check` fails while one is297 missing, and the spec holds every text to the tone rules. For a language without298 rules of its own in `tests/_helpers.ts` that is the ban on the long dash alone: read299 the texts against step 1 yourself, and if the owner speaks the language, ask them to300 read the form once.3013. **The address hint** a visitor without JavaScript reads ("name [at] example [dot]302 com") takes its word for "dot" from `DOT_WORD` in `src/lib/obfuscate.ts` (English and303 German there); add the language's word. The spec fails while the hint says "dot".3044. **The privacy page.** The starter has it in English and German only. A site in this305 language needs its own, with the section on contact by email (§4).3065. The page and its test, as in §2 steps 3 and 4.307308## 3. Try it once (the owner)309310It works the same on a laptop as on the live site, since there is nothing on a server311to wait for. After `npm run build && npm run preview`, or on the preview address of the312pull request:3133141. The owner fills in the form and presses the button. Their mail program opens with a315 new message: to the address from §2, the subject line and the message as they316 typed it, umlauts and line breaks included.3172. They send it to themselves and see it arrive.3183. Nothing opened: their computer has no mail program set up for `mailto:` links. That319 is exactly what some visitors meet, and why the address shows under the form. On a320 Mac it is set in Mail's settings, on Windows under default apps; in Chrome a webmail321 such as Gmail can ask to open these links. Not a fault of the form.322323## 4. The privacy page324325The starter's privacy page already has a section on contact by email ("4. Contact by326email", German "4. Kontakt per E-Mail"), naming the name, the address and the message.327That is what this form produces: an email, sent by the visitor. **Nothing to add**, and328no processor paragraph, since no service handles the message on the way.329330Check two things only: the section is still there (a rewritten privacy page may have331lost it; then write it, covering what is processed, why, the legal basis and how long332it is kept), and any field added in §2 step 5 that asks for more than the message is333named in it. Like the kit's other legal drafts, a baseline, not legal advice.334335**With Plausible on**, a press of the button sends one "Email Tap" event, the same one336the starter's email link sends (nothing typed goes with it). Section 3 of the starter's337privacy page (EN `privacy.astro`; German `_datenschutz.astro`, served as338`datenschutz.astro` once a German site renames it) already says so ("a button that opens your339email program"). An older site's privacy page may lack that sentence, and its own340`src/components/EmailLink.astro`, which shows the address under the form, may not count341clicks yet (no `addEventListener` in it). Take whatever is missing from the starter: the342sentence, the click listener, or both. The form sends its event343either way, so the sentence is not optional on a site that runs Plausible. In Plausible's344installer leave "Form submissions" unticked: whether Plausible would count this form a345second time was not checked.346347**A site made before 0.35 in analytics server mode** (`ANALYTICS.mode: 'server'`) does not348count the button: no Plausible script runs, so the form's call does nothing, and counting349it from the server would mean passing what the visitor typed through it. The mail program350opens as before. A site made with 0.35 or later has no server mode.351352## 5. What it does not do353354- **No sending, no storage, no count of sent messages.** The site never learns whether355 a message was sent. The owner's mailbox is the record. With Plausible on, the press of356 the button is counted (§4): a visitor who asked to write, not an opened mail program357 and not a message.358- **No help for a visitor without a mail program**, beyond the address under the form359 and the sentence that points to it.360- **Very long messages.** The form stops at 2,000 typed characters (`LIMITS` in361 `mail-form-text.ts`). In the link they become more: about 2,800 for English prose,362 more with umlauts and line breaks. Some mail programs cut a very long link, and at363 what length was not measured, so a long message may arrive cut in some of them, and364 then the sign-off at its end is the first thing lost. The visitor sees the mail365 before pressing Send, and can write on in their mail program. Whether a mail program366 adds the visitor's own signature under it was not checked.367- **The address line under a strict Content-Security-Policy.** The form works under368 `script-src 'self'` (the spec proves it). The address under it, the starter's369 `EmailLink`, decodes through an inline script, so under such a policy it stays as the370 readable "name [at] example [dot] com" hint and cannot be clicked. The starter's own371 policy (`public/_headers`) allows inline scripts, so a site that kept it is not372 affected.373- **Not checked in every mail program.** The link follows the standard for `mailto:`374 links (RFC 6068), and the spec checks it to the character. How each mail program375 shows it was not tried beyond the owner's own (§3).376377## Boundaries (do not duplicate)378379- Which hosting tier a site needs: `new-website` §1 Q2 and380 `references/WEBSITE_ARCHITECTURE.md`.381- Getting the suite green, and what else to test on a new feature: `website-qa` §1b.382- The privacy page as a whole: the starter's `privacy.astro` and `_datenschutz.astro`.383- The address link alone, with no form: the starter's `EmailLink`.384385## Done means386387The owner chose the form knowing its weak spots; it is on its page in the site's388language with the right address and the owner's greeting; `npm test` is green with389`PAGE`, `TO`, `SUBJECT` and `GREETING` set; the390privacy page's section on contact by email is in place; and the owner has opened one391message from it in their own mail program and seen it arrive.