@xenonbyte/da-vinci-workflow 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -4,6 +4,24 @@
 
 - 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
+- `docs/visual-adapters.md` and `docs/zh-CN/visual-adapters.md` to explain visual-adapter configuration, resolution, and fallback behavior
+- `docs/visual-assist-presets/` and `docs/zh-CN/visual-assist-presets/` with ready-to-copy `Visual Assist` presets for mobile, desktop, web, and tablet product surfaces
+
+### Changed
+- forward-test example artifacts now show `Visual Assist`, `Visual Adapter Resolution`, and project-local `.pen` persistence patterns
+- workflow examples and README navigation now point to the new visual-adapter and preset documentation
+
 ## v0.1.8 - 2026-03-27
 
 ### Added

package/README.md

@@ -27,10 +27,17 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.8`
+- `@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
 - Codex natural-language usage is now documented explicitly, including `intake`, `prompt`, `continue`, and direct mode entry patterns
 - project-local Pencil `.pen` files are now documented to persist under `.da-vinci/designs/`
 - design registry and artifact templates now record preferred persisted `.pen` paths for project-local reuse
@@ -83,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:
@@ -229,6 +297,22 @@ 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:
+
+- `DA-VINCI.md` may declare preferred visual adapters for design assistance
+- visual adapters are optional helpers for composition, hierarchy, spacing, and motion guidance
+- they may refine `DA-VINCI.md`, `design.md`, and `pencil-design.md`
+- 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:
 
@@ -239,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:
@@ -256,6 +341,7 @@ Before generating Pencil designs for a greenfield project, Da Vinci should colle
 - density
 - brand direction
 - responsive priority
+- optional visual-adapter preferences
 
 Preferred inference order:
 
@@ -270,6 +356,12 @@ If `DA-VINCI.md` does not exist:
 - generate it from stable user preferences, existing project signals, or inferred defaults
 - save it before generating many project pages, so later pages do not drift stylistically
 
+If the project requests visual adapters:
+
+- resolve them from the user request first, then `DA-VINCI.md`, then locally available skills
+- choose one primary adapter when multiple helpers are available
+- treat them as non-blocking unless the user explicitly requires a specific adapter
+
 ## Installation
 
 Install the package:
@@ -417,6 +509,8 @@ See:
 
 - `docs/prompt-entrypoints.md`
 - `docs/codex-natural-language-usage.md`
+- `docs/visual-adapters.md`
+- `docs/visual-assist-presets/`
 - `docs/workflow-examples.md`
 - `docs/mode-use-cases.md`
 
@@ -425,6 +519,8 @@ See:
 Chinese companion documents are included in this repository:
 
 - `README.zh-CN.md`
+- `docs/zh-CN/visual-adapters.md`
+- `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`
 
 ## Repository layout

package/README.zh-CN.md

