@xenonbyte/da-vinci-workflow 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -4,6 +4,26 @@
 
 - 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
+- visual-adapter execution now requires explicit runtime declaration of the resolved primary adapter, available and unavailable requested adapters, and pre-anchor thesis writing instead of relying on artifact metadata alone
+- redesign guidance now requires anchor-surface structural-delta notes, shared primitives before broad page expansion, and screenshot review that cannot auto-pass when analysis reports hierarchy, spacing, clarity, or inconsistency issues
+- `.da-vinci/designs/` is now documented more strictly as a `.pen`-only directory, and design-source guidance now expects shell-visible `.pen` persistence immediately after the first successful Pencil write
+- Pencil workflow guidance now explicitly rejects web-only properties such as `flex` and `margin`, and platform-adapter docs now warn against assuming cross-platform equivalence between near-name visual adapters
+
 ## v0.1.12 - 2026-03-27
 
 ### Changed

package/README.md

@@ -27,10 +27,18 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.12`
+- `@xenonbyte/da-vinci-workflow@0.1.14`
 
 Release highlights:
 
+- visual-adapter execution now requires explicit runtime declaration of the resolved primary adapter and any unavailable requested adapters
+- 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`
 - visual-adapter resolution now requires the resolved primary adapter to actively lead the first design pass
 - complex redesigns now default to anchor-first Pencil generation: design 1-3 anchor surfaces, review screenshots, then expand
 - design checkpoint now explicitly blocks placeholder-heavy repeated scaffolds and premature broad multi-screen generation
@@ -109,6 +117,7 @@ Recommended default:
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -134,6 +143,7 @@ Quality-first redesign configuration:
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -151,9 +161,19 @@ 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
 - on complex redesigns, design 1-3 anchor surfaces first and review screenshots before broad multi-screen generation
+- for each anchor surface, explain how the new composition differs structurally from the current layout
+- do not auto-pass screenshot review when analysis reports hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues
+- define shared primitives from the approved anchor surfaces before broad page expansion
+- keep `.da-vinci/designs/` reserved for `.pen` files only and verify the registered `.pen` path is shell-visible after the first Pencil write
+- use only Pencil-supported properties; do not rely on web-only props such as `flex` or `margin`
 - keep `Fallback: native-da-vinci` unless you explicitly want missing adapters to block the workflow
 - keep `Require Adapter: false` by default and raise it to `true` only for design-critical work
 - keep `Scope` limited to presentation quality; do not use it to delegate behavior, routes, or state truth

package/README.zh-CN.md

@@ -29,10 +29,18 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.12`
+- `@xenonbyte/da-vinci-workflow@0.1.14`
 
 已发布版本重点：
 
+- visual adapter 的执行现在要求在运行时明确声明解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
+- `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 属性
 - visual adapter 解析现在要求“解析出来的主 adapter 必须真正主导首轮设计”，而不是只登记在工件里
 - 复杂重设计现在默认采用 anchor-first 的 Pencil 生成策略：先做 1 到 3 个 anchor surface，截图审查后再扩展
 - design checkpoint 现在会明确拦截大量空占位、重复模板和过早的大批量多页面脚手架
@@ -114,6 +122,7 @@ Da Vinci V2 支持四种模式：
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -139,6 +148,7 @@ Da Vinci V2 支持四种模式：
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -156,9 +166,19 @@ 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 成为设计方向来源
 - 面对复杂重设计时，先做 1 到 3 个 anchor surface，并完成截图审查，再扩展到更多页面
+- 对每个 anchor surface，都要说明“新的构图和当前布局结构相比，具体改了什么”
+- 如果截图分析指出 hierarchy、spacing、clarity、inconsistency 或 unresolved placeholder 问题，就不能自动判通过
+- 在扩展更多页面前，先从已通过的 anchor surface 中抽出 shared primitives
+- `.da-vinci/designs/` 只应该放 `.pen` 文件，并且第一次 Pencil 写入后就要验证登记路径已经成为 shell 可见文件
+- 只使用 Pencil 支持的属性，不要继续使用 `flex`、`margin` 这类 Web 属性
 - 默认保留 `Fallback: native-da-vinci`
 - `Require Adapter` 默认保持 `false`，只有设计要求很高时再改成 `true`
 - `Scope` 只管 presentation 质量，不要拿它去定义 behavior、route 或 state truth

package/SKILL.md

@@ -185,7 +185,10 @@ Do not repeatedly ask for inputs that are already stable in the artifacts.
 Treat visual adapters as optional design-assist layers.
 
 - resolve them from the user request first, then `DA-VINCI.md`, then locally available skills
