@xenonbyte/da-vinci-workflow 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 - No unreleased changes yet.
 
+## v0.1.10 - 2026-03-27
+
+### Changed
+- `redesign-from-code` now documents a stricter contract: existing code is behavior truth, not layout truth
+- complex screens are now documented to decompose into subpages, overlays, materially different states, and implementation surfaces before broad Pencil redesign
+- design-checkpoint guidance now explicitly blocks skin-swap redesigns, generic card mosaics, weak visual anchors, and decorative clutter
+- `Visual Assist` documentation and README guidance now include clearer field explanations, quick-start recommendations, quality-first configuration advice, and stronger usage examples for Android-style redesign work
+
 ## v0.1.9 - 2026-03-27
 
 ### Added

package/README.md

@@ -27,10 +27,14 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.9`
+- `@xenonbyte/da-vinci-workflow@0.1.10`
 
 Release highlights:
 
+- `redesign-from-code` now states explicitly that existing code is behavior truth, not layout truth
+- complex pages are now expected to decompose into subpages, overlays, materially different states, and implementation surfaces before broad Pencil redesign
+- design-checkpoint guidance now explicitly blocks skin-swap redesigns, generic card mosaics, weak visual anchors, and decorative clutter
+- `Visual Assist` docs now include quick-start recommendations and a quality-first configuration for design-critical work
 - visual-adapter configuration is now documented explicitly, including field meanings, resolution order, and fallback behavior
 - ready-to-copy `Visual Assist` presets are now included for mobile, desktop, web, and tablet scenarios
 - the repo-local forward test now shows how `Visual Assist`, adapter resolution, and persisted `.pen` paths should be recorded
@@ -86,6 +90,67 @@ Route discipline:
 - they should not default the user into `build`
 - `build` remains a direct expert route for workflows that are already implementation-ready
 
+## Visual Assist Quick Start
+
+Use `Visual Assist` when the project wants optional help from local UI-design skills such as `frontend-skill` or `ui-ux-pro-max`.
+
+Recommended default:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+Use this when:
+
+- the project is an app, dashboard, desktop tool, or other product surface
+- the workflow should continue even if no local adapter is installed
+- you want better composition and hierarchy without turning adapter availability into a blocker
+
+Quality-first redesign configuration:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - frontend-skill
+  - ui-ux-pro-max
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+```
+
+Use this when:
+
+- the project is visually sensitive and plain fallback quality is not acceptable
+- prior redesign attempts drifted into generic card grids, weak anchors, or skin-swap outputs
+- you want the workflow to stop instead of silently continuing without a strong local design helper
+
+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
+- 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
+
 ## Core workflow
 
 Da Vinci runs in this order:
@@ -232,6 +297,8 @@ Rules:
 - `.da-vinci/designs/` is the default project-local location for persisted `.pen` files
 - `page-map.md` is the source of truth for implementation pages
 - `pencil-bindings.md` is the source of truth for implementation page -> Pencil page mapping
+- in `redesign-from-code`, existing code is behavior truth, not layout truth
+- complex pages should be decomposed into subpages, states, overlays, and implementation surfaces before Pencil redesign is treated as final
 
 Optional visual-adapter policy:
 
@@ -241,6 +308,12 @@ Optional visual-adapter policy:
 - they must not override behavior truth, route truth, page-state truth, or acceptance rules
 - if a requested adapter is unavailable locally, Da Vinci should continue with native design rules and record the fallback in `design-registry.md`
 
+Recommended practice:
+
+- configure `Visual Assist` in `DA-VINCI.md` before broad Pencil generation begins
+- for complex Android redesigns, ask Da Vinci to decompose activities, fragments, tabs, sheets, dialogs, and materially different states before design work expands
+- if the output quality is weak, promote `frontend-skill`, tighten the design checkpoint bar, and prefer a fresh composition over a recolor of the old UI
+
 When a relevant mapping already exists:
 
 - iterate on the mapped Pencil source
@@ -250,6 +323,7 @@ When mappings do not exist but local code exists:
 
 - reconstruct the baseline from the local project
 - rebuild inventory, page map, and design registry
+- decompose complex containers into real design surfaces before broad Pencil generation
 - save or export the rebuilt Pencil baseline into `.da-vinci/designs/` when possible
 
 When neither mappings nor usable design sources exist:

package/README.zh-CN.md

@@ -29,10 +29,14 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.9`
+- `@xenonbyte/da-vinci-workflow@0.1.10`
 
 已发布版本重点：
 
+- `redesign-from-code` 现在明确写清：现有代码只是真相行为，不是真相布局
+- 复杂页面现在明确要求在大规模 Pencil 重设计前拆成 subpage、overlay、明显不同 state 和 implementation surface
+- design checkpoint 现在明确会拦截旧 UI 换皮、通用卡片拼贴、弱视觉锚点和装饰性噪音
+- `Visual Assist` 文档现在补了快速上手建议和“设计质量优先”配置
 - visual adapter 的配置字段、解析顺序和回退行为现在有单独文档说明
 - 现在提供按移动端、桌面端、Web、平板拆分的 `Visual Assist` 可复制模板
 - 仓库内的 forward test 示例现在展示了 `Visual Assist`、adapter 解析结果和 `.pen` 持久化记录方式
@@ -91,6 +95,67 @@ Da Vinci V2 支持四种模式：
 - 它们不应该默认把用户直接导向 `build`
 - `build` 仍然保留，但它是给已经实现就绪的高级直接入口
 
+## Visual Assist 快速上手
+
+当项目想借助本地 UI 设计 skill，例如 `frontend-skill` 或 `ui-ux-pro-max`，来提升设计质量时，就配置 `Visual Assist`。
+
+推荐默认配置：
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+适用场景：
+
+- app、dashboard、桌面工具等产品型界面
+- 本地没有 adapter 时工作流也应该继续
+- 想提升构图和层级，但不希望 adapter 缺失变成阻塞
+
+设计质量优先配置：
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - frontend-skill
+  - ui-ux-pro-max
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+```
+
+适用场景：
+
+- 页面视觉质量要求高，不能接受普通 fallback 质量
+- 之前的重设计已经出现“堆卡片、弱锚点、只是旧 UI 换皮”这类问题
+- 你希望没有强设计辅助 skill 时直接停下，而不是继续生成普通结果
+
+选择建议：
+
+- 高密度 app、dashboard、工具型界面，且视觉要求中等时，优先把 `ui-ux-pro-max` 放第一位
+- 如果更重视 art direction、构图和高级感，就把 `frontend-skill` 放第一位
+- 默认保留 `Fallback: native-da-vinci`
+- `Require Adapter` 默认保持 `false`，只有设计要求很高时再改成 `true`
+- `Scope` 只管 presentation 质量，不要拿它去定义 behavior、route 或 state truth
+
 ## 核心工作流顺序
 
 Da Vinci 的默认顺序是：
@@ -185,6 +250,8 @@ project/
 - `.da-vinci/designs/` 是项目内持久化 `.pen` 文件的默认位置
 - `page-map.md` 是实现页面和状态的真相源
 - `pencil-bindings.md` 是实现页面到 Pencil 页面绑定的真相源
+- 在 `redesign-from-code` 里，现有代码只是真相行为，不是真相布局
+- 复杂页面在 Pencil 重设计前应该先拆成 subpage、state、overlay 和 implementation surface
 
 可选 visual adapter 规则：
 
@@ -194,6 +261,12 @@ project/
 - 它不能覆盖 behavior truth、路由真相、页面状态真相或验收规则
 - 如果本地没有请求的 adapter，Da Vinci 应继续使用原生设计规则，并在 `design-registry.md` 里记录回退结果
 
+建议做法：
+
+- 在开始大规模 Pencil 设计前，就在 `DA-VINCI.md` 里写好 `Visual Assist`
+- 面对复杂 Android 重设计时，先要求 Da Vinci 把 activities、fragments、tabs、sheets、dialogs 和明显不同的 states 拆开
+- 如果结果很丑，就把 `frontend-skill` 提到第一位，收紧 design checkpoint，并明确要求 fresh composition，而不是旧 UI 改色
+
 当已有页面映射存在时：
 
 - 优先复用已绑定的 Pencil 设计源
@@ -203,6 +276,7 @@ project/
 
 - 先从当前项目重建设计基线
 - 重建 inventory、page-map、design-registry
