Appearance
Design JSON 字段表
逐字段抄自 packages/design-json/src/（design.ts / layers.ts / geometry.ts / color.ts / units.ts / barcodes.ts）。 这一页是抄件，zod 才是真源：改了 zod 必须同步本页并跑 node docs-site/check.mjs。
- 必填/可选按 zod 判定；"默认值"指 zod
.default()的实际值。 - 长度字段一律 mm，键名以
Mm结尾（例外：transform.x/y、canvasMm.width/height、uvRect.*，见下）。 - 像素只允许出现在
…Px键与assetRef.selection（选区是位图坐标）。
顶层 designSchema（design.ts）
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
schemaVersion | 字面量 1 | ✔ | — | SCHEMA_VERSION = 1。不是 ADR-0002 设想的 meta.schemaVersion，见偏差记录 |
designId | id('ds') | ✔ | — | 正则 ^ds_[a-z0-9]{6,40}$ |
name | string 1–120 | ✔ | — | 人读名称 |
canvasMm | { width>0, height>0 } | ✔ | — | 展开图外接尺寸 mm；由几何生成器写入 |
bleed | bleedSchema | ✔ | 四边 3 | top/right/bottom/left，各为非负 mm |
safeAreaInsetMm | number ≥0 | ✔ | 5 | 安全区内缩 mm |
dieline | dielineRefSchema | ✔ | — | 只存盒型参数与引用，几何本体由 @apw/dieline 生成 |
layers | LayerNode[] | ✔ | [] | 图层树＝设计树 |
assets | assetRefSchema[] | ✔ | [] | 素材，不可变 + 版本引用（P2-11 方向） |
fonts | fontRefSchema[] | ✔ | [] | 字体与授权状态 |
brandTokens | brandTokensSchema | ✔ | 空集合 | Brand Kit |
mappings | artworkMappingSchema[] | ✔ | [] | 2D 面板 ↔ 3D face UV |
provenance | aiProvenanceSchema | ✘ | — | 整图生成 or 局部编辑的审计入口 |
aiEdits | 数组，.max(3) | ✘ | — | 最近 3 次 AI 合成记录；超出即丢弃最旧 |
superRefine 附加断言（真校验只在 zod，JSON Schema 里没有）：图层 id 唯一；image.maskAssetId 也存在； 图层 panelId 必须在 mappings 里；含文字时字体 licenseStatus 不得为 blocked。
dielineRefSchema
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
dielineId | id('dl') | ✔ | — | ^dl_[a-z0-9]{6,40}$ |
boxType | string 1–64 | ✔ | — | 目前只有 rectangular（四摇盖胶封盒） |
paramsMm | Record<string, number> | ✔ | — | 键由盒型生成器定义；本盒型为 width/height/depth/glueMm |
material | { name?, thicknessMm? } | ✔ | {} | thicknessMm 只作元数据；纸厚补偿未实现，见 能力边界 |
assetRefSchema
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
id | id('as') | ✔ | — | ^as_[a-z0-9]{6,40}$ |
storageKey | string 1–512 | ✔ | — | 对象存储 key（不含签名） |
mimeType | image/png | image/jpeg | image/webp | image/tiff | image/svg+xml | ✔ | — | 渲染层今天只吃 PNG/JPEG/WebP（dataUrl 正则限制） |
widthPx / heightPx | 正整数 | ✔ | — | 像素，唯一允许裸 px 的几何位置之一 |
dpi | number >0 | ✘ | — | Preflight 的高频事故入口；缺省时按 300 推算显示尺寸 |
bytes | 非负整数 | ✔ | — | 体积 |
checksumSha256 | 长度 64 的串 | ✔ | — | 完整性；示例里是占位值 |
dataUrl | ^data:image/(png|jpeg|webp);base64, ≤30 MB | ✘ | — | 验证工作台导出时要求存在（tools/validate-design.mjs） |
extraction | 对象 | ✘ | — | 素材提取来源记录：source/resultSource/selection{x,y,width,height,pixels}/mask/createdAt/instruction |
extraction.selection 是位图坐标 + 像素数，用途是让"这块素材怎么来的"可追溯；对应 UI 见 docs/demo/app.mjs。
fontRefSchema
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
id | id('ft') | ✔ | — | ^ft_[a-z0-9]{6,40}$ |
family / style | string | ✔ | style 默认 Regular | |
storageKey | string | ✔ | — | 字体文件 key |
licenseStatus | cleared | pending | blocked | ✔ | pending | 含文字层且为 blocked → parse 失败；商用授权属外部依赖 PE-05 |
embeddable | boolean | ✔ | false | 是否允许子集化嵌入导出（P2-03） |
hasCjk | boolean | ✔ | false | 缺字检测的前提（P2-04） |
brandTokensSchema
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
brandKitId | id('bk') | ✘ | — | |
colors | { name, color }[] | ✔ | [] | color 为 colorSchema，可放专色 |
fontIds | id('ft')[] | ✔ | [] | |
logoAssetIds | id('as')[] | ✔ | [] | |
forbidden | { kind: 'word'|'color'|'asset'|'claim', value, note? }[] | ✔ | [] | 禁用项；命中即阻断生成的编排逻辑属 P1-07/P3-03，未实现 |
fixedCopy | { key, text }[] | ✔ | [] | 法规字段等固定文案，AI 不得改写（外部依赖 PE-07） |
图层（layers.ts）
公共字段（除 aux 外全部继承）：
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
id | ^ly_[a-z0-9]{6,40}$ | ✔ | — | 同一 design 内唯一 |
name | string 1–120 | ✔ | — | |
visible / locked | boolean | ✔ | true / false | aux 层 locked 默认 true |
opacity | 0–1 | ✔ | 1 | |
blendMode | normal | multiply | screen | overlay | darken | lighten | color | luminosity | ✔ | normal | 验证版渲染只接受 normal，其它直接抛错 |
transform | transformSchema | ✔ | — | mm |
panelId | string 1–64 | ✘ | — | 归属面板；必须能在 mappings 找到 |
kind: "text"
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
text | string 1–20000 | ✔ | — | 真实文字，不是位图 |
fontId | id('ft') | ✔ | — | 必须存在于 fonts |
sizeMm | number >0 | ✔ | — | 字号用 mm，不用 pt |
leadingMm | number >0 | ✘ | — | 行距 |
trackingEm | −50…1000 | ✔ | 0 | 字距 |
align | left | center | right | ✔ | left | |
writingMode | horizontal | vertical | arc | ✔ | horizontal | 验证版只支持 horizontal，竖排/弧形属 P2-04 |
boxMm | rectMmSchema | ✘ | — | 文本框 |
color | colorSchema | ✔ | — | |
source | manual | aiRebuilt | aiReference | ✔ | manual | aiReference 只能当参考，见 硬规则 |
kind: "image"
| 键 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
assetId | id('as') | ✔ | — | |
sizeMm | { width>0, height>0 } | ✘ | — | 显示尺寸 mm；缺省时按 widthPx × 25.4 / (dpi ?? 300) 推算（docs/demo/scene.mjs） |
srcRectMm | rectMmSchema | ✘ | — | 源图取用区域（裁剪），缺省整图 |
maskAssetId | id('as') | ✘ | — | 局部编辑遮罩素材 |
colorSpaceOverride | preserve | forceCmyk | forceRgb | ✔ | preserve | 只在导出期生效 |
kind: "path" / "barcode" / "aux" / "group"
| kind | 关键键 | 状态 |
|---|---|---|
path | d（SVG path，坐标系 mm）、viewBoxMm、fill?、stroke?、strokeWidthMm? | schema 已定义；验证版渲染不接受 path 图层（会抛"此验证版未实现"）；矢量保真导入属 P2-06 |
barcode | symbology、value、source | schema 已含校验位守卫；渲染未接入 → 规划 P1-09 |
aux | auxKind、paths[]（≥1）、processName?、panelId? | cut/crease/glue 已用于刀模；其余为语义占位 |
group | children（≥1） | schema 已定义；验证版编辑器有上移/下移但没有编组 → 规划 P2-01/P2-02 |
auxKind 枚举（AUX_LAYER_KINDS）：cut crease glue bleed safeArea foil spotUv whiteInk varnish braille。 非 aux 的层都算印刷层（isPrintLayer）。
WEB_ONLY_BLEND_MODES：overlay darken lighten color luminosity —— 这些混合在 PDF 里合成语义不等价，导出必须显式告警（P2-05，未实现）。
颜色（color.ts）
| mode | 键 | 说明 |
|---|---|---|
rgb | r/g/b 0–255、overprint? | 预览色 |
cmyk | c/m/y/k 0–100、overprint? | 生产色语义；落色待 P3-08 |
spot | spotName 1–80、tint（默认 100）、cmykFallback?、rgbPreview? | 专色；两者都缺时预览显示品红占位以暴露问题 |
overprint（叠印）只是 JSON 语义，实际印前检查属 P3-10。
几何基元与单位（geometry.ts / units.ts）
| 名称 | 形状 | 说明 |
|---|---|---|
pointMmSchema | { x, y } | mm，y 向下 |
rectMmSchema | { x≥0, y≥0, width>0, height>0 } | mm |
polylineMmSchema | { closed=false, points≥2 } | 刀线/压线/胶位轨迹 |
transformSchema | { x, y, rotationDeg∈[−360,360]=0, scaleX>0=1, scaleY>0=1 } | x/y 是 mm（对象原点），旋绕对象原点 |
DEFAULT_PX_PER_MM | 4 | 只在渲染层用；packages/ 内禁止裸像素常量 |
单位口径表（check.mjs 按此校验示例）：
| 容器 | 单位 |
|---|---|
canvasMm、transform、boxMm、sizeMm、srcRectMm、viewBoxMm、dielineRectMm、panelRectMm、paramsMm、sheetMm | mm |
uvRect、uvRectSchema | 归一化 0…1，无单位 |
selection、bounds | 位图 px |
widthPx / heightPx / bytes / pixels | px / 字节 / 像素数 |
条码（barcodes.ts）
| symbology | 值规则 |
|---|---|
ean13 | 13 位数字 + GS1 mod-10 校验位 |
ean8 | 8 位数字 + 校验位 |
upc_a | 12 位数字 + 校验位 |
code128 | 1–80 个可打印 ASCII |
qr | 长度 1–700 |
source: "aiReference" 的条码一律拒绝（schema superRefine）。
其它顶层实体
versionSchema：versionId（前缀rv）、designId、parentVersionId（可为null）、createdAt、label?、design、deltaFromParent?（占位）。projectSchema：projectId（前缀pj）、name、orgId（前缀og）、createdAt、headVersionId?、brief{ product?, brand?, style?, referenceAssetIds[] }—— Brief 的落点，见 AI 提示词手册。
工作台整合字段（2026-10-01）
图片保留 maskAssetId，新增 maskFit（stretch/center，默认 stretch）与 maskInverted（默认 false）。横排文字 align 增加 justify。旧文件缺少新增字段时沿用原有全图/无遮罩效果；现有分组仍使用 children。所有字段由 packages/design-json/src/layers.ts 校验，保存、预览和导出共享同一文档。