@hybridlabor-api/aos 4.6.6 → 4.7.1

package/skills/global_config/editable-design/references/editor-pitfalls.md

@@ -0,0 +1,70 @@
+# 已知陷阱清单
+
+全部为实际踩到并修复的问题，编辑器外壳里已处理。**遇到偏差不为 0 或功能异常时
+先查这里**，不要重写外壳。
+
+## 固化阶段
+
+| # | 陷阱 | 处理 |
+|---|---|---|
+| T1 | 边量边改导致后续元素上跳 | 严格两趟：先全量测量并缓存，再统一写入 |
+| T2 | 图层抽走后容器塌陷。尤以 `bottom` 定位的容器为害：高度一塌，容器整体下移，容器内**未被抽走的**元素（如分隔线）跟着跑位 | 测量阶段一并记录所有「含图层的祖先容器」，在抽离前把 `width/height` 钉死 |
+| T3 | `margin` 残留。文档流元素靠 `margin-top` 排版，转 absolute 后 margin 仍生效，元素在新坐标基础上再偏移 | 写入时统一 `margin:0` |
+| T4 | 把 `transform` 一律清空虽能解决 `translateX(-50%)` 的重复偏移，却会抹掉邮戳、回形针、手写贴纸等设计旋转 | 分别保存未变换布局尺寸、computed transform 与 transform-origin；提升后重施矩阵，再用可见包围盒差值反算 `left/top` |
+| T5 | `right` / `bottom` 定位的元素改 `left/top` 无效 | 写入 `left/top` 的同时把 `right/bottom` 置 `auto` |
+| T6 | z-index 与上下文样式丢失。元素移出原容器后，`.dark-card .label` 等祖先选择器不再命中；模块底色、图片、未标分隔线和 copy 的绘制次序也可能翻转 | 提升前保存发生变化的 computed/pseudo 样式并最小化内联；按顶层 stacking 顺序分配 z 段，区分“容器自身是 surface”与“独立 surface 叶子”两种模块 |
+| T7 | 宽度塌缩。文档流元素宽度由父容器给定，转 absolute 后塌成 `fit-content`，文字重新换行 | 写入测得的 `width` |
+| T8 | 字体未加载完就测量，量到的是 fallback 字体的坐标，落盘后整个版面偏移 | 固化前 `await document.fonts.ready` |
+| T9 | 图片未加载完就测量（高度为 0）。**加载失败也必须放行**，否则一张坏图卡死整个编辑器 | 等待所有 `img` 的 `load` 与 `error` |
+| T10 | DOM 提升顺序反转。多个图层依次插入同一锚点后顺序会颠倒，绘制次序随之改变 | 每组维护滚动锚点，插入后把锚点更新为刚插入的元素 |
+| T11 | 被抽空的容器仍会捕获 pointer 事件，挡住下方图层 | 锁尺寸时一并设 `pointer-events:none` |
+
+## 交互阶段
+
+| # | 陷阱 | 处理 |
+|---|---|---|
+| T12 | **`pointerdown` 里调 `preventDefault()` 会抑制后续 `click` / `dblclick`**（Pointer Events 规范：阻止默认行为会连带抑制兼容鼠标事件）。表现为双击完全无法进入文本编辑 | 不在 `pointerdown` 阻止默认行为；防止拖拽误选文字改为「移动超过阈值后再设 `user-select:none`」 |
+| T13 | **`setPointerCapture` 会把后续 `click` / `dblclick` 的 `target` 重定向到捕获元素**。表现为双击图层内的子元素时 `e.target` 变成整个图层，找不到文本槽。若图层自身恰好就是文本槽则「碰巧能用」，极具误导性 | ① 指针捕获推迟到确认拖拽之后；② `dblclick` 不信任 `e.target`，改用 `document.elementFromPoint()` 重新命中 |
+| T14 | 画布整体 `scale` 后屏幕位移与画布位移不等，不换算则拖拽明显不跟手 | `dx = (e.clientX - startX) / scale` |
+| T15 | 文本编辑态下方向键同时移动光标和图层 | 编辑态的 keydown 在 capture 阶段 `stopPropagation()` |
+| T16 | **中文输入法**：组字期间 Esc 是「取消候选词」、Enter 是「上屏」。不区分则用户打字打到一半就被踢出编辑态 | 按键处理第一行即 `if (e.isComposing \|\| e.keyCode === 229) return;` |
+| T17 | 文本编辑粒度若取整个图层，多字号拼排结构会被破坏（如价格由 `.cup`/`.num`/`.yuan` 三个不同字号字色的 span 拼成，整块 `contenteditable` 时一个退格即崩） | 编辑单元下沉到**文本槽**：图层内部只承载文字的叶子节点；图文混排节点整体算一个槽；SVG 子树排除 |
+| T18 | 从外部粘贴带格式内容会把 HTML 污染进海报 | `contenteditable="plaintext-only"` |
+| T19 | 文字改长或字号变大后被固化宽度挤到换行；但用户手动缩窄文本框时又确实需要换行 | 默认提交时按需扩宽且**不主动收窄**；一旦用户使用宽度手柄，就标记为手动宽度，后续文字与字号编辑保留该宽度 |
+| T23 | `documentElement` 上的 `data-hf-ready` 标记会被 `cloneNode` 带进导出物 | 导出时移除所有 `data-hf-*` 属性（含 `<html>` 自身） |
+
+## 测试与环境
+
+| # | 陷阱 | 处理 |
+|---|---|---|
+| T20 | **Puppeteer 的 `clickCount: 2` 不产生 `dblclick`**。它只设置参数、不真的按两次，`detail` 恒为 1，浏览器不合成双击。会误判成功能 bug | 手动发两轮 down/up，第二轮传 `clickCount: 2`，此时 `detail=2`、`dblclick` 正常派发 |
+| T21 | headless Chrome 启动被用户已开着的实例干扰，报 `Timed out waiting for the WS endpoint URL` | 每次用全新的临时 `--user-data-dir`（顺带保证 localStorage 干净，草稿不干扰固化） |
+| T22 | 断言「导出物无编辑器残留」时，注入的 **HTML 注释节点**不会被 `querySelectorAll` 删除 | 用 `TreeWalker(SHOW_COMMENT)` 一并清理（当前外壳改为动态创建 DOM，已不注入注释） |
+| T24 | `document.fonts` 含**所有**声明的 `@font-face`，未被使用的（如仅作 fallback 列出的字体）一直是 `unloaded`，这是按需加载的正常行为 | 断言只用 `document.fonts.status === 'loaded'`，不要求每个 FontFace 都 loaded |
+| T25 | Google Fonts 把中文字体切成上百个 `unicode-range` 分片，同一 family 下必然部分 loaded 部分 unloaded | 判断一个 family 是否真的没用上，要看「是否**没有任何**分片被加载」 |
+| T26 | 契约检查里把图层的祖先容器误报成「漏标 `data-layer-id`」——容器本身没有 layer-id，但它只是包装 | 候选块需额外排除「内部含 `[data-layer-id]`」的元素 |
+| T27 | 拆解视图开启后原画布被 `display:none`，此时再次下载拆解稿若现场读 `offsetWidth/Height` 会全部得到 0，导出空稿 | 进入拆解态前缓存每层几何；隐藏后导出使用缓存，不重新测量不可见画布 |
+| T28 | 用随机数或直接动画 `left/top` 做拆解，会让每次录制位置不同、截图中途态漂移，并破坏确定性验收；系统“减少动态效果”下还可能卡在初始态 | 终态只由确定性 `left/top` 决定；动画仅叠加 Web Animations 的 `transform/opacity/filter`，结束后取消动画回到 CSS 终态；支持 `prefers-reduced-motion` 与 `?motion=0`，独立稿动画完成后才设置 ready 锚点 |
+| T29 | 拆解舞台过宽会让扫描原稿骤缩；列数太少又会把组件挤成细小侧注 | 使用平衡舞台 `max(1.7×画布宽, 1.275×画布高)`；扫描原点保留编辑态高度至少约 68%，终态按组件数自动使用 2–5 列，并分别约束总览、背景和内容组件的缩放 |
+| T30 | 先播放扫描、之后才创建拆解动画，会让图层在扫描期间提前闪到最终位置；扫描层若未纳入统一结束处理，也会残留遮罩或卡住 ready | 首帧即创建全部 WAAPI：利用 `delay + fill:both` 把图层钉在成稿位置，扫描尾段与散开重叠；扫描层置于独立高层且终帧透明，统一等待和取消；reduced-motion / `?motion=0` 直接跳到终态 |
+| T31 | 只比较 `getBoundingClientRect()` 会把“坐标没变、底色/伪元素/图片/层级已丢”的稿件误判为零偏差 | A 类验收同时截取原稿与 baked 稿做像素比较；几何比较负责定位，像素比较负责视觉真值 |
+| T32 | 海报画布用渐变纸张而 `background-color:transparent` 时，直接读 backgroundColor 会得到透明黑并把拆解舞台误判成黑色 | 优先读取不透明背景色；透明时解析 background-image 中的近不透明颜色，再回退页面底色/暖白 |
+| T33 | 中央常驻完整成稿或大幅空背景，会让终态看起来没有真正拆开并制造无意义留白；继续钻取第二层又会产生过细采集 | 动画起点把组件叠回完整成稿；终态把完整总览、未标记背景和一级内容全部缩成画廊组件，中央不留固定基底，也不提供第二级叶子钻取 |
+| T34 | 从 Grid/Flex 模块容器中直接删除非目标兄弟，会让目标卡自动补位；按原坐标裁切时卡片底色消失，只剩已提升的文字/图标 | 非目标模块改用 `visibility:hidden` 保留布局占位，随后再移除其叶子；不要删除决定轨道位置的兄弟包装 |
+| T35 | FLIP 散开动画把整个模块从扫描原点移动到画廊时，模块说明标签也会随父项同步缩放，运动中变成遮住海报的巨型省略文字；即使停稳后全部常驻，也会重复模块内已有标题 | 模块标签默认隐藏；仅在舞台停稳且用户悬停/聚焦具体模块时淡入，离开即隐藏。名称仍保存在 `title` 中供发现，但不污染扫描动画或静止拆解稿 |
+| T36 | 分组容器只包绝对定位叶子时自身宽高可能为 0，按容器盒裁切会把模块压成不可见细条；一级有效组件过少时画廊也显得空 | 分组盒无效或远小于成员联合边界时回退到成员几何并集；一级内容组件少于 5 个时，把分组内有文字且非 surface/image/icon/decoration 的叶子作为同级补充 tile，保持一级结构不增加钻取层级 |
+| T37 | 把缩放手柄画在已整体 `scale()` 的画布内，会让点击区域随缩放变小；用图层伪元素又无法可靠接收独立的八向拖拽；可见角点若同时就是命中区，在高密度海报上仍很难点中 | 在未缩放舞台中维护独立选框：显示坐标乘 `scale`，指针位移除以 `scale`；手柄使用约 32px 的透明命中区包住 12px 可见标记；进入文字编辑或拆解视图时隐藏，导出时彻底移除 |
+| T38 | 在真正拖动前尚未建立 pointer capture；此时若指针在画布外松开、窗口失焦或浏览器取消手势，`pointerup` 可能不到达画布，旧手势会保持 armed，鼠标回来后图层继续跟随 | 在 window capture 阶段兜底处理 `pointerup/pointercancel`，监听 `lostpointercapture`、窗口失焦和页面隐藏；`pointermove` 发现主键已松开就立即结束；`Esc` 取消并恢复本次手势，下一次 pointerdown 先终止任何残留手势 |
+
+## 诊断偏差不为 0
+
+`bake.mjs` 报偏差时，按可能性排序检查：
+
+1. 契约未满足 —— 先跑 `check-contract.mjs`，十有八九是 `vw/vh/%` 或字体没等到
+2. 上表 T1–T11 未覆盖的布局：`float`、`position:sticky`、伪元素撑开高度、
+   `writing-mode`、CSS `columns`、`subgrid`
+3. 图层之间有重叠依赖（一个图层的位置由另一个图层的内容高度决定）
+
+定位方法：`bake.mjs` 的输出逐图层列出了原始与固化后坐标，先看**哪些图层偏了、
+偏移量是否相同**。同一容器内的图层偏移量一致，通常是 T2 容器塌陷；单个图层偏移
+等于某个 margin 值，是 T3；旋转饰物的包围盒与角度不一致，是 T4。

