@xenonbyte/da-vinci-workflow 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 - No unreleased changes yet.
 
+## v0.1.14 - 2026-03-27
+
+### Added
+- `references/layout-hygiene.md` as the central form-factor-specific layout hygiene gate for mobile, tablet, desktop, and web screenshot review
+
+### Changed
+- screenshot-review and design-checkpoint guidance now apply a resolved layout-hygiene profile per reviewed surface instead of relying on generic spacing checks alone
+- design-input and artifact-template guidance now records the resolved layout-hygiene profile and blocker classes in `design-brief.md` and `pencil-design.md`
+- visual-adapter docs now state explicitly that `Visual Assist` does not replace form-factor-specific layout hygiene
+- prompt presets for mobile, tablet, desktop, and web now point to the form-factor-specific layout hygiene gate before screenshot review passes
+- Chinese documentation now matches the new layout-hygiene guidance instead of mixing untranslated preset instructions
+
 ## v0.1.13 - 2026-03-27
 
 ### Changed

package/README.md

@@ -27,7 +27,7 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.13`
+- `@xenonbyte/da-vinci-workflow@0.1.14`
 
 Release highlights:
 
@@ -35,6 +35,7 @@ Release highlights:
 - cross-platform near-name adapters such as `frontend-skill` and `frontend-design` are now treated as distinct unless the current environment explicitly resolves them
 - complex `redesign-from-code` runs now require a visual thesis, content plan, interaction thesis, and anchor-surface structural-delta notes before broad Pencil generation
 - screenshot review is now documented as a binding gate; analysis that reports hierarchy, spacing, clarity, or inconsistency issues cannot be treated as an automatic pass
+- form-factor-specific layout hygiene is now documented as a separate hard gate from `Visual Assist`, with blocker conditions for mobile, tablet, desktop, and web review
 - `.da-vinci/designs/` is now documented more strictly as a `.pen`-only directory, and project-local `.pen` persistence must be verified as shell-visible immediately after the first Pencil write
 - multi-surface redesign guidance now requires a shared primitive family to be defined from approved anchor surfaces before broad page expansion
 - Pencil generation guidance now explicitly rejects web-only properties such as `flex` and `margin`
@@ -116,6 +117,7 @@ Recommended default:
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -141,6 +143,7 @@ Quality-first redesign configuration:
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -158,8 +161,10 @@ Selection rules:
 
 - keep `ui-ux-pro-max` first for dense app and dashboard surfaces when the visual bar is moderate
 - move `frontend-skill` to the first slot when art direction, composition quality, and premium visual hierarchy matter more
+- write actual installed adapter names for the current environment instead of assuming cross-platform aliases
 - when `Preferred adapters` are configured, the resolved primary adapter should actively lead the first design pass instead of being recorded only for traceability
 - state the resolved primary adapter explicitly at runtime and name any requested adapters that are unavailable
+- treat form-factor-specific layout hygiene as a separate hard gate from `Visual Assist`; adapter choice does not override mobile/tablet/desktop/web review failures
 - do not assume cross-platform equivalence between near-name adapters
 - write a visual thesis, content plan, and interaction thesis before the first anchor surface
 - use Pencil guides as platform/buildability constraints, not as the main art-direction source

package/README.zh-CN.md

@@ -29,7 +29,7 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.13`
+- `@xenonbyte/da-vinci-workflow@0.1.14`
 
 已发布版本重点：
 
@@ -37,6 +37,7 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 - `frontend-skill`、`frontend-design` 这类跨平台近名 adapter 现在明确视为不同能力源，除非当前环境真的解析到了它们
 - 复杂 `redesign-from-code` 现在要求在大规模 Pencil 设计前先写 visual thesis、content plan、interaction thesis 和 anchor surface 的 structural-delta 说明
 - screenshot review 现在被明确强调为硬闸门；只要分析指出 hierarchy、spacing、clarity 或 inconsistency 问题，就不能自动判通过
