@xenonbyte/da-vinci-workflow 0.1.8 → 0.1.10

package/docs/visual-adapters.md

@@ -0,0 +1,255 @@
+# Visual Adapters
+
+Use this document when a project wants optional UI-design assistance from local skills such as `frontend-skill` or `ui-ux-pro-max`.
+
+## What A Visual Adapter Is
+
+A visual adapter is an optional presentation-quality helper.
+
+It may improve:
+
+- visual-contract quality
+- composition
+- hierarchy
+- spacing discipline
+- motion guidance
+- Pencil page refinement
+
+It must not redefine:
+
+- behavior truth
+- route truth
+- page-state truth
+- acceptance criteria
+
+Those still come from requirements, existing code, `page-map.md`, and `pencil-bindings.md`.
+
+## Where To Configure It
+
+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
+## 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:
+  - false
+```
+
+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:
+
+- `Preferred adapters`
+  - 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
+- `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
+  - 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
+  - `native-da-vinci` means continue with the built-in rules instead of stopping
+- `Require Adapter`
+  - whether adapter availability is a hard requirement
+  - `false` means adapter use is optional and should not block delivery
+  - `true` means the workflow should stop if no acceptable adapter is available
+
+Recommended default:
+
+- use `Require Adapter: false`
+- 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:
+
+1. explicit user request
+2. `DA-VINCI.md`
+3. locally available skills
+4. native Da Vinci rules
+
+When multiple helpers are available:
+
+- choose one primary adapter
+- keep secondary helpers only when they serve a clear non-conflicting role
+
+## Where To Record The Result
+
+Record runtime resolution in `design-registry.md`.
+
+Recommended fields:
+
+```md
+## Visual Adapter Resolution
+- Requested adapters: frontend-skill, ui-ux-pro-max
+- Resolved primary adapter: frontend-skill
+- Secondary helpers: none
+- Status: active
+- Scope: DA-VINCI.md, design.md, pencil-design.md
+- Fallback reason if native Da Vinci rules were used: none
+```
+
+If no adapter is available:
+
+```md
+## Visual Adapter Resolution
+- Requested adapters: frontend-skill
+- Resolved primary adapter: native-da-vinci
+- Secondary helpers: none
+- Status: fallback
+- Scope: DA-VINCI.md, design.md, pencil-design.md
+- Fallback reason if native Da Vinci rules were used: requested adapter unavailable locally
+```
+
+## How It Affects Pencil Work
+
+When a visual adapter is active:
+
+- use it before or during Pencil work to sharpen composition and hierarchy
+- keep page names and states aligned with `page-map.md`
+- keep final `.pen` decisions grounded in Pencil, not in adapter prose
+
+Record the outcome in `pencil-design.md`.
+
+Recommended fields:
+
+```md
+## Visual Adapter Use
+- Resolved primary adapter: frontend-skill
+- Secondary helpers: none
+- How it affected composition, hierarchy, or motion guidance:
+  - stronger hero anchor
+  - fewer card treatments
+  - more deliberate CTA placement
+- Whether native Da Vinci fallback was used: no
+```
+
+## Typical Use
+
+Example request:
+
+```text
+$da-vinci use redesign-from-code to globally replace the UI of this existing Android project.
+
+Existing Android code is the behavior source of truth.
+Use the visual-adapter preferences declared in DA-VINCI.md.
+If frontend-skill is available, use it as the primary visual adapter.
+If it is unavailable, fall back to native Da Vinci design rules and continue.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
+## Suggested Adapter Choices
+
+- `frontend-skill`
+  - better for strong art direction, composition, and premium landing or brand surfaces
+- `ui-ux-pro-max`
+  - better for app surfaces, dashboards, admin UI, and dense product workflows
+- `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:
+
+- `docs/visual-assist-presets/mobile-app.md`
+- `docs/visual-assist-presets/desktop-app.md`
+- `docs/visual-assist-presets/web-app.md`
+- `docs/visual-assist-presets/tablet-app.md`

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

@@ -0,0 +1,31 @@
+# Visual Assist Presets
+
+Use these presets as starting points for the `## Visual Assist` section inside `DA-VINCI.md`.
+
+Each preset is intentionally conservative:
+
+- one primary adapter direction
+- one fallback direction
+- 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`
+- `desktop-app.md`
+- `web-app.md`
+- `tablet-app.md`
+
+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

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

@@ -0,0 +1,36 @@
+# Desktop App Preset
+
+Recommended when the product surface is desktop software or a dense productivity workspace.
+
+Use this when the UI needs:
+
+- high information density
+- strong workspace hierarchy
+- restrained chrome
+- panel and inspector judgment
+
+Recommended `DA-VINCI.md` block:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - workspace composition
+  - hierarchy and spacing
+  - motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+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

@@ -0,0 +1,36 @@
+# Mobile App Preset
+
+Recommended when the product surface is a phone-first app.
+
+Use this when the UI needs:
+
+- compact but readable mobile hierarchy
+- strong tap-target discipline
+- restrained motion
+- app-first component judgment rather than brand-poster composition
+
+Recommended `DA-VINCI.md` block:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - mobile page composition
+  - hierarchy and spacing
+  - touch-first motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+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

@@ -0,0 +1,36 @@
+# Tablet App Preset
+
+Recommended when the product surface is tablet-first or must work across tablet-heavy flows.
+
+Use this when the UI needs:
+
+- touch-aware spacing
+- larger compositional regions than phone UI
+- more balanced density than desktop software
+- strong split-pane or canvas-area judgment
+
+Recommended `DA-VINCI.md` block:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - tablet page composition
+  - hierarchy and spacing
+  - touch-aware motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+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

@@ -0,0 +1,36 @@
+# Web App Preset
+
+Recommended when the product surface is a browser-based app, SaaS workspace, or hybrid product UI.
+
+Use this when the UI needs:
+
+- balanced density
+- clear workspace structure
+- stronger marketing-to-product bridge than a pure desktop tool
+- responsive layout judgment
+
+Recommended `DA-VINCI.md` block:
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - responsive motion guidance
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+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

@@ -31,11 +31,12 @@ Expected flow:
 2. create `proposal.md`
 3. create `specs/<capability>/spec.md`
 4. create `page-map.md`
-5. register `.pen` sources in `design-registry.md`
-6. create Pencil pages and record them in `pencil-design.md`
-7. bind implementation pages in `pencil-bindings.md`
-8. generate `tasks.md`
-9. build and verify
+5. configure any optional visual-adapter preferences in `DA-VINCI.md`
+6. register `.pen` sources and visual-adapter resolution in `design-registry.md`
+7. create Pencil pages, persist the preferred `.pen` path, and record adapter use in `pencil-design.md`
+8. bind implementation pages in `pencil-bindings.md`
+9. generate `tasks.md`
+10. build and verify
 
 ## 2. `greenfield-brainstorm`
 
@@ -54,10 +55,11 @@ Expected flow:
 3. stabilize scope in `proposal.md`
 4. write behavior in `specs/<capability>/spec.md`
 5. define pages in `page-map.md`
-6. register and generate Pencil sources
-7. bind implementation pages to Pencil pages
-8. generate tasks
-9. build and verify
+6. resolve any requested visual adapter and record it in `design-registry.md`
+7. register and generate Pencil sources
+8. bind implementation pages to Pencil pages
+9. generate tasks
+10. build and verify
 
 ## 3. `redesign-from-code`
 
@@ -72,14 +74,26 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 Expected flow:
 
 1. scan the existing product into `project-inventory.md`
-2. register any current `.pen` sources in `design-registry.md`
-3. define redesign scope in `proposal.md`
-4. split broad redesign work into `specs/<slice>/spec.md` files when one large `ui-refresh` spec would be too coarse
-5. rebuild or refine `page-map.md`
-6. create new or updated Pencil pages
-7. bind routes and pages to Pencil screens
-8. generate tasks aligned to the redesign slices
-9. build and verify
+2. read any visual-adapter preference from the request or `DA-VINCI.md`
+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`, 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`
 
@@ -96,12 +110,26 @@ Expected flow:
 1. define the change in `proposal.md`
 2. write affected behavior in `specs/<capability>/spec.md`
 3. update the affected subset of `page-map.md`
-4. reuse or update the active design source in `design-registry.md`
+4. reuse or update the active design source and visual-adapter resolution in `design-registry.md`
 5. create the Pencil delta in `pencil-design.md`
 6. update `pencil-bindings.md`
 7. generate tasks
 8. build and verify
 
+## Visual-adapter helper example
+
+When the project wants optional UI-design help from local skills:
+
+```text
+$da-vinci use redesign-from-code to redesign the current product UI.
+
+Existing code is the behavior source of truth.
+Use the visual-adapter preferences declared in DA-VINCI.md.
+If frontend-skill is available, use it as the primary visual adapter.
+If it is unavailable, fall back to native Da Vinci design rules and continue.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
 ## Cross-mode rule
 
 In every mode:
@@ -113,7 +141,9 @@ In every mode:
 And in every mode:
 
 - `design-registry.md` tracks the available `.pen` sources
+- `design-registry.md` also records visual-adapter resolution when one is requested
 - `pencil-bindings.md` tracks implementation page to Pencil page mapping
+- `pencil-design.md` records how the resolved adapter influenced the design pass when relevant
 - the workflow runs as `autonomous-by-default` unless a real blocker exists
 
 ## Complex redesign helper example

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`
 
 适合：
@@ -154,3 +162,11 @@ Da Vinci 应该：
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`
 8. 进入实现
+
+## `DA-VINCI.md` 里的 visual adapter 应该怎么用
+
+- 把 visual adapter 偏好写在 `DA-VINCI.md` 里，而不是单独再造一个配置文件
+- 把它当成可选的 presentation 增强层
+- 可以用来辅助 `DA-VINCI.md`、`design.md`、`pencil-design.md`
+- 例如本地 skill 里的 `frontend-skill` 或 `ui-ux-pro-max`
+- 如果本地没有对应 adapter，就回退到 Da Vinci 原生设计规则，并把结果记录到 `design-registry.md`