package/skills/global_config/editable-design/references/editor-runtime.md

@@ -0,0 +1,131 @@
+# Editor and exploded views
+
+Read this when wiring, validating, baking, or diagnosing the bundled poster
+editor. `poster-building` is the only required skill; no separate editor skill
+or runtime is needed.
+
+## Ownership and delivery
+
+- `assets/editor/layer-editor.css` and `layer-editor.js` are the canonical
+  runtime. Do not rewrite them per poster.
+- `scripts/init-poster.sh` copies that runtime into
+  `PROJECT/scripts/editor-assets/`.
+- `PROJECT/scripts/wire-editor.mjs` copies the runtime beside `index.html` and
+  creates `editor.html` without modifying `index.html`.
+- The finished project remains offline and self-contained. Editor controls never
+  enter the PNG because rendering always targets `index.html`.
+
+## First use of validation tools
+
+The browser-driven validation tools need `puppeteer-core`. Install it once in
+the skill's `scripts/` directory:
+
+```bash
+npm ci --prefix <poster-building-skill>/scripts
+```
+
+The interactive `editor.html` itself needs no installation and no local server.
+
+## Contract and wiring
+
+Run the poster's normal static check first. For a browser-measured compatibility
+preflight before the first render, then wire and verify from any directory with
+absolute paths:
+
+```bash
+node <poster-building-skill>/scripts/check-contract.mjs PROJECT/index.html
+node PROJECT/scripts/wire-editor.mjs PROJECT/index.html
+node <poster-building-skill>/scripts/verify.mjs PROJECT/index.html
+```
+
+Fix every contract or verification failure before delivery. Do not patch the
+editor runtime around a poster-specific violation. Verification compares both
+layer geometry and rendered pixels: matching rectangles alone cannot detect a
+lost card surface, contextual style, pseudo-element, blend, or paint order.
+
+The poster authoring contract is defined in `SKILL.md`; this reference owns only
+runtime wiring, verification, baking, and diagnosis.
+
+## Standalone exploded view
+
+`editor.html` already provides scan, one-level content spreading,
+reverse-collapse, and download controls. Every poster also ships a standalone
+`layers.html`. Groups appear as whole modules; ungrouped content appears as
+individual units. If that produces fewer than five primary content units, the
+gallery keeps those modules and additionally promotes their grouped text leaves
+to companion units. This is a one-level density fallback, not a second-level
+drilldown. The normal
+`verify.mjs` run writes the verified file without another browser launch.
+Use `explode.mjs` only to regenerate it separately while diagnosing a failure:
+
+```bash
+node <poster-building-skill>/scripts/explode.mjs PROJECT/index.html
+node <poster-building-skill>/scripts/explode.mjs PROJECT/index.html PROJECT/layers.html
+```
+
+The exported view contains a small complete-composition overview, a small tile
+for the unmarked paper/texture/fixed frame, whole content modules, and ungrouped
+units. They spread into a 2–5 column component gallery with no
+permanent central base. At the animation origin all tiles overlap at their
+original coordinates, so the complete poster is reconstructed before it
+separates. Text, images, and SVG remain DOM clones. The stage follows the
+poster's actual paper or background tone, including dark hues, instead of
+collapsing every dark poster to generic black. This preserves the intended
+contrast of thin and low-opacity layers. In isolated content tiles only,
+computed opacity below 0.55 receives a bounded presentation boost; the complete
+overview remains visually faithful to the poster. It is a presentation artifact,
+not a second editor.
+Continue editing in `editor.html`.
+
+The transition uses a scan beam followed by deterministic FLIP-style spreading.
+Only `transform`, `opacity`, and `filter` animate; final `left` and `top` remain
+deterministic. `prefers-reduced-motion` is respected, and `?motion=0` opens at a
+stable end state for screenshots and automated review, with the replay-animation
+control hidden because there is no motion to replay.
+
+The settled view uses the center as part of the gallery. Column count depends
+only on the effective component count after the small-gallery text fallback;
+original horizontal position is a light placement preference, and visual weight
+balances the columns. There is no second detailed collection pass.
+
+## Optional offline bake
+
+Use baking only when a stable, absolute-positioned source is useful for CI or
+future editing:
+
+```bash
+node <poster-building-skill>/scripts/bake.mjs PROJECT/index.html
+node <poster-building-skill>/scripts/bake.mjs PROJECT/index.html --in-place
+```
+
+The in-place form overwrites the source, so use it only when that exact target
+is intended and recoverable. Baking must not land when any layer drifts by more
+than 1px.
+
+## Editor scope
+
+The editor supports dragging, alignment snapping, arrow-key nudging, eight-handle
+resizing, plain-text editing, proportional font scaling, switching among
+declared font stacks, delete, undo, local drafts, scan/explode/collapse, and
+clean normal or exploded HTML downloads. Left and right handles change width,
+top and bottom handles change height, and corners change both. A width set by a
+handle remains fixed during later text or font-size edits so wrapping follows
+the user's chosen box; resize state participates in undo, draft restore, reset,
+position-CSS export, and clean HTML export.
+
+Pointer gestures must always have an exit path. Releasing anywhere, pointer
+cancellation, capture loss, window blur, or hiding the page ends the active
+gesture. Pressing Escape during a drag or resize cancels that gesture and
+restores its starting geometry; pressing Escape afterward clears selection.
+
+It intentionally does not add arbitrary layers, import images, reorder the
+stack, rotate, recolor, or expose full typography controls. It is for human
+micro-adjustments after design, not for redesigning the poster.
+
+The automation anchor is `html[data-hf-ready]`. The public API is
+`window.__layerEditor`, including `fullHTML()`, `explodedHTML()`, `download()`,
+`downloadExploded()`, `undo()`, `select()`, `scaleFont()`, `setFont()`,
+`removeLayer()`, `setExploded()`, `layers()`, and `state`.
+
+When validation reports drift or an interaction fails, read
+[Editor pitfalls](editor-pitfalls.md) before changing the runtime.

package/skills/global_config/editable-design/references/font-system.md

@@ -0,0 +1,89 @@
+# Font system
+
+Read this when typography carries the design, when the brief needs a distinctive
+editorial voice, or when the visual editor needs more useful alternatives than
+the platform defaults.
+
+## Two different counts
+
+The **active type system** and the **editable font palette** are not the same.
+
+- A finished poster normally uses two or three families: one display voice, one
+  text voice, and optionally one utility or accent voice.
+- The editor may expose three to five verified font variables so a user has
+  meaningful alternatives. Do not use every exposed family in the composition.
+
+For a poster, cover, flyer, or campaign, declare at least three meaningfully
+different selectable font roles unless the brief deliberately specifies a
+single-family identity. A body sans, another nearly identical sans, and the
+same sans at a different weight are not three roles.
+
+## Curated self-hosted kit
+
+The optional font kit uses versioned Fontsource packages and local WOFF2 files.
+Install it once:
+
+```bash
+scripts/install-font-kit.sh
+```
+
+Inspect the available design roles:
+
+```bash
+node scripts/font-kit.mjs list
+```
+
+Add only the selected families to a poster. The command copies the required
+WOFF2 files and license into `assets/fonts/`, injects local `@font-face` rules,
+and exposes a `--font-kit-*` variable to the editor:
+
+```bash
+node scripts/font-kit.mjs add editorial-serif index.html
+node scripts/font-kit.mjs add clean-sans index.html
+node scripts/font-kit.mjs add cjk-serif index.html
+```
+
+Available roles:
+
+| ID | Voice | Best use |
+| --- | --- | --- |
+| `editorial-serif` | Fraunces Variable | expressive editorial and cultural headlines |
+| `luxury-serif` | Bodoni Moda Variable | fashion, beauty, luxury, magazine covers |
+| `clean-sans` | Instrument Sans Variable | refined campaigns and editorial body copy |
+| `geometric-sans` | Space Grotesk Variable | technology, information, contemporary labels |
+| `condensed-sans` | Roboto Condensed Variable | dense layouts, deck lines, prices, utilities |
+| `experimental-display` | Unbounded Variable | art, music, youth, experimental display |
+| `cjk-sans` | Noto Sans SC Variable | Chinese body copy, campaigns, information design |
+| `cjk-serif` | Noto Serif SC Variable | Chinese editorial, culture, literature, premium display |
+| `cjk-calligraphy` | Ma Shan Zheng | short Chinese handwritten accents and titles |
+| `cjk-display` | ZCOOL XiaoWei | distinctive Chinese editorial display titles |
+
+Self-hosted fonts are preferred when reproducibility matters. System fonts may
+still be used when their exact voice is appropriate and `check-fonts.sh`
+confirms they are installed.
+
+## Pairing by contrast
+
+Choose pairs that differ in structure, not merely in weight:
+
+- luxury campaign: `luxury-serif` + `clean-sans`
+- editorial or culture: `editorial-serif` + `clean-sans`
+- technical information: `geometric-sans` + `condensed-sans`
+- Chinese editorial: `cjk-serif` + `cjk-sans`, optionally a Latin display face
+- Chinese expressive poster: `cjk-display` or `cjk-calligraphy` for short display
+  copy, with `cjk-sans` or `cjk-serif` for everything longer
+- experimental art: `experimental-display` + a quiet sans or serif
+
+Do not set paragraphs in a display or calligraphic face. Do not use synthetic
+bold or italics on CJK fonts that do not supply those styles. Mixed Chinese and
+Latin display lines may use separate editable spans when the intended Latin
+voice would otherwise disappear behind the CJK family.
+
+## Shipping rules
+
+- Use local relative font URLs only; never depend on Google Fonts or another
+  runtime network request.
+- Copy only fonts selected for the current design.
+- Keep each copied `LICENSE.txt` with its font files.
+- Run `scripts/check-fonts.sh index.html` after font injection and before render.
+- Wait for `document.fonts.ready` before measuring, baking, or capturing.

package/skills/global_config/editable-design/references/imagery.md

@@ -0,0 +1,145 @@
+# Imagery
+
+Read this before writing any shipping-asset prompt, and again when generated
+artwork comes back wrong: lettering appeared in the image, the composition does
+not match its slot, a band that should be empty has objects in it, a cutout has
+a dirty matte, or the crop does not fit its planned region. [SKILL.md](../SKILL.md)
+owns asset topology, count, batching, and import policy; this reference owns
+prompt construction and returned-image diagnostics.
+
+## Reserved space: describe appearance only
+
+Work out which regions text will cover, then **describe those regions purely by
+their physical properties**:
+
+```
+WRONG: "leave clean dark negative space at the top for the headline"
+RIGHT: "the top third is a continuous, low-detail, darker sky with no objects,
+        symbols, borders, or high-contrast marks in it"
+```
+
+**Measured: naming the occupant produced an artefact 10 times out of 10;
+describing appearance only, 0 times out of 13.** Holds across two scenes and two
+framing nouns.
+
+The trigger phrases are "for the headline", "space for the logo", "room for the
+price", "space for copy". Tell the model something goes there and it draws
+something — sometimes real lettering, sometimes an empty oval or bar. The second
+is just as harmful: your HTML text lands on it and both become unreadable.
+
+Say what the region **is**: sky, a wall, blurred foliage, flat shadow, an even
+wash of paper — and that it is empty and uniform.
+
+## A stated proportion is an intent, not a contract
+
+Naming a share of the frame gets you a region of roughly that kind, not a region
+of that size. Measured across two backdrops from the same model: one asked for a
+clean right-hand 16 percent and got 22 percent; the other asked for 34 percent and
+got **11**. Over-delivery and under-delivery, same wording pattern, same backend.
+
+So never lay out against the number you asked for. Either measure the generated
+backdrop before writing any coordinates — scan it in horizontal or vertical strips
+and find where the ink actually starts — or leave far more margin than the layout
+needs and accept the wasted space. A layout that survives only because the margin
+happened to be generous was saved by luck, not by planning.
+
+## Band phrasing
+
+Describe a full-bleed backdrop as horizontal bands, one sentence each, giving
+four things: position and share of the height, the material, the brightness, and
+the detail density.
+
+```
+The composition reads as three horizontal bands.
+Top 35 percent: an unbroken, even, pale grey-white fog sky, completely smooth
+and uniform, no clouds, no birds, no sun disc, no objects, no marks, and no
+high-contrast detail anywhere in it.
+Middle band, about 37 percent of the height: layered ridgelines of tea terraces
+receding into mist, dark blue-green silhouettes, soft atmospheric perspective,
+the strongest detail of the whole frame concentrated here.
+Bottom 28 percent: a flat, even wash of low-lying pale mist, extremely low
+texture, uniform brightness, empty.
+```
+
+Two to four bands are both reasonable; let the layout decide. Bands that will
+carry text need brightness well separated from the text colour. Bands that carry
+no text are where the subject and the detail belong.
+
+**Write the prompt in English even when the poster is in another language.**
+Image models follow English more reliably and the prompt never appears in the
+poster.
+
+Note the difference between the "no clouds, no birds, no objects" above and a
+negative instruction. Those clauses modify something already described
+positively — they say how clean that fog sky is. "no text" modifies nothing.
+
+## Negative instructions do not work
+
+"no text, no lettering" has been measured to have no effect. Most current
+image backends are not diffusion models: a diffusion model's negative prompt
+genuinely subtracts a negative embedding inside CFG, whereas a multimodal model
+generating an image has no such channel — the negation is just a few more tokens,
+and models handle negation poorly to begin with.
+
+Describing appearance is the mechanism that actually works.
+
+## Size
+
+**Use the size parameter when the tool has one; do not describe the frame in
+prose.** A parameter is deterministic, prose is probabilistic.
+
+- A full-bleed image gets the canvas proportions
+- Slot artwork gets the slot's own dimensions
+- If the tool only accepts an aspect ratio, give the ratio
+- With no size control at all, the frame can only be implied in prose ("tall
+  vertical portrait composition"), and the same prompt may return 1408x768 one
+  time and 896x1200 the next. Expect to retry
+
+When the returned image has the wrong proportions, crop it deliberately with
+`object-fit` and `object-position`; never let it stretch. **Crop toward the bands
+that carry no text** — keep the flat band the headline sits on and give up the
+one nothing lands on.
+
+## Transparent assets
+
+Native transparency is an output control, not a visual prompt style. Follow the
+active image-generation capability's transparency workflow. When the active
+surface exposes a background parameter, pass `transparent` explicitly and use
+PNG or WebP; do not rely on prompt wording alone. In the default Codex ImageGen
+path, if no background parameter is exposed, ask for a genuinely transparent
+background, never describe a checkerboard, preserve any returned alpha channel,
+and treat the result as provisional until inspected.
+
+Before importing a transparent asset, confirm that the file has an alpha channel
+and that its empty corners are transparent. An RGB file that visibly contains a
+checkerboard has baked pixels, not transparency. If the subject is correct but
+the alpha check fails, do not spend another generation retry on the same subject:
+use deterministic local alpha extraction when the edges permit it, or switch to
+an explicitly authorized API/CLI path that can pass `background=transparent`.
+
+Generate each independently movable cutout as its own file. One call containing
+several separated subjects still returns one bitmap and does not create several
+transparent assets.
+
+Ask for a compact subject with room around it so it can be positioned and
+cropped cleanly.
+
+## Contrast where text sits over artwork
+
+Use an explicit treatment sized to the text block: a solid panel, a scrim, or a
+directional gradient. Do not count on the image being dark enough exactly where
+you need it — change the scale and it no longer is.
+
+Watch the edges of a scrim: the hard edge of a semi-transparent rectangle is
+visible in the render. Either run it to the canvas edge or fade it out.
+
+## Controllable and not
+
+**Controllable**: the prose description, reference images (image-to-image and
+local edits), cutouts, output size or ratio.
+
+**Not controllable**: seed and reproducibility (the same prompt differs every
+time; retrying is the only lever), negative prompts, or several independently
+editable files from one built-in call.
+
+Neither column depends on which image tool is behind it.

package/skills/global_config/editable-design/references/layout-typography.md

@@ -0,0 +1,116 @@
+# Layout and typography
+
+Read this before writing HTML when the layout is unclear, and again when the
+render is "correct everywhere but does not look designed". The "Shape the poster"
+section of [SKILL.md](../SKILL.md) is the entry point.
+
+A poster is read from a distance, scanned once, and taken in a fixed order.
+Everything below serves that.
+
+## Layout
+
+**Hierarchy is the whole job.** A viewer should absorb a poster in three passes:
+the hook, then the claim, then the detail. Build that staircase with size,
+weight, colour, and white space, and make the steps genuinely different. Two
+elements of similar visual weight compete and both lose. Emphasising everything
+emphasises nothing.
+
+**White space is structure, not what is left over.** Generous, deliberate margins
+and gutters are the line between a designed poster and a filled one.
+
+**Align to a grid.** Fix the margins and columns first, then place everything on
+them. Optical alignment beats an offset you typed from memory; an edge that is
+almost aligned reads as a mistake.
+
+**Control the palette by role, not count.** Define the field, text, accent, and
+semantic roles first. A restrained poster may need very few colours; a brand,
+reference-led, or information-dense poster may need more. Every colour must
+have a compositional or semantic job.
+
+**Commit to one direction** — editorial, luxury, brutalist, playful, technical.
+Pick one and let it drive every decision. A poster hedging between two reads as
+neither.
+
+**Anti-patterns:**
+
+- Centring everything by default
+- Equal spacing between unrelated blocks, flattening the hierarchy
+- Text straight over busy artwork with no contrast treatment
+- Borders, badges, and rules filling space in place of real structure
+- Drop shadows and gradients patching a weak layout
+- Marketplace styling: starbursts, unmotivated diagonal ribbons, clip art
+
+A poster should look considered at full size and still read structurally as a
+thumbnail.
+
+## Working with the backdrop
+
+Once the full-bleed backdrop exists, you are not laying out on white paper — you
+are laying out on that image's bands.
+
+- Text blocks land on the **flat** bands; the subject and the detail keep their own
+- Let the text margins breathe with the image's composition; do not run type
+  along the edge of the subject
+- More than two levels of hierarchy inside one band wastes the flatness you
+  asked the band for
+- If the backdrop changes, revisit the layout. The same coordinates rarely hold
+  on a different image
+
+## Typography
+
+Declare font stacks as custom properties on `:root` and reference them
+throughout. Give every family a distinct job and valid script coverage. Add a
+family when the brand, reference, script, or typographic contrast requires it,
+not as decoration.
+
+Do not confuse visual consistency with typographic sameness. A finished poster
+usually activates two or three families, but its editor should expose three to
+five verified and meaningfully different font roles when the format benefits
+from later type changes. Read [Font system](font-system.md) for the curated local
+font kit, pairing patterns, and shipping rules.
+
+**Build a real size ramp.** display, headline, subhead, body, caption, each
+clearly different from the last. A ramp with 10 percent steps reads as an error.
+
+- Tighten tracking on large display type; open it slightly on small caps
+- **A single-line block with `letter-spacing` needs `white-space: nowrap` or an
+  explicit width.** CSS adds the tracking after the last character too, so the
+  measured content width is a fraction wider than the glyphs need. Anything that
+  later writes that measured width back — an editor converting the layout to
+  absolute positioning, for instance — pushes the last character onto a second
+  line. The block's height doubles and nothing reports an error
+- Line height: 1.1–1.2 for display, 1.5–1.7 for body
+- Keep poster body copy to 20–40 characters per line
+- Do not run text to the edge; respect the margins you set
+- Nothing below 9px after rendering. Small type is still meant to be read
+
+## CJK typography
+
+- **Choose a family that genuinely covers the script.** A Latin-only family must
+  not set CJK text; use a CJK-capable family in that stack
+- **No synthetic italics or synthetic bold.** Use a real weight, or another family
+- **Weight is a choice of family, not only of `font-weight`.** Kai, running-script,
+  and handwriting faces are structurally thin and stay thin at any size, so a
+  headline set in one looks weightless however large. When a headline has to hold
+  the page, take the weight from the family itself
+- **CJK display type tolerates tight tracking; body copy does not**
+- **In mixed settings put the Latin family first in the stack**, otherwise digits
+  and roman characters inherit the CJK face's proportions
+
+## Markup and CSS conventions
+
+- **`* { box-sizing: border-box; }`**, always. `getBoundingClientRect()` reports
+  the visual width including padding; under content-box, anything that writes that
+  measured width back into `width` adds the padding a second time. A pill-shaped
+  tag with `padding: 20px 44px` grows 88px wider every round trip, and nothing
+  reports an error
+- One file. CSS in a single `<style>` in the head. Zero external requests
+- Palette and font stacks as `:root` custom properties, referenced throughout
+- Layers absolutely positioned inside the canvas, so every coordinate is explicit
+- Fixed px for every dimension, position, and gap that carries layout. No
+  vw/vh/vmin/vmax/%. Decorative values — gradient stops, radii, shadow spread,
+  texture `background-size` — are unrestricted
+- Semantic class names describing the block's role on the poster
+- Image paths relative to the poster file
+- Never embed, print, or commit a key or credential
+- **Do not write comments**