+- do not assume cross-platform equivalence between near-name adapters such as `frontend-skill` and `frontend-design`; only resolve adapters that are explicitly named and actually installed in the current environment
+- record which requested adapters were available, which were unavailable, and which adapter became the resolved primary adapter
 - when `DA-VINCI.md` or the request declares `Preferred adapters`, the resolved primary adapter must actively lead first-pass design reasoning instead of being recorded only for traceability
+- when a resolved primary adapter is available, state that runtime resolution explicitly before the first anchor-screen design pass and let it drive the visual thesis, content plan, and interaction thesis
 - use them to improve visual contract quality, composition, hierarchy, spacing, and motion guidance
 - use Pencil guides and platform constraints as buildability aids only; they must not replace the resolved primary adapter as the art-direction source
 - do not let them redefine behavior, page truth, route truth, or acceptance rules
@@ -213,6 +216,18 @@ Default completion rule:
 - if the request is `design-only`, stop after design artifacts and bindings
 - otherwise assume `full-delivery` and continue through implementation and verification
 
+## Pencil Generation Rules
+
+During active Pencil work:
+
+- keep `.da-vinci/designs/` reserved for project-local `.pen` files; do not write workflow markdown such as inventories, proposals, or checkpoints into that directory
+- on `redesign-from-code`, write a short structural-delta note for each anchor surface explaining how the new composition differs from the current XML or layout grouping
+- 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
 
 Load only the reference that matches the current step:
@@ -221,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/commands/claude/da-vinci.md

@@ -22,6 +22,9 @@ Notes:
 - Requirements decide behavior.
 - Pencil decides presentation.
 - Code must follow both.
+- If `Visual Assist` is configured, resolve and state the actual primary visual adapter for this environment instead of assuming cross-platform skill equivalence.
+- Keep `.da-vinci/designs/` reserved for `.pen` files only.
+- On complex redesigns, design 1-3 anchor surfaces first and treat screenshot review as a binding gate before broad expansion.
 - Use `intake` when the user needs help phrasing the first workflow request.
 - Use `continue` when `.da-vinci/` artifacts already exist and the workflow must resume.
 - Keep workflow semantics shared across Codex, Claude, and Gemini.

package/commands/codex/prompts/da-vinci.md

@@ -21,6 +21,9 @@ Available routes:
 
 Important:
 - Treat `/prompts:*` as action selectors in Codex.
+- If `Visual Assist` is configured, resolve and state the actual primary visual adapter for this environment instead of assuming cross-platform skill equivalence.
+- Keep `.da-vinci/designs/` reserved for `.pen` files only.
+- On complex redesigns, design 1-3 anchor surfaces first and treat screenshot review as a binding gate before broad expansion.
 - Use `intake` when the user does not know how to phrase the first request.
 - Use `continue` when `.da-vinci/` artifacts already exist and the workflow must resume.
 - If details are still needed after route selection, provide them in the next message.

package/commands/gemini/da-vinci.toml

@@ -24,6 +24,9 @@ Notes:
 - Requirements decide behavior.
 - Pencil decides presentation.
 - Code must follow both.
+- If `Visual Assist` is configured, resolve and state the actual primary visual adapter for this environment instead of assuming cross-platform skill equivalence.
+- Keep `.da-vinci/designs/` reserved for `.pen` files only.
+- On complex redesigns, design 1-3 anchor surfaces first and treat screenshot review as a binding gate before broad expansion.
 - Use `intake` when the user needs help phrasing the first workflow request.
 - Use `continue` when `.da-vinci/` artifacts already exist and the workflow must resume.
 - Keep workflow semantics shared across Claude, Codex, and Gemini.

package/docs/mode-use-cases.md

@@ -42,6 +42,7 @@ Rule:
 - only `DA-VINCI.md` belongs at the project root
 - all other workflow outputs should stay under `.da-vinci/`
 - persisted project-local Pencil files should stay under `.da-vinci/designs/`
+- `.da-vinci/designs/` should contain `.pen` files only, not workflow markdown
 
 ## Quick mode selection
 
@@ -324,9 +325,11 @@ Register the design sources, extract DA-VINCI.md from them, bind covered pages,
 
 6. create or update `pencil-design.md`
    - build the new redesign baseline in Pencil
+   - write the visual thesis, content plan, interaction thesis, and structural-delta notes before broad anchor generation
    - design 1-3 anchor surfaces first before broad multi-screen expansion
    - let the resolved primary visual adapter lead that first pass
    - persist that baseline into the registered `.da-vinci/designs/` file
+   - verify that registered `.pen` path is shell-visible immediately after the first successful Pencil write
 
 7. create or update `pencil-bindings.md`
    - bind pages to redesign screens
@@ -342,9 +345,16 @@ Register the design sources, extract DA-VINCI.md from them, bind covered pages,
 ### Critical rule in this mode
 
 - treat the resolved primary visual adapter as the first-pass design lead when `Preferred adapters` are configured