+- 先把复杂容器拆成真实的设计 surface，再进入大规模 Pencil 设计
 - 在可行时把新的 Pencil 基线保存或导出到 `.da-vinci/designs/`
 
 当既没有映射也没有可用设计源时：

package/SKILL.md

@@ -15,6 +15,7 @@ Keep these rules fixed:
 - Pencil decides presentation.
 - Tasks decide implementation order.
 - Code must follow both requirements and Pencil data.
+- Existing code is behavior truth, not layout truth, during `redesign-from-code`.
 - When requirements and Pencil drift apart, stop and update the source artifacts before continuing implementation.
 
 ## Execution Policy
@@ -356,6 +357,8 @@ If the active mode is `redesign-from-code`:
 
 - inventory current routes, pages, and modules before redefining page structure
 - distinguish preserved behavior from replaced presentation
+- treat existing code as behavior truth and implementation-surface discovery, not as a visual-layout baseline
+- default to fresh visual composition unless the user explicitly asks to preserve the current layout skeleton
 - partition specs by redesign slice when one oversized `ui-refresh` spec would hide important implementation boundaries
 
 ## Spec Partitioning Rules
@@ -460,6 +463,33 @@ When visual adapters are requested:
 
 If the request is too vague to design or implement safely, ask a short clarification question before generating artifacts.
 
+## Surface Decomposition Rules
+
+Do not treat one implementation container as one design surface by default.
+
+For complex products, decompose by:
+
+- canonical page
+- subpage
+- state
+- overlay
+- shared shell region
+- implementation surface such as activity, fragment, tab, bottom sheet, dialog, or full-screen mode
+
+When an Android screen contains multiple fragments, tabs, nested flows, or materially different states:
+
+- split them into distinct design surfaces in `page-map.md`
+- give each meaningful state or subpage its own Pencil target when the layout materially changes
+- avoid collapsing them into one overloaded redesign screen
+
+One implementation page may legitimately map to:
+
+- multiple Pencil screens
+- multiple states of one Pencil page
+- one shared shell plus several detail surfaces
+
+Treat surface decomposition as required when visual structure changes materially across states or subflows.
+
 ## Pencil Design Rules
 
 Use Pencil as a structured UI source, not as a static image source.
@@ -470,9 +500,12 @@ When creating or editing Pencil designs:
 - follow `page-map.md` as the canonical page list
 - follow `design-brief.md` for form factor and visual direction when it exists
 - use the resolved visual adapter, when available, for composition, hierarchy, restraint, and motion guidance
+- before broad page generation, write a visual thesis, a content plan, and an interaction thesis for the current surface
 - Keep page names, section names, and labels aligned with the specs
 - Make important states explicit when they change implementation: empty, loading, success, error, restricted, unavailable
 - Prefer layout clarity and information hierarchy over decorative complexity
+- Reject generic UI patterns such as dashboard-card mosaics, weak visual anchors, decorative clutter, or motion with no hierarchy value
+- For `redesign-from-code`, redesign from page responsibilities and state decomposition, not by recoloring or slightly rearranging the old UI
 - After changes, inspect the result visually before treating it as implementation-ready
 
 When multiple pages exist:

package/docs/mode-use-cases.md

@@ -341,9 +341,22 @@ Register the design sources, extract DA-VINCI.md from them, bind covered pages,
 For redesign work:
 
 - current code decides behavior
+- current code does not decide the new layout or visual composition
 - `DA-VINCI.md` decides the new visual contract
 - Pencil decides page-by-page presentation
 
+Fresh-layout rule:
+
+- default to fresh visual composition driven by page purpose and state coverage
+- do not treat the old UI as the design baseline unless the user explicitly asks to preserve the layout skeleton
+- a recolor, light rearrangement, or minor spacing pass on the old UI is not enough for a true redesign
+
+Complex-surface rule:
+
+- if one screen contains multiple fragments, tabs, overlays, or materially different states, split it into multiple design surfaces
+- one implementation page may map to several Pencil screens or states
+- do not hide that complexity inside one oversized redesign page
+
 ### Spec partitioning rule
 
 For broad refreshes, do not keep everything inside one `ui-refresh/spec.md` unless the project surface is genuinely small or the change is mostly cosmetic.
