@samva/markup 0.1.0

package/generated/sml-email-agent-contract.json

@@ -0,0 +1,790 @@
+{
+  "version": "0.0.0",
+  "qualityBar": [
+    "valid Samva compile",
+    "visually faithful light render",
+    "visually faithful dark render when source has dark mode",
+    "editor-friendly classes and semantic tokens",
+    "no raw HTML tags",
+    "reusable placeholders and template abstractions",
+    "repair compile diagnostics before claiming done"
+  ],
+  "primitives": [
+    {
+      "channel": "email",
+      "tag": "Email",
+      "attributes": {
+        "lang": {
+          "type": "string",
+          "required": false
+        },
+        "dir": {
+          "type": "string",
+          "required": false
+        },
+        "width": {
+          "type": "number",
+          "required": false,
+          "min": 1,
+          "max": 10000
+        },
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "Subject?, Preview?, blocks",
+      "description": "Email document root. Exactly one root per template; wraps the whole message."
+    },
+    {
+      "channel": "email",
+      "tag": "Subject",
+      "attributes": {},
+      "children": "text, {{vars}}",
+      "description": "Email subject line. Text and interpolations only; must appear before body blocks."
+    },
+    {
+      "channel": "email",
+      "tag": "Preview",
+      "attributes": {},
+      "children": "text, {{vars}}",
+      "description": "Inbox preview text (hidden in the body). Text and interpolations only."
+    },
+    {
+      "channel": "email",
+      "tag": "Container",
+      "attributes": {
+        "class": {
+          "type": "string",
+          "required": false
+        },
+        "backgroundImage": {
+          "type": "string",
+          "required": false
+        },
+        "backgroundPosition": {
+          "type": "string",
+          "required": false,
+          "values": ["center", "top", "bottom"]
+        },
+        "backgroundSize": {
+          "type": "string",
+          "required": false,
+          "values": ["cover", "contain", "auto"]
+        }
+      },
+      "children": "blocks",
+      "description": "Centered 600px max-width wrapper. Compiles to a table on the outlook-safe base."
+    },
+    {
+      "channel": "email",
+      "tag": "Section",
+      "attributes": {
+        "class": {
+          "type": "string",
+          "required": false
+        },
+        "backgroundImage": {
+          "type": "string",
+          "required": false
+        },
+        "backgroundPosition": {
+          "type": "string",
+          "required": false,
+          "values": ["center", "top", "bottom"]
+        },
+        "backgroundSize": {
+          "type": "string",
+          "required": false,
+          "values": ["cover", "contain", "auto"]
+        }
+      },
+      "children": "blocks",
+      "description": "Full-width band. Padding splits onto the inner cell for Outlook/Klaviyo."
+    },
+    {
+      "channel": "email",
+      "tag": "Row",
+      "attributes": {
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "Column+",
+      "description": "Horizontal layout. Children must be <Column>. Use instead of flex/grid."
+    },
+    {
+      "channel": "email",
+      "tag": "Column",
+      "attributes": {
+        "class": {
+          "type": "string",
+          "required": false
+        },
+        "width": {
+          "type": "string",
+          "required": false
+        },
+        "valign": {
+          "type": "string",
+          "required": false,
+          "values": ["top", "middle", "bottom"]
+        }
+      },
+      "children": "blocks",
+      "description": "A cell inside a <Row>. `width` is an HTML width (e.g. \"50%\", \"300\")."
+    },
+    {
+      "channel": "email",
+      "tag": "Heading",
+      "attributes": {
+        "level": {
+          "type": "number",
+          "required": false,
+          "min": 1,
+          "max": 6
+        },
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "text, {{vars}}, strong, em, a",
+      "description": "Renders <h1>-<h6> by `level` (default 1)."
+    },
+    {
+      "channel": "email",
+      "tag": "Text",
+      "attributes": {
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "text, {{vars}}, strong, em, a",
+      "description": "Paragraph. Ships sane font-size/line-height/margin defaults."
+    },
+    {
+      "channel": "email",
+      "tag": "Button",
+      "attributes": {
+        "href": {
+          "type": "string",
+          "required": true
+        },
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "text, {{vars}}, strong, em",
+      "description": "Link styled as a button. Set padding via classes; the compiler injects the Outlook mso hack."
+    },
+    {
+      "channel": "email",
+      "tag": "Image",
+      "attributes": {
+        "src": {
+          "type": "string",
+          "required": true
+        },
+        "alt": {
+          "type": "string",
+          "required": false
+        },
+        "width": {
+          "type": "number",
+          "required": false,
+          "min": 0,
+          "max": 10000
+        },
+        "height": {
+          "type": "number",
+          "required": false,
+          "min": 0,
+          "max": 10000
+        },
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "Source?",
+      "description": "Responsive image. Always set `alt` for accessibility. Add a <Source scheme=\"dark\"> child to swap the asset in dark mode."
+    },
+    {
+      "channel": "email",
+      "tag": "Source",
+      "attributes": {
+        "scheme": {
+          "type": "string",
+          "required": true,
+          "values": ["dark"]
+        },
+        "src": {
+          "type": "string",
+          "required": true
+        }
+      },
+      "children": "void",
+      "description": "Image source variant. Inside <Image>, `scheme=\"dark\"` swaps the asset when dark-mode media queries are honored."
+    },
+    {
+      "channel": "email",
+      "tag": "Divider",
+      "attributes": {
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "void",
+      "description": "Horizontal rule (border-top)."
+    },
+    {
+      "channel": "email",
+      "tag": "Spacer",
+      "attributes": {
+        "height": {
+          "type": "number",
+          "required": true,
+          "min": 1,
+          "max": 2000
+        }
+      },
+      "children": "void",
+      "description": "Vertical gap of `height` px."
+    },
+    {
+      "channel": "email",
+      "tag": "List",
+      "attributes": {
+        "type": {
+          "type": "string",
+          "required": false,
+          "values": ["unordered", "ordered"]
+        },
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "ListItem+",
+      "description": "Bulleted or numbered list. `type` is \"unordered\" (default) or \"ordered\". Children must be <ListItem>."
+    },
+    {
+      "channel": "email",
+      "tag": "ListItem",
+      "attributes": {
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "text, {{vars}}, strong, em, a",
+      "description": "A single list row. Inline content only (text, {{vars}}, strong/em/a)."
+    },
+    {
+      "channel": "email",
+      "tag": "If",
+      "attributes": {
+        "test": {
+          "type": "string",
+          "required": true
+        }
+      },
+      "children": "blocks, Else?",
+      "description": "Send-time conditional block. `test` is a predicate over declared variables (see \"Send-time conditionals\" below). Content: blocks, then an optional trailing <Else>."
+    },
+    {
+      "channel": "email",
+      "tag": "Else",
+      "attributes": {},
+      "children": "blocks",
+      "description": "The false branch of an <If>. Valid only as the last direct child of <If>."
+    },
+    {
+      "channel": "email",
+      "tag": "a",
+      "attributes": {
+        "href": {
+          "type": "string",
+          "required": true
+        },
+        "class": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "children": "text, {{vars}}, strong, em",
+      "description": "Inline link. It has deterministic theme-brand color and underline defaults; use safe classes to override either."
+    },
+    {
+      "channel": "email",
+      "tag": "strong",
+      "attributes": {},
+      "children": "text, {{vars}}, strong, em",
+      "description": "Bold inline text."
+    },
+    {
+      "channel": "email",
+      "tag": "em",
+      "attributes": {},
+      "children": "text, {{vars}}, strong, em",
+      "description": "Italic inline text."
+    }
+  ],
+  "utilityFamilies": [
+    {
+      "root": "p",
+      "syntax": "p-*",
+      "descriptions": ["Padding on all sides (p-4 = 16px). Compiles onto table cells for Outlook."]
+    },
+    {
+      "root": "px",
+      "syntax": "px-*",
+      "descriptions": ["Horizontal padding."]
+    },
+    {
+      "root": "py",
+      "syntax": "py-*",
+      "descriptions": ["Vertical padding."]
+    },
+    {
+      "root": "pt",
+      "syntax": "pt-*",
+      "descriptions": ["Top padding."]
+    },
+    {
+      "root": "pr",
+      "syntax": "pr-*",
+      "descriptions": ["Right padding."]
+    },
+    {
+      "root": "pb",
+      "syntax": "pb-*",
+      "descriptions": ["Bottom padding."]
+    },
+    {
+      "root": "pl",
+      "syntax": "pl-*",
+      "descriptions": ["Left padding."]
+    },
+    {
+      "root": "m",
+      "syntax": "m-*",
+      "descriptions": [
+        "Margin on all sides. Warn tier — some clients strip margins. (warn: some clients strip it)"
+      ]
+    },
+    {
+      "root": "mx",
+      "syntax": "mx-*",
+      "descriptions": [
+        "Horizontal margin; mx-auto centers block elements. (warn: some clients strip it)"
+      ]
+    },
+    {
+      "root": "my",
+      "syntax": "my-*",
+      "descriptions": ["Vertical margin. (warn: some clients strip it)"]
+    },
+    {
+      "root": "mt",
+      "syntax": "mt-*",
+      "descriptions": ["Top margin. (warn: some clients strip it)"]
+    },
+    {
+      "root": "mr",
+      "syntax": "mr-*",
+      "descriptions": ["Right margin. (warn: some clients strip it)"]
+    },
+    {
+      "root": "mb",
+      "syntax": "mb-*",
+      "descriptions": ["Bottom margin. (warn: some clients strip it)"]
+    },
+    {
+      "root": "ml",
+      "syntax": "ml-*",
+      "descriptions": ["Left margin. (warn: some clients strip it)"]
+    },
+    {
+      "root": "w",
+      "syntax": "w-*",
+      "descriptions": ["Width from the spacing scale (w-32 = 128px), w-full, or w-[600px]/w-[50%]."]
+    },
+    {
+      "root": "max-w",
+      "syntax": "max-w-*",
+      "descriptions": ["Max width from the container scale (max-w-lg = 512px) or max-w-[600px]."]
+    },
+    {
+      "root": "h",
+      "syntax": "h-*",
+      "descriptions": ["Height from the spacing scale (h-12 = 48px) or h-[80px]."]
+    },
+    {
+      "root": "text",
+      "syntax": "text-*",
+      "descriptions": [
+        "Font size with paired line-height (text-sm = 14px/20px) or bounded px value (text-[15px] = 15px/22.5px). Put an explicit leading-* after it to override line-height.",
+        "Text alignment: text-left, text-center, text-right, text-justify.",
+        "Text color from the palette (text-gray-700) or text-[#374151]."
+      ]
+    },
+    {
+      "root": "leading",
+      "syntax": "leading-*",
+      "descriptions": [
+        "Line height: named ratios (leading-relaxed) or spacing steps (leading-6 = 24px)."
+      ]
+    },
+    {
+      "root": "font",
+      "syntax": "font-*",
+      "descriptions": [
+        "Font weight: font-normal, font-medium, font-semibold, font-bold, ...",
+        "Font stack: font-sans, font-serif, font-mono."
+      ]
+    },
+    {
+      "root": "tracking",
+      "syntax": "tracking-*",
+      "descriptions": [
+        "Letter spacing: tracking-tighter … tracking-widest (em-based; inlines fine in Outlook). Pair tracking-wide/wider with uppercase for eyebrows."
+      ]
+    },
+    {
+      "root": "uppercase",
+      "syntax": "uppercase",
+      "descriptions": ["Uppercase text transform."]
+    },
+    {
+      "root": "underline",
+      "syntax": "underline",
+      "descriptions": ["Underlined text."]
+    },
+    {
+      "root": "no-underline",
+      "syntax": "no-underline",
+      "descriptions": [
+        "Removes the underline (links render underlined by default in most clients)."
+      ]
+    },
+    {
+      "root": "bg",
+      "syntax": "bg-*",
+      "descriptions": ["Background color from the palette (bg-white, bg-blue-600) or bg-[#0088cc]."]
+    },
+    {
+      "root": "bg-gradient",
+      "syntax": "bg-gradient-*",
+      "descriptions": [
+        "Linear gradient background for hero sections: bg-gradient-to-b/t/l/r with from-{color} and to-{color}. Modern base compiles a CSS linear-gradient (plus a solid from-color fallback); the outlook-safe base degrades to the solid from-color — Outlook for Windows never renders the gradient."
+      ]
+    },
+    {
+      "root": "from",
+      "syntax": "from-*",
+      "descriptions": [
+        "Gradient start color (from-indigo-600). Doubles as the solid fallback color on clients without gradient support (Outlook for Windows)."
+      ]
+    },
+    {
+      "root": "to",
+      "syntax": "to-*",
+      "descriptions": ["Gradient end color (to-purple-600)."]
+    },
+    {
+      "root": "border",
+      "syntax": "border-*",
+      "descriptions": [
+        "Solid border width: border (1px), border-2, border-0.",
+        "Border color from the palette (border-gray-200)."
+      ]
+    },
+    {
+      "root": "rounded",
+      "syntax": "rounded-*",
+      "descriptions": [
+        "Border radius (rounded-md = 6px). Ignored by Outlook for Windows — buttons degrade to square corners."
+      ]
+    },
+    {
+      "root": "rounded-t",
+      "syntax": "rounded-t-*",
+      "descriptions": [
+        "Top border radius for card/header blocks (rounded-t-lg). Degrades to square corners in Outlook for Windows."
+      ]
+    },
+    {
+      "root": "rounded-r",
+      "syntax": "rounded-r-*",
+      "descriptions": [
+        "Right-side border radius (rounded-r-lg). Degrades to square corners in Outlook for Windows."
+      ]
+    },
+    {
+      "root": "rounded-b",
+      "syntax": "rounded-b-*",
+      "descriptions": [
+        "Bottom border radius for card/footer blocks (rounded-b-lg). Degrades to square corners in Outlook for Windows."
+      ]
+    },
+    {
+      "root": "rounded-l",
+      "syntax": "rounded-l-*",
+      "descriptions": [
+        "Left-side border radius (rounded-l-lg). Degrades to square corners in Outlook for Windows."
+      ]
+    },
+    {
+      "root": "block",
+      "syntax": "block",
+      "descriptions": ["display: block."]
+    },
+    {
+      "root": "inline-block",
+      "syntax": "inline-block",
+      "descriptions": ["display: inline-block."]
+    },
+    {
+      "root": "hidden",
+      "syntax": "hidden",
+      "descriptions": ["display: none. Pair with sm:block for mobile-only content."]
+    }
+  ],
+  "forbiddenUtilities": [
+    {
+      "match": "flex",
+      "message": "display:flex is unsupported in Outlook for Windows (Word engine) — use <Row>/<Column>"
+    },
+    {
+      "match": "inline-flex",
+      "message": "display:inline-flex is unsupported in Outlook for Windows — use <Row>/<Column>"
+    },
+    {
+      "match": "grid",
+      "message": "display:grid is unsupported in Outlook for Windows and Gmail — use <Row>/<Column>"
+    },
+    {
+      "match": "inline-grid",
+      "message": "display:inline-grid is unsupported in Outlook for Windows — use <Row>/<Column>"
+    },
+    {
+      "match": "gap-",
+      "message": "gap requires flex/grid, unsupported in Outlook for Windows — use padding on <Column>"
+    },
+    {
+      "match": "space-",
+      "message": "space-* margins require selectors Gmail strips — use padding or <Spacer>"
+    },
+    {
+      "match": "items-",
+      "message": "flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column>"
+    },
+    {
+      "match": "justify-",
+      "message": "flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column> and text-center"
+    },
+    {
+      "match": "self-",
+      "message": "flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column>"
+    },
+    {
+      "match": "content-",
+      "message": "flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column>"
+    },
+    {
+      "match": "order-",
+      "message": "flex order is unsupported in Outlook for Windows — reorder the source instead"
+    },
+    {
+      "match": "absolute",
+      "message": "CSS position is ignored by Gmail and Outlook — use nested <Section>s"
+    },
+    {
+      "match": "relative",
+      "message": "CSS position is ignored by Gmail and Outlook — use nested <Section>s"
+    },
+    {
+      "match": "fixed",
+      "message": "CSS position is ignored by Gmail and Outlook — use nested <Section>s"
+    },
+    {
+      "match": "sticky",
+      "message": "CSS position is ignored by Gmail and Outlook — use nested <Section>s"
+    },
+    {
+      "match": "static",
+      "message": "CSS position is ignored by Gmail and Outlook — remove it"
+    },
+    {
+      "match": "inset-",
+      "message": "position offsets are ignored by Gmail and Outlook — use padding"
+    },
+    {
+      "match": "top-",
+      "message": "position offsets are ignored by Gmail and Outlook — use padding"
+    },
+    {
+      "match": "right-",
+      "message": "position offsets are ignored by Gmail and Outlook — use padding"
+    },
+    {
+      "match": "bottom-",
+      "message": "position offsets are ignored by Gmail and Outlook — use padding"
+    },
+    {
+      "match": "left-",
+      "message": "position offsets are ignored by Gmail and Outlook — use padding"
+    },
+    {
+      "match": "z-",
+      "message": "z-index is ignored by Gmail and Outlook — remove it"
+    },
+    {
+      "match": "float-",
+      "message": "float is unreliable across email clients — use <Row>/<Column>"
+    },
+    {
+      "match": "shadow",
+      "message": "box-shadow is unsupported in Outlook for Windows and Gmail — use a border instead"
+    },
+    {
+      "match": "shadow-",
+      "message": "box-shadow is unsupported in Outlook for Windows and Gmail — use a border instead"
+    },
+    {
+      "match": "opacity-",
+      "message": "opacity is unsupported in Outlook for Windows — bake the tint into the color"
+    },
+    {
+      "match": "transform",
+      "message": "CSS transforms are unsupported in email clients — remove them"
+    },
+    {
+      "match": "rotate-",
+      "message": "CSS transforms are unsupported in email clients — remove them"
+    },
+    {
+      "match": "scale-",
+      "message": "CSS transforms are unsupported in email clients — remove them"
+    },
+    {
+      "match": "translate-",
+      "message": "CSS transforms are unsupported in email clients — remove them"
+    },
+    {
+      "match": "skew-",
+      "message": "CSS transforms are unsupported in email clients — remove them"
+    },
+    {
+      "match": "transition",
+      "message": "transitions don't run in email — remove them"
+    },
+    {
+      "match": "transition-",
+      "message": "transitions don't run in email — remove them"
+    },
+    {
+      "match": "duration-",
+      "message": "transitions don't run in email — remove them"
+    },
+    {
+      "match": "animate-",
+      "message": "animations don't run in email — remove them"
+    },
+    {
+      "match": "blur-",
+      "message": "CSS filters are unsupported in most email clients — remove them"
+    },
+    {
+      "match": "brightness-",
+      "message": "CSS filters are unsupported in most email clients — remove them"
+    },
+    {
+      "match": "grayscale",
+      "message": "CSS filters are unsupported in most email clients — remove them"
+    },
+    {
+      "match": "grayscale-",
+      "message": "CSS filters are unsupported in most email clients — remove them"
+    },
+    {
+      "match": "truncate",
+      "message": "text truncation is unsupported in Outlook for Windows — shorten the copy"
+    },
+    {
+      "match": "line-clamp-",
+      "message": "line clamping is unsupported in email clients — shorten the copy"
+    },
+    {
+      "match": "aspect-",
+      "message": "aspect-ratio is unsupported in Outlook and Gmail — set width/height on <Image>"
+    },
+    {
+      "match": "overflow-",
+      "message": "overflow is unreliable across email clients — restructure the layout"
+    }
+  ],
+  "repairExamples": [
+    {
+      "from": "flex gap-4",
+      "to": "<Row><Column>...</Column><Column>...</Column></Row>",
+      "reason": "Email layout must use table-backed Row/Column primitives."
+    },
+    {
+      "from": "md:text-lg",
+      "to": "sm:text-lg",
+      "reason": "Only sm: responsive enhancement is supported."
+    },
+    {
+      "from": "bg-[var(--brand)]",
+      "to": "bg-brand or bg-[#4f46e5]",
+      "reason": "Compiled email has no CSS variables; use a token or literal hex."
+    },
+    {
+      "from": "font-[650]",
+      "to": "font-semibold",
+      "reason": "Use the supported named font-weight utilities instead of arbitrary weights."
+    }
+  ],
+  "recipes": [
+    {
+      "name": "security-notice",
+      "structure": ["Preview", "Container", "Heading", "Text paragraphs", "Button", "Footer Text"],
+      "guidance": "Dense, direct copy; strong contrast; explicit dark background/text classes."
+    },
+    {
+      "name": "product-update",
+      "structure": ["Preview", "Container", "Heading", "Section rows", "CTA Button", "Footer"],
+      "guidance": "Use cards/sections, short headings, and semantic brand tokens."
+    },
+    {
+      "name": "receipt-invoice",
+      "structure": [
+        "Preview",
+        "Container",
+        "Heading",
+        "Row/Column line items",
+        "Divider",
+        "total row"
+      ],
+      "guidance": "Prefer table-backed Row/Column blocks and right-aligned totals."
+    },
+    {
+      "name": "digest",
+      "structure": [
+        "Preview",
+        "Container",
+        "Heading",
+        "repeated Section/Text/Button rows",
+        "Footer"
+      ],
+      "guidance": "Keep repeated rows compact; use Divider between entries."
+    }
+  ]
+}