+- state the resolved primary adapter explicitly at runtime, including which requested adapters were unavailable
+- do not assume cross-platform equivalence between near-name adapters; resolve the installed adapter names for the current environment
+- when a primary adapter is active, write the visual thesis, content plan, and interaction thesis before the first anchor screen
 - do not let Pencil guides or generic style packs replace that adapter as the art-direction source
 - do not start broad redesign work by scaffolding many empty screens
 - for complex products, get 1-3 anchor surfaces through screenshot review before expanding the rest of the redesign
+- for each anchor surface, explain briefly how the new composition differs from the current layout grouping
+- do not auto-pass screenshot review if the analysis reports hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues
+- define a small shared primitive family from the approved anchor surfaces before broad page expansion
+- use only Pencil-supported properties; do not rely on web-only props such as `flex` or `margin`
 
 For redesign work:
 
@@ -362,6 +372,7 @@ Fresh-layout rule:
 Project-local `.pen` rule:
 
 - the preferred `.pen` path in `design-registry.md` is owned by the workflow, not by user hand-editing
+- keep `.da-vinci/designs/` reserved for `.pen` files rather than workflow markdown
 - do not keep redesign work inside an unrelated active Pencil editor just because it is currently open
 - if Pencil MCP does not materialize the registered shell-visible file automatically, reconstruct and write that `.pen` file before mapping or implementation is treated as complete
 

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

@@ -43,9 +43,18 @@ Inventory activities, fragments, tabs, dialogs, bottom sheets, nested flows, ove
 Decompose complex screens into subpages, overlays, materially different states, and implementation surfaces.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
+State the resolved primary visual adapter explicitly in the log and name any requested adapters that are unavailable.
+Before the first anchor surface, write a visual thesis, content plan, and interaction thesis.
 Use Pencil guides only as 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.
+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/`.
+Define shared primitives from the approved anchor surfaces before broad page expansion.
 Do not pass design checkpoint if the result is a skin-swap of the old UI, a generic card grid, repeated placeholder templates, or weak visual anchors.
 Persist project-local Pencil files under .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
@@ -116,9 +124,11 @@ Use the fields like this:
   - the priority list of local skills you want Da Vinci to try first
   - order matters
   - if multiple listed skills are available, Da Vinci should still resolve one primary adapter
+  - do not assume cross-platform equivalence between near-name adapters such as `frontend-skill` and `frontend-design`; resolve the actual installed adapter names for the current environment
 - `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
@@ -178,9 +188,12 @@ Recommended fields:
 ```md
 ## Visual Adapter Resolution
 - Requested adapters: frontend-skill, ui-ux-pro-max
+- Available requested adapters: frontend-skill
+- 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
 ```
@@ -203,6 +216,8 @@ When a visual adapter is active:
 
 - use it before or during Pencil work to sharpen composition and hierarchy
 - treat the resolved primary adapter as the art-direction lead for the first pass, not as a note that merely gets copied into `design-registry.md`
+- explicitly state the resolved primary adapter in the runtime log before the first anchor-screen pass
+- write a visual thesis, content plan, and interaction thesis before the first anchor-screen pass under that adapter's lead
 - keep page names and states aligned with `page-map.md`
 - keep final `.pen` decisions grounded in Pencil, not in adapter prose
 
@@ -211,7 +226,10 @@ For complex redesigns:
 - do not start by scaffolding many screens with empty placeholders
 - design 1-3 anchor surfaces first
 - make each anchor surface fully composed before broad expansion
+- for each anchor surface, explain briefly how the new composition differs structurally from the current layout
 - use screenshot review on each anchor surface before cloning variants or expanding the rest of the product
+- do not treat screenshot analysis as an automatic pass; if the review flags hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues, revise before expanding
+- define a small shared primitive family from the approved anchor surfaces before broad page expansion
 - if the output is still placeholder-heavy or repetitious, mark `design checkpoint` as `BLOCK` and reset from the anchor surfaces instead of layering more screens on top
 
 Record the outcome in `pencil-design.md`.

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/workflow-examples.md

@@ -80,11 +80,13 @@ Expected flow:
 4. define redesign scope in `proposal.md`
 5. split broad redesign work into `specs/<slice>/spec.md` files when one large `ui-refresh` spec would be too coarse
 6. rebuild or refine `page-map.md`, including subpages, overlays, and materially different states
-7. create new or updated Pencil pages from fresh composition rather than a recolor of the old UI, preferring persistence under `.da-vinci/designs/`
-8. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
-9. bind routes and pages to Pencil screens
-10. generate tasks aligned to the redesign slices
-11. build and verify
+7. write the visual thesis, content plan, interaction thesis, and structural-delta notes for the anchor surfaces
+8. create new or updated Pencil pages from fresh composition rather than a recolor of the old UI, preferring persistence under `.da-vinci/designs/`
+9. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
+10. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
+11. bind routes and pages to Pencil screens
+12. generate tasks aligned to the redesign slices
+13. build and verify
 
 ### Complex Android example
 
