#!/usr/bin/env python3
"""Build a print-ready, on-brand flyer as one self-contained HTML file. Stdlib only.
The spec (see templates/flyer-spec.json) gives the content; a brand.json (the brand-kit
skill writes one) gives the logo, colours and fonts. Images are embedded as data URIs, so the
.html file is the whole flyer: open it and print, or save as PDF, at 100% scale.
Usage:
python3 build_flyer.py spec.json -o flyer.html [--brand brand.json] [--pdf flyer.pdf] [--png flyer.png]
--pdf and --png use a local Chrome or Chromium in headless mode when one is installed; without
one the script says so and the HTML is still the deliverable.
"""
import argparse
import base64
import html
import json
import mimetypes
import os
import re
import shutil
import subprocess
import sys
from pathlib import Path
SIZES = { # (width, height) in CSS units, portrait
"letter": ("8.5in", "11in"), "a4": ("210mm", "297mm"), "a5": ("148mm", "210mm"),
"square": ("1080px", "1080px"), "story": ("1080px", "1920px"),
}
PX = {"letter": (816, 1056), "a4": (794, 1123), "a5": (559, 794), "square": (1080, 1080), "story": (1080, 1920)}
LAYOUTS = ("hero", "split", "event", "minimal")
DEFAULTS = {"primary": "#1A2A6C", "secondary": "#4A5A8C", "accent": "#FDBB2D", "background": "#FFFFFF", "text": "#222222"}
WARNINGS = []
def warn(msg):
WARNINGS.append(msg)
print(f"WARN {msg}", file=sys.stderr)
def die(msg):
print(f"ERROR {msg}", file=sys.stderr)
sys.exit(1)
def lum(hex_str):
h = hex_str.lstrip("#")
def ch(v):
v = int(v, 16) / 255
return v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4
r, g, b = (ch(h[i:i + 2]) for i in (0, 2, 4))
return 0.2126 * r + 0.7152 * g + 0.0722 * b
def contrast(a, b):
la, lb = sorted((lum(a), lum(b)), reverse=True)
return (la + 0.05) / (lb + 0.05)
def ink_on(bg, text, light="#FFFFFF"):
"""The readable text colour on a filled band: white or the brand text colour, whichever
contrasts more — so a pale accent gets dark text instead of illegible white."""
return light if contrast(light, bg) >= contrast(text, bg) else text
def data_uri(path, label):
if not path:
return None
p = Path(path)
if not p.exists():
warn(f"{label} not found: {p} — the flyer is built without it")
return None
mime = mimetypes.guess_type(p.name)[0] or "application/octet-stream"
if not mime.startswith("image/"):
warn(f"{label} {p.name} is not an image ({mime})")
return None
return f"data:{mime};base64,{base64.b64encode(p.read_bytes()).decode()}"
def load_json(path):
try:
return json.loads(Path(path).read_text())
except (OSError, json.JSONDecodeError) as e:
die(f"cannot read {path}: {e}")
def resolve(base, ref):
return None if not ref else (Path(ref) if Path(ref).is_absolute() else (base / ref))
def font_stack(f, generic):
if not f:
return generic
fam = f.get("family") if isinstance(f, dict) else f
fb = (f.get("fallback") if isinstance(f, dict) else None) or generic
return f"'{fam}', {fb}" if fam else fb
def esc(s):
return html.escape(str(s or ""), quote=True)
def build(spec_path, out_path, brand_ref=None):
spec_path = Path(spec_path).resolve()
base = spec_path.parent
spec = load_json(spec_path)
brand, bbase = {}, base
ref = brand_ref or spec.get("brand")
if isinstance(ref, dict):
brand = ref
elif ref:
bp = resolve(base, ref) if not brand_ref else Path(ref).resolve()
if bp.exists():
brand, bbase = load_json(bp), bp.parent
else:
warn(f"brand file not found: {bp} — using default colours and no logo")
if not brand:
warn("no brand supplied — the flyer uses default colours. Run brand-kit, or pass --brand")
c = {**DEFAULTS, **{k: v for k, v in (brand.get("colors") or {}).items() if k in DEFAULTS and v},
**{k: v for k, v in (spec.get("colors") or {}).items() if k in DEFAULTS and v}}
for k, v in c.items():
if not re.match(r"^#[0-9A-Fa-f]{6}$", v):
die(f"colour {k} is {v!r}, not a 6-digit hex code")
if contrast(c["text"], c["background"]) < 4.5:
die(f"text on background contrast is {contrast(c['text'], c['background']):.2f}:1, below 4.5:1 — fix the brand colours")
on_primary, on_accent = ink_on(c["primary"], c["text"]), ink_on(c["accent"], c["text"])
fonts = brand.get("fonts") or {}
head_font, body_font = font_stack(fonts.get("heading"), "Georgia, serif"), font_stack(fonts.get("body"), "Helvetica, Arial, sans-serif")
logo = brand.get("logo") or {}
if isinstance(logo, str):
logo = {"primary": logo}
logo_light = data_uri(resolve(bbase, logo.get("primary")), "logo")
logo_dark = data_uri(resolve(bbase, logo.get("on_dark")), "on-dark logo") or logo_light
if not logo_light and not logo_dark:
warn("no logo — the brand name is set as text instead")
name = brand.get("name") or spec.get("name") or ""
size = str(spec.get("size", "letter")).lower()
if size not in SIZES:
warn(f"unknown size {size!r}; using letter")
size = "letter"
w, h = SIZES[size]
landscape = str(spec.get("orientation", "portrait")).lower() == "landscape"
if landscape:
w, h = h, w
layout = str(spec.get("layout", "hero")).lower()
if layout not in LAYOUTS:
warn(f"unknown layout {layout!r}; using hero")
layout = "hero"
headline = spec.get("headline") or die("spec needs a headline")
if len(headline.split()) > 10:
warn(f"headline is {len(headline.split())} words; ten or fewer read from across a room")
points = spec.get("points") or []
if len(points) > 4:
warn(f"{len(points)} points; a flyer carries four at most — the rest belong on the linked page")
body = spec.get("body") or ""
if len(body.split()) > 60:
warn(f"body is {len(body.split())} words; keep it under 60")
cta = spec.get("cta")
if isinstance(cta, list):
warn("more than one call to action; a flyer gets one — using the first")
cta = cta[0] if cta else None
if not cta:
warn("no call to action — what should a reader do next?")
img = spec.get("image") or {}
hero = data_uri(resolve(base, img.get("path")), "image") if isinstance(img, dict) else data_uri(resolve(base, img), "image")
if hero and isinstance(img, dict) and not img.get("alt"):
warn("image has no alt text")
qr = data_uri(resolve(base, spec.get("qr")), "QR code")
contact = {**(brand.get("contact") or {}), **(spec.get("contact") or {})}
footer = spec.get("footer") or (brand.get("legal") or {}).get("footer") or ""
details = spec.get("details") or []
def logo_img(dark):
src = logo_dark if dark else logo_light
return f'
' if src else f'{esc(name)}'
pts = "".join(f"{esc(p)}" for p in points[:4])
det = "".join(f'{esc(d.get("label"))}{esc(d.get("value"))}
' for d in details)
cta_html = (f'{esc(cta.get("text"))}'
+ (f'
{esc(cta.get("url"))}' if cta.get("url") else "")
+ (f'
' if qr else "")
+ "
") if cta else ""
contact_line = " · ".join(esc(v) for k, v in contact.items() if v and k in ("website", "email", "phone", "address"))
img_html = f'' if hero else ""
if layout == "split":
main = f"""{img_html or f'
{logo_img(True)}
'}
{'' if not img_html else logo_img(False)}
{esc(headline)}
{f'
{esc(spec.get("subhead"))}
' if spec.get("subhead") else ''}
{f'
{esc(body)}
' if body else ''}
{det}
{cta_html}
{esc(first.get("label", ""))}{esc(first.get("value", ""))}
{esc(headline)}
{f'
{esc(spec.get("subhead"))}
' if spec.get("subhead") else ''}
{f'
{esc(body)}
' if body else ''}
{"".join(f'
{esc(d.get("label"))}{esc(d.get("value"))}
' for d in details[1:])}
{cta_html}
{logo_img(False)}
{esc(headline)}
{f'
{esc(spec.get("subhead"))}
' if spec.get("subhead") else ''}{img_html}
{f'
{esc(body)}
' if body else ''}
{det}
{cta_html}
{esc(headline)}
{f'
{esc(spec.get("subhead"))}
' if spec.get("subhead") else ''}
{f'
{esc(body)}
' if body else ''}
{det}
{cta_html}