@nxgt/mail-ui 0.1.0

package/docs/guide/messages.md

@@ -0,0 +1,156 @@
+# Shared messages
+
+This page is for the messages `@nxgt/mail-ui` brings to `@nxgt/mail-i18n`:
+what they are, how your catalogues override them, and what a project in
+another locale writes.
+
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { i18n } from '@nxgt/mail-i18n';
+import { ui, uiCatalogues } from '@nxgt/mail-ui';
+
+export default defineMailConfig({
+	plugins: [
+		ui({ brand: { name: 'Acme', url: 'https://acme.example' } }),
+		i18n({ locales: ['en', 'fr'], catalogues: [uiCatalogues] }),
+	],
+});
+```
+
+```vue
+<!-- emails/welcome.vue -->
+<template>
+  <NxLayout>
+    <NxTypography>{{ t('common.greeting', { name: placeholder('name') }) }}</NxTypography>
+    <NxTypography>{{ t('welcome.body') }}</NxTypography>
+    <NxTypography variant="caption">{{ t('common.footer.ignore') }}</NxTypography>
+  </NxLayout>
+</template>
+```
+
+Your `locales/en.json` and `locales/fr.json` hold `welcome.subject` and
+`welcome.body`; the `common` keys come from `uiCatalogues`. The English build
+starts with `Hello {{ name }},` and the footer says `You received this e-mail
+because you have an account with Acme.`
+
+## The messages
+
+| Key | `en` | `fr` | Arguments |
+| --- | --- | --- | --- |
+| `common.greeting` | `Hello {name},` | `Bonjour {name},` | `name` |
+| `common.footer.why` | `You received this e-mail because you have an account with {brand}.` | `Vous recevez cet e-mail parce que vous avez un compte chez {brand}.` | `brand` |
+| `common.footer.ignore` | `If you did not ask for this, you can ignore this e-mail.` | `Si vous n'êtes pas à l'origine de cette demande, vous pouvez ignorer cet e-mail.` | — |
+| `common.avatarGroup.more` | `{count, plural, other {# more}}` | `{count, plural, one {# autre} other {# autres}}` | `count`, a number |
+| `common.timeline.empty` | `No activity yet` | `Aucune activité pour le moment` | — |
+| `common.metrics.ofTarget` | `of {target}` | `sur {target}` | `target` |
+| `common.metrics.thisPeriod` | `This period` | `Cette période` | — |
+| `common.metrics.lastPeriod` | `Last period` | `Période précédente` | — |
+| `common.seeAlso` | `See also` | `Voir aussi` | — |
+
+```ts
+import type { Catalogues } from '@nxgt/mail-i18n';
+import { uiCatalogues } from '@nxgt/mail-ui';
+
+const shared: Catalogues = uiCatalogues; // { en: { common: {…} }, fr: { common: {…} } }
+```
+
+`common.footer.why` is the one `<NxLayout>` writes itself, in its footer,
+with the brand's name; `common.avatarGroup.more` is the label `<NxAvatarGroup>`
+gives its `+N`, for a screen reader; `common.timeline.empty` is what
+`<NxTimeline>` writes for no events, unless given `empty`;
+`common.metrics.ofTarget` is `<NxGoalCard>`'s `of 24`, with its `target`;
+`common.metrics.thisPeriod` and `common.metrics.lastPeriod` label
+`<NxCompareCard>`'s two boxes, unless given their `label`; `common.seeAlso`
+heads `<NxSeeAlso>`, unless given `label`. The other two, `common.greeting`
+and `common.footer.ignore`, are for your templates.
+
+## `<NxLayout>` needs `common.footer.why`
+
+Once `i18n()` is in the plugins, `<NxLayout>` calls
+`t('common.footer.why', { brand })`. Without `uiCatalogues`, and without the
+key in your catalogues, the build fails:
+
+```text
+Error: i18n: fr: welcome calls t('common.footer.why'), which is not a key of the catalogues
+```
+
+Pass `catalogues: [uiCatalogues]`, or write the key yourself. The layout
+formats it even when you fill its `footer` slot, so the key is needed either
+way.
+
+Without `@nxgt/mail-i18n`, `<NxLayout>` calls nothing and the footer shows the
+brand's name alone.
+
+## Overriding a message
+
+Your catalogues are merged **over** `uiCatalogues`, key by key: write the
+keys you want to change, and keep the others.
+
+```json
+// locales/en.json
+{
+	"common": { "greeting": "Hi {name}," },
+	"welcome": { "subject": "Welcome to Acme, {name}", "body": "Your account is ready." }
+}
+```
+
+```json
+// locales/fr.json — no common: the nine French messages are uiCatalogues'
+{
+	"welcome": { "subject": "Bienvenue chez Acme, {name}", "body": "Votre compte est prêt." }
+}
+```
+
+The English build writes `Hi {{ name }},`, the French one
+`Bonjour {{ name }},`; both keep the eight other `common` messages from the
+package. The merge rules — several sources, a
+message replacing a group — are in `@nxgt/mail-i18n`'s
+[Catalogues](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-i18n/docs/guide/catalogues.md#catalogues-from-a-package).
+
+The merged catalogues are checked as your own are, against the fallback
+locale: an override in `fr` may leave `{name}` out, but not use an argument
+the `en` message does not declare.
+
+## Another locale
+
+`uiCatalogues` has `en` and `fr`. For any other locale, your catalogue writes
+the nine `common` keys, or the build fails on the first one missing:
+
+```text
+Error: i18n: de: common.footer.ignore is missing — en, the fallback locale, has it
+```
+
+```json
+// locales/de.json
+{
+	"common": {
+		"greeting": "Hallo {name},",
+		"footer": {
+			"why": "Sie erhalten diese E-Mail, weil Sie ein Konto bei {brand} haben.",
+			"ignore": "Wenn Sie dies nicht angefordert haben, können Sie diese E-Mail ignorieren."
+		},
+		"avatarGroup": { "more": "{count, plural, other {# weitere}}" },
+		"timeline": { "empty": "Noch keine Aktivität" },
+		"metrics": {
+			"ofTarget": "von {target}",
+			"thisPeriod": "Dieser Zeitraum",
+			"lastPeriod": "Vorheriger Zeitraum"
+		},
+		"seeAlso": "Siehe auch"
+	},
+	"welcome": { "subject": "Willkommen bei Acme, {name}", "body": "Ihr Konto ist bereit." }
+}
+```
+
+`<NxLayout>` passes `{brand}` to `common.footer.why`, the brand's name, and
+`<NxGoalCard>` `{target}` to `common.metrics.ofTarget`. A translation may
+leave one out; it cannot add another argument.
+
+## See also
+
+- [Components](components.md#nxlayout) — the layout's footer slot, and the
+  components that write a shared message.
+- `@nxgt/mail-i18n`'s
+  [Templates](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-i18n/docs/guide/templates.md)
+  — `t` and `placeholder`.

package/docs/guide/plugin.md

@@ -0,0 +1,365 @@
+# The plugin
+
+This page is for adding `ui({ brand, theme })` to a project: what it gives
+every template, the options it checks, and how a project replaces one of its
+components or its layout.
+
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { ui } from '@nxgt/mail-ui';
+
+export default defineMailConfig({
+	plugins: [ui({ brand: { name: 'Acme', url: 'https://acme.example' } })],
+});
+```
+
+```vue
+<!-- emails/welcome.vue -->
+<template>
+  <NxLayout preheader="Your account is ready">
+    <NxTypography variant="headline-small">Welcome to {{ brand.name }}</NxTypography>
+    <NxButton href="https://acme.example/start">Get started</NxButton>
+  </NxLayout>
+</template>
+```
+
+`maizzle build` writes `dist/welcome.html`: `Acme` at the top, linked to
+`https://acme.example`, the heading and the button on a white card, and
+`Acme` again in the footer.
+
+## The signature
+
+```ts
+import type { MailPlugin } from '@nxgt/mail-config';
+
+interface Brand {
+	readonly name: string;
+	readonly url?: string;
+	readonly logo?: {
+		readonly src: string;
+		readonly width?: number; // pixels, default 120
+		readonly alt?: string; // default the brand's name
+	};
+}
+
+interface UiOptions {
+	readonly brand: Brand;
+	readonly theme?: Readonly<Record<string, string>>;
+}
+
+function ui(options: UiOptions): MailPlugin;
+```
+
+The plugin it answers, named `ui`, does four things:
+
+- registers every component of the package's `components/` folder under the
+  prefix `Nx` (`card-header.vue` is `<NxCardHeader>`); Maizzle's own stay
+  available (`<Button>`, `<Spacer>`);
+- gives every template `brand`, the brand as passed;
+- provides the brand and the theme's CSS to the components, under
+  [`UI_CONTEXT`](#your-own-layout--ui_context);
+- resolves the tags of a `.vue` file installed in `node_modules` — its own
+  components, and a package's templates such as `@nxgt/mail-presets`' — see
+  [Components from a package](#components-from-a-package).
+
+It sets no build event, and no list but the three `defineMailConfig` joins
+(`components.source`, `vite.plugins`, `vue.plugins`), so it drops nothing
+another plugin or your config sets. See
+[`@nxgt/mail-config`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-config/docs/guide/config.md)
+for how plugins merge.
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `brand` | `Brand` | — (required) | Who sends the e-mail: `<NxLayout>`'s header and footer, and `brand` in templates |
+| `brand.name` | `string` | — (required) | The header's text when there is no logo; the footer's, always |
+| `brand.url` | `string` | none | Where the header and the footer's name link to. Without it, neither is a link |
+| `brand.logo.src` | `string` | — (required in `logo`) | The header's image, instead of the name |
+| `brand.logo.width` | `number` | `120` | The image's `width` attribute, in pixels |
+| `brand.logo.alt` | `string` | `brand.name` | The image's `alt` |
+| `theme` | `Record<string, string>` | `{}` | Tokens of `theme.css` to override — see [The theme](theme.md) |
+
+### `brand.url` and `brand.logo.src` are absolute
+
+```ts
+ui({
+	brand: {
+		name: 'Acme',
+		url: 'https://acme.example',
+		logo: { src: 'https://acme.example/logo.png', width: 96 },
+	},
+});
+```
+
+A mail client opens the e-mail far from your site: it resolves no relative
+URL, and `/logo.png` would show nothing. Both are refused unless they start
+with `http://` or `https://`. The header then shows:
+
+```html
+<a href="https://acme.example" …><img src="https://acme.example/logo.png" width="96" alt="Acme" …></a>
+```
+
+### The brand is fixed when `ui()` is called
+
+`ui()` keeps a frozen copy of `brand`: changing the object you passed, after
+the call, changes nothing in the e-mails.
+
+## `brand` in templates
+
+```vue
+<template>
+  <NxTypography>Thanks for joining {{ brand.name }}.</NxTypography>
+  <NxLink v-if="brand.url" :href="`${brand.url}/help`">Help</NxLink>
+</template>
+```
+
+`brand` is a Vue global property, read-only. It is known at build time, so a
+template may branch on it, unlike a placeholder.
+
+### Typed in the editor and in CI
+
+`ui()` writes `.maizzle/nxgt-mail-ui.d.ts` each time the config loads —
+`maizzle prepare` (the starter's `postinstall`), `maizzle serve`,
+`maizzle build` — only when its text changed, and only on the main thread of
+a parallel build:
+
+```ts
+// .maizzle/nxgt-mail-ui.d.ts, generated
+// Generated by @nxgt/mail-ui each time the config loads. Never edited, never committed:
+// it gives the templates `brand`.
+import type {} from '@nxgt/mail-ui';
+```
+
+That import loads the package's declaration of `brand` on Vue's template
+properties:
+
+```ts
+declare module 'vue' {
+	interface ComponentCustomProperties {
+		readonly brand: Brand;
+	}
+}
+```
+
+The file is needed because the starter's `tsconfig.json` includes `**/*.vue`
+and `.maizzle/*.d.ts`, not `maizzle.config.ts`: nothing the config imports
+reaches the editor otherwise. Keep that include, and run `maizzle prepare`
+once after installing:
+
+```jsonc
+// tsconfig.json — the official starter's
+{ "include": ["**/*.vue", ".maizzle/*.d.ts"] }
+```
+
+```jsonc
+// package.json
+{ "scripts": { "postinstall": "maizzle prepare", "typecheck": "vue-tsc --noEmit" } }
+```
+
+Vue's language tools (the **Vue - Official** extension, `vue-tsc`) then check
+`brand` in every template:
+
+```vue
+<template>
+  <NxTypography>Welcome to {{ brand.nam }}</NxTypography>
+  <!-- Property 'nam' does not exist on type 'Brand'. Did you mean 'name'? -->
+</template>
+```
+
+`.maizzle/` is in the starter's `.gitignore`, and the file is written under
+the directory `maizzle` runs in — run it from the project root. The keys of
+`t` are typed by `@nxgt/mail-i18n`'s own generated file: see its guide,
+[Editor and type checking](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-i18n/docs/guide/editor.md).
+
+A project that sets Maizzle's `root`, or a Laravel project (whose types
+Maizzle writes to `resources/js/types/maizzle`), must include the
+`.maizzle/*.d.ts` of the folder `maizzle` runs in itself. If the editor says
+`Property 'brand' does not exist`, see
+[the troubleshooting entry](../troubleshooting.md#the-editor-says-property-brand-does-not-exist-in-a-template).
+If Biome is the editor's linter, set `html.experimentalFullSupportEnabled` in
+`biome.json`, or it reads a template without `<script>` as JavaScript once you
+edit it — see
+[Biome reports `parse` errors](../troubleshooting.md#biome-reports-parse-errors-in-a-template-as-soon-as-you-edit-it).
+
+## Replacing a component
+
+A file in your project's `components/` named as one of our tags,
+`nx-badge.vue` for `<NxBadge>`, replaces it in every template:
+
+```vue
+<!-- components/nx-badge.vue -->
+<template>
+  <span class="rounded-sm bg-primary px-2 text-xs text-primary-foreground"><slot /></span>
+</template>
+```
+
+The theme's tokens (`bg-primary`, `rounded-sm`) work in it, since it renders
+inside `<NxLayout>`. To start from ours, copy it from the package — its
+folder is `COMPONENTS_DIR`:
+
+```ts
+import { COMPONENTS_DIR } from '@nxgt/mail-ui';
+
+console.log(COMPONENTS_DIR); // /…/node_modules/@nxgt/mail-ui/components
+```
+
+Ours are named without the prefix, which `ui()` adds: `badge.vue` is
+`<NxBadge>` (`nx-button.vue` keeps it, being built on Maizzle's `<Button>`).
+Your `components/` has no prefix, so **rename the copy with the tag's whole
+name**, `nx-badge.vue`: a `components/badge.vue` is `<Badge>`, a component of
+its own, and replaces nothing.
+
+A copied component imports `./ui` for its shared types; copy `ui.ts` from the
+same folder beside it, or inline what it uses.
+
+## Components from a package
+
+Maizzle finds the component behind a tag (`<NxButton>`, `<Container>`) with
+`unplugin-vue-components`, which skips every file under `node_modules`. Left
+alone, our components — installed from npm — and a package's templates, as
+`@nxgt/mail-presets` ships them, would render as an empty document, and the
+build would pass.
+
+`ui()` adds its own resolver to Maizzle's Vite config for those files: a
+`.vue` file under `node_modules`, Maizzle's own excepted. It looks a tag up in
+this order:
+
+1. your project's `components/`: the file Maizzle names as the tag,
+   `nx-badge.vue` or `NxBadge.vue` for `<NxBadge>` — so a component you
+   replace is replaced in a package's templates too;
+2. ours, in `COMPONENTS_DIR`, named without the prefix (`badge.vue`);
+3. Maizzle's built-ins (`Container`, `Spacer`, `Button`, …).
+
+Only the top level of your `components/` counts there: a component in a
+subfolder (`components/brand/logo.vue`, `<BrandLogo>`) or in a
+`components.source` folder is found in your own templates, not inside an
+installed one. Put a component that replaces ours at the top of
+`components/`. Under `maizzle serve`, restart after adding one.
+
+Nothing to write for it: listing `ui()` is enough, and a package's templates
+need no import of their components.
+
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { i18n } from '@nxgt/mail-i18n';
+import { presets } from '@nxgt/mail-presets';
+import { ui, uiCatalogues } from '@nxgt/mail-ui';
+
+const mails = presets();
+
+export default defineMailConfig({
+	plugins: [
+		ui({ brand: { name: 'Acme' } }), // resolves <NxLayout> in the installed templates
+		i18n({
+			locales: ['en', 'fr'],
+			catalogues: [uiCatalogues, mails.catalogues],
+			templates: [mails.templates],
+		}),
+	],
+});
+```
+
+`ui()` brings `unplugin-vue-components` as a dependency — the one Maizzle
+uses — and finds Maizzle's built-ins beside the package, up through each
+`node_modules`; without `@maizzle/framework` installed, the config fails to
+load with `ui: @maizzle/framework is not installed beside @nxgt/mail-ui`.
+
+With `@nxgt/mail-i18n`, an e-mail that still renders empty — a tag none of
+the three places has — fails the build:
+`i18n: en/welcome.html is empty — a tag of its template resolved to no
+component; list the plugin that brings it, as ui()`.
+
+## Your own layout — `UI_CONTEXT`
+
+Replace `<NxLayout>` the same way, with `components/nx-layout.vue`. Read the
+brand and the theme's CSS from `UI_CONTEXT`, so `ui({ theme })` still applies
+to every component inside:
+
+```vue
+<!-- components/nx-layout.vue -->
+<script setup lang="ts">
+import { type UiContext, UI_CONTEXT } from '@nxgt/mail-ui';
+import { inject } from 'vue';
+
+const { brand, css } = inject(UI_CONTEXT) as UiContext;
+const style = `@import "@maizzle/tailwindcss";\n${css}`;
+</script>
+
+<template>
+  <Html lang="en">
+    <Head>
+      <meta name="color-scheme" content="light">
+      <style v-html="style"></style>
+    </Head>
+    <Body class="bg-background font-sans">
+      <Container class="px-6 py-8">
+        <p class="m-0 mb-6 text-lg font-semibold text-primary">{{ brand.name }}</p>
+        <slot />
+      </Container>
+    </Body>
+  </Html>
+</template>
+```
+
+```ts
+const UI_CONTEXT = 'nxgt:mail-ui';
+
+interface UiContext {
+	readonly brand: Brand;
+	/** theme.css, then an @theme block of the overrides. */
+	readonly css: string;
+}
+```
+
+The theme is not a stylesheet link: a mail client loads none. Its tokens go
+in the layout's `<style>` under the Tailwind import, and Maizzle inlines the
+result.
+
+## Errors
+
+`ui()` throws a bare `TypeError` when `maizzle.config.ts` loads:
+
+| Message | Cause |
+| --- | --- |
+| `ui: options must be an object, as { brand: { name: 'Acme' } }` | `ui()` called with nothing, or not an object |
+| `ui: brand must be an object, as { name: 'Acme', url: 'https://acme.example' }` | No `brand`, or `brand: 'Acme'` |
+| `ui: brand.name must be the name the e-mails show` | No `name`, or a blank one |
+| `ui: brand.url must be an absolute http(s) URL` | `url: '/home'`, `url: 'acme.example'` |
+| `ui: brand.logo.src must be an absolute http(s) URL — a mail client loads nothing relative` | `logo: 'logo.png'`, or `logo: { src: 'logo.png' }` |
+| `ui: brand.logo.width must be a width in pixels` | `0`, `1.5`, `'96'` |
+| `ui: brand.logo.alt must be a string` | `alt: 1` |
+| `ui: theme must be an object of tokens, as { 'color-primary': '#0f766e' }` | `theme: ['#0f766e']` |
+| `ui: theme.color-primay is not a token of the theme — name one of theme.css without its --, as color-primary` | A misspelled token, or one written with its `--` |
+| `ui: theme.color-primary must be a CSS value, as #0f766e or 8px` | An empty value, a number, or one holding `;`, `{`, `}`, `<`, `>`, a quote, a backslash, a CSS comment (`/*`, `*/`) or a line break |
+
+```ts
+ui({ brand: { name: 'Acme', url: '/home' } });
+// TypeError: ui: brand.url must be an absolute http(s) URL
+```
+
+One plain `Error`, when `ui()` is called: `@maizzle/framework`, a required
+peer, could not be found up from the package.
+
+```text
+Error: ui: @maizzle/framework is not installed beside @nxgt/mail-ui
+```
+
+A component rendered without the plugin fails the build instead, naming
+itself:
+
+```text
+Error: NxLayout: ui() is not in the plugins of defineMailConfig
+```
+
+It happens when the components are registered by hand from
+`COMPONENTS_DIR` rather than through `ui()`. List `ui()` in the project's
+`plugins`.
+
+## See also
+
+- [Components](components.md) — every component, its props and its slots.
+- [The theme](theme.md) — the tokens `theme` overrides.
+- [Shared messages](messages.md) — the footer's text with `@nxgt/mail-i18n`.

package/docs/guide/theme.md

@@ -0,0 +1,153 @@
+# The theme
+
+This page is for changing how the components look: the tokens of
+`theme.css`, how a colour reaches the built HTML, and what an override
+changes.
+
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { ui } from '@nxgt/mail-ui';
+
+export default defineMailConfig({
+	plugins: [
+		ui({
+			brand: { name: 'Acme' },
+			theme: { 'color-primary': '#0f766e', 'radius-xl': '8px' },
+		}),
+	],
+});
+```
+
+Every `<NxButton>` is then `#0f766e`, every tonal button and the page behind
+the card are tints of it, and the card's corners are 8px.
+
+## Where the theme comes from
+
+`theme.css` is `@nxgt/material-vue`'s light theme, as Tailwind 4 `@theme`
+tokens. `<NxLayout>` writes it in its `<style>`, under
+`@import "@maizzle/tailwindcss"`, then an `@theme` block of your overrides,
+which wins. So any Tailwind class a template writes — `bg-primary`,
+`text-muted-foreground`, `rounded-lg` — uses the theme, in the components and
+in your own markup inside `<NxLayout>`.
+
+The colours are material-vue's, in `oklch`. Maizzle writes each as a hex
+value in the built HTML, followed by a `lab()` one for the clients that read
+it, and leaves no `var()` and no `oklch()` for a client to resolve:
+
+```html
+<p style="color: #020918; color: lab(2.35721% .367686 -8.51797)">…</p>
+```
+
+## Tokens
+
+Name a token in `theme` without its `--`: `--color-primary` is
+`'color-primary'`.
+
+| Token | Default | Used for |
+| --- | --- | --- |
+| `radius-sm`, `radius-md`, `radius-lg`, `radius-xl` | `6px`, `8px`, `10px`, `14px` | `rounded-*`: `NxBanner` (`md`), `NxCode` (`lg`), the card (`xl`) |
+| `color-background` | white | What every tint is mixed over |
+| `color-foreground` | near black | Text |
+| `color-card`, `color-card-foreground` | white, near black | The layout's card, `NxCard` |
+| `color-primary`, `color-primary-foreground` | indigo, near white | The default colour of buttons, badges, alerts |
+| `color-secondary`, `color-secondary-foreground` | blue, near white | `color="secondary"` |
+| `color-muted`, `color-muted-foreground` | light grey, grey | `NxCode`'s background, a table's footer, an avatar's initials; descriptions, captions, the footer |
+| `color-accent`, `color-accent-foreground` | light grey, near black | `bg-accent` in your markup |
+| `color-error`, `color-success`, `color-info`, `color-warning` | red, teal, blue, orange | The status colours |
+| `color-error-foreground`, … `color-warning-foreground` | near white | Text on a status colour |
+| `color-border` | light grey | Card, separator, table and outlined borders |
+| `color-paper` | 5% primary over background | The page behind the layout's card |
+| `color-<colour>-5`, `-10`, `-15`, `-20`, `-25`, `-40`, `-50` | the colour mixed over background | Tints — see below |
+
+The exact values are in the file itself:
+
+```ts
+import { readFileSync } from 'node:fs';
+import { THEME_FILE } from '@nxgt/mail-ui';
+
+const css = readFileSync(THEME_FILE, 'utf8'); // @theme { --radius-sm: 6px; … }
+```
+
+A layout of your own that does not read [`UI_CONTEXT`](plugin.md#your-own-layout--ui_context)
+can import the file by its subpath — without the `theme` overrides, which
+only `UI_CONTEXT` carries:
+
+```vue
+<template>
+  <Html>
+    <Head>
+      <style>
+        @import "@maizzle/tailwindcss";
+        @import "@nxgt/mail-ui/theme.css";
+      </style>
+    </Head>
+    <Body><p class="bg-primary-15 text-primary">…</p></Body>
+  </Html>
+</template>
+```
+
+## Tints, where material-vue uses an alpha
+
+material-vue writes a translucent colour: `bg-primary/15`, `border-error/50`.
+A mail client cannot be trusted with an alpha, so the theme declares each tint
+as a plain colour: `bg-primary-15` is the primary colour mixed at 15% over the
+background, in sRGB — the colour a browser shows for the alpha — and written
+as hex in the built HTML.
+
+| Tint | Used by |
+| --- | --- |
+| `-5` | `NxAlert`'s background; `NxListTile`'s; `NxHero`'s; `paper` |
+| `-10` | `NxBanner`'s background; a selected `NxListTile size="sm"` |
+| `-15` | `NxButton` and `NxChip variant="tonal"`; a selected `NxListTile`; an `NxTimeline` marker's ground; `NxRatioCard`'s track |
+| `-20` | `NxProgress`'s track |
+| `-25` | `NxStepsItem`'s circle |
+| `-40` | `NxBanner`'s border; `NxSummaryData`'s lines; a selected `NxListTile`'s border; an `NxTimeline` marker's border |
+| `-50` | `NxButton` and `NxChip variant="outlined"`'s border |
+
+They exist for `primary`, `secondary`, `info`, `success`, `warning`, `error`
+and `foreground`, so your own markup can use them too:
+
+```vue
+<template>
+  <p class="m-0 rounded-md bg-success-10 p-3 text-success">Your payment went through.</p>
+</template>
+```
+
+## Overriding a token
+
+```ts
+ui({ brand: { name: 'Acme' }, theme: { 'color-primary': '#0f766e' } });
+```
+
+- **A tint follows its colour.** Each is mixed from the colour's token, so
+  `color-primary` above makes the tonal button `#dbeae9` and `paper`
+  `#f3f8f8`, with no other token to change.
+- **A tint can be overridden alone**: `{ 'color-primary-15': '#e0f2f1' }`.
+- **Any CSS colour works**, `oklch()` included: Maizzle turns it into hex,
+  as it does the theme's own.
+- **The value is trimmed**, and refused if it is empty or holds `;`, `{`,
+  `}`, `<`, `>`, a quote, a backslash, a CSS comment (`/*`, `*/`) or a line
+  break: it must stay one declaration.
+- **Only tokens of `theme.css`.** A name it does not declare is refused, so a
+  misspelling fails when the config loads rather than being ignored.
+
+```ts
+ui({ brand: { name: 'Acme' }, theme: { 'color-primay': '#0f766e' } });
+// TypeError: ui: theme.color-primay is not a token of the theme — name one of theme.css without its --, as color-primary
+```
+
+The full list of errors is in [The plugin](plugin.md#errors).
+
+## Light only
+
+The layout declares `<meta name="color-scheme" content="light">` and
+`supported-color-schemes` `light`, and the theme has no dark tokens. A client
+in dark mode may still invert the colours on its own; the e-mail asks it not
+to, and does not ship a second palette.
+
+## See also
+
+- [Components](components.md) — which tokens each component uses.
+- [The plugin](plugin.md) — `theme` among the other options, and your own
+  layout on the same CSS.