@@ -409,13 +422,14 @@ Please inventory the current pages and shared layouts, register the HTML drafts
 Expected behavior:
 
 1. inventory current pages and shared regions
-2. register the HTML drafts as design references
-3. extract a stable `DA-VINCI.md`
-4. split broad redesign work into multiple spec slices when needed
-5. create or refine Pencil redesign screens
-6. bind implementation pages to redesign screens
-7. generate `tasks.md` aligned to the redesign slices
-8. continue into code changes without stopping at "next recommended step"
+2. decompose complex containers into real design surfaces, subpages, overlays, and states
+3. register the HTML drafts as design references
+4. extract a stable `DA-VINCI.md`
+5. split broad redesign work into multiple spec slices when needed
+6. create or refine Pencil redesign screens
+7. bind implementation pages to redesign screens
+8. generate `tasks.md` aligned to the redesign slices
+9. continue into code changes without stopping at "next recommended step"
 
 ### Best fit
 

package/docs/visual-adapters.md

@@ -28,6 +28,15 @@ Those still come from requirements, existing code, `page-map.md`, and `pencil-bi
 
 Configure visual-adapter preferences inside `DA-VINCI.md`.
 
+Start from one of these two setups:
+
+- balanced default
+  - keep delivery non-blocking
+  - better for most app and dashboard work
+- quality-first redesign
+  - raise the visual bar
+  - better when prior outputs were generic, ugly, or too close to the old UI
+
 Recommended shape:
 
 ```md
@@ -49,6 +58,56 @@ Recommended shape:
 
 Use `Require Adapter: true` only when the workflow must stop if the preferred adapter is unavailable locally.
 
+## Quick-Start Configurations
+
+Balanced default:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+Use this when:
+
+- the project is an app, dashboard, desktop tool, or dense product surface
+- you want stronger layout discipline but still want the workflow to continue without a local helper
+
+Quality-first redesign:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - frontend-skill
+  - ui-ux-pro-max
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+```
+
+Use this when:
+
+- the project is design-sensitive or premium-facing
+- the previous redesign attempt produced generic card grids, weak anchors, or a skin-swap of the old UI
+- you would rather stop than silently continue without a strong local design helper
+
 ## What Each Field Means
 
 Use the fields like this:
@@ -75,6 +134,27 @@ Recommended default:
 - use `Fallback: native-da-vinci`
 - keep `Scope` narrowly focused on visual-quality decisions
 
+Adapter-selection rule of thumb:
+
+- `ui-ux-pro-max` first for dense app, dashboard, and admin surfaces when the visual bar is moderate
+- `frontend-skill` first when art direction, composition quality, and visual restraint matter more than speed or density tuning
+
+## When The Output Still Looks Weak
+
+If the workflow is functionally correct but the Pencil result still looks generic or ugly:
+
+- move `frontend-skill` to the front of `Preferred adapters`
+- set a stronger visual direction in `DA-VINCI.md` instead of leaving it broad
+- treat `Require Adapter: true` as acceptable for design-critical work where plain fallback quality is not good enough
+- tighten the `Scope` toward composition, hierarchy, and Pencil refinement rather than vague style language
+- use the design checkpoint to block generic card mosaics, weak anchors, and decorative clutter
+
+For `redesign-from-code`, also do this:
+
+- restate that existing code is behavior truth, not layout truth
+- decompose complex activities, fragments, tabs, overlays, and materially different states before broad Pencil work
+- explicitly require fresh composition instead of recoloring or slightly rearranging the old UI
+
 ## Resolution Order
 
 Resolve adapters in this order:
@@ -163,6 +243,8 @@ Persist project-local Pencil files under .da-vinci/designs/.
 - `native-da-vinci`
   - use when no adapter is available or when the project only needs the built-in workflow rules
 
+If the output quality bar is especially high, promote `frontend-skill` to the first slot even for app surfaces and use `native-da-vinci` only as a fallback.
+
 ## Scenario Presets
 
 Ready-to-copy presets live here:

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

@@ -9,6 +9,13 @@ Each preset is intentionally conservative:
 - clear scope boundaries
 - non-blocking behavior by default
 
+If the project is design-critical or previous outputs were weak, generic, or too close to the old UI:
+
+- keep the same preset family
+- move `frontend-skill` to the first slot
+- consider `Require Adapter: true`
+- raise the design checkpoint bar before broad Pencil generation
+
 Available presets:
 
 - `mobile-app.md`

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

@@ -33,3 +33,4 @@ Notes:
 - prefer `ui-ux-pro-max` first for dense app layout decisions
 - 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

@@ -33,3 +33,4 @@ Notes:
 - prefer `ui-ux-pro-max` first for app-surface density and control balance
 - 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

@@ -33,3 +33,4 @@ Notes:
 - keep spacing more generous than desktop but more structured than phone UI
 - 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

@@ -33,3 +33,4 @@ Notes:
 - keep `ui-ux-pro-max` first for product surfaces, dashboards, and operational UI
 - 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

@@ -78,12 +78,23 @@ Expected flow:
 3. register current `.pen` sources and visual-adapter resolution in `design-registry.md`
 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`
-7. create new or updated Pencil pages, preferring persistence under `.da-vinci/designs/`
+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. bind routes and pages to Pencil screens
 9. generate tasks aligned to the redesign slices
 10. build and verify
 
+### Complex Android example
+
+```text
+$da-vinci use redesign-from-code to redesign this existing Android app.
+
+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.
+Do not pass design checkpoint if the result is just a skin-swap of the old UI.
+```
+
 ## 4. `feature-change`
 
 Use when an existing product needs a scoped requirement or page change.

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

@@ -129,6 +129,7 @@ Da Vinci 应该：
 4. 生成 `proposal.md`
 5. 按 redesign slice 拆分 `specs/`
 6. 重建或更新 `page-map.md`
+   - 把复杂页面拆成 subpage、state、overlay、fragment surface
 7. 生成 `design.md`
 8. 生成 `pencil-design.md`
    - 在可行时把新的 Pencil 基线持久化到 `.da-vinci/designs/`
@@ -136,6 +137,13 @@ Da Vinci 应该：
 10. 生成 `tasks.md`
 11. 进入实现
 
+关键规则：
+
+- 现有代码决定 behavior，不决定新的视觉布局
+- `redesign-from-code` 默认应该基于页面职责和状态重新构图
+- 不能把“旧页面换个配色、换点间距、挪一点位置”当成真正的重设计
+- 一个实现页如果包含多个 Fragment、多个 tab、多个状态或多个 overlay，应该拆成多个设计 surface
+
 ## 4. `feature-change`
 
 适合：

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

@@ -30,6 +30,15 @@ visual adapter 是可选的 presentation 质量增强层。
 
 把 visual adapter 偏好写在 `DA-VINCI.md` 里。
 
+可以先在下面两种配置里选一种：
+
+- 平衡默认版
+  - 不阻塞交付
+  - 适合大多数 app 和 dashboard
+- 设计质量优先版
+  - 主动抬高视觉门槛
+  - 适合之前结果很丑、很普通、或太像旧 UI 的场景
+
 推荐结构：
 
 ```md
@@ -51,6 +60,56 @@ visual adapter 是可选的 presentation 质量增强层。
 
 只有当你希望“本地没有对应 adapter 就必须停下”时，才把 `Require Adapter` 设成 `true`。
 
+## 快速上手配置
+
+平衡默认版：
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+适用场景：
+
+- app、dashboard、桌面工具、高密度产品界面
+- 想提升布局和层级，但本地没有 adapter 时工作流也应该继续
+
+设计质量优先版：
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - frontend-skill
+  - ui-ux-pro-max
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+```
+
+适用场景：
+
+- 页面视觉要求高，或者面对 premium / brand-sensitive 场景
+- 上一次重设计产出了通用卡片网格、弱锚点或只是旧 UI 换皮
+- 你宁可停下，也不想在没有强本地设计辅助 skill 时继续
+
 ## 每个字段是什么意思
 
 可以这样理解这些字段：
@@ -77,6 +136,27 @@ visual adapter 是可选的 presentation 质量增强层。
 - 优先用 `Fallback: native-da-vinci`
 - `Scope` 保持在视觉质量相关范围内
 
