@xenonbyte/da-vinci-workflow 0.1.8 → 0.1.10

package/references/artifact-templates.md

@@ -149,6 +149,12 @@ Use this structure:
 - CTA tone
 - navigation tone
 
+## Visual Assist
+- Preferred adapters
+- Scope
+- Fallback
+- Require Adapter
+
 ## Do
 - approved stylistic moves
 
@@ -162,6 +168,13 @@ Use this structure:
 - inferred baseline
 ```
 
+Field meaning:
+
+- `Preferred adapters`: desired local-skill priority order
+- `Scope`: allowed presentation-quality influence areas only
+- `Fallback`: what to do when preferred adapters are unavailable
+- `Require Adapter`: whether missing adapters should block the workflow
+
 Use this artifact as a project-level visual contract. Generate it when the project does not already have one.
 
 Recommended path:
@@ -224,6 +237,14 @@ Use this structure:
 - Which `.pen` file is authoritative
 - Why that file should be preferred over live-only or external sources
 
+## Visual Adapter Resolution
+- Requested adapters
+- Resolved primary adapter
+- Secondary helpers
+- Status: active / fallback / unavailable
+- Scope
+- Fallback reason if native Da Vinci rules were used
+
 ## Historical Or Secondary Sources
 - Legacy files
 - Alternate explorations
@@ -252,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
@@ -272,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`
@@ -404,6 +436,12 @@ Use this structure:
 - project-local persisted path under `.da-vinci/designs/` when available
 - Active pages
 
+## Visual Adapter Use
+- Resolved primary adapter
+- Secondary helpers
+- How it affected composition, hierarchy, or motion guidance
+- Whether native Da Vinci fallback was used
+
 ## Page Mapping
 - Requirement -> Pencil page
 

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/design-inputs.md

@@ -7,6 +7,7 @@ Use this reference when collecting product form factor, UI direction, and design
 Check for `DA-VINCI.md` first, then check whether the project already has persisted Pencil files under `.da-vinci/designs/`.
 
 - if it exists, treat it as the project visual contract
+- if `DA-VINCI.md` declares preferred visual adapters, treat them as optional design-assist preferences
 - if `.da-vinci/designs/*.pen` exists, treat those files as project-local design inputs and record the exact preferred path in `design-registry.md`
 - 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
@@ -40,6 +41,11 @@ Collect or infer:
    - existing layout shell
    - responsive priority
 
+5. visual assist preferences
+   - preferred visual adapter names
+   - whether adapter use is required or optional
+   - fallback expectation when adapters are unavailable
+
 ## Inference Order
 
 Infer in this order:
@@ -68,3 +74,10 @@ 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 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`
+- if no adapter is available, continue with native Da Vinci design rules unless the user explicitly required a specific 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

@@ -28,6 +28,14 @@ When MCP is available, read:
 
 Prefer structural reads over screenshots.
 
+## 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
+- 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
+
 ## Map Pencil To Frontend
 
 Use these default mappings: