@xenonbyte/da-vinci-workflow 0.1.9 → 0.1.11

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,17 @@
 - 清晰的作用范围
 - 默认不阻塞工作流
 
+建议搭配：
+
+- `docs/zh-CN/prompt-presets/`
+
+如果项目对设计质量要求很高，或者之前结果很普通、很丑、太像旧 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,11 +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/`
-8. 绑定路由和 Pencil 页面
-9. 生成和 redesign slice 对齐的任务
-10. 实现并验证
+6. 重建或细化 `page-map.md`，把 subpage、overlay、重要 state 一起拆出来
+7. 创建新的或更新后的 Pencil 页面，基于重新构图而不是旧 UI 换皮，并优先持久化到 `.da-vinci/designs/`
+8. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
+9. 绑定路由和 Pencil 页面
+10. 生成和 redesign slice 对齐的任务
+11. 实现并验证
+
+### 复杂 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.11",
   "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

@@ -230,12 +230,14 @@ Use this structure:
 ## Active Design Sources
 - `.pen` file path
 - whether it lives under `.da-vinci/designs/`
+- whether the path is workflow-generated or external
 - status
 - purpose
 
 ## Preferred Design Source
 - Which `.pen` file is authoritative
 - Why that file should be preferred over live-only or external sources
+- whether the active Pencil editor matches that same path
 
 ## Visual Adapter Resolution
 - Requested adapters
@@ -252,7 +254,8 @@ Use this structure:
 ## Notes
 - Why a source is active
 - Whether a source is safe to iterate
-- Whether local export is still pending
+- Whether shell-visible filesystem persistence exists
+- Whether the file had to be reconstructed from MCP-readable document data
 ```
 
 Use this artifact whenever a project can have one or more Pencil sources.
@@ -273,6 +276,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 +305,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`
@@ -423,6 +437,7 @@ Use this structure:
 ## Source
 - `.pen` file path
 - project-local persisted path under `.da-vinci/designs/` when available
+- whether the active Pencil editor matched that same path
 - Active pages
 
 ## Visual Adapter Use
@@ -448,7 +463,7 @@ Use this structure:
 
 ## Implementation Notes
 - Important layout or styling constraints to preserve in code
-- Persistence notes if the live Pencil source has not yet been exported locally
+- Persistence notes if the project-local `.pen` file had to be reconstructed from MCP-readable document data
 ```
 
 Recommended path:
@@ -495,6 +510,7 @@ Use this structure:
 ## Source
 - `.pen` file path
 - project-local persisted path under `.da-vinci/designs/` when available
+- whether the active Pencil editor matched that same path
 
 ## Bindings
 - implementation page or route -> Pencil page or screen
@@ -505,7 +521,7 @@ Use this structure:
 ## Notes
 - intentional deviations
 - pages without Pencil coverage yet