+adapter 选择经验：
+
+- 高密度 app、dashboard、admin 界面且视觉要求中等时，`ui-ux-pro-max` 更适合放第一位
+- 更强调 art direction、构图质量和克制感时，`frontend-skill` 更适合放第一位
+
+## 如果结果还是很丑怎么办
+
+如果流程是通的，但 Pencil 结果仍然很平庸或很丑：
+
+- 把 `frontend-skill` 提到 `Preferred adapters` 的第一位
+- 在 `DA-VINCI.md` 里把视觉方向写得更明确，不要太宽泛
+- 对设计质量要求很高的项目，可以接受把 `Require Adapter: true`
+- 把 `Scope` 收紧到 composition、hierarchy、Pencil refinement 这些具体能力
+- 在 design checkpoint 里把“堆卡片、弱视觉锚点、装饰性噪音”当成不过关条件
+
+对于 `redesign-from-code`，还应该补三句：
+
+- 重申 existing code 只是真相行为，不是真相布局
+- 在大规模 Pencil 设计前先拆 activities、fragments、tabs、overlays 和明显不同的 states
+- 明确要求 fresh composition，而不是旧 UI 改色或轻微挪位置
+
 ## 解析顺序
 
 adapter 的解析顺序建议固定为：
@@ -165,6 +245,8 @@ Persist project-local Pencil files under .da-vinci/designs/.
 - `native-da-vinci`
   - 本地没有 adapter，或只需要 Da Vinci 自身规则时使用
 
+如果你对设计质量要求很高，即使是 app 界面，也可以把 `frontend-skill` 放到第一位，并把 `native-da-vinci` 只当成兜底。
+
 ## 场景推荐配置
 
 可直接复制的场景模板在这里：

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

@@ -9,6 +9,13 @@
 - 清晰的作用范围
 - 默认不阻塞工作流
 
+如果项目对设计质量要求很高，或者之前结果很普通、很丑、太像旧 UI：
+
+- 仍然先选对应场景模板
+- 把 `frontend-skill` 提到第一位
+- 视情况把 `Require Adapter` 改成 `true`
+- 在大规模 Pencil 设计前先把 design checkpoint 门槛抬高
+
 可用模板：
 
 - `mobile-app.md`

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

@@ -29,3 +29,4 @@
 
 - 优先用 `ui-ux-pro-max` 做高密度 app 布局判断
 - `frontend-skill` 更适合作为辅助，不要反过来把工具界面做成营销页
+- 如果结果太平、太盒子化、太像通用后台，就把 `frontend-skill` 调到第一位，并提高 design checkpoint 的要求

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

@@ -28,3 +28,4 @@
 
 - `ui-ux-pro-max` 更适合移动端 app 表面的密度和平衡
 - motion 要轻，不要把普通 app 页面做成营销页
+- 如果结果总是变成泛化卡片堆砌或层级太弱，就把 `frontend-skill` 调到第一位，并考虑把 `Require Adapter` 改成 `true`

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

@@ -28,3 +28,4 @@
 
 - spacing 一般要比手机更舒展，但又不能像桌面端那样过密
 - 更适合用 adapter 去辅助分栏、画布区和主次区域的平衡
+- 如果结果还是寡淡或被边框框死，就把 `frontend-skill` 调到第一位，并要求在 Pencil 设计前先写清楚 visual thesis

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

@@ -29,3 +29,4 @@
 
 - 如果是典型 product UI，优先 `ui-ux-pro-max`
 - 如果页面更偏品牌表达或强视觉，可以把 `frontend-skill` 放前面
+- 如果结果像很普通的 SaaS 模板，就把 `frontend-skill` 提到第一位，并把 `DA-VINCI.md` 的视觉方向写得更具体

package/docs/zh-CN/workflow-examples.md

@@ -89,12 +89,23 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 3. 在 `design-registry.md` 中登记现有设计源和 visual adapter 解析结果
 4. 在 `proposal.md` 中定义重设计范围
 5. 当范围过大时，把工作拆成多个 `specs/<slice>/spec.md`
-6. 重建或细化 `page-map.md`
-7. 创建新的或更新后的 Pencil 页面，并优先持久化到 `.da-vinci/designs/`
+6. 重建或细化 `page-map.md`，把 subpage、overlay、重要 state 一起拆出来
+7. 创建新的或更新后的 Pencil 页面，基于重新构图而不是旧 UI 换皮，并优先持久化到 `.da-vinci/designs/`
 8. 绑定路由和 Pencil 页面
 9. 生成和 redesign slice 对齐的任务
 10. 实现并验证
 
+### 复杂 Android 页面示例
+
+```text
+$da-vinci use redesign-from-code to redesign this existing Android app.
+
+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.
+Do not pass design checkpoint if the result is just a skin-swap of the old UI.
+```
+
 ## 4. `feature-change`
 
 适用：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "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

@@ -273,6 +273,15 @@ Use this structure:
 - Route or identifier
 - Purpose
 
+## Implementation Surfaces
+- Activity / fragment / tab / dialog / sheet / overlay
+- Which canonical page each surface belongs to
+
+## Subpages And Overlays
+- Subpage name
+- Overlay name
+- When each one appears
+
 ## States Per Page
 - Empty
 - Loading
@@ -293,6 +302,8 @@ Use this structure:
 
 Use this artifact for every mode. It is the canonical page list.
 
+For complex products, do not stop at route names. Record implementation surfaces, subpages, and overlays when they materially affect design work.
+
 Recommended path:
 
 - `.da-vinci/page-map.md`

package/references/checkpoints.md

@@ -36,6 +36,7 @@ Use the design checkpoint to confirm:
 - `DA-VINCI.md` exists or has been intentionally generated for the current project
 - the current Pencil pages follow the same visual baseline
 - later pages are not re-inventing the product style from scratch
+- `redesign-from-code` is not treating the old UI layout as the new design baseline
 
 ## `discovery checkpoint`
 
@@ -93,12 +94,18 @@ Check:
 - major layout strategy matches the design artifact
 - Pencil names and artifact names are aligned enough to implement from
 - Pencil pages follow the current `DA-VINCI.md` visual contract
+- 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
+- motion ideas, if present, improve hierarchy or affordance instead of adding noise
+- complex pages with multiple fragments, subpages, overlays, or materially different states are decomposed clearly enough to design and implement from
+- `redesign-from-code` output is a fresh composition driven by page responsibility and state, not a skin-swap of the old UI
 
 Result meanings:
 
 - `PASS`: safe to generate implementation tasks
-- `WARN`: minor design gaps exist
-- `BLOCK`: design is not ready to drive implementation
+- `WARN`: minor design gaps exist, but the visual direction is still coherent
+- `BLOCK`: design is not ready to drive implementation, or the result is generic, cluttered, or materially below the intended visual bar
 
 ## `mapping checkpoint`
 

package/references/page-mapping.md

@@ -14,14 +14,17 @@ Treat `pencil-bindings.md` as the source of truth for:
 
 - implementation page -> Pencil page
 - route -> Pencil screen
+- implementation surface -> Pencil surface
 - shared region -> Pencil region
 
 ## Mapping Rules
 
 - define one canonical implementation page name per page
+- decompose complex pages into subpages, states, overlays, and implementation surfaces when layout changes materially
 - define one canonical Pencil page or screen per implementation page when possible
 - if multiple implementation pages share one Pencil page, record the reason
 - if one implementation page needs multiple Pencil screens, record the sub-page or state split
+- if one Android page hosts multiple fragments or tabs, map each meaningful surface separately instead of treating the container as one redesign target
 
 ## Minimum Binding Shape
 
@@ -43,6 +46,14 @@ For shared regions:
 - `App sidebar` -> `Navigation Shell`
 ```
 
+For complex surface decomposition:
+
+```md
+- `HomeActivity/HomeFragment[loaded]` -> `Home Loaded`
+- `HomeActivity/HomeFragment[empty]` -> `Home Empty`
+- `HomeActivity/FilterBottomSheet` -> `Home Filters Sheet`
+```
+
 ## When To Block
 
 Treat bindings as insufficient when:
@@ -50,6 +61,7 @@ Treat bindings as insufficient when:
 - no active `.pen` source is registered
 - the only known Pencil source is a live or external session and no project-local persistence path is recorded
 - the implementation page has no Pencil source
+- a complex page with multiple fragments, tabs, overlays, or materially different states has been flattened into one ambiguous design target
 - the Pencil page exists but cannot be traced to a route or page responsibility
 - shared layout regions are undefined and implementation would guess too much