description: The theme JSON design system stored under ~/workspace/themes/, its schema, and how to generate or apply a theme.

Theme schema and generation / 主题模式（schema）与生成

A theme is a small JSON design system stored under ~/workspace/themes/. The artifact builder's
theme decision lives in /opt/hatch/skills/artifacts/pdf/references/visual.md; read this file when generating or applying
a theme.

主题是存储在 ~/workspace/themes/ 下的一个小型 JSON 设计系统。工件构建器的主题决策位于 /opt/hatch/skills/artifacts/pdf/references/visual.md；在生成或应用主题时阅读本文件。

Theme file schema / 主题文件模式

Each theme JSON has two blocks: ui (document styling) and visual (image-generation guidance). Example:

每个主题 JSON 包含两个块：ui（文档样式）和 visual（图像生成指引）。示例：

{
  "name": "Paper & Ink", "mode": "light",
  "ui": {
    "colors": { "bg": "#FAF9F6", "surface": "#F5F0EB", "text": "#1A1A1A", "accent": "#3D3229", "textMuted": "#8B7355", "danger": "#9B2C2C", "success": "#16A34A", "warning": "#D97706" },
    "font": "Georgia, 'Times New Roman', serif", "fontSans": "system-ui, sans-serif",
    "radius": { "card": "6px", "button": "4px" },
    "shadows": { "md": "0 1px 3px rgba(61,50,41,.08)" },
    "notes": "Editorial, bookish. Uppercase headers, thin dividers, generous whitespace."
  },
  "visual": {
    "style": "1970s vintage film photography", "mood": "warm, nostalgic",
    "lighting": "golden hour", "palette": "warm golds, sun-bleached pastels",
    "texture": "35mm film grain", "references": "Slim Aarons",
    "orientation": "landscape", "filter": "contrast(1.05) saturate(0.85) sepia(0.1)"
  }
}

`ui` block fields / `ui` 块字段

Field	Purpose
`colors`	Full palette: bg, surface, borders, text, accent, textMuted, and semantic colors (danger, success, warning)
`font` / `fontSans` / `fontMono`	Typography stacks for body, UI, and code
`fontWeight`	Weight mapping for headings, body, and labels
`radius`	Border-radius tokens per element type
`shadows`	Box-shadow tokens (or "none" for flat themes)
`notes`	Theme personality and special component patterns

字段	用途
`colors`	完整调色板：bg、surface、边框、text、accent、textMuted 以及语义色（danger、success、warning）
`font` / `fontSans` / `fontMono`	正文、UI 和代码的字体栈
`fontWeight`	标题、正文和标签的字重映射
`radius`	各元素类型的圆角令牌
`shadows`	盒阴影令牌（扁平主题用 "none"）
`notes`	主题个性与特殊组件样式

Maintain a 4.5:1 minimum contrast between text and background.

文字与背景之间保持最低 4.5:1 的对比度。

`visual` block fields / `visual` 块字段

Field	Purpose	Examples
`style`	Art direction	"3D Pixar render", "watercolor", "vintage film"
`mood`	Emotional tone	"cozy and warm", "dark and mysterious"
`lighting`	Light direction	"golden hour", "dramatic chiaroscuro"
`palette`	Image color guidance	"jewel tones", "neon on black"
`texture`	Surface quality	"clean digital", "film grain"
`references`	Style references	"Wes Anderson", "Studio Ghibli"
`orientation`	Default image orientation	"landscape", "square", "vertical"
`filter`	CSS filter applied to `<img>` tags	"contrast(1.05) sepia(0.1)" or "none"

字段	用途	示例
`style`	美术方向	"3D Pixar render"（3D 皮克斯渲染）、"watercolor"（水彩）、"vintage film"（复古胶片）
`mood`	情绪基调	"cozy and warm"（温馨暖意）、"dark and mysterious"（黑暗神秘）
`lighting`	光线方向	"golden hour"（黄金时刻）、"dramatic chiaroscuro"（戏剧性明暗对照）
`palette`	图像配色指引	"jewel tones"（宝石色）、"neon on black"（黑底霓虹）
`texture`	表面质感	"clean digital"（干净数字感）、"film grain"（胶片颗粒）
`references`	风格参照	"Wes Anderson"、"Studio Ghibli"
`orientation`	默认图像方向	"landscape"（横版）、"square"（方形）、"vertical"（竖版）
`filter`	应用于 `<img>` 标签的 CSS 滤镜	"contrast(1.05) sepia(0.1)" 或 "none"

Generating a theme / 生成主题

Infer the ui block: colors, fonts, and shapes matching the vibe. Ensure a 4.5:1 minimum contrast. Pick light or dark mode.
推断 ui 块：与整体气质匹配的颜色、字体和形状。确保最低 4.5:1 的对比度。选定浅色或深色模式。
Infer the visual block: art style, mood, references, CSS filter.
推断 visual 块：美术风格、情绪、风格参照、CSS 滤镜。
Save to ~/workspace/themes/<kebab-case-name>.json.
保存到 ~/workspace/themes/<kebab-case-name>.json。
Confirm: "I created 'Wes Anderson': pastel pinks, Futura, cinematic film stills. Want me to use this?"
确认："我创建了 'Wes Anderson' 主题：柔和粉色调、Futura 字体、电影剧照质感。需要我使用它吗？"

Capture the feel (color temperature, density, typography personality), not an exact layout clone.

捕捉的是感觉（色温、密度、排版个性），而不是对布局的精确克隆。

Applying a theme (builder side) / 应用主题（构建器侧）

Fonts render offline. Map every theme font to an installed local family (verify with fc-list) before using it in CSS. Do not rely on Google Fonts imports or Microsoft fonts; see /opt/hatch/skills/artifacts/pdf/references/workflow.md for reliable local families.
字体离线渲染。 在 CSS 中使用主题字体之前，先把每个字体映射到已安装的本地字族（用 fc-list 验证）。不要依赖 Google Fonts 导入或 Microsoft 字体；可靠的本地字族参见 /opt/hatch/skills/artifacts/pdf/references/workflow.md。
Imagery. When generating hero or illustrative imagery with media.generate_image, build prompts from the visual block (style, mood, lighting, palette, references), set output_dir to artifact_media_dir, and apply the theme's filter to the embedded images.
图像。 用 media.generate_image 生成主视觉或插图时，从 visual 块（style、mood、lighting、palette、references）构建提示词，把 output_dir 设为 artifact_media_dir，并对嵌入图像应用主题的 filter。