-- whether bindings depend on a live-only source that still needs local export
+- whether bindings depend on a live-only source that still needs reconciliation
 ```
 
 Use this artifact whenever implementation must trace back to Pencil pages.

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,37 @@ 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
+
+## `design-source checkpoint`
+
+Run after `design-registry.md` resolves the preferred project-local `.pen` path and after active Pencil work exists, but before mapping is treated as safe.
+
+Check:
+
+- `design-registry.md` records one specific preferred project-local `.pen` path
+- the preferred `.pen` path is workflow-owned state, not a hand-wavy placeholder
+- the active Pencil editor path matches the preferred project-local `.pen` path, or the mismatch has been reconciled explicitly
+- if the workflow created or edited Pencil work, the preferred project-local `.pen` file exists as a shell-visible file
+- if Pencil MCP only exposed a live document, the workflow reconstructed and wrote the registered project-local `.pen` file from MCP-readable document data before continuing
+- `design-registry.md`, `pencil-design.md`, and `pencil-bindings.md` describe the same active project-local `.pen` source clearly enough to map and implement from
+
+Result meanings:
+
+- `PASS`: safe to continue into mapping
+- `WARN`: the workflow is intentionally staying on an older but still shell-visible baseline, or no new Pencil edits have happened yet
+- `BLOCK`: the registered `.pen` path, the active Pencil work, and the shell-visible project-local file do not agree well enough to treat the design source as traceable
 
 ## `mapping checkpoint`
 
@@ -107,6 +133,9 @@ Run after `design-registry.md` and `pencil-bindings.md`.
 Check:
 
 - the correct `.pen` source is identified
+- the preferred `.pen` path in `design-registry.md` is workflow-owned and specific, not hand-wavy
+- the active Pencil editor path matches the preferred project-local `.pen` path, or the project-local file has been reconstructed explicitly
+- the preferred project-local `.pen` file exists as a shell-visible file when the workflow created or edited Pencil work
 - each implementation page has a Pencil page or an explicit exception
 - shared layouts and shared regions are bound clearly enough to implement from
 - route names and Pencil names are traceable
@@ -116,7 +145,7 @@ Result meanings:
 
 - `PASS`: safe to generate implementation tasks
 - `WARN`: some bindings are weak, but implementation can continue carefully
-- `BLOCK`: implementation would guess too much without fixing bindings
+- `BLOCK`: implementation would guess too much without fixing bindings, or the workflow edited Pencil work without producing the required project-local `.pen` source
 
 ## `task checkpoint`
 
@@ -147,12 +176,14 @@ Examples of `WARN`, not `BLOCK`:
 
 - an additional follow-up spec may be needed for currently untouched behavior
 - some legacy or out-of-scope surfaces remain intentionally excluded
-- the active Pencil source should also be saved or exported for stronger repository traceability
+- the project intentionally remains on an older but still shell-visible `.pen` baseline while a new design pass is deferred
 
 Examples of `BLOCK`:
 
 - the implementation would invent new behavior that has no spec support
 - page-to-Pencil bindings are too weak to know which redesign screen to follow
+- `design-registry.md` points to a project-local `.pen` path, but the workflow actually edited a different live editor document and did not reconcile the mismatch
+- the workflow created or edited Pencil pages but no shell-visible `.pen` file exists under the registered project-local path
 - required permissions, environment access, or protected files are unavailable
 - the implementation would overwrite the project baseline in a destructive way without an explicit go-ahead
 

package/references/design-inputs.md

@@ -12,6 +12,31 @@ Check for `DA-VINCI.md` first, then check whether the project already has persis
 - if it does not exist, generate it from the best stable inputs before broad Pencil page generation
 - avoid re-deriving the visual language page by page
 
+## Project-Local `.pen` Path Resolution
+
+The preferred `.pen` path in `design-registry.md` is workflow-owned state.
+
+- it should be generated and maintained by Da Vinci
+- it should not rely on the user manually typing a path into `design-registry.md`
+- external references may influence source priority, but the project-local path should still be resolved explicitly
+
+Use these defaults:
+
+1. `.da-vinci/designs/project-baseline.pen`
+2. `.da-vinci/designs/<change-id>.pen`
+3. `.da-vinci/designs/<change-id>/main.pen` only when a nested design bundle is truly needed
+
+Before broad Pencil work begins:
+
+- resolve the exact project-local path
+- record that path in `design-registry.md`
+- treat that path as the required target for the active design pass
+
+If Pencil MCP is currently pointing at a different active editor:
+
+- switch to the registered project-local path when possible
+- otherwise reconstruct the project-local `.pen` file from MCP-readable document data before treating the workflow as traceable
+
 ## Minimum Inputs
 
 Collect or infer:
@@ -73,7 +98,11 @@ Write stable answers into `design-brief.md`.
 
 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, save or export the `.pen` file into `.da-vinci/designs/` when possible and register that exact path in `design-registry.md`.
+If Pencil creates or updates a baseline during the workflow:
+
+- register the exact project-local path in `design-registry.md`
+- verify that the same path is readable through MCP and shell-visible in the project filesystem
+- if Pencil MCP does not materialize the shell-visible file automatically, reconstruct and write the `.pen` file from MCP-readable document data before closing mapping or implementation work
 
 If the project requests a visual adapter:
 

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
 

package/references/pencil-design-to-code.md

@@ -17,7 +17,7 @@ Do not infer behavior from appearance alone.
 When MCP is available, read:
 
 - the preferred project-local `.pen` file under `.da-vinci/designs/` when one is registered
-- active `.pen` file
+- the active `.pen` file only after confirming it matches the registered project-local path
 - target page frame
 - child section hierarchy
 - text content
@@ -28,6 +28,12 @@ When MCP is available, read:
 
 Prefer structural reads over screenshots.
 
+If the current active Pencil editor does not match the preferred path in `design-registry.md`:
+
+- do not silently continue from the unrelated editor
+- switch to the registered file when possible
+- otherwise reconstruct the registered project-local `.pen` file from MCP-readable document data before implementation depends on it
+
 ## Visual Adapter Use
 
 If the project resolved a visual adapter: