Launch Announcement (Auto Layout)

A release card whose text has no hand-placed coordinates. The headline column
and the feature row are auto-layout groups, and every color and font size
comes from a theme block, so changing the copy or the brand doesn't mean
re-measuring anything.
Install uv and clone the repository to run this example:
git clone https://github.com/sjquant/quickthumb
cd quickthumb
uv run --extra svg python examples/launch_announcement.py
The script writes examples/launch_announcement.png, replacing an existing file with that name.
The svg extra is needed for the sparkle, which is an SVG file.
How it's built
- Theme tokens. Colors and sizes are defined once under
themeand used as"$theme.colors.blue"or"$theme.sizes.title". A token that is the whole value keeps its JSON type, so"$theme.sizes.title"becomes the number116, not a string. - A column group for the text. The release label, headline, and subtitle
are children of one
groupwith"direction": "column"and"gap": 22. The group is placed once, at["7%", "44%"]; the children have noposition. Add a line to the subtitle and the column re-flows around it. - A row group for the features. "01 GROUPS" through "04 DIAGNOSTICS" are a
second group with
"direction": "row", so the spacing between them stays even when you rename one. - Simple shapes for the art. The circle, the four bars, and the star are
ordinary
ellipse,rectangle, andstarshapes. The sparkle isassets/images/spark.svg, turned white withFilter(saturation=0, brightness=3). - Checked before rendering. The script calls
canvas.diagnose()and prints any findings before it renders. The same check is available from the terminal asuv run --extra cli quickthumb lint examples/launch_announcement.json.
The spec
{
"kind": "canvas",
"width": 1280,
"height": 720,
"theme": {
"colors": {
"paper": "#F5F5F7",
"ink": "#1D1D1F",
"blue": "#0066CC",
"muted": "#515154",
"rule": "#1D1D1F26"
},
"sizes": {
"title": 116,
"subtitle": 28,
"meta": 18,
"chip": 18
}
},
"layers": [
{
"type": "background",
"color": "$theme.colors.paper",
"effects": [
{ "type": "grain", "intensity": 0.006, "monochrome": true, "seed": 7 }
]
},
{
"type": "shape",
"shape": "ellipse",
"position": ["94%", "50%"],
"width": 460,
"height": 460,
"color": "$theme.colors.blue",
"align": "center"
},
{
"type": "shape",
"shape": "rectangle",
"position": ["82%", "35%"],
"width": 170,
"height": 12,
"color": "$theme.colors.paper"
},
{
"type": "shape",
"shape": "rectangle",
"position": ["82%", "43%"],
"width": 112,
"height": 6,
"color": "$theme.colors.paper"
},
{
"type": "shape",
"shape": "rectangle",
"position": ["82%", "51%"],
"width": 214,
"height": 6,
"color": "$theme.colors.paper"
},
{
"type": "shape",
"shape": "rectangle",
"position": ["82%", "59%"],
"width": 142,
"height": 6,
"color": "#FFFFFFB3"
},
{
"type": "shape",
"shape": "rectangle",
"position": ["80.5%", "32%"],
"width": 1,
"height": 252,
"color": "#FFFFFF80"
},
{
"type": "svg",
"path": "assets/images/spark.svg",
"position": ["80.6%", "35.5%"],
"width": 16,
"align": "center",
"effects": [{ "type": "filter", "saturation": 0.0, "brightness": 3.0 }]
},
{
"type": "shape",
"shape": "star",
"position": ["80.6%", "59.5%"],
"width": 16,
"height": 16,
"color": "$theme.colors.paper",
"align": "center",
"star_points": 5,
"inner_radius": 0.42
},
{
"type": "group",
"direction": "column",
"gap": 22,
"position": ["7%", "44%"],
"align": ["left", "middle"],
"children": [
{
"type": "text",
"content": "QUICKTHUMB 0.5 / RELEASE",
"size": "$theme.sizes.meta",
"color": "$theme.colors.muted",
"weight": 700,
"letter_spacing": 3,
"align": "left"
},
{
"type": "text",
"content": [
{ "text": "Layouts that\n", "color": "$theme.colors.ink", "weight": 700 },
{ "text": "build themselves.", "color": "$theme.colors.blue", "weight": 700 }
],
"size": "$theme.sizes.title",
"color": "$theme.colors.ink",
"weight": 700,
"line_height": 1.02,
"letter_spacing": -3,
"align": "left"
},
{
"type": "text",
"content": "Auto-layout groups, theme tokens, and built-in lint —\nno pixel coordinates required.",
"size": "$theme.sizes.subtitle",
"color": "$theme.colors.muted",
"line_height": 1.35,
"align": "left"
}
]
},
{
"type": "shape",
"shape": "rectangle",
"position": ["7%", "83%"],
"width": 860,
"height": 1,
"color": "$theme.colors.rule"
},
{
"type": "group",
"direction": "row",
"gap": 54,
"position": ["7%", "88%"],
"align": ["left", "middle"],
"children": [
{
"type": "text",
"content": "01 GROUPS",
"size": "$theme.sizes.chip",
"color": "$theme.colors.ink",
"weight": 700,
"letter_spacing": 1
},
{
"type": "text",
"content": "02 TOKENS",
"size": "$theme.sizes.chip",
"color": "$theme.colors.ink",
"weight": 700,
"letter_spacing": 1
},
{
"type": "text",
"content": "03 SVG",
"size": "$theme.sizes.chip",
"color": "$theme.colors.ink",
"weight": 700,
"letter_spacing": 1
},
{
"type": "text",
"content": "04 DIAGNOSTICS",
"size": "$theme.sizes.chip",
"color": "$theme.colors.ink",
"weight": 700,
"letter_spacing": 1
}
]
}
]
}
The script
"""
JSON-first launch announcement card.
Exercises the quickthumb 0.5 feature set in a single themed spec:
- A top-level `theme` block with `$theme.*` token references across layers
- Auto-layout `group` layers for the headline column and feature row — no
hand-placed coordinates inside either text group
- `star` shape primitives and decorative `svg` layers
- Film grain on the base background
- `canvas.diagnose()` before rendering, mirroring `quickthumb lint`
"""
import os
from quickthumb import Canvas
FILE_DIR = os.path.dirname(__file__)
REPO_DIR = os.path.abspath(os.path.join(FILE_DIR, ".."))
SPEC_PATH = os.path.join(FILE_DIR, "launch_announcement.json")
OUTPUT_PATH = os.path.join(FILE_DIR, "launch_announcement.png")
os.environ["QUICKTHUMB_FONT_DIR"] = os.path.join(REPO_DIR, "assets", "fonts")
os.environ["QUICKTHUMB_DEFAULT_FONT"] = "Roboto"
with open(SPEC_PATH, encoding="utf-8") as f:
json_spec = f.read()
previous_cwd = os.getcwd()
try:
# The checked-in JSON spec uses repo-relative asset paths to stay easy to read.
os.chdir(REPO_DIR)
canvas = Canvas.from_json(json_spec)
findings = canvas.diagnose().findings
for finding in findings:
print(
f"[{finding.severity}] layer {finding.layer_index}: {finding.code} — {finding.message}"
)
if not findings:
print("✓ diagnose(): no layout or legibility issues")
canvas.render(OUTPUT_PATH)
finally:
os.chdir(previous_cwd)
print(f"✓ Launch announcement card created: {OUTPUT_PATH}")
print(f" Spec source: {SPEC_PATH}")