@samva/markup 0.13.0 → 0.14.0

package/AGENTS.md

@@ -30,7 +30,7 @@ Authoring entries are what a template file imports:
   mode) and `BrandFooter` (company, postal address, social links and the unsubscribe row the send
   path fills). The compiler binds them to the brand the build resolves; add
   `"types": ["@samva/markup/samva-brand"]` to the project's tsconfig for `tsc`. In `theme.css`,
-  `@import "samva:brand";` layers the brand theme; `samva:brand/<slug>` names one brand. These are
+  `@import "samva:brand";` layers the brand theme over the default theme (`DEFAULT_THEME`); `samva:brand/<slug>` names one brand. These are
   Samva's brand plugin (`samvaBrandPlugin` from `@samva/markup/brand`), the default; a host that
   delivers mail itself passes its own `BrandPlugin` as `brandPlugin` to `compileTemplate`,
   `renderIr` and `renderBrandFooter` to rename the brand import, the footer markers, the
@@ -65,6 +65,7 @@ entry?)` is the synchronous structural check: it runs the compiler's lowering wi
   conditional or element is a locked segment; and JSX source locations. Browser-safe: Babel parser
   only.
 - `@samva/markup/brand` — brand records and their CSS model (`parseBrandCss`, `printBrandCss`), the
+  theme vocabulary (`THEME_COLOR_ROLES`, `THEME_TOKENS`, `DEFAULT_THEME`, `foregroundDefaults`), the
   footer markers a send reads (`renderedFooterMarkers`, `withoutUnsubscribeRow`), and project
   assets (`isAssetPath`, `ASSET_CONTENT_TYPES`, `assetUrl`): which imported files become
   content-addressed assets. The send path imports it, so its closure holds only the css-tree parser
@@ -117,6 +118,15 @@ Read the contract before authoring. Import only subpaths declared in `package.js
   into file paths, so each must match `TEMPLATE_NAME_PATTERN`, one plain path segment.
   `defineTemplate` throws a `TypeError` where the name is declared. Code that builds a path from these
   names imports the pattern instead of restating it.
+- **Naming a second set of tokens for dark mode.** A theme states dark mode once, in
+  `@media (prefers-color-scheme: dark) { @theme { --color-card: … } }`, with the same names as its
+  light `@theme`. The cascade gives every element whose inlined styles read one of those colors a
+  generated `sml-dark-*` class, so `bg-card` switches by itself. A `--color-card-dark` token is just
+  another color, and `dark:` only picks a different token. A block styled with palette colors
+  (`bg-indigo-600`) or raw hex ignores the theme; style with the vocabulary in `THEME_COLOR_ROLES`.
+- **Reading contrast off the light render.** `checkEmailCompatibility` includes `email-contrast`,
+  which judges each fixture in light and dark mode (`CONTRAST_THRESHOLDS`); a color a dark block
+  leaves unpaired is an error there, not a visual nit.
 - **Declaring a webfont as if every client loads it.** A project font is an ordinary `@font-face`
   in the project's CSS (usually `theme.css`) whose `src` is a `.woff2` file in the project, named
   by a path relative to that stylesheet; the compiler serves it as a content-addressed asset and

package/CHANGELOG.md

@@ -1,3 +1,53 @@
+## @samva/markup@0.14.0
+
+### A semantic theme vocabulary, one dark-mode mechanism and a contrast check
+
+Every project compiles over a default theme in a shadcn-style vocabulary: `background`,
+`foreground`, `card`, `primary`, `secondary`, `muted`, `accent` (each with its `-foreground`),
+`border`, `--radius` (with `rounded-sm` to `rounded-xl` derived from it), `--font-sans` and
+`--font-heading`. `starter.css`, a brand and the project's own `@theme` set the same names, so
+`bg-card` or `text-primary-foreground` resolve in any project and a theme restyles every block that
+reads them. `reference.md` and `contract.json` list the tokens, their roles and their defaults;
+`@samva/markup/brand` exports `THEME_COLOR_ROLES`, `THEME_TOKENS` and `DEFAULT_THEME`.
+
+Dark mode is one mechanism: the theme's `@media (prefers-color-scheme: dark) { @theme { … } }`
+block, in project CSS and brand CSS alike. The compiler gives each element whose inlined styles
+read a color that block redefines a generated `sml-dark-*` class with a dark-mode rule, so a block
+writes `bg-card` once. Explicit `dark:` utilities still apply after it and resolve theme colors at
+their dark values. A layer that sets a color in light mode only keeps it in dark mode, and a layer
+that sets `--color-primary`, `--color-secondary` or `--color-accent` without its `-foreground` gets
+black or white by contrast.
+
+Breaking: the `-dark` suffix convention is gone. Nothing lowers a dark color to
+`--color-<name>-dark` any more; move those values into the dark-mode block and drop the matching
+`dark:…-dark` classes. `brandTailwindCss`, `brandThemeVariables`, `darkVariableName`,
+`BRAND_COLOR_VARIABLE`, `BRAND_FOREGROUND_VARIABLE` and the `brand-css-dark-conflict` finding are
+removed; `brandForegroundDefaults(brand)` is `foregroundDefaults(light, dark)` over the fills.
+The brand footer and logo use `text-muted-foreground`.
+
+The primitives read the theme. `Email` paints the page color (`--color-background` by default) on
+the body and, as `bgcolor`, on the wrapper table, and pads its content 16px each side (`gutter`).
+`Section` treats a pixel width as a maximum, so it fits a phone. `Columns` stacks its cells below
+600px (`stack={false}` keeps a row) and spaces them with `gap` in both layouts. `Button`, `Link`
+and `Divider` default to the primary fill, the primary color and the border color through classes
+a utility on them overrides; their explicit props are inline styles as before. These change the
+compiled output of every template, so the email-parity golden digests change.
+
+`checkEmailCompatibility` adds `email-contrast`: each fixture is judged in light and dark mode,
+and text below 3:1 or a button below 1.5:1 against its surroundings is an error located at the
+element; normal-size text below 4.5:1 and a button below 3:1 are warnings. New diagnostic codes:
+`email-contrast`, `invalid-columns-stack`, `invalid-columns-gap` and `invalid-number-prop`.
+
+The email starter is redesigned on the vocabulary from copyable blocks in `templates/blocks/`.
+
+## @samva/markup@0.13.1
+
+### The authoring reference omits channel-only upgrade recipes
+
+`generated/reference.md` lists upgrade recipes only for diagnostics that apply to every template,
+matching its diagnostics table and `contract.json`. The `whatsapp-template-name` recipe stays in the
+diagnostic codes, where an agent migrating a WhatsApp template reads it.
+
 ## @samva/markup@0.13.0
 
 ### Meta's WhatsApp template name comes from the template's handle

package/dist/{assets-DCULM6QD.d.ts → assets-tISHaQNF.d.ts}

@@ -33,7 +33,7 @@ interface EmailBrand {
   readonly footer?: EmailBrandFooter | undefined;
 }
 /** Every class the brand components use, compiled for any project that imports them. */
-declare const BRAND_COMPONENT_CLASSES: readonly ["dark:hidden!", "hidden", "dark:block!", "text-xs", "text-gray-500", "text-center", "font-semibold", "underline"];
+declare const BRAND_COMPONENT_CLASSES: readonly ["dark:hidden!", "hidden", "dark:block!", "text-xs", "text-muted-foreground", "text-center", "font-semibold", "underline"];
 interface BrandLogoProps {
   /** Rendered width in pixels; the height follows the image. */
   readonly width?: number | undefined;

package/dist/{brand-C45QBKX9.js → brand-B-t62NJB.js}

@@ -67,7 +67,7 @@ const BRAND_COMPONENT_CLASSES = [
 	"hidden",
 	"dark:block!",
 	"text-xs",
-	"text-gray-500",
+	"text-muted-foreground",
 	"text-center",
 	"font-semibold",
 	"underline"
@@ -138,7 +138,7 @@ const brandComponents = (brand, plugin = samvaBrandPlugin) => {
 		const links = footer.socialLinks ?? [];
 		if (links.length > 0) rows.push(row(links.flatMap((link, index) => [...index === 0 ? [] : [" · "], jsx("a", {
 			href: link.url,
-			className: "text-gray-500 underline",
+			className: "text-muted-foreground underline",
 			children: link.label
 		})])));
 		rows.push(row(unsubscribeLink(unsubscribeLabel, plugin), {
@@ -155,7 +155,7 @@ const brandComponents = (brand, plugin = samvaBrandPlugin) => {
 			[BRAND_FOOTER_MARKER]: true,
 			children: jsx("tbody", { children: jsx("tr", { children: jsx("td", {
 				align: "center",
-				className: classes("text-xs text-gray-500 text-center", className),
+				className: classes("text-xs text-muted-foreground text-center", className),
 				style: { padding: "32px 16px" },
 				children: jsx("table", {
 					role: "presentation",
@@ -179,7 +179,7 @@ const brandComponents = (brand, plugin = samvaBrandPlugin) => {
 */
 const unsubscribeLink = (label, plugin) => jsx("a", {
 	href: plugin.unsubscribeUrlPlaceholder,
-	className: "text-gray-500 underline",
+	className: "text-muted-foreground underline",
 	[UNSUBSCRIBE_LINK]: true,
 	children: label
 });

package/dist/brand.d.ts

@@ -1,5 +1,5 @@
 import { t as BrandPlugin } from "./brand-plugin-CHhcei-j.js";
-import { _ as EmailBrandSocialLink, a as assetUrl, b as renderedFooterMarkers, c as isExternalAsset, d as BrandFooterProps, f as BrandLogoProps, g as EmailBrandFooter, h as EmailBrandAssets, i as assetEntry, l as BRAND_COMPONENT_CLASSES, m as EmailBrandAddress, n as AssetEntry, o as checkAssetBase, p as EmailBrand, r as AssetManifest, s as isAssetPath, t as ASSET_CONTENT_TYPES, u as BrandComponents, v as RenderedFooterMarkers, x as withoutUnsubscribeRow, y as brandComponents } from "./assets-DCULM6QD.js";
+import { _ as EmailBrandSocialLink, a as assetUrl, b as renderedFooterMarkers, c as isExternalAsset, d as BrandFooterProps, f as BrandLogoProps, g as EmailBrandFooter, h as EmailBrandAssets, i as assetEntry, l as BRAND_COMPONENT_CLASSES, m as EmailBrandAddress, n as AssetEntry, o as checkAssetBase, p as EmailBrand, r as AssetManifest, s as isAssetPath, t as ASSET_CONTENT_TYPES, u as BrandComponents, v as RenderedFooterMarkers, x as withoutUnsubscribeRow, y as brandComponents } from "./assets-tISHaQNF.js";
 import { t as Diagnostic } from "./diagnostic-model-DxthUZBT.js";
 import { Result } from "better-result";
 //#region src/email/samva-brand-plugin.d.ts
@@ -29,8 +29,6 @@ interface BrandCss {
   readonly dark: Readonly<Record<string, string>>;
   readonly fontFaces: readonly BrandFontFace[];
 }
-/** The theme variable a dark-mode color lowers to: `--color-brand` → `--color-brand-dark`. */
-declare const darkVariableName: (property: string) => string;
 /** Parse brand theme CSS against the closed grammar above. */
 declare const parseBrandCss: (css: string) => Result<BrandCss, ReadonlyArray<Diagnostic>>;
 /**
@@ -39,9 +37,43 @@ declare const parseBrandCss: (css: string) => Result<BrandCss, ReadonlyArray<Dia
  * output always parses back to the same value.
  */
 declare const printBrandCss: (brand: BrandCss) => string;
-/** The brand color, and the text color that sits on it. */
-declare const BRAND_COLOR_VARIABLE = "--color-brand";
-declare const BRAND_FOREGROUND_VARIABLE = "--color-brand-foreground";
+/**
+ * The semantic color tokens, as Tailwind color names (`bg-card`,
+ * `text-primary-foreground`, `border-border`), each with the role a block uses
+ * it for. A block reads only these, so swapping the theme reskins it.
+ */
+declare const THEME_COLOR_ROLES: {
+  readonly background: "The page, behind everything.";
+  readonly foreground: "Text on the page.";
+  readonly card: "A surface that groups the message's content.";
+  readonly "card-foreground": "Text on a card.";
+  readonly primary: "The main action's fill (a button), and links.";
+  readonly "primary-foreground": "Text on a primary fill.";
+  readonly secondary: "A quieter action's fill.";
+  readonly "secondary-foreground": "Text on a secondary fill.";
+  readonly muted: "A subdued surface: a code block, a table header.";
+  readonly "muted-foreground": "Secondary text on the page, a card or a muted surface: labels, captions, the footer.";
+  readonly accent: "A highlighted surface: a callout, a selected row.";
+  readonly "accent-foreground": "Text on an accent surface.";
+  readonly border: "Rules, dividers and outlines.";
+};
+declare const THEME_COLORS: readonly (keyof typeof THEME_COLOR_ROLES)[];
+type ThemeColor = (typeof THEME_COLORS)[number];
+/**
+ * The non-color tokens: the corner radius (`rounded`; `rounded-sm` to `rounded-xl` follow it) and
+ * the body and heading families (`font-sans`, `font-heading`).
+ */
+declare const THEME_TOKENS: readonly ["--radius", "--font-sans", "--font-heading"];
+/**
+ * The theme every project compiles with, beneath its own: a neutral light and
+ * dark palette, an 8px radius and the system sans-serif stack. A project's
+ * `theme.css`, its imported stylesheets and its brand layer over it.
+ */
+declare const DEFAULT_THEME: BrandCss;
+/** `DEFAULT_THEME` as theme CSS. */
+declare const DEFAULT_THEME_CSS: string;
+/** The fills whose text color a brand may leave out: `--color-primary` and `--color-primary-foreground`, and so on. */
+declare const FILL_COLORS: readonly ["primary", "secondary", "accent"];
 /**
  * Black or white, whichever has the higher WCAG contrast ratio against
  * `color`. A translucent color is judged over white, the page an email sits on.
@@ -51,25 +83,16 @@ declare const BRAND_FOREGROUND_VARIABLE = "--color-brand-foreground";
  */
 declare const contrastForeground: (color: string) => "#000000" | "#ffffff" | undefined;
 /**
- * The text-on-brand colors a brand gets when it leaves them out: for the light
- * theme and, when the brand sets a dark-mode brand color, for dark mode. Each
- * is the `contrastForeground` of the brand color it sits on. A brand that sets
- * the foreground, or whose brand color does not evaluate, gets no default.
+ * The text colors a theme layer gets for the fills it sets without one: for
+ * each of `FILL_COLORS`, the `contrastForeground` of the fill, in light mode
+ * and, where the layer's dark-mode block sets the fill, in dark mode. A layer
+ * that sets the foreground, or whose fill does not evaluate, gets no default.
+ * Every build lowers each theme layer with these, so stored theme CSS never
+ * carries them.
  */
-declare const brandForegroundDefaults: (brand: BrandCss) => {
-  readonly light?: string | undefined;
-  readonly dark?: string | undefined;
+declare const foregroundDefaults: (light: Readonly<Record<string, string>>, dark: Readonly<Record<string, string>>) => {
+  readonly light: Readonly<Record<string, string>>;
+  readonly dark: Readonly<Record<string, string>>;
 };
-/**
- * A brand theme as flat theme variables, the way a build compiles it. Email
- * inlining resolves `var()` once, so a dark-mode `@theme` cannot switch a
- * value at run time; each dark color lowers to its `-dark` theme variable,
- * which `dark:` utilities read (`dark:bg-brand-dark`). A text-on-brand color
- * the brand leaves out is filled in by `brandForegroundDefaults`, so every
- * build compiles the same default and the stored CSS never carries it.
- */
-declare const brandThemeVariables: (brand: BrandCss) => Readonly<Record<string, string>>;
-/** The stylesheet Tailwind compiles for the theme's brand import: `brandThemeVariables` and the font faces. */
-declare const brandTailwindCss: (brand: BrandCss) => string;
 //#endregion
-export { ASSET_CONTENT_TYPES, AssetEntry, AssetManifest, BRAND_COLOR_VARIABLE, BRAND_COMPONENT_CLASSES, BRAND_FOREGROUND_VARIABLE, BrandComponents, BrandCss, BrandFontFace, BrandFooterProps, BrandLogoProps, type BrandPlugin, EmailBrand, EmailBrandAddress, EmailBrandAssets, EmailBrandFooter, EmailBrandSocialLink, RenderedFooterMarkers, assetEntry, assetUrl, brandComponents, brandForegroundDefaults, brandTailwindCss, brandThemeVariables, checkAssetBase, contrastForeground, darkVariableName, isAssetPath, isExternalAsset, parseBrandCss, printBrandCss, renderedFooterMarkers, samvaBrandPlugin, withoutUnsubscribeRow };
+export { ASSET_CONTENT_TYPES, AssetEntry, AssetManifest, BRAND_COMPONENT_CLASSES, BrandComponents, BrandCss, BrandFontFace, BrandFooterProps, BrandLogoProps, type BrandPlugin, DEFAULT_THEME, DEFAULT_THEME_CSS, EmailBrand, EmailBrandAddress, EmailBrandAssets, EmailBrandFooter, EmailBrandSocialLink, FILL_COLORS, RenderedFooterMarkers, THEME_COLORS, THEME_COLOR_ROLES, THEME_TOKENS, ThemeColor, assetEntry, assetUrl, brandComponents, checkAssetBase, contrastForeground, foregroundDefaults, isAssetPath, isExternalAsset, parseBrandCss, printBrandCss, renderedFooterMarkers, samvaBrandPlugin, withoutUnsubscribeRow };

package/dist/brand.js

@@ -1,4 +1,4 @@
 import { D as samvaBrandPlugin } from "./html-eOZfDwVf.js";
-import { a as brandThemeVariables, c as parseBrandCss, i as brandTailwindCss, l as printBrandCss, n as BRAND_FOREGROUND_VARIABLE, o as contrastForeground, r as brandForegroundDefaults, s as darkVariableName, t as BRAND_COLOR_VARIABLE } from "./theme-css-CEUrDpqq.js";
-import { a as ASSET_CONTENT_TYPES, c as checkAssetBase, i as withoutUnsubscribeRow, l as isAssetPath, n as brandComponents, o as assetEntry, r as renderedFooterMarkers, s as assetUrl, t as BRAND_COMPONENT_CLASSES, u as isExternalAsset } from "./brand-C45QBKX9.js";
-export { ASSET_CONTENT_TYPES, BRAND_COLOR_VARIABLE, BRAND_COMPONENT_CLASSES, BRAND_FOREGROUND_VARIABLE, assetEntry, assetUrl, brandComponents, brandForegroundDefaults, brandTailwindCss, brandThemeVariables, checkAssetBase, contrastForeground, darkVariableName, isAssetPath, isExternalAsset, parseBrandCss, printBrandCss, renderedFooterMarkers, samvaBrandPlugin, withoutUnsubscribeRow };
+import { a as THEME_COLOR_ROLES, c as foregroundDefaults, i as THEME_COLORS, l as parseBrandCss, n as DEFAULT_THEME_CSS, o as THEME_TOKENS, r as FILL_COLORS, s as contrastForeground, t as DEFAULT_THEME, u as printBrandCss } from "./theme-css-s9QwD5Ko.js";
+import { a as ASSET_CONTENT_TYPES, c as checkAssetBase, i as withoutUnsubscribeRow, l as isAssetPath, n as brandComponents, o as assetEntry, r as renderedFooterMarkers, s as assetUrl, t as BRAND_COMPONENT_CLASSES, u as isExternalAsset } from "./brand-B-t62NJB.js";
+export { ASSET_CONTENT_TYPES, BRAND_COMPONENT_CLASSES, DEFAULT_THEME, DEFAULT_THEME_CSS, FILL_COLORS, THEME_COLORS, THEME_COLOR_ROLES, THEME_TOKENS, assetEntry, assetUrl, brandComponents, checkAssetBase, contrastForeground, foregroundDefaults, isAssetPath, isExternalAsset, parseBrandCss, printBrandCss, renderedFooterMarkers, samvaBrandPlugin, withoutUnsubscribeRow };

package/dist/compiler.d.ts

@@ -1,8 +1,8 @@
 import { n as parseBrandSpecifier, t as BrandPlugin } from "./brand-plugin-CHhcei-j.js";
 import { a as TemplateDiagnostic, r as EmailDiagnostic } from "./diagnostics-CUYlQ_6x.js";
 import { r as EmailNode } from "./jsx-runtime-DC7xG0aA.js";
-import { n as AssetEntry, p as EmailBrand, u as BrandComponents } from "./assets-DCULM6QD.js";
-import { C as Compound, D as EmittedPosition, S as CompiledSelector, T as matchesSelector, _ as Specificity, b as parseStylesheet, ct as TemplateIr, g as CssRule, h as CssDeclaration, r as RenderedEmail, v as Stylesheet, w as classListOf, x as Ancestry, y as compileSelector } from "./render-C6OTH8BQ.js";
+import { n as AssetEntry, p as EmailBrand, u as BrandComponents } from "./assets-tISHaQNF.js";
+import { C as Compound, D as EmittedPosition, S as CompiledSelector, T as matchesSelector, _ as Specificity, b as parseStylesheet, ct as TemplateIr, g as CssRule, h as CssDeclaration, r as RenderedEmail, v as Stylesheet, w as classListOf, x as Ancestry, y as compileSelector } from "./render-C1X3S5or.js";
 import { a as TEMPLATE_NAME_PATTERN, n as EmailContent } from "./template-B-UDXK8a.js";
 import { caniemail } from "caniemail";
 //#region src/email/compatibility.d.ts
@@ -81,7 +81,7 @@ declare const finalizeValue: (value: string, variables: Readonly<Record<string,
 /** Media Queries Level 4 range syntax down to the `min-`/`max-` prefixes clients support. */
 declare const downlevelMediaQuery: (condition: string) => string;
 /** Render the rules that could not be inlined as one `<style>` body. */
-declare const renderHeadCss: (rules: readonly CssRule[], headAtRules: readonly string[], variables: Readonly<Record<string, string>>) => string;
+declare const renderHeadCss: (rules: readonly CssRule[], headAtRules: readonly string[], variables: Readonly<Record<string, string>>, darkVariables?: Readonly<Record<string, string>>) => string;
 //#endregion
 //#region src/email/css-color.d.ts
 /** A color in extended sRGB, alpha included, before clamping and gamma. */
@@ -101,15 +101,24 @@ declare const downlevelColors: (value: string) => string;
 //#region src/email/cascade.d.ts
 interface AppliedStyles {
   readonly tree: EmailNode;
-  /** Rules that could not be inlined, ready for a `<style>` element in `<head>`. */
+  /** Rules that could not be inlined, ready for a `<style>` element in `<head>` after `darkRules`. */
   readonly headCss: string;
+  /**
+   * A generated class for each distinct set of dark-mode declarations, mapped
+   * to those declarations. An element whose inlined styles read a color the
+   * theme's dark-mode block redefines carries the class.
+   */
+  readonly darkRules: ReadonlyMap<string, string>;
   /** Project `@font-face` rules, for a `<head>` style classic Outlook cannot see. */
   readonly fontFaceCss: string;
   readonly diagnostics: readonly EmailDiagnostic[];
 }
 /**
  * Resolve every stylesheet against the tree: inline what a client will honor on
- * the element, and keep the rest for `<head>`.
+ * the element, and keep the rest for `<head>`. Where the sheet has a dark-mode
+ * theme, an element whose inlined styles read a color it redefines also gets a
+ * generated class whose dark-mode rule restates those styles at their dark
+ * values.
  */
 declare const applyStylesheet: (root: EmailNode, sheet: Stylesheet, options?: {
   readonly knownClasses?: ReadonlySet<string>;
@@ -194,7 +203,10 @@ interface TransformOptions {
 }
 interface ProjectTransform {
   readonly assets: readonly AssetEntry[];
-  /** The compiled Tailwind sheet, when the project used any utility class. */
+  /**
+   * The compiled Tailwind sheet: the default theme, the primitives' rules, the project theme and
+   * the utilities the project uses. Without Tailwind, the default theme and the primitives' rules.
+   */
   readonly tailwindSheet: Stylesheet | undefined;
   /** Every project stylesheet, parsed, by path. */
   readonly stylesheets: ReadonlyMap<string, Stylesheet>;
@@ -215,6 +227,11 @@ declare const transformProject: (files: Readonly<Record<string, string | Uint8Ar
 interface RenderedBrandFooter {
   readonly html: string;
   readonly text: string;
+  /**
+   * The rules the footer needs in the message's `<head>`: its dark-mode colors and the
+   * `dark:` swap of the brand logo. Empty when it needs none.
+   */
+  readonly headCss: string;
 }
 /**
  * Render `BrandFooter` against a brand on its own, for the send path to