@@ -29,10 +29,17 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.8`
+- `@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` 持久化记录方式
 - Codex 的自然语言用法现在有单独文档，明确说明 `intake`、`prompt`、`continue` 和直接 mode 调用方式
 - 项目内 Pencil `.pen` 文件现在明确约定默认持久化到 `.da-vinci/designs/`
 - 设计源登记和工件模板现在会记录项目内优先使用的 `.pen` 路径
@@ -88,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 的默认顺序是：
@@ -182,6 +250,22 @@ project/
 - `.da-vinci/designs/` 是项目内持久化 `.pen` 文件的默认位置
 - `page-map.md` 是实现页面和状态的真相源
 - `pencil-bindings.md` 是实现页面到 Pencil 页面绑定的真相源
+- 在 `redesign-from-code` 里，现有代码只是真相行为，不是真相布局
+- 复杂页面在 Pencil 重设计前应该先拆成 subpage、state、overlay 和 implementation surface
+
+可选 visual adapter 规则：
+
+- `DA-VINCI.md` 可以声明期望使用的 visual adapter 来辅助设计
+- visual adapter 只用于增强构图、层级、留白、节奏和 motion 判断
+- 它可以影响 `DA-VINCI.md`、`design.md`、`pencil-design.md`
+- 它不能覆盖 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 改色
 
 当已有页面映射存在时：
 
@@ -192,6 +276,7 @@ project/
 
 - 先从当前项目重建设计基线
 - 重建 inventory、page-map、design-registry
+- 先把复杂容器拆成真实的设计 surface，再进入大规模 Pencil 设计
 - 在可行时把新的 Pencil 基线保存或导出到 `.da-vinci/designs/`
 
 当既没有映射也没有可用设计源时：
@@ -200,6 +285,13 @@ project/
 - 在可行时把基线保存到 `.da-vinci/designs/`
 - 并在 `design-registry.md` 里记录准确路径
 
+如果项目声明了 visual adapter：
+
+- 先看用户请求，其次看 `DA-VINCI.md`，再看本地可用 skill
+- 如果存在多个可用辅助 skill，收敛出一个 primary adapter，必要时再保留 secondary helpers
+- 默认把它当成非阻塞增强层
+- 只有用户明确要求必须使用某个 adapter 时，缺失才应阻塞工作流
+
 ## 安装
 
 安装 npm 包：
@@ -330,6 +422,8 @@ Continue into full-delivery.
 
 - `docs/codex-natural-language-usage.md`
 - `docs/prompt-entrypoints.md`
+- `docs/visual-adapters.md`
+- `docs/visual-assist-presets/`
 - `docs/workflow-examples.md`
 - `docs/mode-use-cases.md`
 - `references/`
@@ -337,6 +431,8 @@ Continue into full-delivery.
 中文文档：
 
 - `README.zh-CN.md`
+- `docs/zh-CN/visual-adapters.md`
+- `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`
 
 ## 仓库布局

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
@@ -151,6 +152,7 @@ Before generating new Pencil designs for a greenfield project, collect or infer:
    - detect whether `DA-VINCI.md` already exists
    - if it exists, treat it as the visual baseline for future pages
    - if it does not exist, generate it from stable user preferences, existing project signals, or inferred defaults before broad Pencil page generation
+   - if it declares preferred visual adapters, treat them as optional design-assist preferences, not as behavior truth
 
 1. product form factor
    - desktop software
@@ -180,6 +182,13 @@ Use this priority order:
 
 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
+- use them to improve visual contract quality, composition, hierarchy, spacing, and motion guidance
+- do not let them redefine behavior, page truth, route truth, or acceptance rules
+- if a requested adapter is unavailable locally, continue with native Da Vinci design rules and record the fallback
+
 ## Default Workflow
 
 Run the workflow in this order:
@@ -348,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
@@ -396,6 +407,13 @@ Use `DA-VINCI.md` as the project-level visual source of truth for:
 - typography direction
 - component tone
 - rules for cross-page consistency
+- optional visual adapter preferences
+
+Treat visual adapters as optional helpers for presentation quality only.
+
+- they may refine `DA-VINCI.md`, `design.md`, and `pencil-design.md`
+- they must not override behavior truth from requirements or existing code
+- they must not replace `page-map.md`, `design-registry.md`, or `pencil-bindings.md`
 
 When a relevant mapping already exists:
 
@@ -407,6 +425,7 @@ When `DA-VINCI.md` already exists:
 
 - use it as the baseline visual contract
 - do not regenerate visual direction from scratch unless the change explicitly rebrands or resets the product style
+- if it declares preferred visual adapters, try to resolve them without blocking the workflow
 
 When page-to-Pencil bindings already exist:
 
@@ -435,8 +454,42 @@ When a Pencil session cannot yet be exported locally:
 - record why local persistence is pending
 - do not hide the lack of a project-local `.pen` path
 
+When visual adapters are requested:
+
+- resolve them from local availability when possible
+- choose one primary adapter when multiple helpers are available
+- record the requested adapters, resolved primary adapter, any secondary helpers, and fallback status in `design-registry.md`
+- continue with native Da Vinci design rules when no adapter is available unless the user explicitly requires a specific adapter
+
 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.
@@ -446,9 +499,13 @@ When creating or editing Pencil designs:
 - Build the pages required by the current scope, not an abstract moodboard
 - 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
 
@@ -505,6 +519,7 @@ Use it like this:
    - reuse it
    - avoid asking duplicate style questions
    - avoid page-by-page style reinvention
+   - read any declared visual-adapter preferences as optional design-assist guidance
 
 2. if it does not exist
    - generate it from stable user preference, existing code signals, or prior design sources
@@ -514,6 +529,13 @@ Use it like this:
    - update `DA-VINCI.md`
    - then propagate the new baseline through Pencil and implementation
 
+Recommended `DA-VINCI.md` pattern:
+
+- keep visual-adapter preferences inside `DA-VINCI.md`
+- treat them as optional presentation helpers
+- examples can include local skills such as `frontend-skill` or `ui-ux-pro-max`
+- if the preferred adapter is unavailable locally, continue with native Da Vinci design rules and record the fallback in `design-registry.md`
+
 ---
 
 ## How to choose between design sources