+- form factor 专用的 layout hygiene 现在被定义成独立于 `Visual Assist` 的硬闸门，mobile、tablet、desktop、web 都有各自的 blocker 条件
 - `.da-vinci/designs/` 现在更明确只用于放 `.pen` 文件，而且第一次 Pencil 写入后就要验证对应 `.pen` 已经成为 shell 可见文件
 - 多 surface 重设计现在要求先从已通过的 anchor surface 中抽出 shared primitive family，再扩展更多页面
 - Pencil 生成规则现在明确拒绝 `flex`、`margin` 这类 Web 属性
@@ -121,6 +122,7 @@ Da Vinci V2 支持四种模式：
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -146,6 +148,7 @@ Da Vinci V2 支持四种模式：
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -163,8 +166,10 @@ Da Vinci V2 支持四种模式：
 
 - 高密度 app、dashboard、工具型界面，且视觉要求中等时，优先把 `ui-ux-pro-max` 放第一位
 - 如果更重视 art direction、构图和高级感，就把 `frontend-skill` 放第一位
+- `Preferred adapters` 里要写当前环境里真实存在的 adapter 名，不要默认套用跨平台别名
 - 一旦配置了 `Preferred adapters`，解析出来的主 adapter 应该真正主导首轮设计，而不是只登记在工件里
 - 运行时必须明确写出解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
+- form factor 专用的 layout hygiene 是独立于 `Visual Assist` 的硬闸门；adapter 选择不能覆盖 mobile、tablet、desktop、web 的版式失败条件
 - 不要默认把跨平台的近名 adapter 当成同一个能力源
 - 在第一个 anchor surface 之前，先写 visual thesis、content plan 和 interaction thesis
 - Pencil 的 guide 只应该约束平台布局和可实现性，不应该替代主 adapter 成为设计方向来源

package/SKILL.md

@@ -225,6 +225,7 @@ During active Pencil work:
 - after the first successful Pencil write, verify that the registered project-local `.pen` path exists as a shell-visible file before treating the design source as persistent
 - use only Pencil-supported properties; do not emit web- or CSS-only layout properties such as `flex` or `margin`
 - on complex redesigns, turn approved anchor surfaces into a small shared primitive family before broad page expansion
+- apply the resolved form-factor-specific layout hygiene profile before passing screenshot review on any anchor surface or other approval candidate
 - screenshot review is binding: if the review calls out hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues, revise the screen before treating the checkpoint as `PASS`
 
 ## Load References On Demand
@@ -235,6 +236,7 @@ Load only the reference that matches the current step:
 - Read `references/artifact-templates.md` when creating or updating workflow artifacts
 - Read `references/checkpoints.md` when running or reporting checkpoints
 - Read `references/design-inputs.md` when collecting product form factor, style, and constraints
+- Read `references/layout-hygiene.md` when screenshot review or the design checkpoint needs form-factor-specific layout hygiene rules
 - Read `references/page-mapping.md` when defining project pages, Pencil pages, and route-to-screen bindings
 - Read `references/pencil-design-to-code.md` when turning Pencil data into implementation
 - Read `references/platform-adapters.md` when guiding users on Codex, Claude, or Gemini invocation patterns

package/docs/prompt-presets/README.md

@@ -25,6 +25,7 @@ Design rule:
 
 - prompt presets define workflow intent, decomposition rules, and truth-source handling
 - visual-assist presets define UI-design helper preferences
+- form-factor-specific layout hygiene remains a separate hard gate that screenshot review must apply before a screen passes
 - use both together for the strongest result
 
 Each scene preset should now include:

package/docs/prompt-presets/desktop-app.md