@@ -95,8 +97,16 @@ Existing code is the behavior source of truth, not the layout truth.
 Inventory activities, fragments, tabs, dialogs, bottom sheets, nested flows, and important states.
 Decompose complex screens into separate design surfaces before Pencil work.
 Use frontend-skill explicitly as the primary visual reasoning source.
+State the resolved primary visual adapter explicitly in the log before the first anchor surface.
+Write a visual thesis, content plan, and interaction thesis before the first anchor surface.
+Use Pencil guides only as 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.
+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.
+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 `.da-vinci/designs/` reserved for `.pen` files only.
 Do not pass design checkpoint if the result is just a skin-swap of the old UI.
 ```
 

package/docs/zh-CN/mode-use-cases.md

@@ -35,6 +35,7 @@ project/
 - `DA-VINCI.md` 放根目录
 - 其他工作流工件放 `.da-vinci/`
 - 项目内持久化的 Pencil `.pen` 文件默认放 `.da-vinci/designs/`
+- `.da-vinci/designs/` 里只应该放 `.pen` 文件，不应该混入工作流 markdown
 
 ## 快速选 mode
 
@@ -134,9 +135,11 @@ Da Vinci 应该：
    - 把复杂页面拆成 subpage、state、overlay、fragment surface
 7. 生成 `design.md`
 8. 生成 `pencil-design.md`
+   - 在大规模 anchor 设计前，先写 visual thesis、content plan、interaction thesis 和 structural-delta 说明
    - 先做 1 到 3 个 anchor surface，再扩展更多页面
    - 首轮设计由解析出来的主 visual adapter 主导
    - 把新的 Pencil 基线真正落到登记好的 `.da-vinci/designs/` 路径
+   - 在第一次成功写入 Pencil 后，立即验证登记的 `.pen` 路径已经成为 shell 可见文件
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
 11. 进入实现
@@ -147,13 +150,21 @@ Da Vinci 应该：
 - `redesign-from-code` 默认应该基于页面职责和状态重新构图
 - 不能把“旧页面换个配色、换点间距、挪一点位置”当成真正的重设计
 - 一旦配置了 `Preferred adapters`，解析出来的主 adapter 应该主导首轮设计，而不是只登记不使用
+- 运行时必须明确声明解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
+- 不要把跨平台的近名 adapter 默认当成同一个能力源，应该按当前环境里真实安装的名字解析
+- 当主 adapter 生效时，先写 visual thesis、content plan 和 interaction thesis，再开始第一个 anchor screen
 - 不要让 Pencil 的 guide 或样式模板取代主 adapter 成为设计方向来源
 - 不要一上来就批量搭很多空 screen
 - 对复杂产品，先把 1 到 3 个 anchor surface 做到通过截图审查，再扩展其他页面
+- 对每个 anchor surface，都要说明“新的构图与当前布局结构相比具体改了什么”
+- 只要截图分析指出 hierarchy、spacing、clarity、inconsistency 或 unresolved placeholder 问题，就不能自动判通过
+- 在扩展更多页面前，先从已通过的 anchor surface 中抽出一组 shared primitives
+- 只使用 Pencil 支持的属性，不要继续使用 `flex`、`margin` 这类 Web/CSS 属性
 - 一个实现页如果包含多个 Fragment、多个 tab、多个状态或多个 overlay，应该拆成多个设计 surface
 - `design-registry.md` 里的首选 `.pen` 路径由工作流自动维护，不应该依赖用户手工填写
 - 不要因为当前 Pencil 里正好打开了一个文档，就直接在那个文档上继续做重设计
 - 如果 Pencil MCP 没有自动把登记路径的 `.pen` 文件落到磁盘，就应该先补写这个项目内文件，再把 mapping 或 implementation 视为完成
+- `.da-vinci/designs/` 应该只作为 `.pen` 目录使用，不应该混入 inventory、proposal 之类的 markdown
 
 ## 4. `feature-change`
 

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

@@ -43,9 +43,18 @@ Inventory activities, fragments, tabs, dialogs, bottom sheets, nested flows, ove
 Decompose complex screens into subpages, overlays, materially different states, and implementation surfaces.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
+State the resolved primary visual adapter explicitly in the log and name any requested adapters that are unavailable.
+Before the first anchor surface, write a visual thesis, content plan, and interaction thesis.
 Use Pencil guides only as 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.
+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/`.
+Define shared primitives from the approved anchor surfaces before broad page expansion.
 Do not pass design checkpoint if the result is a skin-swap of the old UI, a generic card grid, repeated placeholder templates, or weak visual anchors.
 Persist project-local Pencil files under .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/.
 ```