@xenonbyte/da-vinci-workflow 0.1.10 → 0.1.12

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

@@ -0,0 +1,85 @@
+# Web 应用提示词模板
+
+适用于浏览器中的产品型界面，或带有 app surface 的 Web 产品。
+
+建议搭配：
+
+- `docs/zh-CN/visual-assist-presets/web-app.md`
+
+适合这种需求：
+
+- responsive 层级
+- marketing surface 与 product surface 的区分
+- 明确处理 empty、loading、error、authenticated states
+
+## 如何选择
+
+- `Simple redesign` 适合产品表面不大、主要页面不多、状态分支有限的项目。
+- `Complex redesign` 适合同时混合 marketing、auth、onboarding、app surface、dialogs、drawers 和大量状态的项目。
+- `Design-only` 适合先把设计链路和绑定做完，但暂时不改代码。
+- `Continue` 适合已经有 `.da-vinci/` 工件，需要继续推进的项目。
+
+## Simple Redesign
+
+```text
+$da-vinci use redesign-from-code to redesign this existing web product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve current business logic, routes, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inventory the current product surfaces and important states before Pencil work.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+Do not pass design checkpoint if the result is a generic SaaS card grid or a recolor of the old interface.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+## Complex Redesign
+
+```text
+$da-vinci use redesign-from-code to redesign this existing web product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve current business logic, routes, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
+Inventory responsive product surfaces, marketing surfaces, authenticated areas, settings pages, dialogs, drawers, overlays, and materially different states before broad Pencil work.
+Separate marketing-style surfaces from product-workflow surfaces when they require different visual treatment.
+Decompose complex pages 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.
+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.
+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/.
+```
+
+## Design-Only
+
+```text
+$da-vinci use redesign-from-code to redesign this existing web product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve current behavior, routes, permissions, integrations, and state transitions.
+Inventory product surfaces, marketing surfaces, overlays, and important states.
+Decompose complex pages into real design surfaces before Pencil work.
+Use the Visual Assist preferences declared in DA-VINCI.md.
+If the product is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
+Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
+Do not start code changes yet.
+```
+
+## Continue
+
+```text
+$da-vinci use continue for this existing web-product redesign workflow.
+
+Use the existing Da Vinci artifacts in this project.
+Do not restart discovery unless an artifact is missing or clearly wrong.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth.
+If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
+Continue into the next unfinished stage and do not stop at tasks.md when the active intent is full-delivery.
+```
+
+## 什么时候先走 Intake
+
+- 产品混合了很多 surface 类型和真相源
+- 外部参考让第一条工作流请求变复杂
+- 第一条提示词仍然很难一次说对

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

@@ -204,9 +204,18 @@ adapter 的解析顺序建议固定为：
 当 visual adapter 生效时：
 
 - 在 Pencil 设计前或设计过程中，用它来增强构图和层级判断
+- 解析出来的主 adapter 应该成为首轮设计的 art direction 主导，而不是只登记在 `design-registry.md` 里
 - 页面命名和状态覆盖仍然要服从 `page-map.md`
 - 最终 presentation 真相仍然落在 Pencil `.pen` 数据里，而不是 adapter 的文字建议里
 
+面对复杂重设计时，还要额外遵守：
+
+- 不要一开始就批量搭很多空 screen
+- 先做 1 到 3 个 anchor surface
+- 每个 anchor surface 都要先做成完整构图，再扩展更多页面
+- 每做完一个 anchor surface 都先截图审查，再决定是否 clone 变体或继续扩展
+- 如果结果仍然大量是占位块或重复模板，直接把 `design checkpoint` 判成 `BLOCK`，不要在坏底稿上继续叠更多页面
+
 把结果记录到 `pencil-design.md`。
 
 推荐字段：
@@ -236,6 +245,15 @@ If it is unavailable, fall back to native Da Vinci design rules and continue.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
 
+如果是复杂 Android 或多 surface 项目，建议再额外加上：
+
+```text
+Use frontend-skill explicitly as the primary visual reasoning source.
+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.
+```
+
 ## adapter 选择建议
 
 - `frontend-skill`

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

@@ -9,12 +9,17 @@
 - 清晰的作用范围
 - 默认不阻塞工作流
 
+建议搭配：
+
+- `docs/zh-CN/prompt-presets/`
+
 如果项目对设计质量要求很高，或者之前结果很普通、很丑、太像旧 UI：
 
 - 仍然先选对应场景模板
 - 把 `frontend-skill` 提到第一位
 - 视情况把 `Require Adapter` 改成 `true`
 - 在大规模 Pencil 设计前先把 design checkpoint 门槛抬高
+- 改成 anchor-first：先做 1 到 3 个 anchor surface，截图审查通过后再扩展
 
 可用模板：
 
@@ -29,3 +34,4 @@
 2. 把其中的 `## Visual Assist` 片段复制到 `DA-VINCI.md`
 3. 只有在项目真的有不同视觉偏向时才调整 adapter 顺序
 4. 除非确实“没有某个本地 skill 就不能继续”，否则保持 `Require Adapter: false`
+5. 如果是复杂重设计，不要只复制 preset 就开画；还要配合 anchor-first 的 Pencil 生成策略

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

@@ -64,10 +64,11 @@ $da-vinci use greenfield-brainstorm to turn product brainstorming into a page ma
 4. 写入 `specs/<capability>/spec.md`
 5. 定义 `page-map.md`
 6. 解析请求的 visual adapter，并把结果记到 `design-registry.md`
-7. 建立或登记 Pencil 设计源
-8. 完成页面绑定
-9. 生成任务
-10. 实现并验证
+7. 建立或登记项目内 Pencil 设计源
+8. 先做 1 到 3 个 anchor surface，并完成截图审查，再扩展更多页面
+9. 完成页面绑定
+10. 生成任务
+11. 实现并验证
 
 ## 3. `redesign-from-code`
 
@@ -91,9 +92,10 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 5. 当范围过大时，把工作拆成多个 `specs/<slice>/spec.md`
 6. 重建或细化 `page-map.md`，把 subpage、overlay、重要 state 一起拆出来
 7. 创建新的或更新后的 Pencil 页面，基于重新构图而不是旧 UI 换皮，并优先持久化到 `.da-vinci/designs/`
-8. 绑定路由和 Pencil 页面
-9. 生成和 redesign slice 对齐的任务
-10. 实现并验证
+8. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
+9. 绑定路由和 Pencil 页面
+10. 生成和 redesign slice 对齐的任务
+11. 实现并验证
 
 ### 复杂 Android 页面示例
 
@@ -103,6 +105,9 @@ $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.
+Use frontend-skill explicitly as the primary visual reasoning source.
+Do not start with broad multi-screen scaffolding.
+Design 1-3 anchor surfaces first, review screenshots, then expand.
 Do not pass design checkpoint if the result is just a skin-swap of the old UI.
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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.
@@ -434,14 +437,21 @@ 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
 - Resolved primary adapter
 - Secondary helpers
+- Whether the primary adapter actively led the first-pass composition
 - How it affected composition, hierarchy, or motion guidance
 - Whether native Da Vinci fallback was used
 
+## Anchor Surfaces
+- Which 1-3 anchor screens were designed first
+- Screenshot review status for each anchor
+- Whether broad multi-screen expansion is approved yet
+
 ## Page Mapping
 - Requirement -> Pencil page
 
@@ -459,7 +469,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:
@@ -506,6 +516,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
@@ -516,7 +527,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

@@ -94,9 +94,12 @@ 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
+- if visual adapters were requested, the resolved primary adapter clearly shaped the first design pass instead of being recorded only as metadata
+- complex redesigns have 1-3 fully composed anchor surfaces reviewed before broad multi-screen expansion
 - 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
+- the design is not placeholder-heavy or built from repeated empty templates masquerading as finished screens
 - 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
@@ -107,6 +110,31 @@ Result meanings:
 - `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
 
+Automatic failures:
+
+- if broad Pencil generation starts before anchor surfaces are compositionally stable, treat the design checkpoint as `BLOCK`
+- 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`
+
+## `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`
 
 Run after `design-registry.md` and `pencil-bindings.md`.
@@ -114,6 +142,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
@@ -123,7 +154,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`
 
@@ -154,12 +185,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,11 +98,18 @@ 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:
 
 - try to resolve it from locally available skills
 - choose one primary adapter when multiple helpers are available
 - record the requested adapters, resolved primary adapter, any secondary helpers, and fallback result in `design-registry.md`
+- treat the resolved primary adapter as the design lead for the first Pencil pass, especially for anchor screens and other quality-critical surfaces
+- use Pencil guides or style helpers only as platform and buildability constraints, not as the art-direction source
+- if `Require Adapter: true` and the requested adapter is unavailable, block instead of silently downgrading the visual bar
 - if no adapter is available, continue with native Da Vinci design rules unless the user explicitly required a specific adapter

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,11 +28,19 @@ 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:
 
-- use it to refine composition, hierarchy, spacing discipline, and motion suggestions before or during Pencil design work
+- use it to lead early composition, hierarchy, spacing discipline, and motion suggestions before or during Pencil design work
+- on complex redesigns, apply it first to 1-3 anchor surfaces before expanding the rest of the screen set
+- do not let Pencil guides, generic style packs, or repeated scaffolding override the resolved primary adapter's role in the first-pass art direction
 - do not let it override behavior, route truth, or page-state truth
 - treat it as a presentation-quality assistant, not as a replacement for Pencil or requirements