@@ -46,6 +46,7 @@ Treat the resolved primary visual adapter as the first-pass design lead.
 Use Pencil guides only as workspace constraints, not as the design direction.
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
+Apply the form-factor-specific layout hygiene rules for desktop before passing screenshot review.
 Do not pass design checkpoint if the result is a repeated placeholder scaffold, flat panel soup, or a recolor of the old desktop shell.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```

package/docs/prompt-presets/mobile-app.md

@@ -50,6 +50,7 @@ Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout.
 Do not treat screenshot analysis as an automatic pass if it reports hierarchy, spacing, clarity, or inconsistency issues.
+Apply the form-factor-specific layout hygiene rules for mobile before passing screenshot review.
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.

package/docs/prompt-presets/tablet-app.md

@@ -46,6 +46,7 @@ Treat the resolved primary visual adapter as the first-pass design lead.
 Use Pencil guides only as tablet-layout constraints, not as the design direction.
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
+Apply the form-factor-specific layout hygiene rules for tablet before passing screenshot review.
 Do not pass design checkpoint if the result collapses into a stretched phone layout, repeated placeholders, or weak multi-region hierarchy.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```

package/docs/prompt-presets/web-app.md

@@ -47,6 +47,7 @@ Treat the resolved primary visual adapter as the first-pass design lead.
 Use Pencil guides only as responsive layout constraints, not as the design direction.
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
+Apply the form-factor-specific layout hygiene rules for web before passing screenshot review.
 Do not pass design checkpoint if the result is a generic SaaS card grid, repeated placeholder scaffolds, or a recolor of the old interface.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```

package/docs/visual-adapters.md

@@ -24,6 +24,11 @@ It must not redefine:
 
 Those still come from requirements, existing code, `page-map.md`, and `pencil-bindings.md`.
 
+Visual adapters also do not replace form-factor-specific layout-hygiene rules.
+
+- adapters shape art direction
+- layout hygiene decides whether a reviewed screen is structurally sound for its form factor
+
 ## Where To Configure It
 
 Configure visual-adapter preferences inside `DA-VINCI.md`.
@@ -49,6 +54,7 @@ Recommended shape:
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -71,6 +77,7 @@ Balanced default:
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -95,6 +102,7 @@ Quality-first redesign:
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -120,6 +128,7 @@ Use the fields like this:
 - `Scope`
   - the only areas where adapters are allowed to influence the workflow
   - keep this limited to presentation-quality work such as composition, spacing, and Pencil refinement
+  - include anchor-surface composition when the redesign depends on a strong first-pass visual direction
   - do not use this field to delegate behavior, routes, or state truth
 - `Fallback`
   - what Da Vinci should do if the preferred adapters are unavailable locally

package/docs/visual-assist-presets/README.md

@@ -20,6 +20,7 @@ If the project is design-critical or previous outputs were weak, generic, or too
 - consider `Require Adapter: true`
 - raise the design checkpoint bar before broad Pencil generation
 - switch to anchor-first generation: design 1-3 anchor surfaces, review screenshots, then expand
+- update `Preferred adapters` to the actual installed names for the current environment instead of assuming cross-platform aliases
 
 Available presets:
 
@@ -33,5 +34,6 @@ How to use them:
 1. choose the preset closest to the product surface
 2. copy the `## Visual Assist` block into `DA-VINCI.md`
 3. adjust adapter order only if the project clearly needs a different visual bias
-4. keep `Require Adapter: false` unless the project truly must stop without a specific local skill
-5. for complex redesigns, do not treat the preset alone as enough; pair it with anchor-first Pencil generation and screenshot review
+4. replace adapter names with the actual installed names for the current environment when they differ
+5. keep `Require Adapter: false` unless the project truly must stop without a specific local skill
+6. for complex redesigns, do not treat the preset alone as enough; pair it with anchor-first Pencil generation and screenshot review

package/docs/visual-assist-presets/desktop-app.md

@@ -21,6 +21,7 @@ Recommended `DA-VINCI.md` block:
   - workspace composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -31,6 +32,7 @@ Recommended `DA-VINCI.md` block:
 Notes:
 
 - prefer `ui-ux-pro-max` first for dense app layout decisions
+- replace adapter names with the actual installed names for the current environment when they differ
 - keep section hierarchy stronger than decorative treatment
 - use `frontend-skill` only as a secondary visual-quality helper, not as a marketing-style override
 - if the result looks flat, over-boxed, or too generic, move `frontend-skill` to the first slot and raise the design checkpoint bar

package/docs/visual-assist-presets/mobile-app.md

@@ -21,6 +21,7 @@ Recommended `DA-VINCI.md` block:
   - mobile page composition
   - hierarchy and spacing
   - touch-first motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -31,6 +32,7 @@ Recommended `DA-VINCI.md` block:
 Notes:
 
 - prefer `ui-ux-pro-max` first for app-surface density and control balance
+- replace adapter names with the actual installed names for the current environment when they differ
 - keep motion guidance light and purposeful
 - do not let the adapter turn routine mobile product UI into a marketing page
 - if the output keeps collapsing into generic cards or weak hierarchy, move `frontend-skill` to the first slot and consider `Require Adapter: true`

package/docs/visual-assist-presets/tablet-app.md

@@ -21,6 +21,7 @@ Recommended `DA-VINCI.md` block:
   - tablet page composition
   - hierarchy and spacing
   - touch-aware motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -31,6 +32,7 @@ Recommended `DA-VINCI.md` block:
 Notes:
 
 - keep spacing more generous than desktop but more structured than phone UI
+- replace adapter names with the actual installed names for the current environment when they differ
 - use adapter guidance to improve split layouts, canvases, and workspace balance
 - avoid over-compressing content into phone-like stacking
 - if the result still feels bland or over-framed, move `frontend-skill` to the first slot and require a stronger visual thesis before Pencil work

package/docs/visual-assist-presets/web-app.md

@@ -21,6 +21,7 @@ Recommended `DA-VINCI.md` block:
   - page composition
   - hierarchy and spacing
   - responsive motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -31,6 +32,7 @@ Recommended `DA-VINCI.md` block:
 Notes:
 
 - keep `ui-ux-pro-max` first for product surfaces, dashboards, and operational UI
+- replace adapter names with the actual installed names for the current environment when they differ
 - if the project is more brand-led than tool-led, swap the order and put `frontend-skill` first
 - do not let responsive polish erase product clarity
 - if the output feels like generic SaaS filler, switch `frontend-skill` to first and tighten the visual direction in `DA-VINCI.md`

package/docs/zh-CN/prompt-presets/README.md

@@ -25,6 +25,7 @@
 
 - 提示词模板负责定义工作流意图、拆分规则和真相源处理方式
 - `Visual Assist` 模板负责定义 UI 设计增强偏好
+- form factor 专用的 layout hygiene 仍然是独立硬闸门，screen 在通过 screenshot review 前必须应用对应规则
 - 两者一起使用，结果通常更稳
 
 现在每个场景模板里都固定包含：

package/docs/zh-CN/prompt-presets/desktop-app.md

@@ -46,6 +46,7 @@ Treat the resolved primary visual adapter as the first-pass design lead.
 Use Pencil guides only as workspace constraints, not as the design direction.
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
+在通过 screenshot review 之前，先应用桌面端专用的 form-factor layout hygiene 规则。
 Do not pass design checkpoint if the result is a repeated placeholder scaffold, flat panel soup, or a recolor of the old desktop shell.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```

package/docs/zh-CN/prompt-presets/mobile-app.md

@@ -50,6 +50,7 @@ Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout.
 Do not treat screenshot analysis as an automatic pass if it reports hierarchy, spacing, clarity, or inconsistency issues.
+在通过 screenshot review 之前，先应用移动端专用的 form-factor layout hygiene 规则。
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.

package/docs/zh-CN/prompt-presets/tablet-app.md

@@ -46,6 +46,7 @@ Treat the resolved primary visual adapter as the first-pass design lead.
 Use Pencil guides only as tablet-layout constraints, not as the design direction.
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
+在通过 screenshot review 之前，先应用平板端专用的 form-factor layout hygiene 规则。
 Do not pass design checkpoint if the result collapses into a stretched phone layout, repeated placeholders, or weak multi-region hierarchy.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```

package/docs/zh-CN/prompt-presets/web-app.md

@@ -47,6 +47,7 @@ Treat the resolved primary visual adapter as the first-pass design lead.
 Use Pencil guides only as responsive layout constraints, not as the design direction.
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
+在通过 screenshot review 之前，先应用 Web 专用的 form-factor layout hygiene 规则。
 Do not pass design checkpoint if the result is a generic SaaS card grid, repeated placeholder scaffolds, or a recolor of the old interface.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```

package/docs/zh-CN/visual-adapters.md

@@ -26,6 +26,11 @@ visual adapter 是可选的 presentation 质量增强层。
 
 这些仍然由 requirements、existing code、`page-map.md` 和 `pencil-bindings.md` 决定。
 
+visual adapter 也不能替代按 form factor 执行的 layout hygiene 规则。
+
+- adapter 负责 art direction
+- layout hygiene 负责判断当前 screen 对于其 form factor 是否结构上合格
+
 ## 应该配置在哪里
 
 把 visual adapter 偏好写在 `DA-VINCI.md` 里。
@@ -51,6 +56,7 @@ visual adapter 是可选的 presentation 质量增强层。
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -73,6 +79,7 @@ visual adapter 是可选的 presentation 质量增强层。
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -97,6 +104,7 @@ visual adapter 是可选的 presentation 质量增强层。
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -122,6 +130,7 @@ visual adapter 是可选的 presentation 质量增强层。
 - `Scope`
   - adapter 被允许影响的范围
   - 应该限制在构图、层级、spacing、Pencil refinement 这类 presentation 质量问题
+  - 当重设计高度依赖首轮视觉质量时，也应该把 anchor-surface composition 明确写进 `Scope`
   - 不要把 behavior、route、state truth 交给它
 - `Fallback`
   - 当本地没有可用 adapter 时应该怎么处理

package/docs/zh-CN/visual-assist-presets/README.md

@@ -20,6 +20,7 @@
 - 视情况把 `Require Adapter` 改成 `true`
 - 在大规模 Pencil 设计前先把 design checkpoint 门槛抬高
 - 改成 anchor-first：先做 1 到 3 个 anchor surface，截图审查通过后再扩展
+- 把 `Preferred adapters` 改成当前环境里真实存在的 adapter 名，不要默认沿用跨平台别名
 
 可用模板：
 
@@ -32,6 +33,7 @@
 
 1. 先选最接近当前产品形态的模板
 2. 把其中的 `## Visual Assist` 片段复制到 `DA-VINCI.md`
-3. 只有在项目真的有不同视觉偏向时才调整 adapter 顺序
-4. 除非确实“没有某个本地 skill 就不能继续”，否则保持 `Require Adapter: false`
-5. 如果是复杂重设计，不要只复制 preset 就开画；还要配合 anchor-first 的 Pencil 生成策略
+3. 如果当前环境里的 adapter 名不同，先把 `Preferred adapters` 改成真实可用名称
+4. 只有在项目真的有不同视觉偏向时才调整 adapter 顺序
+5. 除非确实“没有某个本地 skill 就不能继续”，否则保持 `Require Adapter: false`
+6. 如果是复杂重设计，不要只复制 preset 就开画；还要配合 anchor-first 的 Pencil 生成策略

package/docs/zh-CN/visual-assist-presets/desktop-app.md

@@ -18,6 +18,7 @@
   - workspace composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -28,5 +29,6 @@
 说明：
 
 - 优先用 `ui-ux-pro-max` 做高密度 app 布局判断
+- 如果当前环境里的 adapter 名不一样，先改成真实可用名称
 - `frontend-skill` 更适合作为辅助，不要反过来把工具界面做成营销页
 - 如果结果太平、太盒子化、太像通用后台，就把 `frontend-skill` 调到第一位，并提高 design checkpoint 的要求

package/docs/zh-CN/visual-assist-presets/mobile-app.md

@@ -17,6 +17,7 @@
   - mobile page composition
   - hierarchy and spacing
   - touch-first motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -27,5 +28,6 @@
 说明：
 
 - `ui-ux-pro-max` 更适合移动端 app 表面的密度和平衡
+- 如果当前环境里的 adapter 名不一样，先改成真实可用名称
 - motion 要轻，不要把普通 app 页面做成营销页
 - 如果结果总是变成泛化卡片堆砌或层级太弱，就把 `frontend-skill` 调到第一位，并考虑把 `Require Adapter` 改成 `true`

package/docs/zh-CN/visual-assist-presets/tablet-app.md

@@ -17,6 +17,7 @@
   - tablet page composition
   - hierarchy and spacing
   - touch-aware motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -27,5 +28,6 @@
 说明：
 
 - spacing 一般要比手机更舒展，但又不能像桌面端那样过密
+- 如果当前环境里的 adapter 名不一样，先改成真实可用名称
 - 更适合用 adapter 去辅助分栏、画布区和主次区域的平衡
 - 如果结果还是寡淡或被边框框死，就把 `frontend-skill` 调到第一位，并要求在 Pencil 设计前先写清楚 visual thesis

package/docs/zh-CN/visual-assist-presets/web-app.md

@@ -18,6 +18,7 @@
   - page composition
   - hierarchy and spacing
   - responsive motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -28,5 +29,6 @@
 说明：
 
 - 如果是典型 product UI，优先 `ui-ux-pro-max`
+- 如果当前环境里的 adapter 名不一样，先改成真实可用名称
 - 如果页面更偏品牌表达或强视觉，可以把 `frontend-skill` 放前面
 - 如果结果像很普通的 SaaS 模板，就把 `frontend-skill` 提到第一位，并把 `DA-VINCI.md` 的视觉方向写得更具体

package/examples/greenfield-spec-markupflow/DA-VINCI.md

@@ -42,6 +42,7 @@
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci

package/examples/greenfield-spec-markupflow/README.md

@@ -40,7 +40,10 @@ Live design source used for this forward test:
 Visual adapter used for this forward test:
 
 - requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- available requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- unavailable requested adapters: none
 - resolved primary adapter: `frontend-skill`
+- runtime declaration: explicit before first anchor pass
 - fallback: `native-da-vinci` if no local adapter were available
 
 Important note:

package/examples/greenfield-spec-markupflow/design-registry.md

@@ -10,9 +10,12 @@
 
 ## Visual Adapter Resolution
 - Requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- Available requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- Unavailable requested adapters: none
 - Resolved primary adapter: `frontend-skill`
 - Secondary helpers: none
 - Status: active
+- Runtime declaration: explicitly stated before first anchor pass
 - Scope: `DA-VINCI.md`, `design.md`, `pencil-design.md`
 - Fallback reason if native Da Vinci rules were used: none
 

package/examples/greenfield-spec-markupflow/pencil-design.md

@@ -8,8 +8,12 @@
   - `MarkupFlow Product Detail`
 
 ## Visual Adapter Use
+- Available requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- Unavailable requested adapters: none
 - Resolved primary adapter: `frontend-skill`
 - Secondary helpers: none
+- Whether runtime execution explicitly declared the resolved primary adapter: yes
+- Whether the primary adapter actively led the first-pass composition: yes
 - How it affected composition, hierarchy, or motion guidance:
   - stronger hero anchor for the desktop-product story
   - restrained panel treatment instead of generic card grids

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js"

package/references/artifact-templates.md

@@ -175,8 +175,8 @@ Use this structure:
 
 Field meaning:
 
-- `Preferred adapters`: desired local-skill priority order
-- `Scope`: allowed presentation-quality influence areas only
+- `Preferred adapters`: desired local-skill priority order using adapter names that actually exist in the current environment
+- `Scope`: allowed presentation-quality influence areas only, including anchor-surface composition when redesign quality matters
 - `Fallback`: what to do when preferred adapters are unavailable
 - `Require Adapter`: whether missing adapters should block the workflow
 
@@ -214,6 +214,11 @@ Use this structure:
 - workspace density
 - responsiveness expectations
 
+## Layout Hygiene Profile
+- Resolved profile: mobile / tablet / desktop / web
+- Per-surface overrides when mixed product surfaces require them
+- Blocker classes to watch during screenshot review
+
 ## Notes
 - explicit user preferences
 - inferred preferences
@@ -483,7 +488,9 @@ Use this structure:
 - Which 1-3 anchor screens were designed first
 - Structural-delta summary for each anchor surface
 - Screenshot review status for each anchor
+- Applied layout-hygiene profile for each reviewed anchor surface
 - Whether screenshot review found hierarchy, spacing, clarity, or inconsistency issues
+- Whether screenshot review found blocker-level layout-hygiene issues
 - Whether each anchor was revised after screenshot review
 - Whether broad multi-screen expansion is approved yet
 

package/references/checkpoints.md

@@ -48,6 +48,7 @@ Check:
 - the active mode is correct
 - the starting material is stable enough to write specs
 - product form factor and visual direction are known, inferred, or explicitly deferred
+- the form factor is specific enough to resolve the active layout-hygiene profile before screenshot review begins
 - candidate pages or current pages are clear enough to move into `page-map.md`
 - open questions are explicitly tracked
 - workflow artifacts are being written to standard locations, especially keeping `.da-vinci/designs/` for `.pen` files rather than markdown notes
@@ -101,6 +102,7 @@ Check:
 - when a primary adapter is active, the workflow wrote a visual thesis, content plan, and interaction thesis before broad anchor-surface generation
 - complex redesigns have 1-3 fully composed anchor surfaces reviewed before broad multi-screen expansion
 - each anchor surface includes a short explanation of how its composition differs structurally from the current layout truth
+- the relevant form-factor-specific layout-hygiene profile was applied to each reviewed anchor surface and any other screen being treated as approval-ready
 - each page has a clear visual anchor or primary working surface
 - section hierarchy is readable without relying on decorative chrome
 - the design does not collapse into generic card-grid or border-heavy filler UI
@@ -122,6 +124,7 @@ Automatic failures:
 - if more than roughly 20% of a screen's primary content area is unresolved placeholder scaffolding, treat the design checkpoint as `BLOCK`
 - if multiple screens are effectively the same scaffold with title changes, treat the design checkpoint as `BLOCK`
 - if screenshot review or image analysis calls out hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues and the workflow marks the screen as passed without revision, treat the design checkpoint as `BLOCK`
+- if any blocker-level condition from the active form-factor-specific layout-hygiene profile is present on a reviewed screen, treat the design checkpoint as `BLOCK`
 - if a redesign screen materially mirrors the current XML grouping with only recolor, spacing tweaks, or minor rearrangement, treat the design checkpoint as `BLOCK`
 
 ## `design-source checkpoint`

package/references/design-inputs.md

@@ -72,6 +72,11 @@ Collect or infer:
    - whether adapter use is required or optional
    - fallback expectation when adapters are unavailable
 
+6. layout hygiene profile
+   - resolved from the product form factor
+   - per-surface override only when the product intentionally mixes different surface classes
+   - blocker classes that must fail screenshot review
+
 ## Inference Order
 
 Infer in this order:
@@ -97,6 +102,8 @@ Examples:
 
 Write stable answers into `design-brief.md`.
 
+Record the resolved layout-hygiene profile there as well, including any intentional per-surface overrides for mixed products.
+
 If `DA-VINCI.md` did not already exist, generate it from those stable answers and save it as the project visual baseline.
 
 If Pencil creates or updates a baseline during the workflow:

package/references/layout-hygiene.md

@@ -0,0 +1,117 @@
+# Layout Hygiene
+
+Use this reference when screenshot review or the design checkpoint needs form-factor-specific layout hygiene rules.
+
+This layer is separate from `Visual Assist`.
+
+- visual adapters decide art direction and composition quality
+- layout hygiene decides whether a screen is structurally healthy enough to expand or implement
+
+## Resolution Rule
+
+Apply exactly one primary hygiene profile to each reviewed surface:
+
+1. mobile
+2. tablet
+3. desktop
+4. web
+
+Use the resolved project form factor from `DA-VINCI.md`, `design-brief.md`, or stable codebase signals.
+
+For mixed products:
+
+- apply the dominant profile per surface
+- record surface-specific exceptions in `design-brief.md` or `pencil-design.md`
+
+## Generic Checks
+
+Apply these checks to every reviewed surface:
+
+- no clipped or edge-colliding primary content
+- no unexplained whitespace bands that break the screen's visual balance
+- a clear dominant working surface or anchor
+- aligned top-chrome rhythm across related screens
+- spacing rhythm that does not bunch one region while leaving another region visually empty
+- screenshot review findings must be interpreted, not treated as an automatic pass
+
+## Severity
+
+Use these result levels:
+
+- `PASS`
+  - no blocker-level hygiene failure is present
+- `WARN`
+  - minor spacing, rhythm, or proportion issues exist, but the screen is still structurally coherent
+- `BLOCK`
+  - any blocker-level hygiene failure exists
+  - or screenshot analysis reports hierarchy, spacing, clarity, inconsistency, clipping, or unresolved-placeholder issues and the screen is not revised
+
+## Mobile
+
+Use for phone-first app screens.
+
+Check:
+
+- top inset and safe-area rhythm are respected unless the screen is intentionally full-bleed
+- the first content band does not begin flush against the top edge without a clear chrome strategy
+- the main task area is vertically balanced against top chrome and bottom actions
+- bottom trays and action rows do not crowd the main content
+- header and title start lines are consistent across related screens
+
+Treat as `BLOCK` when:
+
+- top content is visibly pinned to the edge without an intentional full-bleed reason
+- a large unexplained void appears above or within the primary task area
+- a bottom action tray compresses the main task area into an obviously cramped strip
+- related anchor screens use incompatible top-chrome alignment systems
+
+## Tablet
+
+Use for tablet-first flows or tablet-dominant surfaces.
+
+Check:
+
+- panes, canvases, and supporting rails use intentional proportions
+- gutters are consistent across primary and secondary regions
+- the screen is not just a stretched phone layout
+- primary and secondary regions have a clear weight relationship
+
+Treat as `BLOCK` when:
+
+- one side of the screen is heavily compressed while another side is mostly empty without purpose
+- pane ratios feel accidental or unstable
+- the layout is essentially a phone stack widened onto a tablet canvas
+
+## Desktop
+
+Use for desktop software and dense workspaces.
+
+Check:
+
+- toolbar, sidebar, workspace, and inspector edges align to a coherent system
+- the main workspace visibly owns the screen
+- panels feel attached to a layout system instead of floating independently
+- chrome height and content start lines are consistent between related screens
+
+Treat as `BLOCK` when:
+
+- the workspace does not read as the dominant region
+- panels feel like disconnected boxed islands or floating soup
+- top chrome and content starts drift enough to make related screens feel structurally inconsistent
+
+## Web
+
+Use for browser-based product UI and marketing/product hybrids.
+
+Check:
+
+- header plus first viewport content fit within a coherent viewport budget
+- max-width and gutters are disciplined
+- responsive behavior does not collapse hierarchy
+- the first impression is not a generic card pile
+
+Treat as `BLOCK` when:
+
+- header plus hero or workspace visibly overruns the initial viewport without intent
+- gutters or max-width rules drift enough to break hierarchy
+- breakpoint changes turn the screen into a generic stacked-card filler layout