发布公告(自动布局)

一款无需手动测量绝对坐标的发布卡片。标题列与特性行均采用自动布局分组,所有颜色与字体尺寸均提取至 theme 块中统一定义,因此修改文案或品牌视觉时无需重新计算任何排版位置。
安装 uv 并克隆代码仓库即可运行此示例:
git clone https://github.com/sjquant/quickthumb
cd quickthumb
uv run --extra svg python examples/launch_announcement.py
该脚本将写入 examples/launch_announcement.png,并覆盖同名旧文件。
其中的星芒装饰为 SVG 文件,因此需要安装 svg 额外依赖。
构成方式
- 主题设计变量(Tokens)。 颜色和尺寸在
theme下统一定义一次,并通过"$theme.colors.blue"或"$theme.sizes.title"引用。当整个属性值完全由变量构成时,会保留原始 JSON 数据类型,因此"$theme.sizes.title"会被解析为数字116,而非字符串。 - 文本使用列式分组。 版本标签、主标题和副标题作为同一个
group的子图层,设置"direction": "column"与"gap": 22。仅需将整个容器定位一次(["7%", "44%"]),子元素无需指定position。即便副标题增加一行文本,整个列也会自动重新流动排版。 - 特性清单使用行式分组。 从“01 GROUPS”到“04 DIAGNOSTICS”是第二个分组,设置
"direction": "row",因此即便修改其中某项的名称,它们之间的间距也能保持严格均匀。 - 使用基础形状构建图形元素。 圆形、四个色条和星形分别使用常规的
ellipse、rectangle和star形状。星芒装饰引用assets/images/spark.svg,并通过Filter(saturation=0, brightness=3)滤镜将其调白。 - 渲染前自动诊断。 脚本在执行渲染前调用
canvas.diagnose()并打印所有检测结果。在终端中也可通过uv run --extra cli quickthumb lint examples/launch_announcement.json执行相同的静态排版检查。
规范定义
{
"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
}
]
}
]
}
脚本代码
"""
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}")